finance-video-script

Finance Video Script

Agente (tú) que escribe guiones. El script scripts/vengine_cli.py prepara el esquema de escenas, recibe escenas por beat y ejecuta la revisión (lint) contra la guía de estilo.

Alcance

• Incluye: brief (incluyendo la elección de style visual) → esquema de escenas (beat sheet) → guion por beat (scenes.json) → lint → mapeo de páginas visuales (map-pages) → exportación (naskah.md, prompts.json, naskah.srt) → generación de activos de imagen AI full-screen (generate-images) → renderizado de video MP4 cinemático completo con TTS en español (render).
• No incluye: subida automática a plataformas.

Preparación

• Python 3.10+ con pip install pydantic pyyaml pillow edge-tts imageio-ffmpeg, o ejecutar mediante uv run (dependencias automáticas).
• <skill-dir> = carpeta donde se encuentra este SKILL.md. Todos los comandos: python <skill-dir>/scripts/vengine_cli.py <comando> ... (en Windows se puede usar py en lugar de python).
• Ejecutar desde la carpeta de trabajo del usuario, no desde dentro de la carpeta del skill. El proyecto se guarda en ./video-projects/<slug>/ (cambiar con --home DIR o la variable VENGINE_HOME).

Flujo de trabajo

1. Recopilar el brief. Preguntar lo que no esté claro: tema, formato (A = historia, B = guía paso a paso, S = corto 30–60 segundos), duración, style visual (predefinidos: claymation, flat-vector, 3d-pixar, anime-ghibli, cinematic-realistic, watercolor, comic-book, dark-moody, o descripción personalizada libre), audiencia, angka_kunci (cifras clave), y específicamente para el formato A los personajes (protagonista, antagonista o comparador, secundarios). Preguntar también por llamadas a comentarios/suscripción e instrumentos financieros que se puedan mencionar. No inventar cifras clave; los números provienen del usuario o de cálculos que tú mismo escribas la fórmula.
2. Leer references/panduan-naskah.md antes de escribir nada. Es la fuente de verdad sobre estilo, técnica y reglas de números/afirmaciones.
3. Crear el proyecto. init <slug> --topic "..." --format A|B|S --minutes N --style <style>, completar brief.yaml con el usuario, luego build <slug> (crea la biblia de la historia y el esquema de escenas).
4. Escribir por beat (repetir hasta que todos los beats estén completos):
   1. beat <slug> muestra la tarea para el siguiente beat: brief, personajes, tres escenas anteriores, puntos de contenido, palabras objetivo por escena y condiciones de etiqueta.
   2. Escribir el JSON de la escena en video-projects/<slug>/draft/<beat>.json. El campo image_prompt debe estar en inglés para cada escena (ya que todas las escenas se renderizan full-screen).
   3. add <slug> --beat <id> --file video-projects/<slug>/draft/<id>.json.
   4. Si hay error, el beat no se guarda. Corregir el JSON según el mensaje y volver a add. Si el beat necesita reescribirse después de guardado, añadir --replace. No usar --force a menos que el usuario lo solicite.
5. Verificar. status <slug> para el progreso, lint <slug> para una revisión completa. Los errores deben ser cero antes de presentar el guion como final; las advertencias se leen y se deciden junto con el usuario.
6. Mapear páginas visuales. Ejecutar map-pages <slug> para asignar automáticamente page_type y props siguiendo el catálogo references/design-video.md.
7. Exportar. export <slug> genera:
   • video-projects/<slug>/out/naskah.md (guion canónico por acto)
   • video-projects/<slug>/out/prompts.json (prompts de ilustración full-screen listos para generar, para todas las escenas, con personajes y estilo)
   • video-projects/<slug>/out/naskah.srt (subtítulos con marcas de tiempo)
8. Generar activos de imagen AI full-screen. Ejecutar generate-images <slug> (se puede añadir --style <style>, --scene <número> para regenerar una escena, o --force para sobrescribir todo) para descargar imágenes AI full-screen (Pollinations Flux) en video-projects/<slug>/out/images/scene_XXX.png.
9. Renderizar video MP4 (opcional/solo si se solicita). Ejecutar render <slug> (se puede añadir --voice id-ID-ArdiNeural o id-ID-GadisNeural, así como --fps 12 para estilo stop-motion claymation) para combinar imágenes de fondo full-screen (con movimiento stop-motion / Ken Burns, viñeta, superposición de vidrio esmerilado para números/remates y subtítulos karaoke), audio de voz en off en español, en video-projects/<slug>/out/video.mp4.

Formato JSON de escena

{"scenes": [
  {"narration": "Estrategia número uno: el dinero debe separarse al principio.",
   "tags": ["SECTION"], "image_prompt": "clean modern workspace with warm morning sunlight beams", "characters": [], "mood": "warm", "notes": ""},
  {"narration": "Si cada día apartas veinte mil rupias, en un mes se acumulan seiscientas mil rupias.",
   "tags": ["CALC"], "image_prompt": "neatly stacked glass savings jars with glowing coins on wooden desk",
   "motion_prompt": "Stop-motion claymation, slow subtle push-in camera, soft ambient light flicker", "characters": [], "mood": "neutral",
   "notes": "20.000 x 30 = 600.000"}
]}

• narration: lista para ser leída, de 15 a 35 palabras. Las escenas PUNCH y SECTION tienen un máximo de 14 palabras y son autónomas.
• tags: PUNCH, BRIDGE, SECTION, CTA, NUMBER, CALC. Las condiciones por beat se indican en la tarea de beat.
• image_prompt: en inglés, sin texto ni números dentro de la imagen; se recomienda rellenarlo en cada escena para que el fondo full-screen sea contextual (si es null, el motor genera automáticamente un prompt contextual para el fondo).
• end_image_prompt (opcional): en inglés para el End Frame si la escena tiene una transición que cambia objetos/iluminación (por ejemplo, pulsar un interruptor de luz de oscuro a claro; se genera con la misma seed).
• motion_prompt (opcional): instrucciones de movimiento por escena (por ejemplo, zoom_flicker, bobbing, switch_light para animación stop-motion claymation).
• characters: ID de personaje de la biblia de la historia (por ejemplo, protagonista), no el nombre.
• mood: tense, neutral, warm, uplift, melancholy.
• notes: obligatorio incluir la fórmula A x B = C para escenas CALC/NUMBER; escribir también la fuente de la afirmación.

Reglas que no se deben violar

• Escribir contenido original. No copiar ni parafrasear videos o transcripciones de referencia; solo se toman la estructura y la técnica.
• Recalcular todos los números. La línea de tiempo hacia el objetivo numérico debe ser explícita y honesta.
• Sin estadísticas sin fuente ("el 90% de las personas..."), sin promesas de resultados. Los instrumentos financieros son solo ejemplos y deben ir acompañados de una frase de exención de responsabilidad.
• El contenido de ficción (formato A) debe etiquetarse como "historia ilustrativa".
• No modificar beats.json ni scenes.json manualmente; usar add para que la validación y la renumeración de escenas se mantengan.

Resolución de problemas

• Módulo 'pydantic' no instalado → pip install pydantic pyyaml o usar uv run.
• Proyecto ... no encontrado → verificar la carpeta de trabajo; el proyecto está en ./video-projects/ en la carpeta donde se ejecuta el comando, o en --home.
• Lint mirip_referensi (similitud con referencia) → colocar la transcripción de referencia como .txt en ./references/ (o --refs DIR); reescribir las partes reportadas con tus propias palabras.
• Lint total_kata (total de palabras) → añadir o eliminar escenas en el beat que se desvíe del objetivo (consultar status), luego add --replace.