Communitygithub.com

documentary-video-skill

Convierte cualquier tema en un cortometraje documental terminado, de principio a fin: investigación, guion narrado verificado, voz en off, imágenes de archivo con fuente, subtítulos, créditos, banda sonora y un MP4 etalonado renderizado con ffmpeg.

¿Qué es documentary-video-skill?

Este skill permite a un agente IA (como Claude Code, Cursor, Codex, etc.) transformar un tema proporcionado por el usuario en un cortometraje documental completo, sin necesidad de que el usuario instale, investigue, escriba o renderice nada. Está diseñado para plataformas que soportan ejecución de scripts y herramientas como ffmpeg, python3 y acceso a web. El skill gestiona todo el flujo de trabajo: investigación con fuentes verificadas, redacción de un guion argumental estructurado en cuatro movimientos, generación de una lista de planos con imágenes de archivo (priorizando dominio público o licencias abiertas), locución (con ElevenLabs como primera opción u offline como respaldo), y renderizado final en MP4 con código de tiempo, subtítulos SRT y créditos. Incluye controles de calidad como la hoja de contacto y la posibilidad de iterar rápidamente con el modo borrador. También maneja la ética del medio: no inventar hechos, citar siempre las fuentes en pantalla, distinguir lo generado por IA de las imágenes reales, y respetar la precisión histórica. El resultado es un documental argumental, no una lista de hechos, que se entrega junto con el script, créditos y enlaces a fuentes.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/0xAkashic/documentary-video-skill/tree/HEAD

Preguntar en tu IA favorita

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

Documentación

Video documental

El usuario da un tema. Tú entregas una película terminada: out/<slug>.mp4 (1920x1080, H.264/AAC), además de .srt, CREDITS.md, el guion y las fuentes. El usuario no debe tener que instalar, investigar, escribir o renderizar nada por sí mismo. Detente solo cuando una decisión sea genuinamente suya: una generación paga, una descarga que necesita permiso, o una afirmación factual que no pueda verificarse.

SKILL_DIR es esta carpeta. DOC significa python3 "$SKILL_DIR/scripts/doc.py".

1. Enmarcar antes de escribir

Haz como máximo dos preguntas, y solo si cambian la película: duración (por defecto 3 minutos) y ángulo (lo que la película argumenta, no solo su tema). Todo lo demás lo decides tú.

Un documental es un argumento con imágenes, no un resumen. Elige una afirmación que un espectador pueda repetir después de verlo — "el farero no perdió contra la tecnología, perdió contra una hoja de cálculo" — y elimina todo lo que no la sirva.

Nunca filmes una lista de hechos. Filma un cambio: algo era verdad, luego dejó de serlo, y esto es lo que costó.

2. Configuración (solo la primera vez)

DOC doctor

Necesita python3 y ffmpeg con libx264. Termux: pkg install ffmpeg. macOS: brew install ffmpeg. Si solo falta ffmpeg, instálalo y vuelve a ejecutar. No escribas nada más hasta que doctor diga Ready.

DOC new <project> --title "El último farero" --subtitle "1985 -- 1997"

Esto crea project.json, shots.json, research.md, script.md, y work/img, work/audio, out.

3. Investigación

Usa búsqueda web. Apunta a cuatro a seis fuentes sólidas: documentos primarios, archivos, páginas de universidades o agencias, periodismo reputado, un libro. Lee lo suficiente para explicar el mecanismo, no solo el resultado.

Guarda en research.md:

# Investigación

## Tesis
Una oración que la película argumenta.

## Hechos (cada uno con su fuente)
- 1841: <hecho> -- <url de la fuente>
- <número>: <hecho> -- <url de la fuente>

## Controvertido / desconocido
- <en qué difieren las fuentes y cómo lo expresará la película>

## Material visual
- <archivos, colecciones, búsquedas probables de imágenes de dominio público>

Cada oración en la narración debe remitir a una línea aquí. Si dos fuentes discrepan, o lo dices en pantalla o descartas el hecho. No inventes un número, una fecha, una cita o una anécdota. Un hecho que falta es un problema de trama; uno falso es un fraude.

