kajisho5/remotion-ffmpeg-skill

¿Qué hace remotion-ffmpeg-skill?

ffmpeg-skill mide → Remotion dibuja → ffmpeg-skill verifica y entrega. Los scripts viven en scripts/ junto a este archivo; ejecútalos con python3 <directorio-del-skill>/scripts/<nombre>.py. --help en un script muestra la lista completa de banderas; references/timeline.md describe el formato de la línea de tiempo y las opciones que toma cada composición.

Este skill depende de ffmpeg-skill (se encuentra junto a este skill, en ~/.claude/skills/ffmpeg-skill o mediante FFMPEG_SKILL_DIR). Nunca ejecuta un comando ffmpeg/ffprobe por sí mismo: la medición, verificación y entrega se realizan a través de los scripts de ffmpeg-skill, por lo que sus garantías se heredan.

Banderas compartidas (cada script): --json (un objeto JSON en stdout; preferible), --dry-run (planificar, no escribir nada), --overwrite (la única forma de reemplazar una salida existente), --timeout SEGUNDOS.

Flujo de trabajo (en este orden)

1. Proyecto una vez. Sin proyecto de Remotion aún: init.py ./motion --install (copia la plantilla, ejecuta npm install; el navegador headless de Remotion se descarga en el primer renderizado). Un proyecto existente de este skill: reutilizarlo.
2. Medir. analyze.py FUENTE [--captions ARCHIVO.srt] [--beats] -o FUENTE.timeline.json. Lee el resumen y las advertencias: una fuente VFR o HDR debe corregirse con ffmpeg-skill antes de dibujar (color.py --to-sdr, una exportación de velocidad de fotogramas constante) — Remotion renderiza SDR en una cuadrícula de fotogramas fija. Nunca escribas o edites números de la línea de tiempo manualmente; en su lugar, vuelve a medir (--threshold, --min-silence para una habitación silenciosa).
3. Previsualizar fotogramas. still.py --project ./motion --comp NOMBRE --timeline TL --at 1.5 --at 6 y visualiza los PNG: colocación de subtítulos, acercamiento, colores. Barato; hazlo antes de un renderizado completo.
4. Renderizar. render.py --project ./motion --comp NOMBRE --timeline TL [--options look.json] -o SALIDA.mp4 (--fast = vista previa a mitad de tamaño, --frames 0-89 = un rango, --codec prores -o master.mov = un master). Verifica la salida contra la línea de tiempo (recuento de fotogramas, FPS, tamaño, audio) y sale con código distinto de cero si hay discrepancia.
   • Forma: dibuja en la forma en que se entregará. --aspect 9:16 para Reels / TikTok / Shorts (también 1:1, 4:5, 16:9); --fit blur (predeterminado cuando cambia la forma: contenido sobre una copia borrosa), contain (barras) o cover (recortar — verifica el sujeto en el fotograma primero). Nunca renderices 16:9 y dejes que una plantilla 9:16 lo recorte: los subtítulos pierden sus bordes. pipeline.py --platform elige la relación de aspecto de la plantilla de ffmpeg-skill por ti.
   • Fuentes: los subtítulos en japonés / chino / coreano obtienen la fuente CJK que ffmpeg-skill encuentra en la máquina automáticamente (preparada en el proyecto, sin tofu); --font-file F.ttf usa una fuente específica; la línea de informe font: indica cuál se usó, o que no se encontró ninguna.
   • Capa para aplicación de edición: --overlay --keep-graphics (Subtitulado / PeakPulse, forma de la fuente) dibuja solo los gráficos como un ProRes 4444 transparente .graphics.mov y lo compone sobre la fuente original sin modificar con ffmpeg-skill overlay.py; entrega el .mov a alguien que finalice en Premiere / Resolve / Final Cut. No es más rápido que un renderizado normal.
5. Entregar. deliver.py SALIDA.mp4 --platform youtube|reels|tiktok|shorts|x|... ejecuta la plantilla de entrega de ffmpeg-skill y su tabla check.py. Las filas de formato son seguras de corregir; las filas de juicio (duración, relación de aspecto) cambian el contenido — pregunta. Menciona las ADVERTENCIAS, no las persigas. Sin destino nombrado: omite este paso y dílo.
6. Revisar. No está terminado hasta que la respuesta nombre la hoja de contactos que escribió render.py (Look: RUTA) y diga lo que muestra. Mecánico (verificar e informar): el texto está donde se pidió, las señales aparecen en su momento, nada está cortado por el fotograma. Juicio (di lo que ves, el usuario decide): texto sobre una cara, un corte que cae mal. Sin visor de imágenes: Look: RUTA (píxeles no inspeccionados) — nunca afirmes que miraste. Sin hoja de contactos (look_error en el resultado, por ejemplo, un FFmpeg sin drawtext): mira los fotogramas de still.py y transmite la solución que nombra el error.

Los archivos de opciones se verifican antes de renderizar: una clave desconocida o un tipo incorrecto se rechazan (kind: input) en lugar de no hacer nada silenciosamente.

MCP: mcp/server.py expone las mismas herramientas (esquemas de scripts/_contract.py, contract --json los imprime).

