Guide de l’encodage vidéo en streaming

1. Vue d'ensemble

L'encodage vidéo en streaming élimine le passage par PNG traditionnel lors de l'enregistrement des jeux de données vidéo. Au lieu de :

1. Capture d'une image -> écriture du PNG sur le disque -> (à la fin de l'épisode) lecture des PNG -> encodage en MP4 -> suppression des PNG

Les images peuvent être encodées en temps réel pendant la capture :

1. Capture d'image -> file d'attente pour le thread d'encodeur -> encodage direct en MP4

Cela rend save_episode() quasi instantané (la vidéo est déjà encodée à la fin de l'épisode) et supprime l'attente bloquante qui se produisait auparavant entre les épisodes, en particulier avec plusieurs caméras lors d'épisodes longs.

2. Paramètres d'ajustement

3. Considérations relatives aux performances

L'encodage en streaming signifie que le CPU encode la vidéo durant la boucle de capture, et non après. Cela crée un budget CPU qui doit être partagé entre :

• Boucle de contrôle (lecture des caméras, contrôle du robot, écriture de données non vidéo)
• Fils d'encodeur (un pool par caméra)
• Réexécuter la visualisation (si activé)
• Système d'exploitation et autres processus

Impact de la résolution et du nombre de caméras

encoder_threads Réglage

Ce paramètre contrôle le nombre de threads utilisés par chaque instance de l'encodeur :

• Des valeurs plus élevées (par exemple, 4-5) : encodage plus rapide, mais utilise plus de cœurs CPU par caméra. Convient aux systèmes haut de gamme dotés de nombreux cœurs.
• Des valeurs plus faibles (par exemple, 1-2) : moins de CPU par caméra, libérant des cœurs pour la capture et la visualisation. Convient aux images basse résolution et aux CPU performants.
• None (par défaut) : Laisse le codec décider. Les informations sont disponibles dans les journaux du codec.

Backpressure et abandon de trames

Chaque caméra dispose d’une file bornée (encoder_queue_maxsize, 30 images par défaut). Lorsque l’encodeur n’arrive pas à suivre :

1. La file d'attente se remplit (consommant de la RAM)
2. Les nouvelles images sont abandonnées (non bloquées) — la boucle de capture continue sans interruption
3. Un avertissement est consigné : "Encoder queue full for {camera}, dropped N frame(s)"
4. À la fin de l'épisode, le nombre total d'images perdues par caméra est signalé

Symptômes d'un encodeur en retard

• Le système est lent et se fige : tous les processeurs sont à 100 %
• Avertissements de frames perdues dans le journal ou un nombre de frames/FPS inférieur à celui attendu dans le jeu de données enregistré
• Mouvement robotique saccadé : si le processeur est fortement surchargé, même la boucle de capture peut être affectée
• Retard d'exécution cumulé : la visualisation accuse un retard par rapport au temps réel

4. Encodage accéléré par le matériel

Quand l'utiliser

Utiliser l’encodage matériel lorsque :

• Le CPU est le goulot d'étranglement (images perdues, robot saccadé, latence de rerun)
• Vous disposez d'un matériel compatible (GPU ou encodeur dédié)
• Vous enregistrez à haut débit (haute résolution ou avec de nombreuses caméras)

Choisir un codec

Encodeurs matériels disponibles

Afin d'utiliser les encodeurs accélérés par le matériel, vous devrez peut-être mettre à jour vos pilotes GPU.

libsvtav1 est le codec par défaut car il offre les meilleures performances d’entraînement ; d’autres vcodecs peuvent réduire l’utilisation du CPU et être plus rapides, mais ils produisent généralement des fichiers plus volumineux et peuvent affecter le temps d’entraînement.

5. Dépannage

6. Configurations recommandées

Ces estimations sont prudentes ; nous vous recommandons de les tester sur votre configuration — commencez par une charge faible et augmentez-la progressivement.

Systèmes haut de gamme : 12 cœurs ou plus (24 threads ou plus) modernes

Un débit compris entre ~250 et 500 M px/sec devrait être confortable sur CPU. Pour de meilleurs résultats, essayez l'encodage matériel s'il est disponible.

# 3camsx 1280x720x3 @30fps: Defaults work well. Optionally increase encoder parallelism.
# 2camsx 1920x1080x3 @30fps: Defaults work well. Optionally increase encoder parallelism.
lerobot-record --dataset.encoder_threads=5 ...

# 3camsx 1920x1080x3 @30fps: Might require some tuning.

Systèmes de milieu de gamme : 8 cœurs ou plus (16 threads ou plus) modernes ou Apple Silicon

Un débit compris entre ~80 et 300 M px/sec devrait être possible sur CPU.

# 3camsx 640x480x3 @30fps: Defaults work well. Optionally decrease encoder parallelism.
# 2camsx 1280x720x3 @30fps: Defaults work well. Optionally decrease encoder parallelism.
lerobot-record --dataset.encoder_threads=2 ...

# 2camsx 1920x1080x3 @30fps: Might require some tuning.

Systèmes à ressources limitées : processeurs modernes 4 cœurs ou plus (8 threads ou plus) ou Raspberry Pi 5

Sur les systèmes très contraints, l’encodage en flux peut entrer en concurrence excessive avec la boucle de capture. Le désactiver revient à l’approche basée sur PNG, où l’encodage a lieu entre les épisodes (bloquant, mais sans interférer avec la capture). En alternative, enregistrez à un débit plus faible pour réduire à la fois la charge de capture et d’encodage. Envisagez également de changer de codec pour h264 et d’utiliser l’encodage par lots.

# 2camsx 640x480x3 @30fps: Requires some tuning.

# Use H.264, disable streaming, consider batching encoding
lerobot-record --dataset.rgb_encoder.vcodec=h264 --dataset.streaming_encoding=false ...

7. Note de clôture

Les performances dépendent en fin de compte de votre configuration exacte — images par seconde, résolution, nombre et charge des cœurs CPU, mémoire disponible, longueur des épisodes et encodeur choisi. Testez toujours avec votre charge de travail cible, tenez compte des capacités de votre CPU et de votre système, et réglez raisonnablement encoder_threads, encoder_queue_maxsize et vcodec. Cela dit, une configuration pratique courante (pour de nombreuses applications) consiste à utiliser trois caméras à 640×480x3 @30fps ; cela fonctionne généralement bien avec les paramètres d’encodage vidéo en streaming par défaut sur les systèmes modernes. Vérifiez toujours que votre jeu de données enregistré est sain en comparant la durée de la vidéo à la durée de l’épisode CLI et en confirmant que le nombre de lignes est égal à FPS × durée CLI.