vincesector/talking-head-pipeline

/autocut

Grabación cruda entra, archivo precortado y limpio sale. Tú ejecutas cada comando; el humano aprueba un plan y ve el resultado. Nunca le entregues una línea de comandos para ejecutar.

Raíz del repositorio (los scripts viven allí):

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

Alcance

Situación	Pipeline
Grabación cruda; silencios, errores y sincronía necesitan corrección	esta
Material ya cortado de una persona en cámara que debe sentirse dinámico	/dynamic-edit, alimentado con el clean.mp4 de este skill

Este skill no añade efectos, subtítulos ni gráficos. Produce el archivo que /dynamic-edit recibe como entrada. El encadenamiento es la ruta normal: /autocut luego /dynamic-edit.

Por qué funciona (explícalo así)

Dos hechos hacen que los cortadores automáticos ingenuos "mastiquen" palabras y se desvíen de la sincronía:

1. Los micrófonos inalámbricos y el software de captura entregan el audio adelantado o atrasado, en una cantidad que cambia entre sesiones (+240 ms se midió en una configuración). Por lo tanto, la sincronía se MIDE por archivo a partir del movimiento de los labios (SyncNet) y se aplica antes que cualquier otra cosa. Nunca predefinida.
2. Las marcas de tiempo de palabras de Whisper aterrizan en un límite real de palabra solo aproximadamente 2 de cada 12 veces. El relleno alrededor de un número incorrecto aún recorta palabras. Por lo tanto, cada palabra se vuelve a cronometrar con un alineador forzado, y al renderizar cada borde de corte se ajusta a la propia forma de onda.

Y un hecho hace que pasen por alto errores: Whisper suaviza las repeticiones. "Entonces hablemos de, entonces hablemos de lo que pasó" regresa como una oración limpia. Una segunda transcripción verbatim (CrisperWhisper) mantiene cada falso inicio, repetición y muletilla; los tropiezos y reinicios se encuentran en esa.

Flujo de trabajo

1. Encuentra el archivo, nunca lo modifiques

Usa el archivo que el humano nombró, o la grabación más reciente en su carpeta de captura (pregunta una vez dónde está). Confirma el nombre del archivo y la duración en una línea. El archivo crudo es de solo lectura durante todo el trabajo; cada salida va a <raw dir>/<raw stem>_autocut/.

2. Modo plan

python3 "$THP_HOME/scripts/autocut/autocut.py" "<raw.mp4>"

La detección de sincronía es la parte lenta (de 3 a 10 minutos, más en una máquina ocupada o Linux solo CPU). Dilo antes de empezar. El resto del modo plan dura aproximadamente un minuto una vez que los modelos están en caché; la primera ejecución por idioma descarga modelos (varios minutos). Añade --lang en|pt|it|es|fr|de|nl solo si el idioma detectado es incorrecto. --offset SEGUNDOS omite la detección cuando el offset ya se conoce; --no-sync para grabaciones de solo pantalla sin rostro.

Si la detección falla (sin rostro, baja confianza), el script lo dice y continúa con offset 0. No inventes un número. Dile al humano que no se pudo medir y pregunta: continuar sin sincronía, o usar un valor que te den.

3. Muestra el plan como tabla compacta, luego DETENTE

Lee plan.md del directorio de trabajo y preséntalo (nunca pegues el archivo crudo):

  Fuente     take-01.mp4   01:47.9
  Sincronía  +240 ms (audio adelantado), confianza 5.5, dispersión 0 ms
  Resultado  01:40.5 planeados, 7.3 s eliminados, 5 cortes

  00:00.0-00:02.8   corte   silencio 3.0 s       2.8 s
  00:23.6-00:24.9   corte   silencio 2.0 s       1.3 s

  Tropiezos (aplicados):  "entonces hablemos de, | entonces hablemos de"   conservar la segunda toma
  Reinicios (propuestos): 01:12.4 "habrá una pérdida en" x2 ...      comando apply_spans listado
  Propuestas de retoma (no aplicadas):
  1  01:45.9-01:47.0  "y entonces"  ->  conservar 01:47.0-01:48.1 "y entonces"