Todo en uno: pipeline.py FUENTE --project ./motion --comp NOMBRE [--captions F] [--platform P] ejecuta 2→4→5 con las mismas comprobaciones y se detiene en el primer paso fallido.

Solicitud → script / composición

Solicitud	Ejecutar
"subtítulos animados en este video"	analyze.py --captions → render.py --comp Captioned
"cortar los silencios / jump cut / apretar esta charla" (con movimiento)	analyze.py → render.py --comp Jumpcut (subtítulos re-sincronizados si se proporcionan)
"gráficos que reaccionen al audio / golpeen en el ritmo / en cortes"	analyze.py [--beats] → render.py --comp PeakPulse (pulsos en ritmos cuando se midió la cuadrícula)
"subtítulos de karaoke / palabras se iluminan mientras se hablan"	analyze.py --words WORDS.json [--captions F.srt] → render.py --comp Karaoke (sincronización de palabras desde un motor de voz local, whisper JSON; sin SRT las señales se agrupan desde las palabras)
"lower thirds / títulos de nombres / títulos de capítulos"	render.py --comp Titled --options con lowerThirds / sceneTitles — el texto proviene del usuario; pregúntalo, nunca inventes nombres
"reel de highlights / mejores momentos"	analyze.py --highlights N [--target S] → render.py --comp Highlights (clasificación por energía de audio: candidatos, dílo)
"cortar al ritmo / montaje musical"	analyze.py --beats [--highlights N] → render.py --comp BeatMontage (audio ininterrumpido, imagen corta cada beatsPerCut ritmos medidos; cortes de escena si no hay cuadrícula confiable)
"para YouTube / Reels / TikTok ..."	pipeline.py --platform (renderiza en la relación de aspecto de la plantilla, luego entrega y verifica), o render.py --aspect + deliver.py --platform
"vertical / 9:16 / cuadrado"	render.py --aspect 9:16 (o 1:1, 4:5)
"subtítulos en japonés" / una fuente específica	nada extra para CJK (fuente automática); --font-file para una fuente elegida
"dame los gráficos como una capa separada"	render.py --overlay --keep-graphics
"cambiar color / fuente / tamaño de subtítulo / zoom"	un JSON --options (references/timeline.md), re-renderizar
varios clips ("intro + charla + outro")	analyze.py A.mp4 B.mov C.mp4 (o pipeline.py con varias entradas): ffmpeg-skill join.py normaliza y une, luego todo se mide en el archivo unido
"vista previa" / "muéstrame un fotograma"	still.py
un nuevo tipo de gráfico	agrega una composición a src/ del proyecto que lea Props de src/timeline.ts; renderiza con --comp TuId (render.py luego informa números medidos sin una expectativa incorporada)
corte simple / recorte / cambio de tamaño / sonoridad sin gráficos	no es este skill: usa ffmpeg-skill directamente
algo se rompió	doctor.py [--project DIR]

Lo que este skill decide y lo que no

• Decide (mecánico): duración de la composición, FPS y tamaño (del análisis); dónde caen los cortes (de los silencios medidos); cuándo aparecen las señales (del archivo de subtítulos); cuándo golpean los pulsos (de los picos medidos); si un renderizado coincide con su línea de tiempo.
• No decide: nombres, títulos y nombres de capítulos (los lower thirds y títulos de escena son texto del usuario — pregunta), qué palabras dice un subtítulo — el texto de las señales se dibuja exactamente como está escrito, nunca se acorta o parafrasea, ni siquiera para "hacerlo encajar" (ofrece un captionSize más pequeño); qué cuenta como un highlight; si un aspecto visual es bueno. Esas pertenecen al usuario o al agente que llama.
• Nunca inventa datos. Sin subtítulos sin un archivo de subtítulos temporizado del usuario o un motor local de texto a voz; sin cuadrícula de ritmo que --beats no haya medido.

Reglas que evitan fallos en los trabajos

• Licencia Remotion: gratuita para individuos y organizaciones con fines de lucro con hasta 3 empleados; las empresas más grandes necesitan una licencia corporativa de Remotion (https://www.remotion.dev/license). Si el usuario es claramente una empresa más grande, dílo una vez.
• Mantén los originales del usuario: las fuentes se enlazan en public/media/ del proyecto, nunca se modifican; las salidas nunca sobrescriben un archivo existente sin --overwrite.
• Subtítulos CJK: la fuente automática proviene de la detección de fuentes de ffmpeg-skill; cuando el informe dice que no se encontró ninguna fuente, instala una (Noto Sans CJK) o pasa --font-file — tofu en la hoja de contactos es un trabajo fallido. Las líneas en japonés se dividen entre frases, no dentro de palabras.
• Velocidad (medida en una máquina Linux de 2 núcleos, todos los núcleos — el valor predeterminado de render.py): aproximadamente 2.6 veces la duración del clip para 1080p30 (30 s tomó 80 s). Previsualiza con still.py y --fast antes de un renderizado completo de metraje largo; informa al usuario el tiempo esperado antes de comenzar un renderizado largo. --concurrency por encima del número de núcleos es rechazado por Remotion.
• Los paquetes Remotion en un proyecto deben tener la misma versión; la plantilla los fija. No mezcles una versión diferente de remotion.
• Un renderizado que falla la verificación es un fallo: informa las filas fallidas de --json, no lo envíes.