Rust FFmpeg
Guía para implementar funcionalidades de FFmpeg en Rust: selección de librerías, generación de código y resolución de problemas.
Marco de Selección
| Librería | Cuándo Usar | Async | Seguridad | Compromiso |
|---|---|---|---|---|
| ez-ffmpeg | Tareas generales, migración CLI, servidor RTMP, filtros GPU personalizados en Rust + WGSL, renderizado nativo de subtítulos, detección/medición, recetas rápidas, I/O personalizado, exportación de fotogramas/muestras en memoria + push de fotogramas (VideoWriter), progreso tipado por salida | ✅ Sí | Segura | Requiere librerías FFmpeg |
| ffmpeg-next | Control a nivel de frame, internos de codec, I/O de stream segura (cualquier Read/Write/Seek) | ❌ No | Segura | Más código boilerplate |
| ffmpeg-sys-next | Cero-copia, I/O de memoria personalizada, máximo rendimiento | ❌ No | Insegura | Gestión manual de memoria |
| ffmpeg-sidecar | Cuando no se puede instalar FFmpeg | ❌ No | Segura | Sobrecarga de proceso, sin I/O personalizado |
Lógica de Decisión
Capa 1: Método de Integración
Por defecto: Integración como Librería (ez-ffmpeg/ffmpeg-next/ffmpeg-sys-next)
- Mejor rendimiento, API type-safe, acceso directo a frames
Alternativa: Enfoque Binario (ffmpeg-sidecar) - considerar cuando:
- No se pueden instalar las librerías de desarrollo de FFmpeg
- Entorno CI/CD restringido sin acceso de administrador
- Procesamiento por lotes puro por CLI (sin necesidades en tiempo real)
Si hay restricciones de instalación → Cargar ffmpeg_sidecar.md
Capa 2: Detección de Escenario
| El Usuario Menciona | Cargar Referencia |
|---|---|
| "convertir formato", "remux", "recortar", "redimensionar", "crop", "simple" | video_transcoding.md |
| "extraer audio", "solo audio", "pista de audio", "extraer mp3", "loudnorm", "normalizar audio", "volumen" | audio_extraction.md |
| "miniatura", "primer fotograma", "miniatura rápida", "skip_frame", "nokey", "solo keyframes", "múltiples salidas", "concat", "marca de agua", "pipeline", "grafo de filtros" | pipelines_multi_output.md — para una miniatura rápida prefiere recipes::thumbnail en image_sequences.md; para la ruta más rápida solo con keyframes (skip_frame=nokey, salta al siguiente keyframe) ver ez_ffmpeg/video.md |
| "tiempo real", "RTMP", "HLS", "en vivo", "stream", "captura", "webcam", "buffer", "contrapresión", "jitter buffer", "jitter de red", "escalera ABR", "escalera HLS", "tasa de bits adaptativa", "lista de reproducción maestra", "empaquetado VOD" | streaming_rtmp_hls.md |
| "GPU", "NVENC", "VideoToolbox", "hardware", "VAAPI", "QSV", "wgpu", "WGSL", "shader personalizado", "filtro GPU", "compute shader", "libplacebo", "filtro de belleza", "chroma key", "pantalla verde" | hardware_acceleration.md |
| "lote", "múltiples archivos", "volumen", "paralelo" | batch_processing.md |
| "subtítulos", "srt", "subtítulos", "quemar subs", "quemado", "hardsub", "ass", "vtt", "subtítulo nativo", "sin libass", "no libass" | subtitles.md |
| "AV1", "AVIF", "HDR", "10 bits", "códec moderno", "HDR a SDR", "mapeo de tonos", "tonemap", "colores lavados", "PQ", "HLG" | modern_codecs.md |
| "depurar", "ffprobe", "inspeccionar", "metadatos", "error", "solucionar problemas", "probe", "duración", "resolución", "corrupto", "integridad" | debugging.md |
| "detectar fotogramas negros", "detección de silencio", "detección de escenas", "cambio de escena", "cropdetect", "EBU R128", "LUFS", "medir sonoridad", "pico real", "análisis de contenido", "QC", "blackdetect", "silencedetect" | detection_analysis.md (API tipada analysis) |
| "filtro", "efecto", "escalar", "crop", "superponer", "marca de agua", "desenfoque", "enfoque", "color", "brillo", "rotar", "voltear", "atenuar", "velocidad", "cámara lenta" | filters_effects.md |
| "secuencia de imágenes", "extracción de fotogramas", "video a imágenes", "imágenes a video", "timelapse", "fotograma a fotograma", "sprite sheet", "storyboard", "hoja de contactos", "cuadrícula de miniaturas" | image_sequences.md |
"receta rápida", "módulo recipes", "miniatura rápida", "receta de miniatura", "receta de sprite sheet", "receta de gif", "receta de escalera HLS" (ez-ffmpeg recipes, sin feature flag) | image_sequences.md (miniatura/sprite), gif_creation.md (gif), streaming_rtmp_hls.md (escalera HLS) |
| "prueba", "validar", "verificar", "archivo golden", "checksum", "generar video de prueba", "testsrc" | testing.md |
| "servidor web", "API", "S3", "trabajo asíncrono", "integración", "trazado", "logging", "log callback", "av_log", "redirección de log" | integration.md |
| "gif", "gif animado", "video a gif", "gif desde video", "bucle gif", "paleta gif" | gif_creation.md |
| "metadatos", "capítulo", "etiqueta", "información del medio", "título", "artista", "álbum", "marcador de capítulo" | metadata_chapters.md |
| "captura de pantalla", "webcam", "captura de cámara", "grabar pantalla", "avfoundation", "directshow", "v4l2", "captura de dispositivo" | capture.md |
| "AVPacket", "AVFrame", "keyframe", "GOP", "NALU", "bitstream", "EAGAIN", "bucle de decodificación", "memoria", "packet" | ffmpeg_next.md + ffmpeg_sys_next.md |
| "avformat_find_stream_info", "AVSEEK_SIZE", "AVFormatContext", "AVCodecID", "API C pura", "FFI" | ffmpeg_sys_next.md + custom_io.md |
| "io personalizado", "callback de lectura", "callback de escritura", "StreamIo", "entrada/salida en memoria", "fuente Read/Write/Seek" | APIs seguras: advanced.md (callbacks de ez-ffmpeg) o ffmpeg_next.md (StreamIo) |
| "AVIOContext", "contexto io", "callback io puro", "io personalizado cero-copia" | custom_io.md (FFI insegura) |
| "extraer fotogramas a memoria", "decodificar a RGB", "fotogramas para IA/ML", "fotograma a tensor", "exportación de fotogramas", "video a fotogramas para un modelo", "FrameExtractor", "whisper PCM", "audio a f32", "SampleExtractor", "ingesta ASR", "N fotogramas uniformes" | frame_io.md (experimental, ez-ffmpeg 0.14) |
| "VideoWriter", "push de fotogramas", "generar video desde fotogramas", "video procedural", "renderizar fotogramas a video", "mp4 en memoria", "codificar desde memoria", "fotogramas a video" | frame_io.md (experimental, ez-ffmpeg 0.14) |
| "WHIP", "salida WebRTC", "salida SRT", "sonda de capacidad", "is_muxer_available", "protocolo de salida disponible", "fMP4 HLS", "segmentos mp4 fragmentados" | streaming.md (WHIP/SRT/capacidades) + streaming_rtmp_hls.md (escalera fMP4) |
| "exportación de paquetes codificados", "packet sink", "PacketSink", "webcodecs", "EncodedVideoChunk", "EncodedAudioChunk", "unidades de acceso h.264", "tramas aac", "avcC", "AudioSpecificConfig", "paquetizador rtp", "segmentador fmp4", "fallo de trabajo", "on_job_failed", "JobFailureSummary" | packet_sink.md (experimental, ez-ffmpeg 0.15; resúmenes de fallo de trabajo 0.16) |
| "progreso", "barra de progreso", "porcentaje completado", "ETA", "qué tan avanzado", "velocidad de codificación", "progress_handle", "ProgressHandle", "instantánea de progreso" | advanced.md; conteo por archivo en lotes: batch_processing.md |
| "codificador por stream", "códec diferente por stream", "StreamMap", "-c:v:0", "opciones de stream indexadas", "opciones de códec por stream" | video.md (ez-ffmpeg 0.16) |
| "ejecutar comando ffmpeg en rust", "from_cli_args", "emit_rust_code", "traducir comando ffmpeg", "cli feature", "cli-compat", "forma verificada" | cli_compat.md (cli feature); mapeo manual: cli_migration.md |
| "compatibilidad de versiones", "FFmpeg 7 vs 8", "error de enlace", "falla de compilación", "links = ffmpeg", "instalar", "vcpkg" | installation.md |
| "qué librería", "comparar", "vs", "migrar a", "portar a", "convertir a", "cambiar desde", "reescribir usando", "viabilidad", "debería usar", "mejor librería", "evaluar", "revisar código FFmpeg", "puede esto funcionar con" | library_selection.md |
Varias filas pueden coincidir con una solicitud — carga todas las referencias aplicables, luego sigue primero el destino de la fila más específica.
Capa 3: Selección de Librería
Migración CLI: Tanto ez-ffmpeg como ffmpeg-sidecar soportan APIs al estilo CLI. Elige según las restricciones a continuación.
- ez-ffmpeg: Guía de Migración CLI — integración como librería, rendimiento nativo
- ffmpeg-sidecar: Migración CLI a Rust — envoltura de proceso, no necesita librerías FFmpeg
- ¿Necesitas async/await? → ez-ffmpeg (única librería con async nativo)
- ¿Necesitas procesamiento de fotogramas personalizado en Rust? → ez-ffmpeg FrameFilter (API segura y simple)
- ¿Necesitas shaders GPU personalizados (WGSL)? → ez-ffmpeg feature
wgpu(WgpuFrameFilter, headless, sin servidor de visualización) — revisa primero el catálogo integradowgpu_filter::effects(13 efectos tipados, 0.13+); para filtros hardware nativos (scale_cuda/scale_vaapi/libplacebo) sondea conget_gpu_filter_backends() - ¿Necesitas quemar subtítulos sin libass? → ez-ffmpeg feature
subtitle(SubtitleFilter, renderizador ASS/SRT puro en Rust, sin--enable-libass) - ¿Necesitas detección/medición tipada (negro/silencio/escena/crop/EBU R128)? → módulo
analysisde ez-ffmpeg (Analysisde un solo uso oMetadataEventFilteren streaming — sin feature flag) - ¿Necesitas una miniatura/hoja de sprites/GIF/escalera ABR HLS de un solo uso? → módulo
recipesde ez-ffmpeg (sin feature flag) - ¿Necesitas control a nivel de frame del códec? → ffmpeg-next para internos del códec
- ¿Necesitas I/O personalizado desde memoria? → ez-ffmpeg (callbacks de lectura/escritura/búsqueda), o ffmpeg-next seguro I/O de stream (
input_from_stream/output_to_stream, cualquierRead/Write/Seek); ffmpeg-sys-next para el control más bajo - ¿Necesitas cero-copia o máximo rendimiento? → ffmpeg-sys-next (requiere código unsafe)
- ¿No puedes instalar las librerías de FFmpeg? → ffmpeg-sidecar (basado en proceso, solo stdin/stdout, sin I/O personalizado)
- ¿Necesitas fotogramas/audio decodificados en memoria para IA/CV/ASR? → ez-ffmpeg
frame_export(FrameExtractor→ RGB empaquetado,SampleExtractor::for_whisper→ f32 mono 16 kHz; sin feature flag; experimental, 0.14) — ver frame_io.md - ¿Necesitas generar/enviar video desde fotogramas renderizados en Rust? → ez-ffmpeg
VideoWriter(push de fotogramas a codificación/multiplexación/streaming, sin demuxer; experimental, 0.14) — ver frame_io.md - ¿Necesitas alimentar un decodificador WebCodecs, paquetizador RTP/SRT o segmentador fMP4 hecho a medida directamente desde el codificador? → ez-ffmpeg
packet_sink(PacketSink, nivel estricto solo H.264/AAC, sin contenedor; sin feature flag; experimental, 0.15) — ver packet_sink.md - ¿Necesitas ejecutar o traducir automáticamente un comando CLI de ffmpeg existente? → ez-ffmpeg feature
cli(from_cli_args/emit_rust_code, subconjunto reducido probado con golden — 6 formas verificadas; 0.15) — ver cli_compat.md; cualquier cosa fuera de ese subconjunto aún necesita las tablas manuales de cli_migration.md
Nota: FrameFilter (procesamiento personalizado de fotogramas en Rust) es independiente de los callbacks de I/O personalizados (fuentes/sumideros de datos personalizados). ez-ffmpeg soporta ambos.
Inicio Rápido
¿Nuevo en Rust FFmpeg? Consulta quick_start.md para una configuración en 5 minutos.
Referencias de Librerías
- ez-ffmpeg - API de alto nivel (síncrona y asíncrona)
- ffmpeg-next - API de nivel medio para control avanzado
- ffmpeg-sys-next - FFI insegura de bajo nivel
- ffmpeg-sidecar - Envoltura CLI
Compatibilidad de Versiones
| Librería | Versión | 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 | no especificada |
| ffmpeg-sys-next | 8.1.0 | 7.0–8.x | no especificada |
| ffmpeg-sidecar | 2.5.2 | Cualquiera | 1.79+ |
Fuente: crates.io
FFmpeg 7 vs 8: las cuatro librerías compilan contra ambas versiones principales con las versiones actuales de crate indicadas arriba — no es necesario hacer coincidir la versión principal del crate con la versión principal del sistema. Precaución: al usar ffmpeg-next junto con ez-ffmpeg, mantenlo en 8.1.0 — una versión 7.1.0 mezclada colisiona a través de la clave links = "ffmpeg". La mecánica de bindgen, la razón de fijar 7.1 heredada y el historial de rust-ffmpeg #246: ver installation.md.
Problemas de Instalación: installation.md — incluye la solución para el enlace estático de Windows con vcpkg (unresolved external symbol) (librerías del sistema adicionales en el build.rs de tu app; VCPKG_ROOT debe configurarse en el shell, no mediante std::env::set_var en build.rs)
Guías para Claude
Cuando este skill se active, sigue este flujo de trabajo:
Para tareas de implementación:
- Identificar la tarea — Determinar: ¿video/audio/streaming/inspección? ¿Simple o compleja?
- Seleccionar librería — Aplicar la lógica de decisión de la Capa 3. Indicar qué librería y por qué en una oración
- Cargar referencias — Seguir la detección de escenarios de la Capa 2 para cargar los archivos de referencia correctos
- Generar código — Listo para producción: manejo adecuado de errores...