vincesector/talking-head-pipeline

/dynamic-edit

Un talking head que nunca se mueve está muerto a la llegada; uno que se mueve sin razón es peor. Este pipeline decide qué efecto se gana su lugar en qué palabra, lo escribe como un plan que el humano puede vetar, y solo entonces gasta cómputo.

Raíz del repositorio:

THP_HOME=${THP_HOME:-$(cat ~/.config/talking-head-pipeline/root)}

Leer antes de planificar: $THP_HOME/docs/STYLE_RULES.md (las reglas de artesanía), $THP_HOME/docs/LAYOUTS.md (geometría y zonas seguras de subtítulos), references/plan-format.md (el esquema), references/qa.md (las compuertas). 3D: $THP_HOME/docs/3D.md.

Contrato de entrada: el metraje ya está cortado. Sin eliminación de silencios, sin pase de relleno aquí. Una toma cruda va a /autocut primero; regresa con su clean.mp4 y su directorio de trabajo (para palabras textuales).

Nunca te saltes el paso del plan. La rotoscopia cuesta unos 12 minutos por minuto de metraje y un renderizado completo decenas de minutos. Una suposición equivocada atrapada en un plan de texto no cuesta nada.

Flujo de trabajo

1. Andamiar el proyecto

P=<directorio de proyectos>/<slug>          # preguntar dónde guarda el humano los proyectos de video; nunca en el Escritorio
cp -R "$THP_HOME/template" "$P"
cd "$P"
uv venv --python 3.11 .venv                 # mediapipe no tiene ruedas más allá de 3.12
uv pip install --python .venv/bin/python "mediapipe==0.10.21" opencv-python backgroundremover numpy pillow
scripts/download_models.sh                  # detector de rostros MediaPipe (no incluido en el repositorio)
(cd remotion && pnpm install)              # o npm install
cp "<directorio de trabajo autocut>/clean.mp4" remotion/public/raw.mp4
python3 "$THP_HOME/scripts/autocut/verbatim_cut_words.py" "<directorio de trabajo autocut>" -o remotion/public/words.json

Reel vertical desde una toma 16:9: scripts/prep_vertical.sh "<directorio de trabajo autocut>" "$P" en lugar de las últimas dos líneas (recorte 9:16 estático en la x mediana de la cabeza, nunca un recorte que sigue).

2. Inventario, cortes, seguimiento

ffprobe -v error -select_streams v:0 -show_entries stream=width,height,r_frame_rate,nb_frames \
  -show_entries format=duration -of default=nw=1 remotion/public/raw.mp4
.venv/bin/python scripts/detect_cuts.py remotion/public/raw.mp4 --out remotion/public/cuts.json
.venv/bin/python scripts/track_head.py remotion/public/raw.mp4 --out remotion/public/track.json --cuts remotion/public/cuts.json

• Espacio para zoom = ancho de fuente / ancho de línea de tiempo (2560 en 1920 = 1.33x gratis). Más allá de eso, se escala hacia arriba.
• El aspecto se detecta automáticamente desde el ancho/alto del plan (perfiles lib/layouts.ts). Un motor, nunca una bifurcación.
• Lee detectionRate en track.json. Por debajo de ~0.9, los movimientos anclados al rostro no son fiables; dilo.
• La detección de cortes omite los cambios graduales (un cambio animado a una pantalla compartida). Toma una muestra por segmento y agrega los límites omitidos a cuts.json manualmente. Los segmentos de pantalla compartida no reciben zooms, no se dibujan subtítulos sobre ellos, no reciben tarjetas (establece captions.silence para esos rangos).

3. Revisar las palabras

Busca en words.json cada nombre propio, marca, ticker y persona que el guión nombra. Los modelos de la familia Whisper los distorsionan y la frase aún se lee con fluidez, por lo que la revisión nunca lo detecta. Corrige el archivo de palabras (fusionar dos tokens en uno está bien), nunca el renderizado. Números como dígitos.

4. Escribir el plan, luego PARAR

1. Lee primero la transcripción completa. Encuentra los momentos que la narrativa realmente tiene: gancho, afirmación, número, giro, revelación, remate, el momento que es mejor mostrar que contar.
2. Elige una herramienta por momento de Elegir efectos a continuación. Muchos momentos no reciben nada.
3. Copia scripts/build_plan.example.py a scripts/build_plan.py y escribe los momentos allí con anclas de palabras ("frase@segundos"). Esto escribe remotion/plan.json y los subtítulos. Rechaza eventos sin razón, sin anclas de palabras para entrada Y salida, o zooms demasiado juntos.
4. Muestra al humano una tabla, una fila por evento: tiempo, efecto,