4. Escribir el guion

Lee references/script-craft.md antes de escribir. En resumen:

  • 155 palabras por minuto. 3 min = ~460 palabras. Presupuesta por acto, no por sensación.
  • Cuatro movimientos: el mundo antes (gancho), el mecanismo (cómo funcionó el cambio), el costo (lo que hizo a las personas), el eco (regreso al gancho, transformado).
  • Una idea por oración. Un respiro por línea. Ninguna oración de más de 22 palabras.
  • Concreto sobre abstracto. "Subió 117 escalones dos veces por noche" vence a "el trabajo era exigente".
  • Tiempo presente para la historia, tiempo pasado para el veredicto.
  • La narración lleva el argumento; los subtítulos llevan la evidencia (nombres, fechas, lugares). Nunca digas en la banda sonora lo que el subtítulo ya prueba.

Escríbelo en script.md como actos, una oración por línea, porque las líneas de shots.json deben coincidir textualmente:

## Acto I -- el mundo antes
Durante doscientos años, alguien tuvo que permanecer despierto para que los barcos pudieran encontrar la costa.
...

Luego muéstrale al usuario el guion completo en un solo mensaje —unas 30 líneas— y continúa. No esperes aprobación a menos que te hayan pedido revisarlo.

5. Lista de planos

Lee references/shot-list.md para cada campo y un ejemplo completo, luego escribe shots.json:

{"shots": [
  {"id": "s01", "kind": "card", "text": "El último farero",
   "sub": "Un trabajo que desapareció en doce años", "hold": 4.0},
  {"id": "s02", "line": "Durante doscientos años, alguien tuvo que permanecer despierto.",
   "img": "work/img/cabo-byron-1891.jpg", "motion": "zoom-in",
   "caption": "Cabo Byron, 1891"}
]}

Reglas importantes:

  • line es la narración, textual del guion, en orden. La duración proviene del audio, así que una línea cambiada cambia la edición.
  • 3.5 – 6 segundos por plano. Una imagen fija necesita más tiempo del que piensas. Nunca menos de 2.5 s excepto un destello deliberado.
  • Una imagen, una idea. Si un plano necesita dos imágenes, son dos planos.
  • Mueve la cámara, no el mundo. zoom-in para intimidad, zoom-out para consecuencia, pan-* para paisajes y documentos, static para rostros y texto.
  • Una tarjeta es un corte de capítulo. Usa 2-4 en una película de 3 minutos: título, una fecha o número, y una tarjeta final que aterrice. Las tarjetas no tienen narración.
  • caption es la pequeña línea de evidencia en pantalla: lugar, año, fuente. Mantén menos de 6 palabras.

6. Imágenes fijas

Prefiere material de archivo real. Es la diferencia entre un documental y una presentación de diapositivas.

DOC archive <project> --query "Cabo Byron faro 1900" --n 3

Esto busca en Wikimedia Commons, descarga imágenes utilizables en work/img/, y escribe sources.json + CREDITS.md con autor y licencia. Por defecto solo conserva dominio público, CC0 y CC BY / BY-SA, porque una película publicada generalmente necesita uso comercial. Añade --license pd para dominio público estricto, --license any para ver todo (luego verifica cada licencia tú mismo).

Si el archivo no tiene nada, en orden de preferencia:

  1. Otras colecciones abiertas — Biblioteca del Congreso, Smithsonian Open Access, NASA, Internet Archive, Europeana. Pregunta al usuario antes de descargar de un sitio nuevo, y registra la licencia y URL en CREDITS.md.
  2. Generar una imagen con cualquier herramienta de imágenes que tengas, usando references/image-prompts.md. Marca los fotogramas generados en CREDITS.md como reconstrucción generada por IA, y ponles un subtítulo para que el espectador nunca sea engañado pensando que son fotografías.
  3. Planos tipográficos y de objetos — un documento, un mapa, una página de un cuaderno de bitácora, una lámina abstracta. Honesto y económico.

Nunca presentes una imagen generada por IA como archivo. Esa línea es toda la ética del formato.

