Communitygithub.com

video-documental

Crea documentales históricos para YouTube al estilo de un tapiz bordado medieval. Videos cortos (~2 min) o largos construidos en partes de 2 minutos durante varios días, con progreso guardado.

¿Qué es video-documental?

Esta habilidad permite a un agente de IA crear documentales históricos para YouTube con un estilo visual único de tapiz bordado medieval (similar al Tapiz de Bayeux). Está diseñada para plataformas como Claude Code, Cursor o Codex, y ofrece un flujo de trabajo completo: desde la generación del guion y la locución con ElevenLabs (voz de narrador británico), hasta la creación de imágenes con Google Flow (gratuito) y la animación de escenas clave con Flow image-to-video (con costo de créditos). El agente ensambla el video final con ffmpeg, uniendo las partes de forma fluida. La habilidad soporta tanto videos cortos de un solo segmento (~2 minutos) como videos largos de hasta 8 minutos, construidos en partes de 2 minutos a lo largo de varios días, guardando el progreso en una carpeta de proyecto. El usuario invoca esta habilidad cuando pide un video de historia 'al estilo de tapiz bordado / Bayeux', un documental como el de Lindisfarne 793, la continuación de un video largo existente, o 'haz un nuevo video con la habilidad del tapiz'.

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

Preguntar en tu IA favorita

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

Documentación

Habilidad de video documental (estilo tapiz)

Probado en "793: El asalto que inició la era vikinga" (doc-test/lindisfarne_793_documentary.mp4). Cada parte: 1920x1080, ~2:00, narrador británico, 15 escenas. Las escenas 1, 2, 3, 5 y 8 son clips de movimiento real de Flow; el resto son imágenes con un zoom lento muy suave.

Primero mira las referencias:

  • references/style/: el estilo deseado del usuario. Cremoso apagado, azul pizarra, verde musgo, ocre y costuras oxidadas, nubes y olas bordadas en remolino.
  • references/approved-examples/: imágenes generadas que el usuario aceptó. Son a pantalla completa, sin borde ni margen blanco.
  • references/avoid/: lo que el usuario rechazó:
    1. Un borde de tela o margen blanco alrededor de la imagen.
    2. Una banda decorativa con friso de animales a lo largo de la parte inferior.

Reglas del usuario (importante)

  • Si un mensaje contiene una pregunta y una tarea, responde la pregunta y espera antes de gastar créditos.
  • Solo las palabras del usuario cuentan como instrucciones. Sé económico con los créditos, no hagas trabajo adicional no solicitado e informa brevemente.
  • Patrón de animación: anima las escenas 1, 2, 3, luego 5, luego 8 de cada parte con Flow image-to-video real. Son 5 clips, alrededor de 120 créditos por parte. Cada otra escena usa su imagen con un zoom lento muy pequeño (aproximadamente 3%, alternando dentro y fuera). assemble.py hace esto automáticamente.
    • Nunca presentes imágenes con zoom como "los videos". Los clips reales deben venir de Flow.
    • Indica el costo (24 créditos por clip) antes de enviar. Si el usuario elige un conjunto diferente de escenas, regístralo con project.py decide.
  • Un proyecto de Flow por video. Créalo una vez y siempre pasa su id. Nunca uses --project-name por llamada, porque eso crea un nuevo proyecto cada vez.
  • El usuario a menudo interrumpe. Después de una interrupción, verifica qué sigue ejecutándose o se ha cobrado antes de hacer cualquier otra cosa.

Formato largo: construir en partes de 2 minutos, durante varios días

Un video de 8 minutos consta de 4 partes de aproximadamente 2 minutos, hechas una parte a la vez. Cada parte pasa por dos revisiones:

  1. Una revisión de borrador gratuita.
  2. Una revisión final después de gastar créditos.

Todo el estado reside en la carpeta del proyecto, por lo que una sesión nueva siempre puede continuar.

