Guia de Codificação de Vídeo em Transmissão

1. Visão geral

A codificação de vídeo em streaming elimina o ciclo tradicional de PNG durante a gravação de conjuntos de dados de vídeo. Em vez de:

1. Capturar quadro -> gravar PNG em disco -> (no final do episódio) ler os PNGs -> codificar para MP4 -> excluir os PNGs

Os quadros podem ser codificados em tempo real durante a captura:

1. Capturar quadro -> enfileirar para a thread do codificador -> codificar diretamente para MP4

Isso torna save_episode() quase instantâneo (o vídeo já está codificado quando o episódio termina) e elimina a espera bloqueante que ocorria anteriormente entre os episódios, especialmente com múltiplas câmeras em episódios longos.

2. Parâmetros de ajuste

3. Considerações de desempenho

A codificação em streaming significa que a CPU está codificando o vídeo durante o loop de captura, e não depois. Isso cria um orçamento de CPU que deve ser compartilhado entre:

• Loop de controle (leitura das câmeras, controle do robô, gravação de dados não em vídeo)
• Threads de codificação (um pool por câmera)
• Executar novamente a visualização (se ativado)
• Sistema operacional e outros processos

Impacto da resolução e do número de câmeras

encoder_threads Ajustes

Este parâmetro controla quantos threads cada instância do encoder usa internamente:

• Valores mais altos (por exemplo, 4-5): codificação mais rápida, mas usa mais núcleos de CPU por câmera. Bom para sistemas de alto desempenho com muitos núcleos.
• Valores menores (por exemplo, 1-2): Menos CPU por câmera, liberando núcleos para captura e visualização. Bom para imagens de baixa resolução e CPUs capazes.
• None (padrão): Deixa o codec decidir. As informações disponíveis estão nos logs do codec.

Backpressure e Descarte de Quadros

Cada câmera possui uma fila limitada (encoder_queue_maxsize, padrão 30 quadros). Quando o codificador não consegue acompanhar:

1. A fila fica cheia (consumindo RAM)
2. Novos quadros são descartados (não bloqueados) — o loop de captura continua ininterrupto
3. Um aviso é registrado: "Encoder queue full for {camera}, dropped N frame(s)"
4. No final do episódio, o total de quadros descartados por câmera é reportado

Sintomas do Encoder ficando para trás

• O sistema fica lento e congela: todos os CPUs estão em 100%
• Avisos de quadros descartados no log ou menos quadros/FPS do que o esperado no conjunto de dados gravado
• Movimento robótico irregular: Se a CPU estiver severamente sobrecarregada, até o loop de captura pode ser afetado
• Atraso acumulado de reexecução: A visualização fica para trás em relação ao tempo real

4. Codificação com Aceleração de Hardware

Quando usar

Use a codificação de HW quando:

• A CPU é o gargalo (quadros perdidos, robô travando, atraso no rerun)
• Você possui hardware compatível (GPU ou codificador dedicado)
• Você está gravando com alto throughput (alta resolução ou com muitas câmeras)

Escolhendo um Codec

Codificadores de HW disponíveis

Para usar os codificadores acelerados por HW, você pode precisar atualizar os drivers da sua GPU.

libsvtav1 é o padrão porque oferece o melhor desempenho de treinamento; outros vcodecs podem reduzir o uso de CPU e ser mais rápidos, mas geralmente produzem arquivos maiores e podem afetar o tempo de treinamento.

5. Solução de problemas

6. Configurações recomendadas

Essas estimativas são conservadoras; recomendamos testá-las no seu ambiente — comece com uma carga baixa e aumente-a gradualmente.

Sistemas de alto desempenho: 12+ núcleos modernos (24+ threads)

Um throughput entre ~250-500M px/sec deve ser confortável em CPU. Para resultados ainda melhores, tente a codificação em HW, se disponível.

# 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 faixa intermediária: 8+ núcleos modernos (16+ threads) ou Apple Silicon

Um throughput de ~80-300M px/sec deve ser possível em 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 de Recursos Limitados: 4+ núcleos modernos (8+ threads) ou Raspberry Pi 5

Em sistemas muito restritos, a codificação em streaming pode competir excessivamente com o loop de captura. Desativá-la faz com que o sistema volte para a abordagem baseada em PNG, na qual a codificação ocorre entre episódios (bloqueante, mas não interfere na captura). Alternativamente, grave com uma taxa de transferência menor para reduzir a carga tanto da captura quanto da codificação. Considere também alterar o codec para h264 e usar codificação em lote.

# 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

O desempenho depende, em última análise, da sua configuração exata — quadros por segundo, resolução, núcleos e carga da CPU, memória disponível, duração do episódio e o codificador escolhido. Sempre teste com a sua carga de trabalho alvo, tenha em mente as capacidades da sua CPU & do sistema e ajuste encoder_threads, encoder_queue_maxsize e vcodec de forma razoável. Dito isso, uma configuração prática comum (para muitas aplicações) é três câmeras em 640×480x3 @30fps; isso geralmente funciona bem com as configurações padrão de codificação de vídeo em streaming em sistemas modernos. Sempre verifique se o seu conjunto de dados gravado está íntegro comparando a duração do vídeo com a duração do episódio da CLI e confirmando que a contagem de linhas é igual a FPS × duração da CLI.