nandinishukla/talking-head-short

Talking-head → short 9:16 finalizado

El pipeline toma una grabación en bruto (más un archivo de audio limpio opcional) y la convierte en edit/final.mp4 (1080×1920, 60 fps, H.264 + AAC 48 kHz). También escribe cuatro pistas completas y un informe. Todo ocurre en código, instalado localmente dentro del proyecto: ffmpeg, Python, Node y HyperFrames. Sin instalaciones a nivel de sistema ni aplicaciones de edición.

• El estándar: references/brief.md es el pliego de condiciones completo, con todos los números para niveles, geometría, tiempos, tipo y color. Cuando este archivo y el brief discrepen en un número, el brief tiene prioridad.
• Leer antes de empezar: references/lessons.md cubre las trampas que costaron horas en la primera ejecución.
• Perfil de sonido: references/sound-profile.md contiene el estilo de efectos de sonido y niveles del creador, medidos a partir de su propia edición.
• Biblioteca de movimiento: references/motion-library.md contiene las referencias de movimiento seleccionadas por el usuario, el aspecto que siguen los gráficos.
• Ejemplos: references/examples/ contiene los gráficos del primer short (r1–r9 más cta). references/example-report.md es un informe completo.

Pregunta primero al editor las preguntas de estilo (paso 0b), luego trabaja de forma autónoma excepto por una parada deliberada: la aprobación del storyboard en el paso 7. Entre esos dos puntos, no preguntes nada al usuario: toma cada decisión (elección de toma, diseño, desacuerdo factual, UI inalcanzable), continúa y regístralo para el informe. La aprobación del storyboard es el único punto donde esperas al usuario. Solo detente si faltan archivos de entrada o son ilegibles.

Diseño de un proyecto

<proyecto>/RAW.MP4 (+ audio limpio si lo hay)
<proyecto>/edit/
  project.json        # cada decisión por video vive aquí (tomas, ejecuciones, subtítulos, portada…)
  tools/              # bin/ffmpeg, bin/ffprobe, venv/, node_modules/ (setup.sh)
  work/               # todos los intermedios (gfx/ es el proyecto HyperFrames)
  stems/  final.mp4  final_master.wav  REPORT.md

Todos los scripts se ejecutan desde edit/ con export PATH="$PWD/tools/bin:$PATH" y PY=tools/venv/bin/python. $S a continuación es la carpeta scripts/ de este skill.

Pasos

0. Configuración y sondeo

bash $S/setup.sh <proyecto>. Luego ffprobe -show_streams el archivo de cámara y anota:

• el tamaño y la rotación (las fuentes en vertical a menudo llegan en horizontal con un flag de −90°);
• los fps;
• la disposición de audio.

Decodifica una vez en un intermedio orientado. No vuelvas a decodificar 4K para cada paso: ffmpeg -i RAW.MP4 -an -vf scale=1080:-2 -c:v libx264 -crf 13 -g 15 work/cam1080.mp4 Usa scale=-2:1080 para una fuente en horizontal. Ejecuta comandos largos en segundo plano: unos 6 min por cada 90 s de 4K en un Mac de 8 GB.

0b. Preguntas de estilo (pregunta una vez, antes de cualquier trabajo)

Pregunta a la persona que edita el video, en UNA ronda de preguntas (usa la herramienta de preguntas cuando la tengas), por las elecciones que solo ellos pueden hacer. Omite cualquier cosa que ya hayan dado y registra las respuestas en project.json → "intake":

1. Subtítulos: el estilo pequeño habitual, "small_style": "pill" (videos tranquilos y generales) o "mono" (máquina de escribir, videos de tecnología/AI/desarrollo); más si usar hero (momentos clave con el gancho y líneas importantes solo con ellos en pantalla).
2. Color de acento: del tema (el color de marca del producto principal; lo investigas tú), combinado con su ropa, o un hex que ellos nombren → "accent".
3. CTA: "cta_style": "box" o "pill", la palabra clave del comentario, y el texto del chip de enlace para la píldora (p.ej. "Gratis en GitHub · propietario/repo").
4. Música: "music": {"mode": "synth" | "file" | "none"} (+ la ruta del archivo).
5. Título de portada: el suyo, o escrito a partir del gancho.

