Communitygithub.com

Rust FFmpeg

Rust FFmpeg 안내서: 비디오/오디오 작업을 위한 라이브러리 선택, 코드 생성, 문제 해결을 지원합니다.

Rust FFmpeg란 무엇인가요?

이 스킬은 Rust에서 FFmpeg 기능을 구현하기 위한 종합 가이드입니다. ez-ffmpeg, ffmpeg-next, ffmpeg-sys-next, ffmpeg-sidecar 네 가지 주요 라이브러리의 사용 시나리오와 의사 결정 로직을 제공하며, '라이브러리 통합' 방식과 '바이너리 실행' 방식 중 상황에 맞게 선택할 수 있습니다. 비디오 트랜스코딩, 오디오 추출, 썸네일 생성, 실시간 스트리밍(RTMP/HLS), GPU 가속(NVENC/VAAPI/QSV), wgpu/WGSL 셰이더, 자막 하드코딩, 음량 측정(EBU R128/LUFS), 프레임 단위 제어, 커스텀 I/O, 메모리 내 프레임 처리(FrameExtractor/VideoWriter), CLI 명령어 자동 변환(from_cli_args) 등 다양한 시나리오를 다룹니다. 또한 각 라이브러리의 FFmpeg 버전 호환성과 Rust MSRV 정보를 포함하여 안정적인 개발 환경을 보장합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/YeautyYE/skill-rust-ffmpeg/tree/HEAD/plugin/skills/rust-ffmpeg

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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-sidecarFFmpeg 설치 불가능❌ 아니요안전프로세스 오버헤드, 커스텀 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를 지원합니다. 아래 제약 조건에 따라 선택하세요.

  1. async/await가 필요하신가요? → ez-ffmpeg (네이티브 비동기를 지원하는 유일한 라이브러리)
  2. 커스텀 Rust 프레임 처리가 필요하신가요? → ez-ffmpeg FrameFilter (안전하고 간단한 API)
  3. 커스텀 GPU 셰이더(WGSL)가 필요하신가요? → ez-ffmpeg wgpu 기능 (WgpuFrameFilter, 헤드리스, 디스플레이 서버 불필요) — 먼저 내장 wgpu_filter::effects 카탈로그를 확인하세요 (13가지 타입화된 효과, 0.13+); 네이티브 하드웨어 필터(scale_cuda/scale_vaapi/libplacebo)의 경우 get_gpu_filter_backends()로 탐색
  4. libass 없이 자막을 하드코딩해야 하나요? → ez-ffmpeg subtitle 기능 (SubtitleFilter, 순수 Rust ASS/SRT 렌더러, --enable-libass 필요 없음)
  5. 타입화된 탐지/측정(블랙/무음/씬/크롭/EBU R128)이 필요하신가요? → ez-ffmpeg analysis 모듈 (Analysis 단일 실행 또는 MetadataEventFilter 스트리밍 — 기능 플래그 없음)
  6. 단일 실행 썸네일 / 스프라이트 시트 / GIF / HLS ABR 래더가 필요하신가요? → ez-ffmpeg recipes 모듈 (기능 플래그 없음)
  7. 프레임 수준의 코덱 제어가 필요하신가요? → ffmpeg-next (코덱 내부용)
  8. 메모리로부터의 커스텀 I/O가 필요하신가요? → ez-ffmpeg (읽기/쓰기/찾기 콜백), 또는 ffmpeg-next 안전한 스트림 I/O (input_from_stream/output_to_stream, 모든 Read/Write/Seek); ffmpeg-sys-next는 가장 낮은 수준의 제어용
  9. 제로 카피 또는 최대 성능이 필요하신가요? → ffmpeg-sys-next (unsafe 코드 필요)
  10. FFmpeg 라이브러리를 설치할 수 없나요? → ffmpeg-sidecar (프로세스 기반, stdin/stdout만 가능, 커스텀 I/O 불가)
  11. AI/CV/ASR을 위해 메모리에 디코딩된 프레임/오디오가 필요하신가요? → ez-ffmpeg frame_export (FrameExtractor → 패킹된 RGB, SampleExtractor::for_whisper → 16kHz 모노 f32; 기능 플래그 없음; 실험적, 0.14) — frame_io.md 참조
  12. Rust에서 렌더링된 프레임으로 비디오를 생성/푸시해야 하나요? → ez-ffmpeg VideoWriter (프레임 푸시를 인코딩/먹싱/스트리밍으로, 디먹서 불필요; 실험적, 0.14) — frame_io.md 참조
  13. WebCodecs 디코더, RTP/SRT 패킷타이저, 또는 수제 fMP4 세그멘터에 인코더에서 직접 공급해야 하나요? → ez-ffmpeg packet_sink (PacketSink, 엄격한 H.264 전용/AAC 계층, 컨테이너 불필요; 기능 플래그 없음; 실험적, 0.15) — packet_sink.md 참조
  14. 기존 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를 확인하세요.

라이브러리 참조

버전 호환성

라이브러리버전FFmpegRust MSRV
ez-ffmpeg0.18.07.1–8.x1.80+ (wgpu: 1.85+)
ffmpeg-next8.1.07.0–8.x명시되지 않음
ffmpeg-sys-next8.1.07.0–8.x명시되지 않음
ffmpeg-sidecar2.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를 위한 지침

이 스킬이 활성화되면 다음 워크플로를 따르세요:

구현 작업의 경우:

  1. 작업 식별 — 확인: 비디오/오디오/스트리밍/검사? 단순 또는 복잡?
  2. 라이브러리 선택 — 레이어 3 의사 결정 로직 적용. 어떤 라이브러리와 그 이유를 한 문장으로 명시
  3. 참조 로드 — 레이어 2 시나리오 탐지를 따라 올바른 참조 파일 로드
  4. 코드 생성 — 프로덕션 준비: 적절한 오류 처리, ...

[번역을 위해 생략됨]

관련 스킬