Rust FFmpeg
Guia para implementar funcionalidades do FFmpeg em Rust: seleção de bibliotecas, geração de código e solução de problemas.
Quadro de Seleção
| Biblioteca | Quando Usar | Async | Segurança | Trade-off |
|---|---|---|---|---|
| ez-ffmpeg | Tarefas gerais, migração de CLI, servidor RTMP, filtros GPU Rust + WGSL personalizados, burn-in de legendas nativo, detecção/medição, receitas one-shot, I/O personalizado, exportação de frames/amostras em memória + push de frames (VideoWriter), progresso tipado por saída | ✅ Sim | Seguro | Requer bibliotecas FFmpeg instaladas |
| ffmpeg-next | Controle em nível de frame, internals de codec, I/O seguro de stream (qualquer Read/Write/Seek) | ❌ Não | Seguro | Mais código boilerplate |
| ffmpeg-sys-next | Zero-copy, I/O de memória personalizado, máximo desempenho | ❌ Não | Inseguro | Gerenciamento de memória manual |
| ffmpeg-sidecar | Quando não é possível instalar o FFmpeg | ❌ Não | Seguro | Overhead de processo, sem I/O personalizado |
Lógica de Decisão
Camada 1: Método de Integração
Padrão: Integração de Biblioteca (ez-ffmpeg/ffmpeg-next/ffmpeg-sys-next)
- Melhor desempenho, API type-safe, acesso direto a frames
Alternativa: Abordagem Binária (ffmpeg-sidecar) - considere quando:
- Não é possível instalar as bibliotecas de desenvolvimento do FFmpeg
- Ambiente CI/CD restrito sem acesso de administrador
- Processamento em lote puro via CLI (sem necessidades em tempo real)
Se a instalação for restrita → Carregue ffmpeg_sidecar.md
Camada 2: Detecção de Cenário
| O Usuário Menciona | Carregue a Referência |
|---|---|
| "converter formato", "remux", "cortar", "redimensionar", "crop", "simples" | video_transcoding.md |
| "extrair áudio", "somente áudio", "faixa de áudio", "extrair mp3", "loudnorm", "normalizar áudio", "volume" | audio_extraction.md |
| "miniatura", "primeiro frame", "miniatura rápida", "skip_frame", "nokey", "somente keyframe", "multi-saída", "concat", "marca d'água", "pipeline", "filtro gráfico" | pipelines_multi_output.md — para uma miniatura única, prefira recipes::thumbnail em image_sequences.md; para o caminho mais rápido (somente keyframe, skip_frame=nokey, encaixa no próximo keyframe) veja ez_ffmpeg/video.md |
| "tempo real", "RTMP", "HLS", "ao vivo", "stream", "captura", "webcam", "buffer", "backpressure", "jitter buffer", "jitter de rede", "escada ABR", "escada HLS", "taxa de bits adaptativa", "playlist mestre", "empacotamento VOD" | streaming_rtmp_hls.md |
| "GPU", "NVENC", "VideoToolbox", "hardware", "VAAPI", "QSV", "wgpu", "WGSL", "shader personalizado", "filtro GPU", "compute shader", "libplacebo", "filtro de beleza", "chroma key", "tela verde" | hardware_acceleration.md |
| "lote", "vários arquivos", "múltiplos", "paralelo" | batch_processing.md |
| "legendas", "srt", "legendas", "queimar legendas", "burn-in", "hardsub", "ass", "vtt", "legenda nativa", "sem libass", "sem libass" | subtitles.md |
| "AV1", "AVIF", "HDR", "10-bit", "codec moderno", "HDR para SDR", "mapeamento de tom", "tonemap", "cores lavadas", "PQ", "HLG" | modern_codecs.md |
| "debug", "ffprobe", "inspecionar", "metadados", "erro", "troubleshoot", "probe", "duração", "resolução", "corrompido", "integridade" | debugging.md |
| "detectar frames pretos", "detectar silêncio", "detectar cena", "mudança de cena", "cropdetect", "EBU R128", "LUFS", "medir loudness", "pico verdadeiro", "análise de conteúdo", "QC", "blackdetect", "silencedetect" | detection_analysis.md (API analysis tipada) |
| "filtro", "efeito", "escala", "crop", "overlay", "marca d'água", "desfoque", "nitidez", "cor", "brilho", "rotacionar", "inverter", "fade", "velocidade", "câmera lenta" | filters_effects.md |
| "sequência de imagens", "extração de frames", "vídeo para imagens", "imagens para vídeo", "timelapse", "frame a frame", "sprite sheet", "storyboard", "contato", "grade de miniaturas" | image_sequences.md |
"receita one-shot", "módulo recipes", "miniatura rápida", "receita de miniatura", "receita de sprite sheet", "receita de gif", "receita de escada HLS" (ez-ffmpeg recipes, sem feature flag) | image_sequences.md (miniatura/sprite), gif_creation.md (gif), streaming_rtmp_hls.md (escada HLS) |
| "teste", "validar", "verificar", "golden file", "checksum", "gerar vídeo de teste", "testsrc" | testing.md |
| "servidor web", "API", "S3", "tarefa assíncrona", "integração", "tracing", "logging", "callback de log", "av_log", "redirecionamento de log" | integration.md |
| "gif", "gif animado", "vídeo para gif", "gif a partir de vídeo", "loop de gif", "paleta de gif" | gif_creation.md |
| "metadados", "capítulo", "tag", "informações de mídia", "título", "artista", "álbum", "marcador de capítulo" | metadata_chapters.md |
| "captura de tela", "webcam", "captura de câmera", "gravar tela", "avfoundation", "directshow", "v4l2", "captura de dispositivo" | capture.md |
| "AVPacket", "AVFrame", "keyframe", "GOP", "NALU", "bitstream", "EAGAIN", "loop de decodificação", "memória", "pacote" | ffmpeg_next.md + ffmpeg_sys_next.md |
| "avformat_find_stream_info", "AVSEEK_SIZE", "AVFormatContext", "AVCodecID", "API C raw", "FFI" | ffmpeg_sys_next.md + custom_io.md |
| "io personalizado", "callback de leitura", "callback de escrita", "StreamIo", "entrada/saída em memória", "fonte Read/Write/Seek" | APIs seguras: advanced.md (callbacks do ez-ffmpeg) ou ffmpeg_next.md (StreamIo) |
| "AVIOContext", "contexto de io", "callback de io raw", "io personalizado zero-copy" | custom_io.md (FFI inseguro) |
| "extrair frames para memória", "decodificar para RGB", "frames para IA/ML", "frame para tensor", "exportar frame", "vídeo para frames para um modelo", "FrameExtractor", "whisper PCM", "áudio para f32", "SampleExtractor", "ingestão ASR", "N frames uniformes" | frame_io.md (experimental, ez-ffmpeg 0.14) |
| "VideoWriter", "enviar frames", "gerar vídeo a partir de frames", "vídeo procedural", "renderizar frames para vídeo", "mp4 em memória", "codificar a partir da memória", "frames para vídeo" | frame_io.md (experimental, ez-ffmpeg 0.14) |
| "WHIP", "saída WebRTC", "saída SRT", "verificação de capacidade", "is_muxer_available", "protocolo de saída disponível", "fMP4 HLS", "segmentos mp4 fragmentados" | streaming.md (WHIP/SRT/capacidades) + streaming_rtmp_hls.md (escada fMP4) |
| "exportação de pacotes codificados", "packet sink", "PacketSink", "webcodecs", "EncodedVideoChunk", "EncodedAudioChunk", "unidades de acesso h.264", "frames aac", "avcC", "AudioSpecificConfig", "rtp packetizer", "segmentador fmp4", "falha de job", "on_job_failed", "JobFailureSummary" | packet_sink.md (experimental, ez-ffmpeg 0.15; sumário de falhas 0.16) |
| "progresso", "barra de progresso", "porcentagem concluída", "ETA", "quão avançado", "velocidade de codificação", "progress_handle", "ProgressHandle", "instantâneo de progresso" | advanced.md; contagem por arquivo em lote: batch_processing.md |
| "codificador por stream", "codec diferente por stream", "StreamMap", "-c:v:0", "opções de stream indexadas", "opções de codec por stream" | video.md (ez-ffmpeg 0.16) |
| "executar comando ffmpeg em rust", "from_cli_args", "emit_rust_code", "traduzir comando ffmpeg", "feature cli", "cli-compat", "forma verificada" | cli_compat.md (feature cli); mapeamento manual: cli_migration.md |
| "compatibilidade de versão", "FFmpeg 7 vs 8", "erro de linking", "build falha", "links = ffmpeg", "instalar", "vcpkg" | installation.md |
| "qual biblioteca", "comparar", "vs", "migrar para", "portar para", "converter para", "mudar de", "reescrever usando", "viabilidade", "devo usar", "melhor biblioteca", "avaliar", "revisar código FFmpeg", "isso funciona com" | library_selection.md |
Várias linhas podem corresponder a uma solicitação — carregue todas as referências aplicáveis e siga o alvo da linha mais específica primeiro.
Camada 3: Seleção de Biblioteca
Migração CLI: Tanto ez-ffmpeg quanto ffmpeg-sidecar suportam APIs no estilo CLI. Escolha com base nas restrições abaixo.
- ez-ffmpeg: Guia de Migração CLI — integração de biblioteca, desempenho nativo
- ffmpeg-sidecar: Migração CLI para Rust — wrapper de processo, sem necessidade de bibliotecas FFmpeg
- Precisa de async/await? → ez-ffmpeg (única biblioteca com async nativo)
- Precisa de processamento de frames Rust personalizado? → ez-ffmpeg FrameFilter (API segura e simples)
- Precisa de shaders GPU personalizados (WGSL)? → recurso
wgpudo ez-ffmpeg (WgpuFrameFilter, headless, sem servidor de exibição) — verifique primeiro o catálogowgpu_filter::effectsintegrado (13 efeitos tipados, 0.13+); para filtros de hardware nativos (scale_cuda/scale_vaapi/libplacebo) useget_gpu_filter_backends() - Precisa queimar legendas sem libass? → recurso
subtitledo ez-ffmpeg (SubtitleFilter, renderizador ASS/SRT puro em Rust, sem--enable-libass) - Precisa de detecção/medição tipada (preto/silêncio/cena/crop/EBU R128)? → módulo
analysisdo ez-ffmpeg (Analysisone-shot ouMetadataEventFilterem stream — sem feature flag) - Precisa de uma miniatura / sprite sheet / GIF / escada ABR HLS one-shot? → módulo
recipesdo ez-ffmpeg (sem feature flag) - Precisa de controle de codec em nível de frame? → ffmpeg-next para internals de codec
- Precisa de I/O personalizado a partir da memória? → ez-ffmpeg (callbacks read/write/seek), ou ffmpeg-next seguro I/O de stream (
input_from_stream/output_to_stream, qualquerRead/Write/Seek); ffmpeg-sys-next para o controle mais baixo nível - Precisa de zero-copy ou máximo desempenho? → ffmpeg-sys-next (requer código inseguro)
- Não pode instalar bibliotecas FFmpeg? → ffmpeg-sidecar (baseado em processo, stdin/stdout apenas, sem I/O personalizado)
- Precisa de frames/áudio decodificados em memória para IA/CV/ASR? → recurso
frame_exportdo ez-ffmpeg (FrameExtractor→ RGB empacotado,SampleExtractor::for_whisper→ 16 kHz mono f32; sem feature flag; experimental, 0.14) — veja frame_io.md - Precisa gerar/enviar vídeo a partir de frames renderizados em Rust? →
VideoWriterdo ez-ffmpeg (push de frames para encode/mux/stream, sem demuxer; experimental, 0.14) — veja frame_io.md - Precisa alimentar um decodificador WebCodecs, um packetizador RTP/SRT ou um segmentador fMP4 artesanal diretamente do codificador? →
packet_sinkdo ez-ffmpeg (PacketSink, tier estrito de H.264-only/AAC, sem contêiner; sem feature flag; experimental, 0.15) — veja packet_sink.md - Precisa executar ou traduzir automaticamente um comando ffmpeg CLI existente? → recurso
clido ez-ffmpeg (from_cli_args/emit_rust_code, subconjunto estreito testado com golden — 6 formas verificadas; 0.15) — veja cli_compat.md; qualquer coisa fora desse subconjunto ainda precisa das tabelas manuais de cli_migration.md
Nota: FrameFilter (processamento de frames Rust personalizado) é separado de callbacks de I/O personalizado (fontes/coletas de dados personalizados). ez-ffmpeg suporta ambos.
Início Rápido
Novo no Rust FFmpeg? Veja quick_start.md para configuração em 5 minutos.
Referências das Bibliotecas
- ez-ffmpeg - API de alto nível (síncrona e assíncrona)
- ffmpeg-next - API de médio nível para controle avançado
- ffmpeg-sys-next - FFI inseguro de baixo nível
- ffmpeg-sidecar - Wrapper de CLI
Compatibilidade de Versões
| Biblioteca | Versão | 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 | não especificado |
| ffmpeg-sys-next | 8.1.0 | 7.0–8.x | não especificado |
| ffmpeg-sidecar | 2.5.2 | Qualquer | 1.79+ |
Fonte: crates.io
FFmpeg 7 vs 8: todas as quatro bibliotecas compilam para ambas as versões principais com as versões atuais das crates acima — não é necessário fazer correspondência entre a versão principal da crate e a versão principal do sistema. Atenção: ao usar ffmpeg-next junto com ez-ffmpeg, mantenha-o em 8.1.0 — uma versão 7.1.0 misturada colide através da chave links = "ffmpeg". A mecânica do bindgen, a lógica do pino 7.1 legado e o histórico do rust-ffmpeg #246: veja installation.md.
Problemas de Instalação: installation.md — inclui a correção do link estático do vcpkg no Windows (unresolved external symbol, bibliotecas extras do sistema no build.rs da sua aplicação; VCPKG_ROOT deve ser definido no shell, não via std::env::set_var no build.rs)
Diretrizes para Claude
Quando esta skill for ativada, siga este fluxo de trabalho:
Para tarefas de implementação:
- Identifique a tarefa — Determine: vídeo/áudio/streaming/inspeção? Simples ou complexa?
- Selecione a biblioteca — Aplique a lógica de decisão da Camada 3. Informe qual biblioteca e o motivo em uma frase
- Carregue as referências — Siga a detecção de cenário da Camada 2 para carregar os arquivos de referência corretos
- Gere o código — Pronto para produção: tratamento de erros adequado, …
[truncado para tradução]