Ofrece valores predeterminados sensatos en las opciones (por ejemplo, el color de marca del tema; pill + hero para videos generales, mono + hero para los de tecnología; el otro estilo de CTA de su último video), para que responder lleve segundos. Si nadie puede responder (una ejecución desatendida), usa esos valores predeterminados y dilo en el informe.

1. Sincronización y transcripción

1. $PY $S/analyze_audio.py <cámara> [audio_limpio] correlaciona a 16 kHz e informa el desfase y la relación de pico. Escribe la fuente de voz en la línea de tiempo de la cámara, la envolvente RMS de 10 ms, el recuento de muestras recortadas y el suelo de ruido. Sin archivo limpio, usa la pista de la cámara y debes decirlo en el informe.
2. $PY $S/transcribe.py medium.en "Nombres de productos, personas, @handles" lista cada palabra con espacios de más de 250 ms marcados.
3. Vuelve a ejecutar analyze_audio.py para que la lista de estiramientos silenciosos muestre las palabras vecinas.
4. Agrupa las palabras en tomas por línea. Para cada línea, conserva la última toma completa. Usa una anterior solo si la última tiene un defecto audible (tartamudeo, palabra recortada o incorrecta, reinicio). Elimina reinicios, autocorrecciones, "vale", sílabas sueltas y murmullos después de las tomas, más el silencio al principio y al final.

2. El corte

Escribe project.json → "lines": [[etiqueta, inicio_src, fin_src], …] con bordes aproximados alrededor de cada toma conservada, en orden de entrega. Las líneas contiguas pueden compartir un rango. Luego:

1. $PY $S/cut.py maneja los inicios/finales verdaderos (−35 dB / −32 dB durante 150 ms), pausas de más de 250 ms → 120 ms, un preámbulo de 40 ms, un adelanto de 50 ms para el J-cut de audio, colas que se desvanecen dentro del espacio, cortes de imagen cuantizados por fotograma y FIN.
2. $PY $S/check_joins.py: cualquier unión con un estiramiento silencioso de más de 150 ms recibe un "gap_overrides": {"<segmento>": -0.0333} negativo. Vuelve a ejecutar cut.py. Nunca añadas silencio.

3. Contacto visual

