vincesector/talking-head-pipeline

/autocut

Enregistrement brut en entrée, fichier prédécoupé propre en sortie. Vous exécutez chaque commande ; l'humain approuve un plan puis regarde le résultat. Ne leur donnez jamais une ligne de commande à exécuter.

Racine du dépôt (les scripts s'y trouvent) :

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

Périmètre

Situation	Pipeline
Enregistrement brut ; silences, bafouillages et synchro à corriger	celui-ci
Images déjà coupées d'une personne à l'écran qui doivent être dynamiques	/dynamic-edit, alimenté par clean.mp4 de ce skill

Ce skill n'ajoute aucun effet, sous-titres ou graphiques. Il produit le fichier que /dynamic-edit prend en entrée. L'enchaînement est le chemin normal : /autocut puis /dynamic-edit.

Pourquoi ça marche (expliquez-le ainsi)

Deux faits font que les coupeurs automatiques naïfs « mastiquent » les mots et dérivent de la synchro :

1. Les micros sans fil et les logiciels de capture délivrent l'audio en avance ou en retard, d'une quantité qui change entre les sessions (+240 ms a été mesuré sur une configuration). Donc la synchro est MESURÉE par fichier à partir du mouvement des lèvres (SyncNet) et appliquée avant toute autre chose. Jamais codée en dur.
2. Les horodatages de mots de Whisper tombent sur une vraie frontière de mot seulement environ 2 fois sur 12. Un padding autour d'un mauvais nombre coupe quand même les mots. Donc chaque mot est retemporisé avec un aligneur forcé, et au moment du rendu chaque bord de coupe est accroché à la forme d'onde elle-même.

Et un fait les fait manquer les erreurs : Whisper lisse les répétitions. « Alors parlons de, alors parlons de ce qui s'est passé » revient comme une phrase propre. Une seconde transcription verbatim (CrisperWhisper) conserve chaque faux départ, répétition et tic de langage ; les bafouillages et redémarrages sont trouvés dans celle-ci.

Workflow

1. Trouver le fichier, ne jamais le toucher

Utilisez le fichier nommé par l'humain, ou l'enregistrement le plus récent dans son dossier de capture (demandez une fois où il se trouve). Confirmez le nom du fichier et sa durée en une ligne. Le fichier brut est en lecture seule pour tout le travail ; chaque sortie va dans <raw dir>/<raw stem>_autocut/.

2. Mode plan

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

La détection de synchronisation est la partie lente (3 à 10 minutes, plus sur une machine chargée ou Linux sans GPU). Dites-le avant de commencer. Le reste du mode plan prend environ une minute une fois les modèles mis en cache ; la première exécution par langue télécharge les modèles (plusieurs minutes). Ajoutez --lang en|pt|it|es|fr|de|nl uniquement si la langue détectée est erronée. --offset SECONDS ignore la détection lorsque le décalage est déjà connu ; --no-sync pour les séquences sans visage (capture d'écran uniquement).

Si la détection échoue (pas de visage, faible confiance), le script le dit et continue avec un décalage de 0. N'inventez pas de nombre. Dites à l'humain qu'il n'a pas pu être mesuré et demandez : continuer sans synchro, ou utiliser une valeur donnée.

3. Afficher le plan sous forme de tableau compact, puis STOP

Lisez plan.md depuis le répertoire de travail et présentez-le (ne collez jamais le fichier brut) :

  Source    take-01.mp4   01:47.9
  Sync      +240 ms (audio en avance), confiance 5.5, étalement 0 ms
  Résultat  01:40.5 prévu, 7.3 s supprimées, 5 coupes

  00:00.0-00:02.8   coupe   silence 3.0 s          2.8 s
  00:23.6-00:24.9   coupe   silence 2.0 s          1.3 s

  Bafouillages (appliqués) :  « alors parlons de, | alors parlons de »   garder la deuxième prise
  Redémarrages (proposés) : 01:12.4 « il y aura une perte à » x2 ...   commande apply_spans listée
  Propositions de reprise (non appliquées) :
  1  01:45.9-01:47.0  « et donc »  ->  garder 01:47.0-01:48.1 « et donc »

Signalez dans le même bloc : étalement de synchro supérieur à 40 ms ou confiance inférieure à 3.5 ; p90 du décalage de début d'alignement supérieur à 500 ms (la transcription est instable) ; toute ligne de reprise signalée comme boucle de décodage Whisper.

Les répétitions et faux départs sont supprimés par défaut. C'est à cela que sert la passe mot par mot. La précision prime sur le rappel : une mauvaise coupe coûte un nouveau tournage, un bafouillage manqué coûte une coupe supplémentaire. Les correspondances sûres (répétitions immédiates, un abandon sans ponctuation entre les prises) sont appliquées ; les cas plus flous sont listés comme candidats redémarrage ?. Lisez chaque candidat dans son contexte. Opposez-vous à tout ce qui est une répétition rhétorique délibérée (« en dessous de 60, en dessous de 70, en dessous de 80 »). Les tics de langage (euh, hum) sont listés, jamais coupés automatiquement. Gardez la DERNIÈRE prise ; lorsqu'une pause se trouve entre deux prises, la pause marque où commence la deuxième prise.

Posez une question : approuver tel quel, ou nommer ce qu'il faut remettre. Si une phrase est ambiguë, demandez spécifiquement ; ne devinez pas. Rien n'est rendu sans réponse.

4. Appliquer les modifications à partir des nombres, jamais de mémoire

• Acceptez une reprise ou un redémarrage par ses mots, pas par des horodatages tapés :

  python3 "$THP_HOME/scripts/autocut/apply_spans.py" <workdir> --drop "[email protected]"   # phrase la plus proche de 22 s
  python3 "$THP_HOME/scripts/autocut/apply_spans.py" <workdir> --span 71.20:74.85     # depuis la commande listée dans plan.md
  

  Lisez chaque ligne de contexte qu'il renvoie.
• Relisez plan.json depuis le disque avant le rendu ; l'humain a pu le modifier. Un plan modifié après une coupe est automatiquement recoupé.
• Les pauses scriptées sont du contenu : un temps délibéré (« et la réponse est... [pause] rien ») va dans plan.json sous keep_silences: [[s, e]] (en secondes source) pour que le coupeur ne le serre jamais.

5. Rendu

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

Ce que fait le rendu, pour expliquer les échecs :

• 09p plans longs (plus de 3 min) : réduit les pauses de plus de 0,65 s à 0,30 s après le dernier son + 0,20 s avant le suivant. Silence signifie ici chaque trame de 5 ms sous -55 dB. N'augmentez jamais ce seuil : les queues de mots décroissent entre -42 et -55 dB et un seuil plus haut mange les consonnes finales.
• 09a accroche chaque bord de coupe hors des plages sonores et à au moins 50 ms du son qu'elle supprime ; rogne le début et la fin au premier et dernier mot réel ; coupe les bruits de crochet ([UH], [lèvres]) dans les intervalles de 0,4 s ou plus.
• 09b déplace tout début conservé avec du son qui continue dedans vers le silence (restaure un début coupé).
• Le coupeur supprime tout morceau de moins d'1 s sans son (un « fragment silencieux » entre deux cuts) et imprime CHECK short piece with sound pour les morceaux de moins d'1 s qu'il conserve. Écoutez chacun.

6. Vérifier le montage (non optionnel, dans cet ordre)

1. qa.md ## Audit des plages supprimées en premier. Chaque intervalle supprimé est vérifié pour la présence de parole résiduelle (énergie + transcription isolée). Une ligne FLAGGÉ signifie que la coupe n'est pas livrable : enquêtez (d'abord la fenêtre la plus forte en dB, puis écoutez qa/removed/spanNN.wav), corrigez keep, et refaites le rendu. Un fragment d'un seul mot avec une fenêtre DB la plus forte faible est généralement un clic ou une respiration, pas de la parole ; faites confiance au nombre d'énergie plutôt qu'au texte de transcription. Les lignes coupe approuvée sont bonnes.
2. Lisez qa/verbatim_cut.txt de bout en bout, comme un éditeur. C'est la transcription verbatim DE LA COUPE par CrisperWhisper. Cherchez toute phrase, fragment ou reprise de phrase entière qui a survécu. Ne vérifiez jamais une coupe avec une transcription Whisper normale : elle cache exactement ces éléments. Les reprises de phrases entières dites dos à dos après une pause ne sont détectées que de cette façon.
3. ## Redémarrages encore dans la coupe et ## Écrêtage des bords dans qa.md : résolvez chaque ligne SIGNALÉE (les séquences de nombres comme « 928 ... 939 » peuvent être des faux positifs ; lisez-les).
4. Vérifications que les scripts ne peuvent pas faire :
   • durée de sortie vs durée prévue : un delta supérieur à 0,6 s est un problème ;
   • parcourez chaque jointure à 5 images/s (images 0,5 s de chaque côté, depuis timemap.json) : aucune jointure sur un flou de geste ou une image dupliquée ;
   • pas de pause interne supérieure à 1,0 s ; pas de morceau sans une image au-dessus de -45 dB ;
   • fréquence d'images constante : le nombre d'images comptées / durée du flux doit être exactement égal à la fréquence nominale (30.0000, pas 29.98). Les enregistreurs perdent des images sous charge, et tous les outils indexés par image en aval dérivent si cela est faux.

Réexécutez uniquement la QA sans recouper : autocut.py --qa-only --workdir <dir>.

Ouvrez clean.mp4 pour l'humain (open sur macOS, xdg-open sur Linux).

7. Rapport et remise

Ce qui a été supprimé (tableau), où se trouve clean.mp4, et une ligne : c'est une entrée prédécoupée ; dites « rendez-le dynamique » pour continuer avec /dynamic-edit. Les sous-titres pour l'étape suivante proviennent des mots verbatim, mappés dans la timeline de la coupe :

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

8. Nettoyage, uniquement quand l'humain dit que la vidéo est terminée

Le répertoire de travail contient synced.mp4 (une copie complète de la prise) et les morceaux de rendu tmp/. Demandez avant de supprimer. plan.json, transcript.json, verbatim.json et qa.md sont petits ; conservez-les.

Règles strictes

• La validation du plan est obligatoire. Pas de rendu sans le feu vert de l'humain.
• Ne codez jamais en dur un décalage de synchro. Mesurez-le par fichier, ou utilisez celui que l'humain vous donne.
• Le fichier brut n'est jamais modifié.
• Vérifiez une coupe avec la transcription verbatim de la coupe, jamais avec une transcription Whisper normale.
• Ne figez jamais un bord généré automatiquement. _meta.pinned_edges est pour les bords qu'un humain a vérifiés par rapport à la forme d'onde ; épingler des bords machine ignore la marge de sécurité du crocheteur et mange des mots.
• Le silence est uniquement sous -55 dB. Rien entre -40 et -55 dB n'est du silence sur un micro à porte.
• Pas de morceau assemblé de moins d'1 s sans parole.
• Lorsqu'un mot ou une instruction est ambiguë, posez une question spécifique.

Pièges

• Whisper hallucine des segments vides sur le bruit de fond résiduel, avec des horodatages au-delà de la fin du fichier. Attendu ; le chercheur de reprises les filtre. Un millier de « reprises » en deux secondes à la fin est une boucle de décodeur, pas de vraies reprises, et plan.md le dit.
• La détection de synchro nécessite un visage à l'écran. Capture d'écran uniquement : --no-sync, et dites-le.
• De nombreux micros enregistrent en faible volume (environ -30 LUFS). autocut ne normalise pas. La sonie appartient au master final (scripts/master/sync_trim.sh --loudnorm) ; ne l'appliquez jamais silencieusement.

Référence complète étape par étape : $THP_HOME/docs/AGENT_GUIDE.md.