vincesector/talking-head-pipeline

/dynamic-edit

Une tête parlante qui ne bouge jamais est morte à l'arrivée ; une tête qui bouge sans raison est pire. Ce pipeline décide quel effet mérite sa place sur quel mot, le consigne dans un plan que l'humain peut opposer son veto, et ne consomme des ressources qu'ensuite.

Racine du dépôt :

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

À lire avant de planifier : $THP_HOME/docs/STYLE_RULES.md (les règles d'artisanat), $THP_HOME/docs/LAYOUTS.md (géométrie et zones de sécurité des sous-titres), references/plan-format.md (le schéma), references/qa.md (les points de contrôle). 3D : $THP_HOME/docs/3D.md.

Contrat d'entrée : les images sont déjà découpées. Pas de suppression de silence, pas de passe de remplissage ici. Une prise brute va d'abord vers /autocut ; revenez avec son clean.mp4 et son répertoire de travail (pour les mots textes).

Ne sautez jamais l'étape de planification. La rotoscopie coûte environ 12 minutes par minute de métrage et un rendu complet des dizaines de minutes. Une mauvaise conjecture rattrapée dans un plan textuel ne coûte rien.

Flux de travail

1. Initialiser le projet

P=<dossier projets>/<slug>                 # demander où l'humain conserve les projets vidéo ; jamais le Bureau
cp -R "$THP_HOME/template" "$P"
cd "$P"
uv venv --python 3.11 .venv            # mediapipe n'a pas de wheels au-delà de 3.12
uv pip install --python .venv/bin/python "mediapipe==0.10.21" opencv-python backgroundremover numpy pillow
scripts/download_models.sh             # Détecteur de visage MediaPipe (non livré dans le dépôt)
(cd remotion && pnpm install)          # ou npm install
cp "<répertoire de travail autocut>/clean.mp4" remotion/public/raw.mp4
python3 "$THP_HOME/scripts/autocut/verbatim_cut_words.py" "<répertoire de travail autocut>" -o remotion/public/words.json

Réel vertical à partir d'une prise 16:9 : scripts/prep_vertical.sh "<répertoire de travail autocut>" "$P" au lieu des deux dernières lignes (recadrage statique 9:16 sur la médiane x de la tête, jamais de recadrage suivi).

2. Inventaire, coupes, suivi

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

• Marge de zoom = largeur source / largeur timeline (2560 dans 1920 = 1,33× gratuit). Au-delà, vous agrandissez.
• L'aspect est détecté automatiquement à partir des dimensions du plan (lib/layouts.ts profils). Un moteur, jamais de branche.
• Lisez detectionRate dans track.json. En dessous de ~0.9, les mouvements ancrés au visage ne sont pas fiables ; signalez-le.
• La détection de coupe manque les changements progressifs (un passage animé à un partage d'écran). Échantillonnez une image par segment et ajoutez manuellement les limites manquées à cuts.json. Les segments de partage d'écran n'ont pas de gros plans, pas de sous-titres dessinés par-dessus, pas de fiches (définissez captions.silence pour ces plages).

3. Relire les mots

Parcourez words.json pour chaque nom propre, marque, ticker et personne que le script nomme. Les modèles Whisper-family les déforment et la phrase reste fluide, donc la relecture ne les attrape jamais. Corrigez le fichier des mots (fusionner deux tokens en un est acceptable), jamais le rendu. Les nombres en chiffres.

4. Écrire le plan, puis STOP

1. Lisez d'abord l'intégralité de la transcription. Trouvez les temps forts que le récit possède réellement : accroche, affirmation, chiffre, virage, révélation, récompense, le moment mieux montré que dit.
2. Choisissez un outil par temps fort dans Choix des effets ci-dessous. Beaucoup de temps forts ne reçoivent rien.
3. Copiez scripts/build_plan.example.py vers scripts/build_plan.py et écrivez-y les temps forts avec des ancres de mots ("phrase@secondes"). Cela écrit remotion/plan.json et les sous-titres. Cela refuse les événements sans raison, sans ancres de mot pour l'ENTRÉE ET LA SORTIE, ou les incrustations trop rapprochées.
4. Montrez à l'humain un tableau, une ligne par événement : temps, effet, « atterrit sur X, part après Y, parce que Z ». Plus : secondes de roto (et le temps de matage que cela implique), tout recadrage au-delà de la marge de zoom, tout étirement au-delà de ~12 s sans événement, et les rendus 3D nécessaires.
5. Attendez l'approbation. Relisez ensuite plan.json depuis le disque ; l'humain a peut-être édité.

Si l'humain a nommé un effet spécifique à un moment spécifique, c'est le plan pour ce temps fort.

5. Construire ce dont le plan a besoin, rien de plus

• Fenêtres roto : scripts/render_and_qa.sh les mate ; ou scripts/matte_frames.py par fenêtre.
• Type héroïque 3D / actifs 3D : tools/render3d (voir docs/3D.md). D'abord des images fixes (--stills), regardez-les, puis --clip --dir=remotion/public/<nom>. Mettez les mêmes images d'entrée/sortie dans le plan que at/until de l'événement.
• Fiches latérales : types dans remotion/src/layouts/cards.tsx ; ajoutez un type là-bas si nécessaire.
• Pages de scène d'écran : remotion/src/screen/pages.tsx. Reconstruisez l'interface en code pour tout ce dans quoi vous zoomez ; une capture d'écran devient floue à 2×.
• Scènes plein écran : scenes/fullscreen/registry.ts (depth, clip, stage).
• SFX : après que le plan soit final, scripts/add_sfx.py "$P" sfx_map.json --library <répertoire>.

6. Vérifier avec des images fixes, puis rendre

Les images fixes coûtent des secondes ; un rendu coûte l'après-midi :

cd remotion && npx remotion still src/index.ts Edit ../qa/landing.png --frame=<N>

Vérifiez chaque atterrissage héroïque (et atterrissage + 25), chaque entrée de mise en page, chaque transition, chaque arrivée 3D. Ensuite :

scripts/render_and_qa.sh "$P" <nom>        # mate les fenêtres roto, effectue le rendu, écrit les feuilles QA

Rendus : --concurrency 4-6, nice le processus, et gardez Config.setChromiumOpenGlRenderer('angle') (déjà dans remotion.config.ts) ou les scènes WebGL échouent sans interface. Livrez yuv420p bt709 ; un fichier yuvj420p s'affiche vide dans QuickTime.

7. QA (references/qa.md), puis ajustement de la synchronisation

Exécutez chaque point de contrôle dans references/qa.md avant que quiconque ne le voie. Mesurez et ajustez ensuite le décalage audio du rendu par rapport à la source (les rendus Remotion accusent quelques dizaines de ms de retard ; mesuré, jamais supposé) :

"$THP_HOME/scripts/master/sync_trim.sh" renders/<nom>.mp4 remotion/public/raw.mp4 renders/<nom>_final.mp4 [--loudnorm -14]

Cible de la synchronisation |finale| sous 5 ms. Normalisation du volume sonore uniquement si l'humain le souhaite (valeur par défaut sociale -14 LUFS). Ouvrez le fichier final pour l'humain.

8. Corrections après livraison : patcher la plage, ne jamais re-rendre la vidéo

scripts/patch_render.sh --base renders/prev.mp4 --replace 0-1049 --render 0-887 --out renders/next.mp4

--replace est la plage de l'ancien rendu à jeter, --render la plage du plan actuel qui la remplace (elles diffèrent lorsque la source a été re-découpée). Seul le patch est encodé ; la tête et la queue sont copiées en flux sur des images clés ; le nombre d'images est vérifié. Lorsqu'un bafouillage doit sortir de la source après que le plan existe, reconstruisez le plan à partir des ancres (build_plan.py) pour que chaque effet se déplace avec son mot.

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

Demandez d'abord. scripts/cleanup.sh supprime les PNG de matage, les dumps d'images, les feuilles QA, les brouillons, le venv et node_modules ; il conserve le plan, la source, le suivi, les sous-titres et le rendu final. Regénérer un matage coûte ~12 min par minute de métrage, ne lancez donc jamais cela sans y avoir été invité.

Choix des effets (une boîte à outils, pas un ordre de passage)

Il n'y a pas de formule. Une vidéo sans mot héroïque, sans roto, sans 3D est un plan valide. Un simple plan face caméra peut n'être que des incrustations et des sous-titres. Chaque effet est mérité par quelque chose dans le script, et chaque événement nomme pourquoi (son rôle narratif), in (le mot sur lequel il atterrit ; le mouvement commence avant pour qu'il ARRIVE sur lui) et out (le mot après lequel il part : fin de cette idée, la prochaine pause réelle, le mot avant un adoucissement). Jamais une tenue fixe, jamais « c'était calme pendant un moment ».

• Visage d'abord. Les 2-3 premières secondes sont le visage de l'orateur, l'image 0 déjà une accroche lisible (pas un fondu au noir). Pas de graphique plein écran avant ~2,5 s : la lecture automatique est muette et une ouverture axée sur les statistiques se lit comme une infographie et se fait défiler.
• Gros plan (le cheval de bataille) : dure une phrase, peu nombreux, intentionnels. Il atterrit lorsque la phrase clé se construit, la tient, se relâche sur son dernier mot. Jamais un gros plan d'un seul mot ; jamais espacé par un minuteur. Environ un toutes les 30-45 s de tête parlante en format long ; plus serré sur les courts uniquement si le script le mérite. Ancré sur le visage suivi. Deux phrases liées : incrustez la moitié qui porte l'histoire. Accent imbriqué (tenue + un petit accent sur la phrase clé) au lieu de trois incrustations dans une phrase.
• Mise en page latérale (16:9) : lorsqu'un nombre, une liste ou une comparaison doit rester à l'écran pendant qu'il est expliqué. Le sujet glisse sur un côté, une fiche de taille de contenu sur l'autre, les fiches changent sur leurs mots et incrustation sur le nombre dit. La plupart des temps forts informatifs en format long veulent cela.
• Scène d'écran (16:9) : la démonstration « voici à quoi cela ressemble ». À utiliser une ou deux fois par vidéo, pas pour chaque mention. En un-à-un avec l'interface réelle si elle recrée un produit ; seules les données changent, et les données sont réelles.
• Recadrage décalé avec fiches : une version plus légère de la mise en page latérale, dans la marge de zoom.
• Roto (derrière le sujet) : uniquement pour les ouvertures et les moments héroïques. Budget par défaut 15 s par vidéo ; prévenez au-dessus de 30 s ; au-dessus de 60 s, demandez. Tout ce qui passe derrière doit valoir la peine d'être occulté.
• Mot héroïque derrière le sujet : une accroche, un virage dur, l'idée nommée. Au-dessus de la tête, chaque glyphe lisible (vérifiez une image fixe à l'atterrissage + 25). Un par vidéo, sauf si deux atterrissent loin l'un de l'autre.
• Type héroïque 3D : une grande affirmation ou un nombre à côté de la tête ou en travers de la poitrine, avec un espacement égal de chaque bord de l'image (au moins ~90 px en 1080 de large), jamais sur le visage.
• Actif 3D : un logo ou un objet que l'orateur nomme, tournant dans l'espace vide à côté du visage, roto derrière s'il se chevauche.
• Scène plein écran : uniquement lorsque montrer clairement bat dire, au plus deux, fondu+flou en entrée et sortie.
• Sous-titres : tiers inférieur fixe, même position et style partout (tête parlante, latérale, écran). Emphase = police d'accentuation ET taille 1,22× sur des phrases entières, jamais répartie sur deux fiches. Les sous-titres suivis de la tête sont désactivés sauf demande.
• SFX : un par événement visible (transition, atterrissage héroïque, incrustation forte, fiche, clic), subtil.

Règles strictes

• Rien sur le visage. Pas de sous-titre, fiche, puce, logo ou objet 3D sur la boîte du visage à aucune image de sa fenêtre. Déplacez-le, réduisez-le, ou placez-le derrière avec roto. Mesurez à partir de track.json.
• Pas de puces de texte encadrées au-dessus de l'orateur. Pas de lignes d'accentuation unilatérales sur aucune fiche (haut, gauche, n'importe quel bord) : utilisez une teinte de remplissage ou une bordure pleine et uniforme.
• Fondu de l'image entière uniquement. Ne fondez jamais des conteneurs tandis qu'un titre reste.
• Transitions : fondu+flou (par défaut), fondu simple, ou un stinger liquide. Jamais de zigzag/dents d'engrenage.
• Pas de texte coupé par un zoom ou le bord de l'image. L'interface zoomée s'estompe au-dessus de la bande de sous-titres (fondu de bord World). Les sous-titres ne zooment jamais.
• Un recadrage part dans le même rendu que ce pour quoi il fait de la place. Pas de mouvement de caméra vers un mur vide.
• Vérifiez chaque nombre à l'écran par rapport à ce qui est dit ou à une extraction sauvegardée et sourcée. N'en inventez jamais un.
• Les objets et icônes sont de vrais logos ou des images générées/sourcées. Le code dessine le mouvement, le texte, l'interface utilisateur, les graphiques. Les pointes de flèche sont un actif, pas un SVG.
• Pas de tirets cadratins à l'écran. Pas d'appels à l'action « commentez ci-dessous » / « envoyez-moi un DM » sauf si l'humain le demande.
• Chaque couche empilée sur la vidéo est son propre AbsoluteFill (une vidéo statique se peint sous n'importe quel frère positionné en absolu, ce qui place silencieusement les graphiques devant le matage).
• Utilisez translate + scale, jamais un transform-origin décalé, pour les recadrages.

Paramètres d'effet et nombres mesurés : references/effects.md.