LeRobot documentation
Guía de codificación de video en streaming
Guía de codificación de video en streaming
1. Resumen
La codificación de video en streaming elimina el recorrido tradicional de PNG durante la grabación de conjuntos de datos de video. En lugar de:
- Capturar fotograma -> escribir PNG en disco -> (al final del episodio) leer los PNG -> codificar a MP4 -> eliminar los PNG
Los fotogramas pueden codificarse en tiempo real durante la captura:
- Capturar fotograma -> encolar en el hilo del codificador -> codificar directamente a MP4
Esto hace que save_episode() sea casi instantáneo (el video ya está codificado para cuando termina el episodio) y elimina la espera bloqueante que ocurría previamente entre episodios, especialmente con múltiples cámaras en episodios largos.
2. Parámetros de ajuste
| Parámetro | Flag de CLI | Tipo | Predeterminado | Descripción |
|---|---|---|---|---|
streaming_encoding | --dataset.streaming_encoding | bool | False | Activar la codificación en tiempo real durante la captura |
vcodec | --dataset.rgb_encoder.vcodec | str | "libsvtav1" | Códec de vídeo. "auto" detecta el mejor codificador de HW |
encoder_threads | --dataset.encoder_threads | int \| None | None (automático) | Hilos por instancia del codificador. None dejará que vcoded decida |
encoder_queue_maxsize | --dataset.encoder_queue_maxsize | int | 30 | Marcos bufferizados máximos por cámara (~1 s a 30 fps). Consume RAM |
3. Consideraciones de rendimiento
La codificación por streaming significa que la CPU codifica el video durante el bucle de captura, no después. Esto crea un presupuesto de CPU que debe compartirse entre:
- Bucle de control (lectura de cámaras, control del robot, escritura de datos no de vídeo)
- Hilos del codificador (un pool por cámara)
- Reejecutar la visualización (si está habilitado)
- Sistema operativo y otros procesos
Impacto de la resolución y el número de cámaras
| Configuración | Throughput (px/seg) | Carga de codificación en CPU | Notas |
|---|---|---|---|
| 2camsx 640x480x3 @30fps | 55M | Bajo | Funciona en la mayoría de los sistemas |
| 2camsx 1280x720x3 @30fps | 165M | Moderado | Cómodo en sistemas modernos |
| 2camsx 1920x1080x3 @30fps | 373M | Alto | Requiere una CPU de gama alta y gran potencia |
encoder_threads Ajustes
Este parámetro controla cuántos hilos utiliza internamente cada instancia del codificador:
- Valores más altos (p. ej., 4-5): codificación más rápida, pero utiliza más núcleos de CPU por cámara. Adecuado para sistemas de gama alta con muchos núcleos.
- Valores más bajos (p. ej., 1-2): Menor uso de CPU por cámara, liberando núcleos para la captura y la visualización. Adecuado para imágenes de baja resolución y CPUs con capacidad suficiente.
None(predeterminado): Deja que el códec decida. La información está disponible en los registros del códec.
Backpressure y descarte de fotogramas
Cada cámara tiene una cola acotada (encoder_queue_maxsize, 30 fotogramas por defecto). Cuando el codificador no puede mantener el ritmo:
- La cola se llena (consumiendo RAM)
- Los nuevos fotogramas se descartan (no se bloquean): el bucle de captura continúa sin interrupciones
- Se registra una advertencia:
"Encoder queue full for {camera}, dropped N frame(s)" - Al final del episodio, se informan los fotogramas perdidos totales por cámara
Síntomas de que el codificador se está quedando atrás
- El sistema se siente lento y se congela: todas las CPUs están al 100%
- Advertencias de fotogramas omitidos en el registro o un número de fotogramas/FPS inferior al esperado en el conjunto de datos grabado
- Movimiento robótico entrecortado: Si la CPU está severamente sobrecargada, incluso el bucle de captura puede verse afectado
- Retraso acumulado de reejecución: La visualización se queda atrás respecto al tiempo real
4. Codificación acelerada por hardware
Cuándo usar
Use la codificación de HW cuando:
- La CPU es el cuello de botella (pérdida de fotogramas, robot entrecortado, retraso en rerun)
- Cuenta con hardware compatible (GPU o codificador dedicado)
- Estás grabando con un alto rendimiento (alta resolución o con muchas cámaras)
Elegir un códec
| Codec | Uso de CPU | Tamaño del archivo | Calidad | Notas |
|---|---|---|---|---|
libsvtav1 (predeterminado) | Alto | Más pequeño | Mejor | Predeterminado. La mejor compresión, pero la más intensiva en CPU |
h264 | Medio | ~30-50% más grande | Bien | Software H.264. Menor CPU |
| Codificadores de HW | Muy bajo | Más grande | Bien | Descarga en hardware dedicado. Ideal para sistemas con limitaciones de CPU |
Codificadores de HW disponibles
| Codificador | Plataforma | Hardware | Valor de la CLI |
|---|---|---|---|
h264_videotoolbox | macOS | Apple Silicon / Intel | --dataset.rgb_encoder.vcodec=h264_videotoolbox |
hevc_videotoolbox | macOS | Apple Silicon / Intel | --dataset.rgb_encoder.vcodec=hevc_videotoolbox |
h264_nvenc | Linux/Windows | GPU de NVIDIA | --dataset.rgb_encoder.vcodec=h264_nvenc |
hevc_nvenc | Linux/Windows | GPU de NVIDIA | --dataset.rgb_encoder.vcodec=hevc_nvenc |
h264_vaapi | Linux | GPU de Intel/AMD | --dataset.rgb_encoder.vcodec=h264_vaapi |
h264_qsv | Linux/Windows | Intel Quick Sync | --dataset.rgb_encoder.vcodec=h264_qsv |
auto | Cualquiera | Investiga el sistema en busca de codificadores de HW disponibles. Si no se encuentra ningún codificador de HW, utiliza libsvtav1 como alternativa | --dataset.rgb_encoder.vcodec=auto |
Para usar los codificadores acelerados por hardware, es posible que necesites actualizar los controladores de tu GPU.
libsvtav1es el predeterminado porque ofrece el mejor rendimiento de entrenamiento; otros vcodecs pueden reducir el uso de CPU y ser más rápidos, pero generalmente producen archivos más grandes y pueden afectar el tiempo de entrenamiento.
5. Solución de problemas
| Síntoma | Causa probable | Corregir |
|---|---|---|
| El sistema se congela o el movimiento del robot es entrecortado o la visualización de Rerun tiene retrasos | CPU con escasez (uso de carga del 100%) | Cierra otras aplicaciones, reduce el rendimiento de codificación, disminuye encoder_threads, usa h264, usa display_data=False. Si la CPU sigue al 100%, es posible que no sea suficiente para tu configuración; considera --dataset.streaming_encoding=false o la codificación por hardware (--dataset.rgb_encoder.vcodec=auto). |
| Avisos de “Encoder queue full” o fotogramas descartados en el conjunto de datos | El codificador no puede mantener el ritmo (desbordamiento de la cola) | Si la CPU no está al 100%: aumenta encoder_threads, aumenta encoder_queue_maxsize o usa codificación por hardware (--dataset.rgb_encoder.vcodec=auto). |
| Alto uso de RAM | La cola se llena más rápido que la codificación | encoder_threads demasiado bajo o CPU insuficiente. Reduce encoder_queue_maxsize o usa codificación por hardware |
| Archivos de video de gran tamaño | Uso del codificador HW o H.264 | Compensación esperada. Cambia a libsvtav1 si la CPU lo permite |
save_episode() sigue siendo lento | streaming_encoding es False | Establezca --dataset.streaming_encoding=true |
| Crash del hilo codificador | Codec no disponible o configuración no válida | Comprueba que vcodec está instalado, prueba --dataset.rgb_encoder.vcodec=auto |
| El conjunto de datos grabado tiene cuadros faltantes | Estarvación de CPU/GPU o picos ocasionales de carga | Si faltan ~5% de los fotogramas, es probable que el sistema esté sobrecargado; siga las recomendaciones anteriores. Si faltan menos fotogramas (~2%), probablemente se deban a picos transitorios ocasionales de carga (a menudo al inicio) y pueden considerarse esperados. |
6. Configuraciones recomendadas
Estas estimaciones son conservadoras; recomendamos probarlas en su configuración: comience con una carga baja y aumente gradualmente.
Sistemas de gama alta: 12 núcleos modernos o más (24 hilos o más)
Un rendimiento entre ~250-500M px/sec debería ser cómodo en CPU. Para obtener mejores resultados, intente la codificación por hardware si 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.Sistemas de gama media: 8 núcleos modernos o más (16 hilos o más) o Apple Silicon
Un rendimiento entre ~80-300M px/seg debería ser posible en 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.Sistemas con recursos limitados: 4 núcleos modernos o más (8 hilos o más) o Raspberry Pi 5
En sistemas muy limitados, la codificación por streaming puede competir demasiado con el bucle de captura. Desactivarla recurre al enfoque basado en PNG, donde la codificación ocurre entre episodios (bloqueante, pero no interfiere con la captura). Alternativamente, graba con un rendimiento menor para reducir tanto la carga de captura como la de codificación. Considera también cambiar el códec a h264 y usar codificación por lotes.
# 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. Nota final
El rendimiento depende en última instancia de tu configuración exacta: fotogramas por segundo, resolución, núcleos de CPU y carga, memoria disponible, duración del episodio y el codificador que elijas. Prueba siempre con tu carga de trabajo objetivo, ten en cuenta las capacidades de tu CPU y del sistema, y ajusta de forma razonable encoder_threads, encoder_queue_maxsize y vcodec. Dicho esto, una configuración práctica común (para muchas aplicaciones) es tres cámaras a 640×480x3 @30fps; esto suele funcionar bien con la configuración predeterminada de codificación de vídeo en streaming en sistemas modernos. Verifica siempre que tu conjunto de datos grabado esté sano comparando la duración del vídeo con la duración del episodio de la CLI y confirmando que el número de filas sea igual a FPS × duración de la CLI.