Communitygithub.com

documentary-maker

Crea un video documental animado 2D (30 seg a 3 min) a partir de una sola frase: investigación con fuentes, guion narrativo, voz offline gratuita (Kokoro), sincronización de palabras (Whisper), escenas con motion design donde cada animación aterriza en una palabra hablada, efectos de sonido y música generados por código, y un MP4 en 1080p. Úsalo cuando el usuario pida un documental, un explicador animado de una historia real, 'haz un video sobre <evento>', o un video sin rostro de historia/ciencia/negocios/crimen.

¿Qué es documentary-maker?

Documentary-maker es una habilidad para agentes de IA (como Claude Code, Cursor o Codex) que te permite convertirte en un equipo de producción cinematográfica completo: investigador, guionista, narrador, editor, animador y diseñador de sonido. El flujo de trabajo consta de seis capítulos que se ejecutan en orden, todo en el ordenador del usuario y sin coste adicional más allá de su plan de Claude. Comienza investigando en la web hechos verificables con fuentes (números, fechas, nombres, citas) y los guarda en un archivo facts.md. Luego escribe un guion estructurado (script.md) donde cada oración se convierte en una animación, y una versión para voz (voice/script_voice.txt) con números escritos como se pronuncian. Tras la aprobación del usuario, genera la voz con Kokoro (modelos como am_michael, am_onyx, etc.), obtiene las marcas de tiempo de cada palabra con Whisper, y crea escenas animadas en 2D usando inline SVG, GSAP y una biblioteca de helpers (tarjetas, titulares cinéticos, contadores, sellos, etc.) donde cada elemento gráfico aparece exactamente en la palabra que lo describe. Finalmente, produce efectos de sonido y música original por código, y renderiza un video 1080p30 (MP4). La habilidad incluye herramientas de verificación (render check, stills) y usa plantillas temáticas de color (midnight, ember, noir, forest, crimson) según el tema del documental. Es ideal para creadores de contenido, educadores o cualquier usuario que quiera producir videos animados de alta calidad sin necesidad de software de edición tradicional.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mehedi11234/claude-documentary-maker/tree/HEAD/documentary-maker

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿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.md con 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 con WA('word', 'alternative') (inicio) y WEnd(...) (fin); termina con B.end = endAfterVoice(2.0); _wc = 0;. Luego build() 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(), tarjetas card() + fly(), stamp() / warnStamp(), counter(), burst(), suspectCard(), quoteCard(), timeline(), dateTag(), typeText(). Consulta engine/lib.js y engine/doc.js para 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.KEYWORDS con 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 con RND(i), nunca Math.random().
  • Errores comunes: anima x/y con GSAP, nunca establezcas una transformación CSS en un elemento que GSAP también mueve; una escena sc(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:

  1. python render.py check -> debe decir err: null y miss: []. (Antes de que exista la voz, puedes diseñar escenas con tiempos falsos: python engine/fake_words.py.)
  2. 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.

Skills relacionados