Señala en el mismo bloque: dispersión de sincronía superior a 40 ms o confianza inferior a 3.5; desplazamiento inicial de alineación p90 superior a 500 ms (la transcripción es inestable); cualquier fila de retoma marcada como bucle de decodificador de Whisper.

Las repeticiones y falsos inicios se cortan por defecto. Para eso está el pase palabra por palabra. La precisión aún supera a la recuperación: un corte incorrecto cuesta una regrabación, un tropiezo perdido cuesta un corte más. Las coincidencias seguras (repeticiones inmediatas, un abandono sin puntuación entre tomas) se aplican; las más dudosas se listan como candidatos reinicio?. Lee cada candidato en contexto. Veta cualquier cosa que sea una repetición retórica deliberada ("por debajo de 60, por debajo de 70, por debajo de 80"). Las muletillas (um, eh) se listan, nunca se cortan automáticamente. Conserva la ÚLTIMA toma; cuando hay una pausa entre dos tomas, la pausa marca dónde comienza la segunda toma.

Haz una pregunta: aprobar tal cual, o nombrar algo para devolver. Si una frase es ambigua, pregunta específicamente; no adivines. Nada se renderiza sin una respuesta.

4. Aplica las ediciones a partir de los números, nunca de memoria

• Acepta una retoma o reinicio por sus palabras, no por marcas de tiempo escritas:

  python3 "$THP_HOME/scripts/autocut/apply_spans.py" <workdir> --drop "[email protected]"   # frase más cercana a 22 s
  python3 "$THP_HOME/scripts/autocut/apply_spans.py" <workdir> --span 71.20:74.85     # del comando listado en plan.md
  

  Lee cada línea de contexto que devuelva.
• Vuelve a leer plan.json del disco antes de renderizar; el humano puede haberlo editado. Un plan editado después de un corte se recorta automáticamente.
• Las pausas guionizadas son contenido: un golpe deliberado ("y la respuesta es... [pausa] nada") va en plan.json como keep_silences: [[s, e]] (segundos de origen) para que el cortador nunca lo apriete.

5. Renderizar

python3 "$THP_HOME/scripts/autocut/autocut.py" "<raw.mp4>" --render

Lo que hace el renderizado, para que puedas explicar fallos:

• 09p tomas largas (más de 3 min): limita las pausas de más de 0.65 s a 0.30 s después del último sonido + 0.20 s antes del siguiente. Silencio aquí significa cada cuadro de 5 ms por debajo de -55 dB. Nunca eleves ese umbral: las colas de palabras decaen a través de -42..-55 dB y un umbral más alto se come las consonantes finales.
• 09a ajusta cada borde de corte fuera de las ráfagas de sonido y al menos 50 ms alejado del sonido que elimina; recorta el inicio y el final hasta la primera y última palabra real; corta ruidos de paréntesis ([UH], [chasquido de labios]) en espacios de 0.4 s o más.
• 09b mueve cualquier inicio conservado que tenga sonido fluyendo hacia él de vuelta al silencio (restaura un inicio recortado).
• El cortador descarta cualquier pieza de menos de 1 s sin sonido (una "astilla silenciosa" entre dos cortes brutos) e imprime CHECK pieza corta con sonido para piezas sub-1 s que conserva. Escucha cada una.

6. Verifica el corte (no opcional, en este orden)

