Talking-head reels

¿Qué hace Talking-head reels?

Conviertes una grabación de una persona hablando a cámara en un reel vertical terminado (MP4). El estilo es editorial y rápido: el orador es la columna vertebral del video, y cada 2-4 segundos el cuadro cambia: un zoom, una palabra grande, un inserto de B-roll, una pantalla dividida, siempre impulsado por lo que se dice en ese momento.

La mecánica está guionizada: cortar pausas, masterizar la voz, máscaras, y un renderizador que dibuja cada fotograma directamente desde una lista de decisiones de edición (EDL). Tu trabajo es la parte editorial: entender el parlamento, decidir cómo debería verse cada compás, encontrar o generar material que encaje, escribir la EDL, revisar los fotogramas y ejecutar las rondas de revisión con el usuario.

Requisitos

macOS (destino de renderizado nativo) - Python 3.9+ con numpy y faster-whisper, ffmpeg con libass (Homebrew ffmpeg o imageio-ffmpeg). Opcional: herramientas de línea de comandos de Xcode (máscaras Apple Vision).

Windows 10/11 (caja de renderizado): el motor de renderizado es multiplataforma. Python 3.9+ con numpy y faster-whisper más una compilación de ffmpeg que incluya libass (compilación "completa" de gyan.dev) es suficiente. Luego use los sustitutos gratuitos incluidos en assets/fonts/win/ (Playfair Display 400/700/italic + Inter Medium, licencia OFL):

1. configure la variable de entorno de usuario una vez: REEL_FONT_FILES = las cuatro rutas .ttf, separadas por punto y coma. El motor las recoge a través de su propio hook REEL_FONT_FILES (textass.py) y extrae los rostros en la carpeta de libass;
2. ponga la anulación de fuentes EDL incorporada en cada EDL: "fonts": {"anton": "Anton-Regular", "serif": "PlayfairDisplay-Bold", "didot": "PlayfairDisplay-Regular", "sub": "Inter-Medium"} (el mapa predeterminado en reel_plan.py no se toca: las EDL de macOS no necesitan anulación);
3. Las máscaras de recorte de Apple Vision no existen en Windows: omita esos compases. python scripts/check_setup.py informa resultados conscientes de Windows.

Sin créditos involucrados: el B-roll proviene del material del usuario y de bibliotecas gratuitas (conectores Pixabay / thesvg MCP, Wikimedia Commons); el apéndice de generación paga (Higgsfield / Seedance) es solo para solicitudes explícitas.

Lo que entregas

• PROJECT/render/<nombre>_vN.mp4 - 1080x1920, H.264, AAC 320 kbps, voz a aproximadamente -14 LUFS.
• PROJECT/edl.json (y copias edl_vN.json por ronda) - toda la edición como datos; volver a renderizarlo siempre da el mismo video.
• Imágenes de control de calidad para revisión (PROJECT/qa/.../sheet.jpg).

Paso 0 - configuración y admisión

Ejecute python3 scripts/check_setup.py (las rutas en este archivo son relativas a la carpeta de la habilidad) y solucione lo que informe. Use el mismo Python para cada script; un entorno virtual con numpy faster-whisper imageio-ffmpeg es la ruta fácil. El ffmpeg debe incluir libass (todo el texto se dibuja con él); la verificación dice qué binario encontró.

Luego asegúrese de saber (pregunte solo lo que falta, un mensaje corto):

1. La grabación (ruta). Idealmente 4K horizontal o 1080x1920 vertical, orador aproximadamente centrado.
2. El idioma, y el guion si lo tienen (ayuda a detectar palabras de relleno y transcripciones incorrectas).
3. La corrección de color: archivo ya corregido, un LUT .cube o "usar el color de la cámara".
4. La llamada a la acción al final (ej. "comenta PALABRA y te envío el enlace").
5. De dónde puede venir el B-roll: su propio material (predeterminado), material de archivo gratuito (Pixabay MCP, Wikimedia Commons), logotipos/iconos a través del conector thesvg MCP (alternativa a representaciones PNG de Commons). Pregunte qué derechos tienen. Generación AI paga (Higgsfield / Seedance) solo si lo solicitan explícitamente.
6. Dónde mantener la carpeta del proyecto (predeterminado: junto al video, <nombre>_reel/).

Paso 1 - preparar y analizar (con script)

python3 scripts/prepare_project.py VIDEO.mov [--graded GRADED.mov | --lut grade.cube] [--project DIR]
python3 scripts/transcribe.py DIR [--language en] [--model small|medium|large-v3]
python3 scripts/cut_pauses.py DIR [--remove 2.40-2.72 ...]
python3 scripts/master_audio.py DIR
python3 scripts/presenter_mattes.py DIR        # necesita swiftc; omitir solo si no está disponible

