Automatic storyteller animate
Proporciónale un archivo de voz y un guion. Termina toda la película: temporización, diseño, renderizado, cortes, subtítulos, sonido, mezcla y control de calidad. Sin storyboard manual, sin código de escenas, sin línea de edición.
python scripts/run.py --project my-film --voice voice.mp3 --script script.md
Ese único comando ejecuta todo el pipeline y deja my-film/out/FILM.mp4, my-film/out/FILM.srt (junto a captioned.mp4), credits.md, beats.json, plan.json, beats.md, imágenes de revisión en out/qa/ y todos los archivos intermedios.
Antes de empezar — la verificación de requisitos (automática)
Cada ejecución comienza con check_requirements.py, antes que nada. Si todas las herramientas disponibles están instaladas, la producción continúa inmediatamente — no se necesita configuración. Si falta algo, se descarga/instala automáticamente, y luego la producción continúa.
Verifica, en orden:
- Python 3.8+
- Paquetes de Python — numpy, skia-python, Pillow, faster-whisper — instalados automáticamente con pip si faltan
- ffmpeg + ffprobe en el PATH — instalados automáticamente mediante
winget(Windows),brew(macOS) oapt-get(Linux) si faltan - cinematic-film junto a esta habilidad (o
CINEMATIC_SCRIPTS=<ruta a sus scripts>)
Si todo está presente: una línea — requirements: ok — y la compilación comienza. Si no se puede instalar un paquete de Python, el script imprime el comando exacto para solucionarlo y sale en lugar de iniciar una compilación fallida. Si no se encuentra cinematic-film, igual — obtienes exactamente lo que falta y qué configurar.
Qué produce (el aspecto)
Dos lenguajes visuales que alternan fijamente cada 3-10 segundos, decididos por bloque según el director:
- Board (Pizarra): una hoja de plano a sangre completa. Las palabras aparecen como tipografía de tiza dibujada a mano sobre una cuadrícula azul oscuro, con cuadros de llamada de boceto, trazos temblorosos, ventanas de código garabateado, marcas de verificación, divisores e iconos neón (dos pases de brillo + núcleo caliente) dibujados en código.
- Photo (Foto): el muro de evidencias nocturno de
cinematic-film: fotos reales de Wikimedia Commons con licencia, fijadas con sombra y chincheta, documentos de papel mecanografiados, reglas de resaltado temblorosas, iconos neón brillantes, todo acreditado encredits.md.
Los subtítulos están centrados en la parte inferior y alineados al borde inferior (6 px en 720p, escalando con la resolución), en mayúsculas, uno de nueve tintas de caramelo seleccionadas, con entrada suavizada (elevar/pop/deslizar/inclinar/desvanecer/barajar/entretejer) y salida (desvanecer/caer/elevar/encoger), halo de floración de tres pases, un barrido de gradiente arcoíris en la palabra hablada (trazo blanco de tubo neón). Un gradiente detrás de la banda mantiene la legibilidad sobre cualquier fondo. El texto refleja la voz exactamente.
Empezar de nuevo vs. reanudar
- Nuevo proyecto: dale la voz y el guion; la habilidad construye todo.
python scripts/run.py --project my-film --voice voice.mp3 --script script.md - Reanudar: volver a ejecutar sobre un proyecto que ya tiene
out/FILM.mp4(y el plan/fotos) solo vuelve a verificar con control de calidad — nada se descarga ni renderiza de nuevo. Añade--forcepara reconstruir desde cero.
Entradas
--voice: cualquier archivo de audio que ffmpeg pueda leer (mp3/wav/m4a...). Los mejores resultados provienen de una narración limpia en una sola toma. Se usa tal cual, solo se convierte a AAC estéreo de 48 kHz.--script:.md/.txt/.srt/.json. Los encabezados de Markdown se convierten en titulares de sección en pantalla; las líneas en blanco y los párrafos se dividen en oraciones, luego en fragmentos de subtítulos (<= 9 palabras / <= 64 caracteres). El texto en pantalla es el texto del archivo, palabra por palabra.script.jsoncon{"title": ..., "takes": [...]}se respeta cuando está presente.
Opciones
| Banderín | Efecto |
|---|---|
--size 1920x1080 | tamaño de renderizado (predeterminado 1920x1080) |
--crf 16 | calidad (menor = mejor; 16 película, 26 previsualización) |
| `--photos auto | existing |
| `--music auto | none |
--model tiny.en | tamaño de faster-whisper para alineación (base.en/small.en son más precisos) |
--preview | renderizar solo los bloques 0-1 a 640x360 para una vista rápida |
--skip-render | solo replanificar (sin renderizar) |
--workers WORKERS | trabajadores de renderizado + subtítulos (0 = todos los núcleos menos uno) |
--force | reconstruir incluso si ya existe un out/FILM.mp4 terminado |
Rendimiento y seguridad
- Caché de producción en
E:\Storyteller catche files(sobrescríbelo conSTORYTELLER_CACHE). Cada artefacto pesado se almacena en caché bajo un hash de contenido, por lo que volver a ejecutar o ajustar etapas posteriores solo rehace lo que cambió:
| Carpeta | Qué se almacena en caché | Clave |
|---|---|---|
whisper/ | tiempos de palabra de faster-whisper | archivo de voz + modelo + dispositivo |
commons_search/ | conjuntos de resultados de búsqueda de Commons | consulta + límite |
commons_files/ | originales descargados de Commons + archivos laterales de crédito | título de Commons |
blocks/ | bloques de estilo renderizados | escena + compases + geometría del bloque + tamaño + CRF |
silent/ | película silenciosa cosida | archivos de bloque + CRF + fps |
captioned/ | película subtitulada + SRT | video + temporización + código de subtítulos + CRF |
sfx/ | bus de efectos de sonido sintetizados | hoja de señales + build_sfx.py |
music/ | pista de banda sonora en bucle | archivo de partitura + duración de la película |
mix/ | mezcla de audio terminada | voz + señales + música + niveles + LUFS |
Los archivos se nombran <etiqueta>-<hash12>.<ext> y se ordenan por tipo (una lista sort se lee de forma natural), con un manifiesto index.jsonl de solo adición y un README.txt en la raíz. Las faltas de caché se reconstruyen automáticamente; eliminar la caché siempre es seguro. Una re-ejecución completa de etapas sin cambios es cuestión de segundos (whisper/bloques/cosido/subtítulos/sfx/mezcla todos aciertan).
- Cada bloque se renderiza por separado, luego los bloques se cosen con un filtro
concatde precisión de fotogramas. Volver a ejecutar después de una edición del guion solo re-renderiza los bloques cuyo plan cambió (render_blocks.pyreutiliza archivos de bloque frescos, además de la caché de producción como segunda capa). - 12 núcleos / mucha RAM: usa
--workers 6. Una película de 3 minutos en 1080p tarda aproximadamente 15-30 minutos. - Nunca renderices la película final sin que el usuario lo pida: usa primero
--previewo un--sizepequeño, muéstralo, y solo entonces produceFILM.mp4a tamaño completo. - Whisper tiny.en es aproximadamente 1x tiempo real en CPU; usa
--model base.ensi los tiempos se desvían en líneas largas.
Lo que hace el director
Cada línea de subtítulo se convierte en un compás. Un compás recibe exactamente un diseño elegido según sus palabras:
| Diseño | Disparador | Dibujo |
|---|---|---|
title / end | primeras 2 / últimas 2 líneas | icono neón + título grande en tiza (título = mayúscula inicial de las palabras de contenido de la línea) |
chain | primero/segundo/luego/proceso/pipeline | 3 cajas de boceto con flechas |
split | antes/después/versus/comparado/en lugar | dos marcos etiquetados a cada lado de un divisor rasgado |
window | código/script/terminal/agente/modelo/servidor | ventana de terminal dibujada a mano con filas de garabatos + línea resaltada |
check | proteger/parchear/asegurar/prevenir/nunca | marcas de verificación en tiza en una lista |
stat | cualquier número | enorme numeral brillante |
quote | todo lo demás / preguntas | cita destacada en tiza |
| variantes de foto | cada dos bloques | station (foto + tarjeta), doc (documento de papel + sello), stat |
Líneas consecutivas (1-4, máximo ~9 s, corte al final de oraciones) se agrupan en bloques; los bloques alternan pizarra/foto a lo largo de la película. El primer y último bloque son siempre pizarra.
Archivos escritos
audio/narration.m4a voz normalizada
audio/timing.json inicio/fin por línea (esquema del motor)
script.json tomas en orden de habla, id se conserva
beats.json por línea: inicio/fin/diseño/titular/encabezado/puntos/número/icono/tinta/foto/x
plan.json bloques (estilo, rango de fotogramas, mundo x), fps, duración
beats.md tabla humana de todo el plan
sfx_cues.json efectos sintetizados para `build_sfx.py`
photos.json selecciones de Commons con licencia/crédito/fuente
out/blocks/bNNN.mp4 un clip por bloque de estilo
out/silent.mp4 imagen cosida
out/captioned.mp4 + subtítulos neón quemados (+ .srt)
out/FILM.mp4 final, con audio mezclado
out/qa/*.png imágenes de revisión
credits.md créditos de imagen + música
Puertas de control de calidad (scripts/qa.py, ejecutado automáticamente por run.py)
Falla la compilación en: desajuste de recuento de fotogramas vs timing.total_duration * fps, flujo de audio faltante/!stream, sonoridad fuera de -15 +/- 1.5 LUFS, pico verdadero > -0.8 dBTP, un fragmento de subtítulo no visible, o una línea base de subtítulo más del 8.5% de la altura del fotograma sobre el borde inferior.
Habilidades complementarias (cómo se completa realmente una producción)
Esta habilidad es el orquestador dedicado para el flujo de trabajo de películas educativas/explicativas ("video como la película del agente de explotación de IA"). Impulsa dos habilidades complementarias para terminar una producción, exactamente como se hicieron las películas anteriores — nunca las llamas directamente; run.py y qa.py lo hacen. La regla es absoluta: nunca edites una habilidad complementaria — ni ningún otro proyecto (ej. C:\remotion-build\dark-reality-explainer) — para hacer funcionar esta; manéjalas tal como se entregan. Toda la lógica de orquestación, caché, control de calidad y decisiones de estilo residen aquí en esta habilidad.
1. cinematic-film — el mundo, las fotos, el sonido (requerido, dependencia estricta)
Ubicado junto a esta habilidad (sobrescríbelo con CINEMATIC_SCRIPTS=<ruta a su directorio de scripts>). Llamado por:
| Script | Usado por | Qué hace para esta película |
|---|---|---|
prep_assets.py | etapa prep | gradúa las fotos de Commons al aspecto blanco y negro (`--grade bw |
fetch_commons.py | fetch_photos.py | descarga los originales con licencia (get), llena el archivo/crédito/licencia, y escribe credits.md (credits) |
render.py | render_blocks.py | renderiza cada bloque de estilo con --t0/--t1; dibuja el mundo de pizarra/foto, la cámara y cada elemento por fotograma |
engine.py | storyboard.py, cada render | el modelo del mundo: Film, claves de cámara, Board, PaperDoc, StylePanel, la cámara spline |
captions.py | captions_burn.py | el reloj de palabras (words_with_times) usado para temporizar la palabra activa |
build_sfx.py | audio_finish.py | sintetiza el bus de efectos desde sfx_cues.json (sin librería de muestras que licenciar) |
mix_soundtrack.py | audio_finish.py | voz + SFX + partitura: -19 dB SFX, -18 dB música, reducción 4:1, master -15 LUFS / -1.5 dBTP |
Reglas de compromiso: no edites sus scripts para esta habilidad — los cambios de comportamiento pertenecen a storyboard.py / render_blocks.py / aquí. Sus contratos CLI (--t0/--t1, fetch_commons get|credits, mix_soundtrack --lufs) son lo que la caché de producción hashea; si cinematic-film cambia uno, actualiza la etapa aquí y elimina E:\Storyteller catche files para que no sobrevivan aciertos obsoletos.
2. remotion-studio — previsualización en navegador / dirección (opcional, solo revisión)
npx remotion studio (abre la URL impresa; o --no-open y abre la URL tú mismo).
Alcance honesto, para que nadie pierda tiempo: Studio solo previsualiza composiciones de Remotion — componentes de React registrados en un proyecto de Remotion. No puede reproducir el master terminado de esta habilidad (out/FILM.mp4 es un render de skia/ffmpeg, no un proyecto de Remotion; tampoco lo fue la película del ataque de IA). Úsalo cuando el entregable también exista como proyecto de Remotion y quieras la experiencia de previsualización mientras editas (o para dirigir una variante basada en Remotion). Para revisar la salida propia de esta habilidad, usa out/FILM.mp4 / out/preview_captioned.mp4 más las imágenes en out/qa/ — Studio no tiene nada a qué adjuntarse.
La receta de producción (cómo las tres habilidades completan una película, como la última vez)
- Voz + guion ->
run.py --preview(2 bloques, 640x360, ~2 min). Revisa el aspecto, el ritmo pizarra/foto, el tamaño de subtítulos y alineación inferior, y queqa.pydiga PASS. - Plan completo — ingesta (alineación whisper) -> director (compases, diseños, alternancia de estilo) -> fotos de Commons (licencia libre, créditos en
credits.md) -> preparación (graduación blanco y negro) -> escena -> señales. - Renderizar — cada bloque por separado a 1080p; reutiliza mediante la caché de producción en
E:\Storyteller catche files. - Terminar — coser (filtro concat) -> subtítulos neón alineados al borde inferior -> SFX
-19 dB/ partitura-18 dB, con reducción, master-15 LUFS. - Revisar —
out/FILM.mp4se reproduce;out/qa/contiene las imágenes. Si se desea un paso de empaquetado/revisión de Remotion, abre ese proyecto de Remotion conremotion studioy verifica que se cargue allí. - Entregar —
FILM.mp4+FILM.srt+credits.md. La subida/exportación ocurre fuera de esta habilidad.
SRT / lado de distribución de la producción
Después de qa PASS: out/captioned.srt está junto a out/captioned.mp4 (el paso de finalización puede copiarlo junto a FILM.mp4). Para variantes sociales (re-cortes 9:16, exportaciones para plataformas, preparación de miniaturas), usa una habilidad de distribución en lugar de re-renderizar en esta — esta habilidad produce solo el master 16:9.
Requisitos
Ver Antes de empezar — la verificación de requisitos arriba: Python 3.8+, numpy, skia-python, Pillow, faster-whisper, ffmpeg/ffprobe en el PATH, y la habilidad cinematic-film junto a esta (sobrescríbelo con CINEMATIC_SCRIPTS). La verificación se ejecuta automáticamente al inicio de cada ejecución.
Limitaciones conocidas
- La alineación usa whisper tiny.en por defecto; una toma mal articulada puede desviarse dentro de...
... [truncado para traducción]