1. qa.md ## Auditoría de intervalos eliminados primero. Cada espacio eliminado se verifica en busca de habla restante (energía + una transcripción aislada). Una fila MARCADA significa que el corte no se puede enviar: investiga (dB de ventana más fuerte primero, luego escucha qa/removed/spanNN.wav), corrige keep y vuelve a renderizar. Un fragmento solitario de una palabra con dB de ventana más fuerte BAJO suele ser un clic o respiración, no habla; confía en el número de energía sobre el texto de la transcripción. Las filas corte aprobado están bien.
2. Lee qa/verbatim_cut.txt de principio a fin, como un editor. Es la transcripción verbatim de CrisperWhisper DEL CORTE. Busca cualquier frase repetida, fragmento o retoma de oración completa que haya sobrevivido. Nunca verifiques un corte con una transcripción Whisper normal: oculta exactamente estos. Las retomas de oraciones completas dichas espalda con espalda después de una pausa solo se detectan así.
3. ## Reinicios aún en el corte y ## Recorte de bordes en qa.md: resuelve cada fila MARCADA (secuencias de números como "928 ... 939" pueden ser falsos positivos; léelos).
4. Comprobaciones que los scripts no pueden hacer:
   • duración de salida vs planeada: una delta superior a 0.6 s es un problema;
   • barre cada unión a 5 fps (cuadros 0.5 s a cada lado, desde timemap.json): ninguna unión sobre un desenfoque de gesto o un cuadro duplicado;
   • ninguna pausa interna superior a 1.0 s; ninguna pieza sin un cuadro por encima de -45 dB;
   • frecuencia de cuadros constante: los cuadros contados / duración del flujo deben ser iguales exactamente a los fps nominales (30.0000, no 29.98). Las grabadoras pierden cuadros bajo carga, y cada herramienta indexada por cuadros aguas abajo se desvía si esto está mal.

Vuelve a ejecutar solo el QA sin recortar: autocut.py --qa-only --workdir <dir>.

Abre clean.mp4 para el humano (open en macOS, xdg-open en Linux).

7. Informa y entrega

Lo que se eliminó (tabla), dónde está clean.mp4, y una línea: esta es entrada precortada; di "hazlo dinámico" para continuar con /dynamic-edit. Los subtítulos para la siguiente etapa provienen de las palabras verbatim, mapeadas en la línea de tiempo del corte:

python3 "$THP_HOME/scripts/autocut/verbatim_cut_words.py" <workdir> -o words.json

8. Limpieza, solo cuando el humano diga que el video está listo

El directorio de trabajo contiene synced.mp4 (una copia completa de la toma) y piezas de tmp/ del renderizado. Pregunta antes de eliminar. plan.json, transcript.json, verbatim.json y qa.md son pequeños; consérvalos.

Reglas estrictas

• La compuerta del plan es obligatoria. Sin renderizar sin la aprobación del humano.
• Nunca predefinir un offset de sincronía. Mídelo por archivo, o usa uno que te dé el humano.
• El archivo crudo nunca se modifica.
• Verifica un corte con la transcripción verbatim del corte, nunca con una transcripción Whisper normal.
• Nunca fijes un borde generado automáticamente. _meta.pinned_edges es para bordes que un humano verificó contra la forma de onda; fijar bordes de máquina omite la verificación de espacio libre del ajustador y se come palabras.
• El silencio es solo por debajo de -55 dB. Nada entre -40 y -55 dB es silencio en un micrófono con compuerta.
• Ninguna pieza unida de menos de 1 s sin habla.
• Cuando una palabra o instrucción sea ambigua, haz una pregunta específica.

Errores comunes

• Whisper alucina segmentos vacíos sobre el tono de ambiente final, con marcas de tiempo más allá del final del archivo. Esperado; el buscador de retomas los filtra. Mil "retomas" en dos segundos al final es un bucle de decodificador, no retomas reales, y plan.md lo dice.
• La detección de sincronía necesita un rostro en pantalla. Grabación de solo pantalla: --no-sync, y dilo.
• Muchos micrófonos graban bajo (alrededor de -30 LUFS). autocut no normaliza. La sonoridad pertenece a la masterización final (scripts/master/sync_trim.sh --loudnorm); nunca la apliques en silencio.

Referencia completa etapa por etapa: $THP_HOME/docs/AGENT_GUIDE.md.