cut_pauses.py imprime cada segmento conservado con sus palabras. Léalo contra la transcripción: elimine falsos comienzos, tomas repetidas y palabras de relleno con --remove inicio-fin (segundos de origen) y ejecútelo de nuevo. Informe al usuario cuánto se eliminó (ej. "81.5 s -> 73.4 s"). Los pasos posteriores usan todos la línea de tiempo del programa (analysis/program_words.json).

Paso 2 - planificar la edición (tu criterio)

Lea references/style-guide.md (el aspecto y las reglas) y references/edit-planning.md (cómo convertir un discurso en compases), luego escriba una hoja de compases: una fila por compás con tiempos del programa, las palabras habladas, lo que está en pantalla (presentador ancho/apretado, tipo de inserto, diseño), el tratamiento del texto y la idea del material. Muéstrela al usuario antes de buscar material: es barato cambiarla ahora y caro después.

Paso 3 - material de archivo

Siga references/broll-sourcing.md: qué buscar, de dónde puede venir, licencias y las recetas de recuperación gratuita probadas (búsquedas en Pixabay MCP + verificación de URL, API de Wikimedia Commons + curl UA/reintentos + comprobaciones SHA-1, conector thesvg MCP para logotipos, transcodificaciones de ffmpeg). La generación paga (Seedance a través de Higgsfield) está en el apéndice, solo cuando el usuario solicite explícitamente tomas generadas por IA y apruebe el costo. Ponga todo en PROJECT/broll/ y los logotipos en PROJECT/logos/. Revise los candidatos con scripts/clip_sheet.py. Si el usuario ya tiene clips o insertos, úselos: no busque de nuevo lo que ya existe.

Paso 4 - EDL y validación

Escriba PROJECT/edl.json siguiendo references/edl-schema.md (un ejemplo completo de trabajo, el reel sobre el que se construyó este estilo, está en assets/examples/example_edl.json). Luego:

python3 scripts/validate_edl.py DIR/edl.json

Corrija todos los errores; lea todas las advertencias y corríjalas o acéptelas conscientemente.

Paso 5 - imágenes fijas, luego el renderizado

python3 scripts/render_reel.py DIR/edl.json --stills 0.6 2.4 4.8 ... --out-dir DIR/qa/stills_v1
python3 scripts/render_reel.py DIR/edl.json --out DIR/render/<nombre>_v1.mp4

Las imágenes fijas toman segundos: elija un momento dentro de cada compás, más la mitad de cada transición, y verifique la hoja de contactos con la lista de verificación en references/style-guide.md (sin bordes vacíos, palabras legibles y dentro del encuadre, nada sobre los ojos, texto en la pila central, tratamiento de color correcto). Corrija la EDL y vuelva a verificar hasta que esté limpia. Luego renderice el reel completo (unos minutos en un Mac reciente; consulte references/renderer.md) y dé al usuario la ruta más los números que imprima el renderizador (tamaño, fps, duración, sonoridad).

Paso 6 - rondas de revisión (cómo quiere trabajar el usuario)

• El usuario envía notas una por una, a menudo capturas de pantalla con unas pocas palabras. Numérelas (1, 2, 3...), confirme brevemente y no cambie nada hasta que digan que han terminado ("empezar", "adelante", "eso es todo"). Luego aplíquelas todas en una sola pasada.
• Cada ronda es una nueva versión: copie edl.json a edl_vN.json antes de editar, renderice a <nombre>_vN.mp4. Nunca sobrescriba un renderizado o una versión de EDL que el usuario ya haya visto.
• Verifique los momentos cambiados con --stills primero, luego renderice el video completo una vez.
• Mantenga el mismo estilo en todas las rondas; cuando una nota implique una regla general ("sin bordes vacíos", "subtítulos más grandes"), aplíquela en todas partes, no solo en la captura de pantalla.
• Si el usuario quiere material diferente para una toma, cambie ese clip en la EDL (consulte "Intercambio de clips" en references/edl-schema.md) - nada más se mueve.

Otras herramientas

• scripts/render_reel.py --stills ... - cualquier momento, como PNGs más una hoja de contactos.
• scripts/clip_sheet.py - fotogramas y tiempos de corte duro de clips candidatos.
• references/renderer.md - cómo funciona el renderizador, velocidad, fuentes, solución de problemas.

Reglas básicas

• Material de archivo: use solo material sobre el que el usuario tenga derechos: propio, con licencia o de stock gratuito, o clips generados para ellos. Las personas generadas no deben parecerse a actores reales o celebridades, y no se pueden recrear personajes famosos, disfraces, logotipos o escenas de películas.
• Cada renderizado es un archivo nuevo. Nunca sobrescriba algo que el usuario haya revisado.
• Trabaje en inglés en los archivos del proyecto; hable con el usuario en su idioma.