Haz un proxy pequeño (scale=-2:540), luego $PY $S/eyesheet.py work/proxy.mp4 y mira work/eye/*.jpg. Añade pasos de 100 ms alrededor de cualquier giro de cabeza. La cámara solo muestra mientras el hablante está mirando al objetivo. Si miran hacia otro lado a mitad de línea, divide en el límite de la palabra antes del giro y haz el resto completamente visual.

4. Planificar las ejecuciones (antes de cualquier gráfico)

$PY $S/plan.py imprime los tiempos de corte de imagen. Escribe "runs": [[inicio_ms, fin_ms, diseño, "R1 hook"], …] cubriendo [0, FIN] (usa "END" para el último fin), luego vuelve a ejecutarlo. Valida las reglas:

• el gancho es un split y el outro (desde CTA en adelante) es cámara completa;
• ninguna ejecución dura más de unos 8 s y las vecinas nunca comparten diseño;
• se usan los tres diseños.

Elige diseños según el contenido:

• opiniones e historias directas a cámara → cam;
• una captura de pantalla, tarjeta, fila de logotipos o lista corta → split;
• grabaciones de pantalla, páginas de noticias, UI de producto que necesita zoom → visual.

Pon los límites en los cortes de imagen. plan.py luego imprime las palabras de cada ejecución con tiempos relativos a la ejecución; sincroniza los gráficos con esos tiempos.

5. Investigación y capturas

Para cada producto nombrado y cada afirmación (lanzamiento, cita, número), encuentra la fuente real y verifica los datos contra dos o más fuentes reputadas. Anota cualquier desacuerdo para el informe.

• Captura páginas reales con node $S/shot.mjs <url> <out.png> 1280 1400 0, ejecutado desde edit/. Encuentra el chrome-headless-shell de HyperFrames por sí mismo. Respeta el robots.txt y los términos de cada sitio: captura las páginas que citas, no hagas crawling.
• Los repositorios a menudo incluyen un GIF de UI o capturas de pantalla en docs/; reconstruye la UI a partir de esos.
• Una UI detrás de inicio de sesión se reconstruye a partir de capturas de pantalla públicas o docs y se anota en el informe.
• "Claude Code" significa la UI de la aplicación de escritorio de Claude a menos que el hablante esté hablando del terminal.

6. Subtítulos y portada (planificados ahora, porque el storyboard los muestra)

$PY $S/captions.py work/cam1080.mp4 (el video de cámara es para el color hero). Establece "small_style": "mono" para videos de tecnología / herramientas de AI / desarrollo / explicación de productos (cualquier cosa con terminales, código o pantallas de app), o "pill" para videos generales y de estilo de vida. Sin "captions.chunks" imprime un borrador automático (el estilo pequeño en todas partes, un hero redactado en el gancho). Edítalo y pégalo de vuelta. Hay tres estilos:

• mono [a, b, "mono", [palabra acento]]: 1–3 palabras, una máquina de escribir de terminal. VT323 en mayúsculas sobre una caja casi negra que crece a medida que se escriben las letras (30 letras/s), una palabra clave significativa sobre un bloque sólido de acento, y un cursor de bloque de acento (constante mientras escribe, parpadeando después). assemble.py lo escribe fotograma a fotograma.
• pill [a, b, "pill"]: 1–3 palabras, Poppins Bold pequeño sobre una caja redondeada oscura translúcida: el estilo pequeño más tranquilo para videos no técnicos.
• hero [a, b, "hero", [índices de palabras grandes]]: 2–5 palabras con 1–2 palabras ENORMES sólidas (Archivo Black) entre palabras pequeñas arriba y abajo, que siguen el estilo pequeño del video (píldoras o cajas mono estáticas). El color de la palabra grande coincide con la ropa del hablante: captions.py work/cam1080.mp4 muestra el torso en el primer fotograma hero e imprime el color que eligió. Tiene un contorno profundo del mismo tono para que se lea sobre esa ropa. Sobrescribe con "hero_color": "#RRGGBB" si la selección es incorrecta (estampados ocupados, una chaqueta sobre una camisa). Úsalo en el gancho y en líneas importantes donde solo el hablante esté en pantalla (cámara completa o la tarjeta en un split), nunca sobre un gráfico y nunca dos seguidas. Elige palabras que transmitan el significado (la afirmación, el número o el beneficio), nunca palabras funcionales.

Establece "cover": [línea1, línea2] (escríbelo a partir del gancho si el usuario no dio ninguno, unas 14 caracteres por línea a 110 px). Establece el centro de la píldora por diseño en "y" y el centro del bloque hero en "hero_y".

• Los subtítulos nunca deben estar sobre la cara, el borde de la tarjeta o un visual.
• Con una fuente vertical, el espacio del split es la cara, así que pon las píldoras aproximadamente a y 1660 sobre el torso y verifica el outro en un fotograma real.
• assemble.py compone ambos estilos.

7. Storyboard y tabla de ritmos: PARADA para aprobación

Nada se renderiza hasta que el usuario haya visto y aprobado el plan.

1. Elige referencias de movimiento para cada ritmo gráfico de references/motion-library.md (el aspecto seleccionado por el usuario). references/motion-prompts.md contiene los textos completos de los prompts (acreditados a sus creadores); lee el bloque de cada id citado. Nunca raspes galerías de terceros. Las entradas de la biblioteca fueron añadidas por el usuario, y algunos sitios, p.ej. prompt-motion.com, bloquean los rastreadores de AI.
2. Elige el color de acento del video a partir de lo que se está enseñando: el color de marca del producto principal (logotipo, botón primario), si no, un color que se adapte al tema. Escribe "accent": {"color": "#RRGGBB", "why": "..."} y ejecuta $PY $S/accent.py. Escribe work/gfx/assets/accent.css (relleno de acento, un tono de texto 4.5:1 y un tinte de banda claro), que cada composición recoge a través de base.css. Nunca codifiques valores hex de acento en composiciones: usa var(--clay), var(--clayText) y var(--band). El color del subtítulo hero es independiente (viene de la ropa).
3. Escribe "beats" en project.json, uno o más por ejecución: {"run": "R1", "t": 0.0, "visual": "...", "camera": "...", "sfx": "...", "refs": ["id"], "source": "captura real / UI reconstruida / logotipo"}. Opcionalmente añade "storyboard_notes": {"R1": "por qué este diseño"}.
4. $PY $S/storyboard.py work/cam1080.mp4 escribe work/storyboard.html: un boceto 9:16 por ejecución (zonas de diseño, el fotograma del hablante, el gráfico, estilo y posición de subtítulos) y la tabla de ritmos (tiempo, ejecución, diseño, palabras exactas, acción en pantalla, movimiento de cámara, SFX, estilo de subtítulos con cada momento hero, referencias de movimiento, fuente).
5. Muéstralo al usuario (la página muestra la muestra de acento y por qué se eligió): publícalo como un artefacto, o envía el archivo, y da una línea sobre qué mirar. Luego termina tu turno y espera. Aplica sus cambios a project.json, regenera y muéstralo de nuevo. Continúa solo con una aprobación clara.

8. Gráficos (HyperFrames)

1. Copia assets/engine.js, assets/base.css, assets/accent.css, assets/fonts/ y assets/motion/ en work/gfx/assets/ (luego vuelve a ejecutar accent.py para que el acento por video reemplace el predeterminado), más hyperframes.json de hyperframes init.
2. Escribe un work/gfx/compositions/<clave de ejecución en minúsculas>.html por cada ejecución split/visual. Su data-duration debe igualar la ejecución exactamente.
3. Construye exactamente lo que muestra el storyboard aprobado, coincidiendo con las referencias de movimiento de cada ritmo. Empieza desde el ejemplo más cercano en references/examples/:
   • r1, r3, r5, r7: mundos split con pasos y empujes;
   • r2: bloqueo de logotipo, luego un látigo a una captura real en el marco fijo sobre su clon lavado;
   • r4, r6, r9: ventanas de producto donde solo la cámara interior se mueve;
   • cta: la tarjeta de comentarios transparente (CTA estilo A); cta_pill.html: la píldora de comentarios (CTA estilo B);
   • motion/*.html: una demo por componente de movimiento (cursor, glass, morph, flood + iris, maskrise, kinetic, wall, whip; explain-flow, explain-callout, explain-status, explain-loop); ver "Componentes de movimiento" y "Componentes de explicación" más abajo.

Cómo funciona el motor y las reglas que importan:

• E.run(id, dur, render) registra una línea de tiempo en pausa. render(t) debe ser una función pura de t.
• E.path da los fotogramas clave de la cámara mundial. E.camera los aplica y desenfoca el viewport a lo largo de la velocidad de pantalla (σ = 0.29·v·0.75/60, ≤ 40 px, cero en reposo y en t = 0).
• E.track y E.land animan propiedades por objeto (opacidad, x, y, escala, desenfoque). Profundidad de campo: vecinos hasta 14 px de desenfoque y 70% de opacidad; el antiguo hero 9 px y 40%.
• Movimientos de cámara:
  • deslizamiento: sine.inOut, cambio de escala ≤ 0.04;
  • paso: 0.5 s power3.inOut, comenzando 0.25 s antes de la palabra que nombra el siguiente elemento;
  • empuje: 1.2–2 s power2.inOut, hasta aproximadamente 1.6×;
  • retroceso: 1–2 s;
  • látigo: como máximo uno por ejecución, 0.45 s de salida power3.in, 0.6 s de entrada power3.out.
• El fotograma 0 es el estado de aterrizaje, nítido, con la cámara en reposo.
• Mientras una ventana de producto es el sujeto, solo la cámara dentro de la ventana se mueve (1.15–1.4×, 0.4–0.7 s power2.inOut).
• Zonas de contenido:
  • los splits mantienen el contenido en y 40–900, y el mundo se desvanece desde y 900;
  • los visuales mantienen el contenido por encima de y 1230;
  • en el fotograma 0, el gráfico de introducción permanece por debajo de y 620 (la portada está encima).
• Estilo visual:
  • un sujeto escaso por escena;
  • Poppins y nada por debajo de 30 px;
  • suelo radial casi blanco y la sombra de tres capas;
  • nada oscuro, sin cuadrícula;
  • anima la acción, nunca la etiquetes.
• Cada evento visiblemente digno de sonido va en el <script type="application/json" id="events"> de la composición (pop / click / chime / thud para iconos que aterrizan / flash para destellos blancos / whoosh en el punto medio del látigo / keys / ticks, relativos a la ejecución). El paso de audio los lee, por lo que los SFX siempre caen en sus …

… [truncado para la traducción]