¿Qué hace documentary-maker?
Eres todo el equipo de producción: investigador, guionista, narrador, editor, animador, diseñador de sonido. Trabaja a través de los seis capítulos en orden. Todo se ejecuta en el ordenador del usuario y no cuesta nada más allá de su plan de Claude.
Las herramientas están en esta carpeta de skill (<skill> más abajo). Las herramientas de Python se ejecutan con el venv del skill:
~/.documentary-maker/venv/Scripts/python.exe en Windows, ~/.documentary-maker/venv/bin/python en otros sistemas (<py>).
0. Configuración (una sola vez)
Si falta ~/.documentary-maker/venv o <skill>/engine/vendor/gsap.min.js, ejecuta python <skill>/tools/setup.py
(Python 3.10-3.12; en Windows py -3.12 <skill>/tools/setup.py). Necesita Node, FFmpeg y Chrome o Edge; si falta alguno,
indica al usuario cuál y detente. Luego python <skill>/tools/new_doc.py <project> <theme> en la carpeta del usuario.
Elige el tema según el tema del documental: midnight (espacio, ciencia, tecnología), ember (historia, negocios, personas), noir (crimen,
estafas, misterios), forest (naturaleza, clima, salud), crimson (guerra, desastres - tono serio). Un color de acento
hace todos los resaltados; el color de advertencia es solo para peligro, dinero perdido, muertes, fracasos.
1. Investigación -> facts.md
- Busca en la web. Cada número, fecha, nombre y cita en el guion debe estar en
facts.mdcon una URL de origen. Prefiere informes oficiales, documentos judiciales, las propias páginas de la organización y los principales periódicos antes que blogs. - Cuando las fuentes discrepen (dinero, número de víctimas), usa la cifra más citada y di "aproximadamente" / "alrededor de" en el guion.
- Nunca inventes una cita, un pensamiento, un detalle de escena o un número. Si no puedes encontrar la fuente, déjalo fuera.
2. Guion -> script.md + voice/script_voice.txt
Duración: aproximadamente 2.4 palabras habladas por segundo (30 s ~ 75 palabras, 60 s ~ 145, 3 min ~ 430).
- Abre dentro de un momento, no con un resumen: una fecha, un lugar, una acción ("Junio de 1996. Un cohete nuevo reposa en la plataforma de lanzamiento."). El espectador debe verlo.
- Frases cortas. Una idea por frase: cada frase se convierte en una animación.
- Guarda el número más grande para el final, y permite que cada revelación abra la siguiente pregunta ("¿La causa? Ni los motores. Ni el clima. Un número.").
- Termina con una línea corta que cierre la apertura.
script.md= el guion con un título.voice/script_voice.txt= las mismas palabras para la voz: números y símbolos escritos como se pronuncian ("mil novecientos noventa y seis", "sesenta y cuatro bits", "trescientos setenta millones de dólares"), sin encabezados, sin [etiquetas]; una línea en blanco entre párrafos = una pausa (párrafos de 1-3 frases).- Muestra al usuario el guion y los hechos principales, y espera su aprobación antes de generar la voz, a menos que diga que no preguntes.
3. Voz -> voice/voice.wav
cd <project> && <py> voice.py --voice am_michael (otros narradores: am_onyx, am_fenrir, bm_george, bm_daniel, af_heart,
bf_emma; --speed 0.95 para una lectura más pausada). Kokoro se ejecuta en la CPU a aproximadamente 2x tiempo real.
4. Tiempos de palabra -> engine/data.js
<py> words.py. Imprime una verificación de palabras; si falta una palabra del guion o es incorrecta, edita ese párrafo (a menudo un nombre:
escríbelo como suena) y repite el capítulo 3. Whisper escribe los números como dígitos ("1996", "64-bit", "$370"), por lo que
los subtítulos muestran dígitos; ancla las animaciones en palabras sencillas.
5. Escenas -> engine/scenes.js
Lee primero <skill>/examples/ariane-501/scenes.js: es un documental completo y funcional. Escribe el tuyo de la misma manera.
anchors()primero: busca los tiempos de cada beat en orden conWA('word', 'alternative')(inicio) yWEnd(...)(fin); termina conB.end = endAfterVoice(2.0); _wc = 0;. Luegobuild()llama a una función por beat.- Cada elemento aterriza en una palabra hablada. Nada aparece antes de su palabra; la pantalla nunca está vacía durante más de aproximadamente un segundo.
- Dibuja la historia, no la escribas. Ilustraciones SVG en línea en los colores del tema (cohete, edificio, forma de mapa,
moneda, silueta de persona, documento) con movimientos de cámara (escala/traslación de una capa), más titulares cinéticos
hd(), tarjetascard()+fly(),stamp()/warnStamp(),counter(),burst(),suspectCard(),quoteCard(),timeline(),dateTag(),typeText(). Consultaengine/lib.jsyengine/doc.jspara ver todos los helpers y sus opciones. - Mantén el texto corto (etiquetas, números, titulares de 2-4 palabras). Los subtítulos ya muestran cada palabra en la parte inferior: mantén el contenido por encima de y = 930. Establece
window.KEYWORDScon las palabras que los subtítulos deben colorear. - Etiqueta los dibujos que podrían confundirse con imágenes reales o documentos: una pequeña etiqueta "ILUSTRACIÓN".
- Solo movimientos a escala de segundos: ningún tween más rápido de 0.25 s, nada que parpadee.
- Usa solo los colores del tema (
LIME= acento,LIME2,PAPER,MUTE,DIM,CARD1,CARD2,PINK= advertencia,acc(a),warnA(a),PAPA(a),MUTEA(a)); aleatoriedad determinista conRND(i), nuncaMath.random(). - Errores comunes: anima
x/ycon GSAP, nunca establezcas una transformación CSS en un elemento que GSAP también mueve; una escenasc(t0, t1)debe cubrir cada hijo que aún se está moviendo; no nombres una variable como un helper (rise,cl,card...).
Verifica antes de renderizar:
python render.py check-> debe decirerr: nullymiss: []. (Antes de que exista la voz, puedes diseñar escenas con tiempos falsos:python engine/fake_words.py.)python render.py stills <8-24 times>y mira cada imagen: superposiciones, texto cortado, pantallas vacías, cosas que aparecen antes de su palabra, colores fuera del tema. Corrige y vuelve a mirar.
6. Sonido + renderizado -> final.mp4
python render.py cues # lista de señales de efectos de sonido desde las escenas
<py> audio.py # SFX hechos por código + música original de fondo bajo la voz, -14 LUFS -> mix.wav
python render.py video 4 # captura a 120 fps -> desenfoque de movimiento -> 1080p30 final.mp4 (+ final_sheet.jpg)
Ejecuta render.py video en segundo plano o con un tiempo de espera de 15 minutos: toma aproximadamente 1.5 minutos por cada 10 s de video con 4 workers (medido: 38 s de video en 6 minutos en un PC solo CPU). Si un fragmento informa fotogramas perdidos, ejecuta de nuevo con menos workers. Mira final_sheet.jpg. Luego informa al usuario: el archivo, su duración, cuáles son las fuentes, y cualquier cosa que no hayas podido verificar. Recuérdales que lean facts.md antes de publicar, y que tú no puedes escuchar el audio: su escucha es la verdadera verificación.