sridhar-raj/video-craft

Video craft

Dos trabajos, un mismo estándar. Edita el material que alguien grabó, o crea una película a partir de una guía de marca y un texto. En ambos casos, el trabajo se planifica antes de renderizar, se renderiza mediante scripts exactos y se verifica con mediciones antes de que nadie sepa que está terminado.

Lo que hace que un vídeo tenga aspecto profesional, en orden:

1. Estructura. Un gancho en los primeros 3 segundos, una idea, nada que no merezca su tiempo.
2. Ritmo. Los cortes y movimientos caen sobre el habla y el ritmo; nada está muerto, nada apresura.
3. Detalles de oficio. Aire alrededor de cada corte, subtítulos que se leen bien, movimiento que desacelera hasta su posición, sonido suficientemente alto y que nunca satura.
4. Prueba. qa.py pasa y se ha revisado la hoja de contacto.

Ruta rápida

Pregunta	Haz
"Ajusta / limpia esta grabación"	transcribir → planificar_cortes → revisar EDL → renderizar → qa
"Haz un Short/Reel/TikTok con esto"	como arriba, además captions.py --style punch, render.py --preset shorts --fit crop (o blur para grabaciones de pantalla)
"Añade subtítulos"	transcribe.py → captions.py → render.py --captions (o entrega el .srt)
"Añade música"	render.py --music bed.mp3 (se atenúa automáticamente bajo el habla)
"Haz que se oiga bien / arregla el audio"	render.py --voice --denoise, objetivo según platforms.md
"Intro de marca / revelación de logotipo / golpe de efecto"	copiar films/brand-sting, rellenar la guía de marca, fotogramas → borrador → maestro → qa
"Vídeo de lanzamiento / promoción / anuncio"	copiar films/launch, escribir el texto, elegir formatos, fotogramas → borrador → maestro → qa
"Revisa este vídeo"	qa.py video.mp4 --sheet sheet.jpg [--safe]
Proyecto ya en Remotion	references/remotion.md

Requisitos

ffmpeg 6+ y Python 3.9+ para edición. Transcripción: pip install faster-whisper (o openai-whisper, o whisper.cpp). Películas: Node 18+ y Playwright (npm i -D playwright && npx playwright install chromium). Los subtítulos se queman con libass cuando ffmpeg lo tiene, si no se dibujan con Pillow (pip install pillow). Ejecuta python3 scripts/doctor.py para ver qué está instalado.

Todos los scripts aceptan --help. Trabaja en una carpeta por trabajo: work/ para archivos intermedios, out/ para entregables.

Editar material grabado

python3 scripts/transcribe.py raw.mp4 -o work/words.json            # transcripción palabra por palabra
python3 scripts/plan_cuts.py raw.mp4 --words work/words.json -o work/edl.json
python3 scripts/captions.py work/words.json --edl work/edl.json --style clean -o work/cap
python3 scripts/render.py work/edl.json -o out/final.mp4 --preset youtube \
        --captions work/cap.cues.json --music bed.mp3 --voice --zoom auto
python3 scripts/qa.py out/final.mp4 --edl work/edl.json --sheet out/sheet.jpg \
        --words work/words.json --words-check

1. Lee primero la transcripción y decide la estructura: qué se va por completo (los cortes de sección se leen limpios; muchos cortes a media frase se leen nerviosos) y cuál es el gancho. Si es necesario, añade decisiones de secciones completas a los segments del EDL manualmente.
2. plan_cuts.py elimina silencios (acortados a una respiración, no a cero), muletillas y tomas descartadas (conserva la última toma). El silencio se mide por grabación, cada borde se fija al audio real, el relleno es asimétrico (80 ms antes, 140 ms después) y nunca invade una palabra eliminada. Lee su lista: una repetición enfática puede parecer una toma descartada.
3. Haz un punto de control con la persona para cualquier cosa larga: duración antes/después, secciones cortadas, tomas eliminadas. Sus notas se convierten en ediciones del EDL.
4. render.py lo hace todo en un único grafo de ffmpeg: cortes exactos al fotograma, fundidos de 8 ms en cada corte, frecuencia de fotogramas constante, zooms, reencuadre, subtítulos, pulido de voz, música atenuada y sonoridad de dos pasos.
5. qa.py, luego mira la hoja. --words-check retranscribe el resultado y nombra cualquier palabra que un corte haya tragado.

Juicio, números y modos de fallo: references/editing.md. Audio: references/sound.md.

Crear películas (intros de marca, spots de lanzamiento, anuncios)