Iniciar una sesión en un video existente:

  1. Lee <proyecto>/PROGRESS.md.
  2. Ejecuta python3 scripts/project.py status <proyecto>. Muestra las decisiones, el estado de cada parte y NEXT, la acción a realizar.
  3. Continúa desde NEXT. Nunca rehagas partes terminadas y nunca cambies una decisión (voz, estilo, proyecto de Flow, patrón) sin la aprobación del usuario.

Estructura del proyecto (crear con project.py new doc-test/videos --title "..." --minutes 8):

doc-test/videos/<slug>/
  project.json      decisiones (voice_id, style, flow_project_id, animation_pattern, zoom...) + estado/créditos por parte
  PROGRESS.md       registro fechado de cada paso y decisión - añadir mediante project.py, nunca reescribir
  outline.md        arco completo del video + por parte: portadas / línea de apertura / línea de cierre para el siguiente
  parts/partNN/     scenes.json, voiceover.mp3, timing.json, images/, clips/, draft.mp4, partNN.mp4
  final/<slug>_full.mp4

Flujo de estado de una parte: planned → script_review → draft_review → final_review → final. Establece cada estado con project.py set <proyecto> <n> <status> --note "..." [--credits N].

Por parte:

  1. Guion (la parte 1 también completa outline.md para todo el video primero).
    • Escribe parts/partNN/scenes.json, usando templates/scenes.example.json como plantilla. Mantén la cadena style de project.json.
    • La primera escena debe retomar la línea de cierre de la parte anterior. La última línea hace la transición a la siguiente parte.
    • Visualmente, la última escena de la parte N y la primera escena de la parte N+1 deben compartir escenario y paleta, para que la disolución entre ellas se sienta natural.
    • Envía el guion al usuario, luego set ... script_review.
  2. Después de que el usuario apruebe el guion, haz toda la parte de una sola vez:
    • Genera la locución (paso A) y el tiempo (paso D), luego las imágenes (paso B; generalmente la extensión del usuario desde image_prompts.txt).
    • Anima las escenas del patrón 1, 2, 3, 5 y 8 en Flow (paso C). El usuario espera los clips reales en la primera versión que revise.
    • Ejecuta assemble.py parts/partNN para el partNN.mp4 en 1080p.
    • Envía la ruta completa al usuario y ábrela con xdg-open.
    • Luego set ... final_review --credits <gastado>.
    • Nunca envíes un borrador hecho solo de imágenes con zoom como "el video". --draft es solo para una verificación privada rápida.
  3. (El estado draft_review es opcional. Omítelo a menos que el usuario pida una vista previa barata primero).
  4. Después de que el usuario apruebe el render final: set ... final.
  5. Cuando todas las partes estén finales: ejecuta python3 scripts/join_parts.py <proyecto>, que escribe final/<slug>_full.mp4. Luego verifica cada unión (sonido e imagen).

Por qué las uniones son suaves (no rompas esto):

  • assemble.py renderiza cada parte con formato idéntico: 1920x1080, 30 fps, yuv420p, AAC 48 kHz estéreo, volumen de la voz normalizado a -16 LUFS.
  • Cada parte también tiene bordes idénticos: 0,4 s de imagen antes de la primera palabra y 1,2 s de imagen silenciosa después de la última palabra.
  • join_parts.py disuelve la imagen durante 1 s dentro de esa cola silenciosa y corta el audio dentro del silencio, para que las palabras no se superpongan y el nivel no salte.
  • Probado: el espacio de unión fue de 0,84 s, el mismo que una pausa normal de párrafo, y el volumen fue de -16,4 frente a -16,5 LUFS en ambos lados.
  • Usa siempre el mismo voice_id y tts_model para cada parte, según lo registrado en project.json.

Pasos de producción (usados dentro de cada parte)