7. Locución

DOC tts <project>

Usa ElevenLabs cuando ELEVENLABS_API_KEY esté configurada (mejor), sino una voz offline (espeak-ng, Android termux-tts-speak, macOS say). Una sola toma. Escribe para el oído: frases cortas, sin trabalenguas, números escritos como se dicen.

Si no hay voz disponible, la película se renderiza igual con tiempos estimados —dilo, y entrega el .srt para que el usuario pueda grabar su propia locución después. Mantén line sin cambios para que una regrabación encaje directamente.

La calidad de grabación supera a la calidad del modelo: una grabación con teléfono en una habitación silenciosa es mejor que una voz sintética para la mayoría de los documentales. Ofrece eso.

8. Construir y verlo

DOC build <project> --draft     # pase rápido mientras se itera
DOC build <project> --subs      # final, subtítulos quemados
DOC sheet <project>             # hoja de contacto de 12 fotogramas

Mira out/contact.jpg cada vez. Verifica:

  • nada importante queda debajo de un subtítulo, y ningún subtítulo se sale del cuadro;
  • los cortes caen en finales de oración, y ningún plano se mantiene en una parte vacía o irrelevante de una imagen;
  • la gradación es consistente, los rostros no están aplastados, y las imágenes con texto son legibles;
  • la última tarjeta llega después de que la narración se detiene, no encima de ella.

Corrige editando shots.json (imagen, movimiento, subtítulo, orden) y reconstruyendo. Los clips interiores se almacenan en caché por id de plano, así que solo los planos modificados se rerenderizan.

Velocidad. El renderizado depende de la CPU. A 1080p una película de tres minutos tarda aproximadamente un minuto en un portátil y 10-20 minutos en un teléfono. Siempre itera con --draft (media resolución, preset rápido), y haz un pase completo al final. build imprime cada plano a medida que avanza, así que puedes detener un renderizado que claramente está mal.

9. Música

Pregunta antes de añadir música. Sugiere una fuente, verifica la licencia, coloca el archivo en public/music/bed.mp3, luego:

DOC build <project> --music public/music/bed.mp3

Se repite en bucle, se sitúa en ~14% y se atenúa automáticamente bajo la voz. El silencio es una opción legítima y a menudo la mejor para una película seria.

10. Entrega

Dale al usuario:

  • el MP4;
  • el .srt (también útil en YouTube);
  • CREDITS.md — cada imagen fija, autor, licencia, enlace;
  • el guion, un párrafo sobre el ángulo y 3-5 enlaces a fuentes;
  • una nota directa sobre qué es archivo, qué es generado y qué se cortó por falta de evidencia.

Luego ofrece un siguiente paso: un corte más largo, una apertura diferente, un segundo acto, o la misma película como un corte vertical de 60 segundos.

Buen juicio

  • La película es el argumento, no el metraje. Si las imágenes son hermosas pero la afirmación es vaga, reescribe.
  • Elimina el tercer ejemplo. Dos prueban un patrón; tres son una lista.
  • Fuentes en pantalla, no solo en la descripción. Un subtítulo con año y lugar es lo que hace que un espectador confíe en el resto.
  • Di lo que no sabes. "Nadie se pone de acuerdo en el número" es una línea más fuerte que una equivocada con seguridad.
  • Respeta a los muertos. Personas reales, eventos reales: sin diálogos inventados, sin recreaciones presentadas como registro, sin rostros generados para personas nombradas.
  • La duración es una promesa. Si el material solo da para 90 segundos, entrega 90 segundos.

Archivos

  • scripts/doc.py — toda la tubería (DOC -h para cada bandera).
  • references/script-craft.md — cómo escribir narración que suene a película.
  • references/shot-list.md — esquema completo de shots.json y ejemplo resuelto.
  • references/sourcing.md — archivos, reglas de licencia, formato de atribución.
  • references/image-prompts.md — indicaciones para imágenes generadas que encajen con archivo.
  • examples/last-lightkeeper/ — un ejemplo terminado de 3 planos (guion + planos).

Skills relacionados