Rust FFmpeg은(는) 무엇을 하나요?
Rust에서 FFmpeg 기능을 구현하기 위한 안내서: 라이브러리 선택, 코드 생성, 문제 해결
선택 프레임워크
| 라이브러리 | 사용 시기 | 비동기 | 안전성 | 트레이드오프 |
|---|---|---|---|---|
| ez-ffmpeg | 일반 작업, CLI 마이그레이션, RTMP 서버, 커스텀 Rust + WGSL GPU 필터, 네이티브 자막 하드코딩, 탐지/측정, 단일 실행 레시피, 커스텀 I/O, 인메모리 프레임/샘플 내보내기 + 프레임 푸시(VideoWriter), 타입별 출력 진행률 | ✅ 예 | 안전 | FFmpeg 라이브러리 필요 |
| ffmpeg-next | 프레임 수준 제어, 코덱 내부, 안전한 스트림 I/O (모든 Read/Write/Seek) | ❌ 아니요 | 안전 | 더 많은 보일러플레이트 |
| ffmpeg-sys-next | 제로 카피, 커스텀 메모리 I/O, 최대 성능 | ❌ 아니요 | 불안전 | 수동 메모리 관리 |
| ffmpeg-sidecar | FFmpeg 설치 불가능 | ❌ 아니요 | 안전 | 프로세스 오버헤드, 커스텀 I/O 불가 |
의사 결정 로직
레이어 1: 통합 방식
기본값: 라이브러리 통합 (ez-ffmpeg/ffmpeg-next/ffmpeg-sys-next)
- 더 나은 성능, 타입 안전 API, 직접 프레임 접근
대안: 바이너리 방식 (ffmpeg-sidecar) - 다음 경우 고려:
- FFmpeg 개발 라이브러리를 설치할 수 없는 경우
- 관리자 권한이 없는 제한된 CI/CD 환경
- 순수 CLI 배치 처리 (실시간 요구 사항 없음)
설치가 제한된 경우 → ffmpeg_sidecar.md 로드
레이어 2: 시나리오 탐지
| 사용자 언급 | 참조 문서 로드 |
|---|---|
| "포맷 변환", "리먹스", "트림", "크기 조정", "자르기", "단순" | video_transcoding.md |
| "오디오 추출", "오디오만", "오디오 트랙", "mp3 추출", "loudnorm", "오디오 정규화", "볼륨" | audio_extraction.md |
| "썸네일", "첫 프레임", "빠른 썸네일", "skip_frame", "nokey", "키프레임만", "다중 출력", "연결", "워터마크", "파이프라인", "필터 그래프" | pipelines_multi_output.md — 단일 실행 썸네일의 경우 image_sequences.md의 recipes::thumbnail 선호; 가장 빠른 키프레임 전용 경로(skip_frame=nokey, 다음 키프레임으로 스냅)는 ez_ffmpeg/video.md 참조 |
| "실시간", "RTMP", "HLS", "라이브", "스트림", "캡처", "웹캠", "버퍼", "백프레셔", "지터 버퍼", "네트워크 지터", "ABR 래더", "HLS 래더", "적응형 비트레이트", "마스터 재생목록", "VOD 패키징" | streaming_rtmp_hls.md |
| "GPU", "NVENC", "VideoToolbox", "하드웨어", "VAAPI", "QSV", "wgpu", "WGSL", "커스텀 셰이더", "GPU 필터", "컴퓨트 셰이더", "libplacebo", "뷰티 필터", "크로마 키", "그린 스크린" | hardware_acceleration.md |
| "배치", "여러 파일", "대량", "병렬" | batch_processing.md |
| "자막", "srt", "캡션", "자막 하드코딩", "하드서브", "ass", "vtt", "네이티브 자막", "libass 없이", "libass 없음" | subtitles.md |
| "AV1", "AVIF", "HDR", "10비트", "최신 코덱", "HDR to SDR", "톤 매핑", "tonemap", "색 바램", "PQ", "HLG" | modern_codecs.md |
| "디버그", "ffprobe", "검사", "메타데이터", "오류", "문제 해결", "프로브", "재생 시간", "해상도", "손상", "무결성" | debugging.md |
| "검은 프레임 탐지", "무음 탐지", "씬 탐지", "씬 변경", "cropdetect", "EBU R128", "LUFS", "음량 측정", "트루 피크", "콘텐츠 분석", "QC", "blackdetect", "silencedetect" | detection_analysis.md (타입화된 analysis API) |
| "필터", "효과", "크기 조정", "자르기", "오버레이", "워터마크", "블러", "샤픈", "색상", "밝기", "회전", "뒤집기", "페이드", "속도", "슬로우 모션" | filters_effects.md |
| "이미지 시퀀스", "프레임 추출", "비디오를 이미지로", "이미지를 비디오로", "타임랩스", "프레임별", "스프라이트 시트", "스토리보드", "연락처 시트", "썸네일 그리드" | image_sequences.md |
"단일 실행 레시피", "레시피 모듈", "빠른 썸네일", "썸네일 레시피", "스프라이트 시트 레시피", "GIF 레시피", "HLS 래더 레시피" (ez-ffmpeg recipes, 기능 플래그 없음) | image_sequences.md (썸네일/스프라이트), gif_creation.md (GIF), streaming_rtmp_hls.md (HLS 래더) |
| "테스트", "검증", "확인", "골든 파일", "체크섬", "테스트 비디오 생성", "testsrc" | testing.md |
| "웹 서버", "API", "S3", "비동기 작업", "통합", "추적", "로깅", "로그 콜백", "av_log", "로그 리디렉션" | integration.md |
| "GIF", "애니메이션 GIF", "비디오를 GIF로", "GIF로 만들기", "GIF 루프", "GIF 팔레트" | gif_creation.md |
| "메타데이터", "챕터", "태그", "미디어 정보", "제목", "아티스트", "앨범", "챕터 마커" | metadata_chapters.md |
| "화면 캡처", "웹캠", "카메라 캡처", "화면 녹화", "avfoundation", "directshow", "v4l2", "장치 캡처" | capture.md |
| "AVPacket", "AVFrame", "키프레임", "GOP", "NALU", "비트스트림", "EAGAIN", "디코드 루프", "메모리", "패킷" | ffmpeg_next.md + ffmpeg_sys_next.md |
| "avformat_find_stream_info", "AVSEEK_SIZE", "AVFormatContext", "AVCodecID", "원시 C API", "FFI" | ffmpeg_sys_next.md + custom_io.md |
| "커스텀 I/O", "읽기 콜백", "쓰기 콜백", "StreamIo", "메모리 입력/출력", "Read/Write/Seek 소스" | 안전 API: advanced.md (ez-ffmpeg 콜백) 또는 ffmpeg_next.md (StreamIo) |
| "AVIOContext", "io 컨텍스트", "원시 IO 콜백", "제로 카피 커스텀 I/O" | custom_io.md (불안전 FFI) |
| "메모리로 프레임 추출", "RGB로 디코딩", "AI/ML용 프레임", "프레임을 텐서로", "프레임 내보내기", "모델용 비디오를 프레임으로", "FrameExtractor", "whisper PCM", "오디오를 f32로", "SampleExtractor", "ASR 수집", "균일 N 프레임" | frame_io.md (실험적, ez-ffmpeg 0.14) |
| "VideoWriter", "프레임 푸시", "프레임으로 비디오 생성", "프로시저 비디오", "프레임을 비디오로 렌더링", "인메모리 mp4", "메모리에서 인코딩", "프레임을 비디오로" | frame_io.md (실험적, ez-ffmpeg 0.14) |
| "WHIP", "WebRTC 출력", "SRT 출력", "기능 탐색", "is_muxer_available", "출력 프로토콜 사용 가능", "fMP4 HLS", "fragmented mp4 세그먼트" | streaming.md (WHIP/SRT/기능) + streaming_rtmp_hls.md (fMP4 래더) |
| "인코딩된 패킷 내보내기", "패킷 싱크", "PacketSink", "webcodecs", "EncodedVideoChunk", "EncodedAudioChunk", "h.264 접근 유닛", "aac 프레임", "avcC", "AudioSpecificConfig", "rtp 패킷 타이저", "fmp4 세그멘터", "작업 실패", "on_job_failed", "JobFailureSummary" | packet_sink.md (실험적, ez-ffmpeg 0.15; 작업-실패 요약 0.16) |
| "진행률", "진행률 표시줄", "완료 비율", "예상 시간", "얼마나 진행되었는지", "인코딩 속도", "progress_handle", "ProgressHandle", "진행률 스냅샷" | advanced.md; 배치 파일별 카운팅: batch_processing.md |
| "스트림별 인코더", "스트림별 다른 코덱", "StreamMap", "-c:v:0", "인덱스 스트림 옵션", "스트림별 코덱 옵션" | video.md (ez-ffmpeg 0.16) |
| "Rust에서 ffmpeg 명령 실행", "from_cli_args", "emit_rust_code", "ffmpeg 명령 변환", "cli 기능", "cli-compat", "검증된 형태" | cli_compat.md (cli 기능); 수동 매핑: cli_migration.md |
| "버전 호환성", "FFmpeg 7 vs 8", "링킹 오류", "빌드 실패", "links = ffmpeg", "설치", "vcpkg" | installation.md |
| "어떤 라이브러리", "비교", "vs", "마이그레이션", "포팅", "전환", "전환 대상", "재작성", "적합성", "사용할 라이브러리", "평가", "FFmpeg 코드 검토", "이것으로 작동할까요" | library_selection.md |
여러 행이 하나의 요청과 일치할 수 있습니다 — 모든 해당 참조를 로드한 후, 가장 구체적인 행의 대상을 먼저 따르세요.
레이어 3: 라이브러리 선택
CLI 마이그레이션: ez-ffmpeg와 ffmpeg-sidecar 모두 CLI 스타일 API를 지원합니다. 아래 제약 조건에 따라 선택하세요.
- ez-ffmpeg: CLI 마이그레이션 가이드 — 라이브러리 통합, 네이티브 성능
- ffmpeg-sidecar: CLI to Rust 마이그레이션 — 프로세스 래퍼, FFmpeg 라이브러리 불필요
- async/await가 필요하신가요? → ez-ffmpeg (네이티브 비동기를 지원하는 유일한 라이브러리)
- 커스텀 Rust 프레임 처리가 필요하신가요? → ez-ffmpeg FrameFilter (안전하고 간단한 API)
- 커스텀 GPU 셰이더(WGSL)가 필요하신가요? → ez-ffmpeg
wgpu기능 (WgpuFrameFilter, 헤드리스, 디스플레이 서버 불필요) — 먼저 내장wgpu_filter::effects카탈로그를 확인하세요 (13가지 타입화된 효과, 0.13+); 네이티브 하드웨어 필터(scale_cuda/scale_vaapi/libplacebo)의 경우get_gpu_filter_backends()로 탐색 - libass 없이 자막을 하드코딩해야 하나요? → ez-ffmpeg
subtitle기능 (SubtitleFilter, 순수 Rust ASS/SRT 렌더러,--enable-libass필요 없음) - 타입화된 탐지/측정(블랙/무음/씬/크롭/EBU R128)이 필요하신가요? → ez-ffmpeg
analysis모듈 (Analysis단일 실행 또는MetadataEventFilter스트리밍 — 기능 플래그 없음) - 단일 실행 썸네일 / 스프라이트 시트 / GIF / HLS ABR 래더가 필요하신가요? → ez-ffmpeg
recipes모듈 (기능 플래그 없음) - 프레임 수준의 코덱 제어가 필요하신가요? → ffmpeg-next (코덱 내부용)
- 메모리로부터의 커스텀 I/O가 필요하신가요? → ez-ffmpeg (읽기/쓰기/찾기 콜백), 또는 ffmpeg-next 안전한 스트림 I/O (
input_from_stream/output_to_stream, 모든Read/Write/Seek); ffmpeg-sys-next는 가장 낮은 수준의 제어용 - 제로 카피 또는 최대 성능이 필요하신가요? → ffmpeg-sys-next (unsafe 코드 필요)
- FFmpeg 라이브러리를 설치할 수 없나요? → ffmpeg-sidecar (프로세스 기반, stdin/stdout만 가능, 커스텀 I/O 불가)
- AI/CV/ASR을 위해 메모리에 디코딩된 프레임/오디오가 필요하신가요? → ez-ffmpeg
frame_export(FrameExtractor→ 패킹된 RGB,SampleExtractor::for_whisper→ 16kHz 모노 f32; 기능 플래그 없음; 실험적, 0.14) — frame_io.md 참조 - Rust에서 렌더링된 프레임으로 비디오를 생성/푸시해야 하나요? → ez-ffmpeg
VideoWriter(프레임 푸시를 인코딩/먹싱/스트리밍으로, 디먹서 불필요; 실험적, 0.14) — frame_io.md 참조 - WebCodecs 디코더, RTP/SRT 패킷타이저, 또는 수제 fMP4 세그멘터에 인코더에서 직접 공급해야 하나요? → ez-ffmpeg
packet_sink(PacketSink, 엄격한 H.264 전용/AAC 계층, 컨테이너 불필요; 기능 플래그 없음; 실험적, 0.15) — packet_sink.md 참조 - 기존 ffmpeg CLI 명령을 실행하거나 자동 변환해야 하나요? → ez-ffmpeg
cli기능 (from_cli_args/emit_rust_code, 좁은 골든 테스트 하위 집합 — 6가지 검증된 형태; 0.15) — cli_compat.md 참조; 해당 하위 집합을 벗어난 항목은 여전히 수동 cli_migration.md 테이블이 필요
참고: FrameFilter(커스텀 Rust 프레임 처리)는 커스텀 I/O 콜백(커스텀 데이터 소스/싱크)과 별개입니다. ez-ffmpeg는 둘 다 지원합니다.
빠른 시작
Rust FFmpeg를 처음 사용하시나요? 5분 설정을 위해 quick_start.md를 확인하세요.
라이브러리 참조
- ez-ffmpeg - 고수준 API (동기 및 비동기)
- ffmpeg-next - 고급 제어를 위한 중간 수준 API
- ffmpeg-sys-next - 저수준 불안전 FFI
- ffmpeg-sidecar - CLI 래퍼
버전 호환성
| 라이브러리 | 버전 | FFmpeg | Rust MSRV |
|---|---|---|---|
| ez-ffmpeg | 0.18.0 | 7.1–8.x | 1.80+ (wgpu: 1.85+) |
| ffmpeg-next | 8.1.0 | 7.0–8.x | 명시되지 않음 |
| ffmpeg-sys-next | 8.1.0 | 7.0–8.x | 명시되지 않음 |
| ffmpeg-sidecar | 2.5.2 | 모든 버전 | 1.79+ |
출처: crates.io
FFmpeg 7 vs 8: 위의 현재 크레이트 버전으로 네 라이브러리 모두 두 메이저 버전에 대해 빌드됩니다 — 크레이트 메이저 대 시스템 메이저 일치 필요 없음. 주의: ez-ffmpeg와 함께 ffmpeg-next를 가져올 때는 8.1.0으로 유지하세요 — 7.1.0이 섞이면 links = "ffmpeg" 키를 통해 충돌합니다. Bindgen 메커니즘, 레거시 7.1 고정 이유 및 rust-ffmpeg #246 이력은 installation.md를 참조하세요.
설치 문제: installation.md — Windows vcpkg 정적 링크 unresolved external symbol 수정 사항 포함 (앱의 build.rs에 추가 시스템 라이브러리; VCPKG_ROOT는 build.rs에서 std::env::set_var가 아닌 셸에서 설정해야 함)
Claude를 위한 지침
이 스킬이 활성화되면 다음 워크플로를 따르세요:
구현 작업의 경우:
- 작업 식별 — 확인: 비디오/오디오/스트리밍/검사? 단순 또는 복잡?
- 라이브러리 선택 — 레이어 3 의사 결정 로직 적용. 어떤 라이브러리와 그 이유를 한 문장으로 명시
- 참조 로드 — 레이어 2 시나리오 탐지를 따라 올바른 참조 파일 로드
- 코드 생성 — 프로덕션 준비: 적절한 오류 처리, ...
[번역을 위해 생략됨]