A. Locución (ElevenLabs MCP)

  1. Llama a creative_generate_speech con:
    • model_id: el tts_model del proyecto, eleven_v4
    • voice_id: el voice_id del proyecto, QngvLQR8bsLR5bzoa6Vv ("Michael Dan – Narrador de documentales británico")
    • prompt: las narraciones de la parte unidas con líneas en blanco entre ellas
  2. Consulta creative_get_flow_run_status hasta que termine. Devuelve 2 tomas, cada una de aproximadamente 1650 créditos de ElevenLabs (≈$0.30).
  3. Descarga la toma 1 con curl desde content_url a parts/partNN/voiceover.mp3.

Escribe los años en palabras, p. ej., "seven ninety-three", para que el narrador los diga correctamente.

B. Imágenes (gratis) - el usuario generalmente las hace con su propia extensión del navegador

Las imágenes se crean a partir de un texto de prompt únicamente (cadena de estilo + escena). No se pasa ninguna imagen de referencia: gflow rechaza las imágenes de referencia en esta cuenta, y las carpetas de referencia son solo para verificar los resultados visualmente.

Preferido (extensión del usuario): haz primero la locución y timing.py, para que se conozcan los tiempos de las escenas, luego escribe parts/partNN/image_prompts.txt y dale al usuario esa ruta. El formato es exactamente un prompt por escena, luego una línea en blanco:

[0.00-0.06] <estilo>. Escena: <imagen>. IMPORTANTE: no escribas la hora, ningún número, ninguna etiqueta ni ningún texto en la imagen.

[0.06-0.14] ...
  • Las horas están en m.ss desde timing.json.
  • El usuario pasa el archivo a la extensión y envía de vuelta una carpeta, p. ej., ~/Downloads/zapi-img-doc/. Contiene archivos con el nombre NN_[mss-mss]_....webp, a veces con tomas _1/_2.
  • Revisa cada imagen en hojas de contactos etiquetadas. Busca un borde de tela o raya, un margen, una banda de borde, texto suelto, el tema incorrecto o una falta de coincidencia de estilo. Elige la mejor toma y conviértela a parts/partNN/images/sceneNN.jpg.
  • Regenera solo las malas con gflow (gratis) e informa al usuario cuáles y por qué.

Alternativa (gflow MCP):

  1. Ejecuta gflow_generate_image con prompt "<estilo>. Escena: <imagen>.", aspect "16:9", model nano2 y project <flow_project_id>.
  2. Para la primera imagen de un video nuevo, omite project y pasa project_name. Luego ejecuta project.py decide <p> flow_project_id <id>.
  3. Copia el archivo desde ~/Downloads/gflow-cli/images/<fecha>/<media>_1.jpg a parts/partNN/images/sceneNN.jpg.

Hoja de contactos: ffmpeg -pattern_type glob -i 'images/scene*.jpg' -vf "scale=344:192,tile=5x3" -frames:v 1 contact.jpg

C. Animar las escenas del patrón (sitio web de Flow, cuesta créditos)

