LeRobot documentation
스트리밍 비디오 인코딩 가이드
스트리밍 비디오 인코딩 가이드
1. 개요
Streaming video encoding는 비디오 데이터셋 기록 과정에서 전통적인 PNG 왕복을 제거합니다. 다음과 같은 방식 대신:
- 프레임 캡처 -> 디스크에 PNG 작성 -> (에피소드 종료 시) PNG 읽기 -> MP4로 인코딩 -> PNG 삭제
Frames는 캡처 중에 실시간으로 인코딩될 수 있습니다:
- 프레임 캡처 -> 인코더 스레드에 큐잉 -> MP4로 직접 인코딩
이로 인해 save_episode()가 거의 즉시 실행되며(에피소드가 끝날 시점에 이미 비디오가 인코딩되어 있음), 특히 여러 카메라가 있는 긴 에피소드에서 에피소드 사이에 발생하던 차단 대기 시간이 제거됩니다.
2. 튜닝 매개변수
| 매개변수 | CLI 플래그 | 유형 | 기본값 | 설명 |
|---|---|---|---|---|
streaming_encoding | --dataset.streaming_encoding | bool | False | 캡처 중 실시간 인코딩 활성화 |
vcodec | --dataset.rgb_encoder.vcodec | str | "libsvtav1" | 비디오 코덱. "auto"는 최적의 HW 인코더를 감지합니다 |
encoder_threads | --dataset.encoder_threads | int \| None | None (자동) | 인코더 인스턴스당 스레드 수. None이면 vcoded가 결정합니다 |
encoder_queue_maxsize | --dataset.encoder_queue_maxsize | int | 30 | 카메라당 최대 버퍼링 프레임 수(30fps 기준 약 1초). RAM을 소모합니다 |
3. 성능 고려 사항
Streaming encoding은 캡처 루프 중에, 캡처 루프 이후가 아니라 CPU가 비디오를 인코딩하는 것을 의미합니다. 이는 다음 항목들 사이에 공유되어야 하는 CPU 예산을 생성합니다:
- 제어 루프(카메라 읽기, 로봇 제어, 비비디오 데이터 쓰기)
- 인코더 스레드(카메라당 1개 풀)
- (활성화된 경우) 시각화 다시 실행
- OS 및 기타 프로세스
해상도 및 카메라 수의 영향
| 설정 | 처리량(px/sec) | CPU 인코딩 로드 | The input is a single word "Notes". 참고 |
|---|---|---|---|
| 2camsx 640x480x3 @30fps | 55M | 낮음 | 대부분의 시스템에서 작동합니다 |
| 2camsx 1280x720x3 @30fps | 165M | 중간 | 현대 시스템에서 편안하게 |
| 2camsx 1920x1080x3 @30fps | 373M | 높음 | 강력한 고성능 CPU가 필요합니다 |
encoder_threads 튜닝
이 매개변수는 각 인코더 인스턴스가 내부적으로 사용하는 스레드 수를 제어합니다:
- 높은 값(예: 4-5): 인코딩 속도가 빨라지지만 카메라당 더 많은 CPU 코어를 사용합니다. 코어가 많은 고성능 시스템에 적합합니다.
- 낮은 값(예: 1-2): 카메라당 CPU 사용량이 줄어들어 캡처 및 시각화에 코어가 더 할당됩니다. 저해상도 이미지와 성능이 좋은 CPU에 적합합니다.
None(기본값): 코덱이 결정하도록 합니다. 코덱 로그에서 정보를 확인할 수 있습니다.
백프레셔와 프레임 드롭
각 카메라에는 제한된 큐(encoder_queue_maxsize, 기본값 30프레임)가 있습니다. 인코더가 속도를 따라가지 못할 때:
- 큐가 가득 차면(RAM을 소모함)
- 새 프레임은 제거됩니다(차단되지 않음) — 캡처 루프는 중단 없이 계속됩니다
- 경고가 기록됩니다:
"Encoder queue full for {camera}, dropped N frame(s)" - 에피소드 종료 시, 카메라별 총 드롭 프레임 수가 보고됩니다
인코더가 뒤처지는 증상
- 시스템이 느리고 멈춤 현상이 발생함: 모든 CPU가 100% 사용 중
- 로그에 프레임 드롭 경고가 표시되거나, 기록된 데이터셋에서 예상보다 낮은 프레임/FPS가 나타나는 경우
- 부자연스러운 로봇 움직임: CPU가 심각하게 과부하 상태라면 캡처 루프에도 영향을 미칠 수 있습니다
- 누적된 재실행 지연: 시각화가 실시간을 따라가지 못함
4. 하드웨어 가속 인코딩
사용 시점
다음과 같은 경우 HW 인코딩을 사용하세요:
- CPU가 병목 현상(프레임 드롭, 로봇 동작 끊김, rerun 지연)
- 호환되는 하드웨어(GPU 또는 전용 인코더)를 보유하고 있습니다
- 높은 처리량(높은 해상도 또는 여러 카메라 사용)으로 녹화 중입니다
코덱 선택
| 코덱 | CPU 사용량 | 파일 크기 | 품질 | The input is a single word "Notes". 참고 |
|---|---|---|---|---|
libsvtav1 (기본값) | 높음 | 가장 작은 | 최고 | 기본값. 압축률이 가장 높지만 CPU 부하가 가장 큽니다 |
h264 | 중간 | ~30-50% 더 큼 | 좋습니다 | 소프트웨어 H.264. 낮은 CPU |
| HW 인코더 | 매우 낮음 | 가장 큰 | 좋습니다 | 전용 하드웨어로 오프로드합니다. CPU 제약이 있는 시스템에 가장 적합합니다 |
사용 가능한 HW 인코더
| 인코더 | 플랫폼 | 하드웨어 | 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 | NVIDIA GPU | --dataset.rgb_encoder.vcodec=h264_nvenc |
hevc_nvenc | Linux/Windows | NVIDIA GPU | --dataset.rgb_encoder.vcodec=hevc_nvenc |
h264_vaapi | Linux | Intel/AMD GPU | --dataset.rgb_encoder.vcodec=h264_vaapi |
h264_qsv | Linux/Windows | Intel Quick Sync | --dataset.rgb_encoder.vcodec=h264_qsv |
auto | 모두 | 사용 가능한 HW 인코더를 시스템에서 탐색합니다. HW 인코더가 발견되지 않으면 libsvtav1로 대체합니다. | --dataset.rgb_encoder.vcodec=auto |
HW 가속 인코더를 사용하려면 GPU 드라이버를 업그레이드해야 할 수 있습니다.
libsvtav1은 최고의 학습 성능을 제공하기 때문에 기본값입니다. 다른 vcodec은 CPU 사용량을 줄이고 더 빠를 수 있지만, 일반적으로 더 큰 파일을 생성하며 학습 시간에 영향을 줄 수 있습니다.
5. 문제 해결
| 증상 | 가능한 원인 | 수정 |
|---|---|---|
| 시스템이 멈추거나 로봇 움직임이 끊기거나 Rerun 시각화가 지연되는 경우 | CPU 부족 (100% 로드 사용률) | 다른 앱을 종료하고, 인코딩 처리량을 줄이고, encoder_threads를 낮추고, h264를 사용하고, display_data=False를 사용하세요. CPU가 여전히 100%를 유지한다면 현재 설정에 충분하지 않을 수 있으므로, --dataset.streaming_encoding=false 또는 HW 인코딩(--dataset.rgb_encoder.vcodec=auto)을 고려해 보세요. |
| 데이터셋에서 “Encoder queue full” 경고 또는 프레임 드롭 | Encoder가 따라가지 못함(큐 오버플로우) | CPU가 100%가 아닌 경우: encoder_threads를 증가시키거나, encoder_queue_maxsize를 증가시키거나, HW 인코딩(--dataset.rgb_encoder.vcodec=auto)을 사용하세요. |
| 높은 RAM 사용량 | 인코딩보다 큐가 더 빠르게 채워지는 경우 | encoder_threads 값이 너무 낮거나 CPU 자원이 부족합니다. encoder_queue_maxsize 값을 줄이거나 HW 인코딩을 사용하세요. |
| 대용량 비디오 파일 | HW 인코더 또는 H.264 사용 | 기대되는 트레이드오프. CPU가 허용하는 경우 libsvtav1로 전환하세요 |
save_episode()가 여전히 느립니다 | streaming_encoding이 False입니다 | --dataset.streaming_encoding=true를 설정합니다 |
| 인코더 스레드 충돌 | 코덱을 사용할 수 없거나 잘못된 설정 | vcodec이 설치되어 있는지 확인하고, --dataset.rgb_encoder.vcodec=auto를 시도해 보세요. |
| 기록된 데이터셋에서 프레임이 누락되었습니다 | CPU/GPU 기아 또는 간헐적인 부하 스파이크 | 프레임의 약 5%가 누락된 경우 시스템이 과부하 상태일 가능성이 높으므로, 위의 권장 사항을 따르십시오. 누락된 프레임이 더 적을 경우(약 2%)는 일시적인 부하 스파이크(시작 시에 자주 발생)로 인한 것으로 간주할 수 있으며, 이는 예상된 현상으로 볼 수 있습니다. |
6. 권장 구성
이 추정치는 보수적으로 설정되어 있습니다. 해당 구성에서 테스트해 보시길 권장하며, 낮은 부하로 시작하여 점진적으로 부하를 높여가세요.
고사양 시스템: 최신 12개 이상 코어(24개 이상 스레드)
CPU에서 ~250-500M px/sec 사이의 처리량이 편안해야 합니다. 더 나은 결과를 원하시면 사용 가능한 경우 HW 인코딩을 시도해 보세요.
# 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.중급 시스템: 최신 8개 이상 코어(16개 이상 스레드) 또는 Apple Silicon
CPU에서 ~80-300M px/sec의 처리량이 가능해야 합니다.
# 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.저자원 시스템: 최신 4코어 이상(8스레드 이상) 또는 Raspberry Pi 5
매우 제한적인 시스템에서는 스트리밍 인코딩이 캡처 루프와 과도하게 경쟁할 수 있습니다. 이를 비활성화하면 에피소드 사이에 인코딩이 수행되는 PNG 기반 방식으로 폴백됩니다(블로킹 방식이지만 캡처에 간섭을 주지 않음). 대안으로, 캡처 및 인코딩 부하를 모두 줄이기 위해 더 낮은 처리량으로 녹화할 수 있습니다. 또한 코덱을 h264로 변경하고 배치 인코딩을 사용하는 것도 고려해 보세요.
# 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. 마무리
성능은 결국 정확한 환경 설정에 따라 달라집니다. 초당 프레임 수, 해상도, CPU 코어 수와 부하, 사용 가능한 메모리, 에피소드 길이, 그리고 선택한 인코더 등이 모두 영향을 미칩니다. 반드시 대상 워크로드를 기준으로 테스트하고, CPU 및 시스템 성능을 충분히 고려한 뒤 encoder_threads, encoder_queue_maxsize, vcodec 값을 적절히 조정하세요. 일반적으로 많은 애플리케이션에 적용되는 실용적인 구성은 640×480x3 해상도로 30fps의 카메라 3대입니다. 최신 시스템에서는 기본 스트리밍 비디오 인코딩 설정으로도 이 구성이 원활하게 동작하는 경우가 많습니다. 기록된 데이터셋이 정상인지 항상 확인하세요. 이를 위해 비디오 재생 시간을 CLI 에피소드 시간과 비교하고, 행 수가 FPS × CLI 시간과 일치하는지 검증합니다.