cp -r films/brand-sting my-film && python3 scripts/sfx.py --out my-film/sfx
# edita PARAMS en my-film/index.html (o pasa --params '{"name": "...", ...}')
node scripts/render_film.mjs my-film/index.html --stills 0.5,1.6,2.4,3.5 -o work/stills  # míralos
node scripts/render_film.mjs my-film/index.html --draft -o work/draft.mp4                 # juzga el ritmo
node scripts/render_film.mjs my-film/index.html --blur 4 -o out/intro.mp4                 # maestro
python3 scripts/qa.py out/intro.mp4 --no-gaps --sheet out/intro.sheet.jpg --safe

1. Guía de marca primero (references/brand-intro.md): el archivo oficial del logotipo, colores hex, tipografía, palabras exactas, registro, formatos, sonido y una fuente para cada número. Nunca redibujes ni recolorees un logotipo; nunca inventes afirmaciones, clientes o interfaz de producto.
2. Guión de golpes antes del código: cada golpe con su tiempo, qué se mueve, la curva de easing y el sonido. Elige un registro (premium, limpio, tecnológico, audaz, divertido) y escala toda la línea de tiempo con él.
3. Construye sobre assets/film.js: cada píxel es una función de t. Film.tween, Film.spring, Film.stagger, Film.random(seed); sin animaciones CSS, temporizadores ni Date.now. Abre el HTML en un navegador para moverlo en tiempo real.
4. Fotogramas en cada golpe, luego un borrador, luego el maestro. Arregla lo que muestran los fotogramas antes de renderizar vídeo. Los maestros renderizan ~2–5 fotogramas por segundo; los borradores son 10× más rápidos.
5. El sonido es parte de la película. scripts/sfx.py sintetiza el kit (golpe, boom, whoosh ×3, ascensor, pop, tic, campana, base); las señales están en la configuración de la película y son mezcladas y normalizadas por el renderizador. El pico del golpe cae en el fotograma de revelación.

Plantillas: films/brand-sting (revelación de logotipo de 3–7 s, cinco registros, 16:9 / 9:16 / 1:1) y films/launch (gancho de 15 s → problema → revelación → prueba → CTA, los tres formatos, 9:16 dentro del área segura de las plataformas, énfasis con *palabra*). Úsalas como punto de partida; cambia la estructura cuando el briefing lo necesite.

Doctrina (tiempos, easing por rol, escalonamiento, tamaños de letra, color, transiciones con causa, los aspectos genéricos a evitar y las pruebas que los detectan): references/motion.md.

Reglas que siempre aplican

• Recodifica cada corte. Los cortes por copia de flujo se fijan a los fotogramas clave.
• Frecuencia de fotogramas constante en todo lo entregado; H.264 + yuv420p + AAC + +faststart.
• Sonoridad por medición: -14 LUFS / ≤ -1 dBTP para web y redes, -16 para podcasts.
• Texto dentro de áreas seguras: en 9:16 nada en los 288 px superiores, 672 px inferiores ni 192 px derechos (a 1080×1920). Tipo ≥ 28 px a 1080.
• Contenido honesto: logotipos reales, números reales con fuentes, interfaz de producto real; indica si la música, la voz o el material están generados.
• Solo música con licencia. Nunca extraigas audio de vídeos o servicios de streaming.
• Terminado significa revisado: qa.py pasa, la hoja se ha revisado y cualquier cosa que no se haya podido comprobar se dice claramente.

Archivos

Ruta	Qué es
scripts/transcribe.py	words.json con tiempos de palabra (faster-whisper / whisper / whisper.cpp)
scripts/plan_cuts.py	EDL: pausas, muletillas, tomas descartadas eliminadas, con razones
scripts/captions.py	SRT, ASS con estilo y JSON de señales sobre la línea de tiempo editada
scripts/render.py	EDL → vídeo terminado (preajustes, reencuadre, subtítulos, música, sonoridad)
scripts/qa.py	formato, duración, negro, congelado, silencio, sonoridad, palabras, hoja de contacto
scripts/sfx.py	kit de sonido sintetizado
scripts/render_film.mjs	HTML de película → MP4 (borrador, maestro con desenfoque de movimiento, fotogramas, póster)
scripts/doctor.py	qué está instalado y qué falta
assets/film.js	motor de movimiento determinista + previsualización en navegador con control de avance
films/	plantillas brand-sting y launch
references/	edición, movimiento, intro de marca, sonido, plataformas, ffmpeg, remotion