El i2v de gflow es rechazado en esta cuenta: Flow le sirve el "compositor solo para agentes" (problema de gflow #799). El rechazo no cuesta nada. Usa el sitio web en su lugar. El diseño de Flow cambió en noviembre de 2026: ya no hay chat de agente ni paso de Aprobación.

Si el usuario también quiere hacer los clips él mismo, escribe parts/partNN/video_prompts.txt en el mismo formato [m.ss-m.ss] prompt. Usa el texto "Animar esta imagen exacta..." más el motion de la escena, uno por escena animada, y enumera qué sceneNN.jpg corresponde a cada uno.

  1. Verifica los créditos con gflow_get_credits. No cuesta nada.
  2. Ejecuta scripts/launch_flow_chrome.sh "https://flow.google.com/project/<id>".
  3. Ejecuta ~/.local/share/uv/tools/gflow-cli/bin/python scripts/flow_animate.py --project <id> --part parts/partNN --upload --prefix <corto>_pN_ 1 2 3 5 8.
    • --upload coloca las imágenes de las escenas en el proyecto de Flow. Es necesario cuando la extensión del usuario las creó.
    • Cambia el compositor a Video → Fotogramas → x1, para que el clip comience desde la imagen exacta. Es Omni 1.2 Flash, 720p, 8 s, 24 créditos por clip.
    • Selecciona cada fotograma de inicio, escribe el prompt de movimiento, envía y espera.
    • Nunca envíes mientras el compositor esté en Imagen/Nano Banana. Eso crea 2 imágenes, no un video. Son gratis, pero no se anima nada.
  4. Ejecuta ~/.local/share/uv/tools/gflow-cli/bin/python scripts/flow_download.py --project <id> --part parts/partNN 1 2 3 5 8.
    • Descarga los videos más nuevos (tamaño original) y archiva cada uno como clips/sceneNN.mp4 emparejando su primer fotograma con la imagen de la escena.
    • La distancia de coincidencia debe ser aproximadamente 4 para la escena correcta y más de 30 para las demás.
  5. Verifica los fotogramas de cada clip: mismo aspecto de tapiz, sin texto.
  6. Cierra la ventana de Chrome CDP con CDP Browser.close. Las llamadas a gflow MCP fallan mientras mantiene el perfil.
  7. Vuelve a verificar los créditos. La disminución debe ser exactamente 24 × el número de clips.

D. Tiempo y ensamblaje

  1. python3 scripts/timing.py parts/partNN: ajusta los límites de las escenas a las pausas de párrafo en la locución. Verifica las duraciones impresas. Cualquier valor por debajo de 5 s o por encima de 11 s es un mal ajuste, así que corrígelo manualmente en timing.json.
  2. python3 scripts/assemble.py parts/partNN --draft hace una copia de revisión. Sin --draft hace el render final.
  3. Verifica los fotogramas antes de enviar.

E. Título de YouTube

Mantenlo por debajo de 60 caracteres, pon el gancho primero e incluye el año. Ejemplo: "El día que comenzó la era vikinga (793 d.C.)". Ofrece de 3 a 5 opciones más una idea de miniatura con 2 o 3 palabras de texto.

Notas del entorno / problemas conocidos

  • gflow MCP: registrado a través de ~/.local/bin/gflow-clean (copia en scripts/gflow-clean). El envoltorio elimina las variables de entorno GTK/GIO de la instantánea de VS Code. Sin él, Chrome se bloquea al iniciar, lo que gflow informa erróneamente como "Perfil bloqueado".
  • Cuenta: el perfil de gflow es sajeel135. La generación de imágenes es gratuita; los videos cuestan créditos.
  • Chrome debe usar --password-store=basic: cualquier Chrome abierto en el perfil de gflow necesita --password-store=basic, que launch_flow_chrome.sh ahora establece. Sin él, Chrome vuelve a cifrar las cookies con el llavero del sistema. gflow no puede leerlas y termina en flow.google.com/about (código de error 31), y el usuario tiene que iniciar sesión de nuevo.
    • Cuando Flow muestra /about pero Google tiene la sesión iniciada, abre la ventana CDP, presiona "Crear con Google Flow", deja que el usuario complete cualquier inicio de sesión, luego ciérrala limpiamente con CDP Browser.close.
  • Bloqueos obsoletos: elimina los archivos de bloqueo Singleton* obsoletos en ~/.local/share/gflow-cli/profile_sajeel135/, pero solo cuando ningún Chrome esté usando ese perfil (launch_flow_chrome.sh hace esto).
  • Detener procesos: no ejecutes pkill -f <nombre> desde un shell cuya propia línea de comandos contenga ese nombre, porque se mata a sí mismo. Mata por PID en su lugar.
  • Renders largos: el render de una parte final toma unos minutos. Ejecuta los renders largos en segundo plano si la llamada a la herramienta podría agotar el tiempo de espera.

Skills relacionados