zenstory-ai/video-recap

1. Positionnement et flux de travail

Cette compétence est un processus autonome de commentaire vidéo et de montage. Elle concentre la compréhension vidéo, la conception narrative, le montage, la rédaction de la voix off, la synthèse vocale et le mixage audio-vidéo dans un même flux de travail cohérent. Chaque étape partage le même répertoire de travail work_dir avec des fichiers JSON et MP4 :

understand.py (compréhension vidéo) ▶ Agent élabore le plan narratif/audio et écrit clip_plan.json ou narration.json ▶ [cut.py (montage et résumé de la sortie)] ▶ validate.py (validation locale basique) ▶ voiceover.py (synthèse TTS) ▶ assemble.py (mixage et rendu des sous-titres)

Pour une utilisation quotidienne, invoquez directement le point d'entrée global scripts/recap.py qui enchaîne automatiquement l'ensemble du processus et s'arrête aux points de création. Vous pouvez aussi appeler individuellement les étapes via scripts/ (understand.py, cut.py, validate.py, voiceover.py, assemble.py).

La décomposition d'une production existante en référence (production_reference.json) ne fait pas partie de la chaîne de production par défaut. Lorsque l'utilisateur demande d'analyser un échantillon : exécutez d'abord understand.py sur l'échantillon (suggérez ASR_SEGMENT_SECONDS=5), puis utilisez une compétence de décomposition distincte pour effectuer les mesures (measure), l'annotation, la validation (check) et l'export (export). Copiez le production_reference.json exporté dans le work_dir de la prochaine exécution, ou enregistrez-le comme modèle production_reference dans la bibliothèque de ressources et liez-le via --project. Le flux principal n'exécute pas automatiquement la décomposition et ne compare pas mécaniquement la nouvelle production à la référence.

Le processus complet prend en charge la reprise après interruption : une fois que l'Agent a écrit clip_plan.json ou narration.json, relancez la même commande recap.py pour continuer. Lors de la reprise, le script vérifie le chemin de la vidéo source, la taille du fichier, la date de modification et les paramètres d'exécution enregistrés dans recap_run_manifest.json. Si le répertoire de travail provient d'une autre vidéo ou d'une combinaison de paramètres différente, la reprise est refusée. Le cache de compréhension vidéo n'est utilisé que si la source et la configuration sont identiques. À chaque arrêt, la commande de reprise affichée dans le terminal conserve l'appel d'origine et convertit automatiquement les chemins vidéo et de répertoire en chemins absolus, en ajoutant --work-dir. Vous pouvez la copier-coller et l'exécuter depuis n'importe quel répertoire.

Le flux d'images --edit-mode full|cut et la stratégie audio --audio-mode narration|source-mix sont indépendants : narration suit la chaîne de commentaire standard avec TTS, tandis que source-mix n'utilise pas de TTS mais mélange directement l'audio original avec une musique de fond optionnelle. Seules les cinq combinaisons légitimes listées dans le tableau ci-dessous sont autorisées. Toute autre combinaison est immédiatement bloquée au lancement :

Entrée	--edit-mode	--audio-mode	Point d'arrêt Agent	Processus	Détails
Vidéo unique	full	narration	1 fois : écriture narration.json	Compréhension → Rédaction → Validation → TTS → Synthèse	§4
Vidéo unique	cut	narration	2 fois : d'abord écriture clip_plan.json, après montage écriture narration.json sur le film fini	Compréhension → Montage → Résumé sortie temps → Rédaction → Validation → TTS → Synthèse	§4
Multi-vidéos	cut	narration	2 fois : idem, chaque segment doit avoir un source_id	Compréhension par source → Montage → Rédaction → Validation → TTS → Synthèse	§4.5
Vidéo unique	full	source-mix	Aucun arrêt	Synthèse directe de la vidéo entière actuelle (pas de compréhension ni TTS)	§4.7
Unique/Multi	cut	source-mix	1 fois : écriture clip_plan.json	Compréhension → Montage → Synthèse (pas de commentaire)	§4.7

2. Responsabilités créatives

La décision finale créative appartient entièrement à l'Agent. Avant de commencer à écrire, déterminez le mode de contrôle créatif de ce tour (CREATE création libre / DIRECTED création dirigée / REVISION révision finale, indépendant de --edit-mode). Ensuite, en tant que même cerveau créatif, effectuez cinq jugements d'un seul tenant avant d'entrer dans la synthèse vocale et le rendu :

1. Jugement de mise en scène : Clarifiez pourquoi le spectateur regarde, quel point de vue (POV) est suivi tout au long, quel est le suspens central, où commence et où se termine l'émotion, et quelle carte est gardée pour la fin.
2. Édition narrative : Chaque beat doit exprimer un changement substantiel de la situation. N'écrivez jamais un résumé de scène comme un simple catalogue.
3. Montage image : Choisissez les moments d'action les plus percutants, les réactions les plus marquantes et les meilleurs points d'entrée et de sortie. Supprimez les transitions inutiles.
4. Son/Commentaire : Décidez d'abord, pour chaque beat, si l'image, le dialogue original, le bruit d'action, le silence ou la voix off mène. Ensuite, écrivez en suivant le principe "remplir la moitié de la phrase, laisser la moitié, reprendre la moitié".
5. Vérification public : Du point de vue d'un spectateur qui regarde pour la première fois, effectuez séparément une vérification en regardant l'image sans la voix off, en écoutant uniquement le son les yeux fermés, et en vérifiant la promesse du début et la fin.

Les rôles des trois modes de contrôle, les règles de verrouillage sans retour en arrière en mode REVISION, les techniques de montage et d'écriture spécifiques, ainsi que les formats standard de recap_story_plan.json, visual_audio_board.json et style_card.json sont détaillés dans references/creative-editing-playbook.md. Ces JSON servent à cristalliser les décisions créatives vérifiables, garantissant que le choix des plans, les silences originaux et le commentaire restent fidèles à une même intention narrative du début à la fin.

3. Environnement et appels distants

# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***

La même MIMO_API_KEY suffit pour piloter toute la chaîne par défaut. Pour garantir la transparence du flux de données, voici les appels réseau distants de cette compétence :

• Compréhension vidéo (understand.py) : Envoie les fenêtres audio découpées à MiMo ASR (mimo-v2.5-asr) et les images JPEG extraites ainsi que le résumé background_research.json à MiMo VLM (mimo-v2.5). Si le répertoire de travail contient déjà des analyses complètes, l'option --brief-only ou --edited-storyboard-only exécute uniquement localement, sans aucun appel réseau.
• Synthèse vocale TTS (voiceover.py) : Selon --tts-provider (par défaut auto priorise MiMo configuré, puis Fish Audio, jamais index-tts automatiquement), envoie le texte de commentaire au service TTS correspondant :
  • mimo-tts : Envoie à MiMo TTS (mimo-v2.5-tts). Si --voice-ref <audio> est explicitement passé, un échantillon de l'audio de référence est également envoyé à mimo-v2.5-tts-voiceclone (assurez-vous d'avoir l'autorisation de la voix avant utilisation).
  • fish-audio : Nécessite FISH_API_KEY. Envoie chaque segment de commentaire avec FISH_TTS_REFERENCE_ID à FISH_TTS_API_URL (par défaut https://api.fish.audio/v1/tts).
  • index-tts : Activé uniquement si --tts-provider index-tts est explicitement spécifié. Envoie le texte avec INDEX_TTS_VOICE au serveur INDEX_TTS_ENDPOINT de l'utilisateur (voir references/index-tts.md).
• Validation du commentaire (validate.py), montage vidéo (cut.py, shot_review.py) et mixage audio-vidéo (assemble.py) : Logique déterministe locale et appels à ffmpeg/ffprobe uniquement. Aucun appel réseau émis.

Les clés Token Plan commençant par tp- sont envoyées par défaut au cluster en Chine. Vous pouvez changer de cluster via MIMO_TOKEN_PLAN_CLUSTER. La liste complète des configurations se trouve dans references/config-playbook.md, et le format de tous les produits intermédiaires dans references/data-schema.md. Les scripts/... ci-dessous sont relatifs au répertoire de cette compétence.

4. Processus créatif et de montage fluide

4.1 Recherche de contexte et compréhension vidéo

Dès que le nom du film, de la série ou du sujet scientifique est identifiable à partir du nom de fichier ou des instructions de l'utilisateur, effectuez d'abord une recherche contextuelle selon references/research-guide.md (relations entre personnages, contexte antérieur) et écrivez-la dans work_dir/background_research.json. Ainsi, lorsque l'analyse d'image sera exécutée ultérieurement, les noms des personnages seront correctement identifiés, évitant des descriptions vagues comme "homme en noir" ou "jeune femme". Pour les montages multi-vidéos, écrivez également dans le work_dir racine du projet ; le script synchronisera automatiquement les données dans les sous-répertoires sources/<source_id>/ de chaque source.

Ensuite, lancez le point d'entrée de compréhension et d'organisation :

python3 scripts/recap.py <video> --work-dir <work_dir> --context "contexte"

Après l'extraction audio, la détection des pauses de fin de phrase (speech_boundary_anchors.json), le découpage de scène, l'analyse VLM et la transcription ASR, le script génère un puzzle de storyboard storyboard/storyboard_*.jpg et un brief créatif agent_narration_brief.md, puis s'arrête automatiquement.

4.2 Intention de mise en scène et plan de sélection des plans (phase 1 cut)

Après avoir lu agent_narration_brief.md et examiné directement les images extraites du storyboard, écrivez d'abord recap_story_plan.json (au moins 2 candidats, avec le POV principal choisi, l'accroche d'ouverture, l'arc émotionnel et la carte de réserve) et visual_audio_board.json (pour chaque beat, précisez quel moment est choisi, pourquoi on y entre et en sort, et qui mène le son).

En mode cut, phase 1, écrivez ensuite work_dir/clip_plan.json basé sur la trame temporelle SOURCE originale (à ce stade, n'écrivez pas encore narration.json) :

{
  "target_duration": "3m",
  "clips": [
    {
      "start": 12.0,
      "end": 38.0,
      "reason": "b01 | hook | connaissance: inconnue→menace | POV=沈曼 | Découvre le fiancé embrassant une héritière pour un mariage arrangé | Entrée=ouvre la porte, voit les deux | Sortie=se retourne, serre le livret de mariage"
    }
  ],
  "required_evidence": {
    "nodes": [
      {"id": "e1", "source": "/abs/source.mp4", "start": 14.2, "end": 18.6, "track": "video", "content": "Ouvre la porte, voit les deux s'embrasser"}
    ],
    "before": []
  }
}

Le choix des plans et des points de coupe doit respecter strictement les règles suivantes :

• Structure reason en sept parties : Écrire successivement beat_id | fonction narrative | changement d'état de la situation (A→B) | POV=personnage | intérêt substantiel de ce segment | Point d'entrée=action concrète/ancrage original | Point de sortie=réaction concrète/point de chute. Cela force chaque segment d'image à servir la progression narrative.
• Preuves image et son original obligatoires (required_evidence) : Les moments forts, les changements de visage ou les dialogues clés à conserver doivent être inscrits dans le required_evidence de niveau supérieur (les nodes enregistrent id/source chemin absolu/start/end/track/content, before enregistre les paires d'ordre qui ne peuvent pas être inversées). Si l'adsorption des bords supprime une plage obligatoire ou perturbe l'ordre, le script bloquera immédiatement avec une erreur.
• Entrée tardive et sélection des plans : Par défaut, entrez "tardivement" dans l'action (coupez directement dans le conflit, le contraste absurde ou l'action clé, en supprimant les introductions lentes comme l'entrée dans la pièce, les salutations, etc.). Ce n'est que si le conflit dans l'ordre chronologique arrive trop tard qu'il est permis de prendre une image d'accroche froide <= 2.5s. Cela doit être compréhensible sans préparation, ne pas répéter la même prise de vue que dans le film, ne garder que le mystère sans révéler le retournement final. Lorsque la voix off couvre l'audio original, privilégiez les réactions de visage, les détails d'action ou les plans stables. Évitez de placer des images de personnages parlant abondamment mais dont le son est coupé sous la voix off. Ne répétez pas plus de deux fois la même réaction de hochement de tête ou de regard vide.
• Points de coupe sûrs en fin de phrase et souffle de fin : Les points de coupe doivent tomber au début ou à la fin du film original, dans les ancres de pause de fin de phrase ou dans une fenêtre de silence, ou bien être une jonction transparente entre fragments adjacents de la même source. Lors de l'adsorption à la fin d'une phrase, réservez automatiquement jusqu'à 0.30s pour la respiration/l'émotion dans la fenêtre de pause, sans jamais franchir le point de coupe dur. La durée minimale d'un fragment est de 0.8s. Le dernier beat du film doit laisser une rémanence émotionnelle de 1.5–2.5s après que l'action ou la réplique finale est stabilisée, et se terminer proprement avant de passer à la scène suivante. Couper au milieu d'une réplique originale déclenche un blocage unsafe_clip_sentence_boundary avec indication du nearest_safe ; si le retrait de l'adsorption dure expose simultanément des images flash <= 0.20s et coupe la réplique, un blocage shot_speech_conflict est immédiatement émis.
• Détection des coupes rapides fréquentes et des fragments de plan : Après le rendu de edited_source.mp4 par cut.py, shot_review.py est automatiquement appelé pour générer shot_review.json. Les fragments de plan très courts <= 0.20s (environ 1 à 5 images) sont directement bloqués (flash_slivers). Pour les scènes d'action ou les champ-contrechamp denses, vous pouvez également exécuter manuellement ffmpeg -i <video> -vf "select='gt(scene,0.35)',showinfo" -f null - ou l'outil en lecture seule scripts/shot_review.py (voir references/shot-review.md) pour localiser les points de coupe élevés. Mais il est impératif de distinguer les points de coupe inhérents au film original des points de coupe créés par l'assemblage actuel. S'il s'agit de plans courts inutiles inhérents au film original supprimés entièrement, ou si le point de coupe est déplacé à l'extérieur du cluster de coupes rapides. S'il s'agit de points de coupe créés par l'assemblage actuel (comme des résidus d'images du plan voisin sur le bord d'une coupe dure, des contrechamps fragmentaires), élargissez alors les points d'entrée et de sortie ou fusionnez les fragments adjacents de la même source. Il est strictement interdit de masquer ces défauts avec des transitions.

Après avoir écrit clip_plan.json, relancez recap.py. Le script appelle cut.py pour effectuer l'adsorption en trois étapes (adsorption par coupe dure → adsorption par silence de fin de phrase avec souffle → alignement sur la grille d'images), rend la vidéo edited_source.mp4 à fréquence d'images constante, effectue la détection des flashs d'images, puis remappe les ancres ASR, VLM et de fin de phrase sur la timeline de sortie (speech_boundary_anchors_output.json, storyboard/edited_storyboard.*). Ensuite, il s'arrête à nouveau en attendant l'écriture du commentaire.

4.3 Écriture du commentaire et conception des silences originaux (phase 2 full / cut)

Une fois entré dans la phase de rédaction (premier arrêt en mode full, deuxième arrêt après le montage edited_source.mp4 en mode cut), examinez d'abord le storyboard après montage, complétez visual_audio_board.json avec les temps de sortie du film fini, rédigez style_card.json si nécessaire, puis écrivez work_dir/narration.json :

[
  {
    "start": 0.2,
    "end": 5.0,
    "narration": "Après cinq ans d'amour, en route pour demander la main de sa fiancée, Shen Man pousse la porte et découvre son fiancé enlacer une héritière, négociant un mariage arrangé.",
    "pause_after_ms": 250,
    "overlaps_speech": true
  }
]

Important : En mode cut (montage), narration.json doit directement utiliser les timestamps OUTPUT du film fini (0 .. durée totale du film fini) (lors de l'appel séparé du validateur, utilisez validate.py --mode cut_output). En écrivant, suivez les neuf règles d'écriture fondamentales (détails et exemples positifs/négatifs dans references/creative-editing-playbook.md) :

1. Dans les 2,5 premières secondes, révélez l'accroche ou le moment fort sonore original. Jetez directement un contraste d'action concret ou le suspens central. N'écrivez pas de CV de personnage, de bulletin d'information ou d'ouverture de salutations. Un démarrage à froid de plus de 2.5s sans voix off ni dialogue original déclenche un blocage weak_cold_open_silence.
2. Expliquez clairement le contexte, les relations entre personnages et les causes/conséquences. Limitez la densité des noms. Refusez la "description d'image". Lorsque des noms de personnages sont fournis dans background_research.json, il est strictement interdit d'utiliser des termes vagues comme "homme en noir" ou "jeune femme" pour les désigner (déclenche alors un signalement generic_character_label). Pour les courts métrages de moins de 60 secondes, nommez au maximum 1 à 2 personnages principaux (dans la première phrase, nommez au maximum 1 personne et précisez son rôle). Les autres rôles secondaires sont désignés par leur relation/statut (ex : "ex-petite amie", "son supérieur", "médecin impérial"). Chaque phrase doit avancer autour de la "situation → action → conséquence immédiate".
3. Correspondance son-image : "remplir la moitié, laisser la moitié, reprendre la moitié" et synchronisation obligatoire pour les visuels forts. Avant un dialogue original percutant, un bruit de gifle, ou un changement de visage en silence, taisez-vous décisivement. Après la fin de l'original, reprenez avec une demi-phrase pour révéler le sous-texte. Lorsque l'image montre un baiser, une gifle, une génuflexion, un évanouissement, la révélation d'un objet clé, etc., l'action visuelle forte doit être expliquée soit par l'audio original conservé, soit par une voix off immédiatement adjacente. Il est interdit que l'image et le son racontent des choses différentes. Interdiction d'avoir une fenêtre morte de plus de 5.0s sans voix off ni dialogue original (déclenche un blocage excessive_dead_air).
4. Respect des lignes rouges d'entrée et de retour du son original. Lorsque la voix off chevauche l'audio original (overlaps_speech: true), le start doit être collé à une ancre de fin de phrase ou à une zone de silence (déclenche un blocage interrupts_source_sentence). De même, lorsque la voix off se termine et que l'audio original revient, le volume ne doit pas être rétabli au milieu d'une réplique à moitié dite (déclenche un blocage unsafe_source_release / unsafe_source_handoff lors de la validation et du mixage).
5. Contrôle strict du budget de mots dans la fenêtre de temps. Maintenez un débit naturel et terminez les phrases complètes. Chaque segment doit se terminer par un signe de ponctuation final de phrase complète (une phrase incomplète déclenche un blocage incomplete_sentence). Adaptez le nombre de mots à la fenêtre de temps par la concision, sans compter sur un taux de lecture élevé forcé. En mode full, un dépassement de 1,25x du budget déclenche un blocage over_budget. Le validateur ne supprime jamais de mots pour le compte de l'Agent.
6. Éliminez le ton éditorial et le style télégraphique. Laissez la fin être jouée par l'image. Écrivez des phrases orales naturelles et fluides, pas des phrases hachées mot par mot. Interdiction d'écrire des commentaires et des envolées lyriques comme "Cela signifie...", "C'est un combat sur...", "Laissez le pouvoir et l'orgueil s'effacer", "Les rouages du destin", etc. (déclenche un avertissement editorial_commentary_tone). La conclusion de l'histoire doit être jouée directement par l'image et l'audio original. Il est strictement interdit d'ajouter une voix off de synthèse ou de conclusion après que l'histoire est déjà terminée, ni de traîner une queue de réplique originale répétant le même résultat après la voix off finale.
7. Ancrage sur des preuves visuelles concrètes et discipline musicale purement instrumentale. Parlez avec les regards, les accessoires, les détails d'action que l'on voit. N'inventez pas d'activité psychologique hors cadre pour les personnages. Si une musique externe est utilisée (BGM_PATH), elle doit être purement instrumentale (zéro parole vocale). Si le film original contient déjà une chanson intégrée avec voix forte et inévitable, n'ajoutez pas de musique externe supplémentaire pour éviter la compétition entre plusieurs pistes vocales.
8. Vérifiez les sous-titres des silences originaux. Lorsque le masque de sous-titres du film original est activé et que des passages forts de l'audio original sont conservés, écrivez simultanément les répliques originales corrigées (en fonction du temps du film fini) dans work_dir/original_subtitles.json, en corrigeant les erreurs homophoniques de l'ASR.
9. Après l'écriture, effectuez trois auto-vérifications. D'abord, lisez l'intégralité du texte pour vérifier la cohérence de l'histoire et la correspondance avec le film original. Ensuite, vérifiez les fenêtres de temps pour détecter les chevauchements de parole ou les dépassements de mots. Enfin, exécutez validate.py (ou relancez simplement recap.py). Si vous devez rédiger un titre promotionnel externe, une image de couverture ou un plan de texte décoratif (packaging_plan.json), faites-le en suivant references/promotional-copy.md une fois l'histoire principale verrouillée.

4.4 Synthèse TTS et mixage audio-vidéo

Après avoir écrit narration.json, relancez la même commande recap.py :

1. Validation locale déterministe (validate.py) : Génère narration_lint.json. Effectue des vérifications strictes sur les chevauchements temporels, les dépassements, les dépassements de budget de mots, les phrases incomplètes, les démarrages à froid, les fenêtres mortes de plus de 5 secondes, les interruptions de répliques originales, les retours de son original en milieu de phrase, les désignations génériques de personnages et les fuites d'espaces réservés. Une erreur provoque un arrêt immédiat.
2. Synthèse TTS (voiceover.py) : Synthétise la voix segment par segment et écrit dans tts_segments/ et tts_meta.json. Le cache est précisément atteint en fonction du texte, du timbre, du modèle et de l'empreinte audio de référence. Si la durée audio d'un segment est inférieure à la limite inférieure de débit normal (TTS_MIN_SPEECH_RATE), suspect d'une hallucination du modèle, une nouvelle tentative est automatiquement effectuée et le fichier *.rejected.wav est conservé sans être intégré.
3. Mixage audio-vidéo (assemble.py) : Mélange l'image, la voix off segment par segment, l'audio original réduit et remonté en fin de phrase (voir references/data-schema.md pour la description de source_handoff_status), une éventuelle BGM (BGM_PATH), des effets sonores de transition optionnels, un packaging visuel élaboré (work_dir/packaging_plan.json : prise en charge des formats verticaux 9:16 avec doubles lignes d'or pour scène/série, des formats 16:9 avec cachet cinéma et bandeaux de sous-titres sur fond blanc cassé, des plaques nominatives @2x suréchantillonnées, des cartes de données, des textes décoratifs calligraphiques, ainsi que des sous-titres surlignés à double couche douce pour les mots-clés ; ou bien packaging_layers.json pour des images statiques), un fondu de sortie en douceur (par défaut 350ms), et rend le tout en MP4 final. Un fichier timeline.json indépendant du backend est également produit (avec --export-jianying, un brouillon Jianying peut être exporté).

Si une voix off ne peut pas tenir dans la fenêtre de temps disponible même avec la micro-accélération autorisée, le synthétiseur déclenche un blocage no_safe_fit, et ne coupe jamais la fin de la voix off. Plus de modes audio, de routage audio et de normes de packaging visuel sont disponibles respectivement dans references/audio-modes.md, references/audio-routing.md et references/packaging.md.

4.5 Montage multi-vidéos et bibliothèque de ressources

Les entrées multi-vidéos ne sont prises en charge qu'en mode cut. Le brief au niveau du projet liste le source_id fixe de chaque vidéo. Lors de l'écriture de clip_plan.json, chaque segment doit indiquer le source_id auquel il appartient :

python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep

Pour stocker les résultats de compréhension d'un épisode dans un répertoire local afin de les réutiliser entre épisodes, activez la bibliothèque de matériaux légère (--material-library-dir .video-materials --save-materials et --use-materials). Utilisez grep pour rechercher des fichiers JSON/MD. Dans le même répertoire racine de la bibliothèque, vous pouvez enregistrer des ressources de production réutilisables (BGM, effets sonores, timbres vocaux, polices, images), des modèles avec historique d'utilisation (subtitle_style, packaging, production_reference) et des échantillons. Interrogez-les via scripts/library.py check|list|show, et liez-les automatiquement à l'exécution en cours via --project recap_project.json. Après chaque synthèse, les ressources effectivement utilisées et leur état d'autorisation sont enregistrés dans work_dir/resource_lock.json. Voir references/resource-library.md.

Pour mesurer l'intervalle de pixels verticaux des sous-titres incrustés du film original afin d'activer le masquage précis, exécutez tools/measure_subtitle.py <video> dans le dépôt source complet, ou examinez directement les images extraites pour mesurer les bords supérieur et inférieur, puis transmettez --subtitle-y-top et --subtitle-y-bot.

4.6 Visionnage final et contrôle qualité de livraison

Aucun indicateur de script, note de montage, puzzle d'images extraites ou rapport QC automatique ne peut remplacer le visionnage et l'écoute humains. Avant chaque livraison, ouvrez directement le fichier final destiné à l'utilisateur et effectuez cinq vérifications :

1. Visionnage complet à vitesse normale : Du début à la fin, sans accélérer ni sauter. Notez tous les points gênants ou saccadés.
2. Examen individuel de chaque point de coupe : Regardez les 0,5 à 1 seconde autour de chaque point de coupe pour détecter les images flash, les fondus incomplets, les sauts d'action et les répliques originales coupées.
3. Écoute les yeux fermés : Sans regarder l'image, écoutez uniquement le son. Vérifiez si la voix off est hachée, si les transitions sonores sont fluides, si les répliques originales clés sont bien audibles.
4. Examen de trois points clés : Revoyez séparément l'accroche des 5 premières secondes, le point d'émotion culminant du milieu et la dernière scène de la fin. Confirmez que le timing d'entrée, le maintien de l'émotion et la rémanence finale sont tous convaincants.
5. Vérification des modifications et conformité des spécifications : En mode REVISION, confirmez d'abord que "ce qui a été demandé de changer a vraiment été changé, et ce qui n'a pas été mentionné est resté strictement identique". Enfin, vérifiez l'intégrité du décodage, la durée totale, le balayage des images résiduelles et les spécifications de codage audio-vidéo dans final_qc.json (--require-final-qc activé par défaut, les blocages déterminent le code de sortie ; uniquement pour le débogage, utilisez --no-require-final-qc).

Lors de la livraison du film fini, vérifiez impérativement les metadata.warnings dans final_qc.json. Dès qu'ils ne sont pas vides (par exemple, partial_tts avec segments manquants suite à une tolérance partielle, ou subtitle_burn_degraded avec rétrogradation en sous-titres .srt externes car libass manque dans ffmpeg local), vous devez en informer honnêtement l'utilisateur, sans vous contenter de dire "rendu réussi".

4.7 Film fini en son original sans commentaire

# Pour un mixage direct de l'entrée entière ; n'exécute pas implicitement la compréhension, l'ASR ou le TTS
python3 scripts/recap.py locked_picture.mp4 --work-dir source_work --audio-mode source-mix
# Génère un plan de montage selon le flux cut, monte et synthétise directement le film fini en son original, sans pause pour attendre narration.json
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --work-dir cut_work --audio-mode source-mix

source-mix exécute le mixage complet, le fondu de sortie en douceur et le ré-encodage audio. Utilisez un nouveau répertoire de travail lors du changement de mode audio. Voir references/audio-routing.md.

5. Auto-vérification et tableau de bord en lecture seule

python3 scripts/doctor.py
python3 scripts/dashboard_server.py --root <répertoire> [--port 0] [--open]

doctor.py vérifie la présence locale de ffmpeg/ffprobe, des filtres de sous-titres et la connectivité des clés de services distants. dashboard_server.py démarre une station de visionnage minimaliste strictement en lecture seule sur 127.0.0.1 (ne répond qu'aux requêtes GET et HEAD). Elle analyse automatiquement les répertoires de travail de films finis et library.json sous --root, affichant de manière intuitive la lecture du film fini, la synchro du commentaire et des plans, ainsi que l'aperçu de la bibliothèque de matériaux.

6. Sorties et paramètres

Livrables principaux :

• recap_<video>.mp4 : Film fini final avec commentaire ou son original.
• subtitles.srt / subtitles.ass : Fichiers de sous-titres générés.
• work_dir/ : Ensemble des produits intermédiaires d'analyse, de planification et de validation. Le contrat des champs est défini dans references/data-schema.md.
• work_dir/recap_story_plan.json et visual_audio_board.json : Décisions de mise en scène et de storyboard/audio prises par l'Agent.

La liste complète des paramètres de ligne de commande est disponible via python3 scripts/recap.py --help et l'--help de chaque script d'étape. Le paramètre --style est un texte libre transmis tel quel à l'Agent de rédaction ; ce n'est pas une option fixe ou une énumération.

7. Limites de capacité

• Les validations locales déterministes (images résiduelles/fragmentées, coupure de réplique, voix off chevauchant un dialogue, limite dure du nombre de mots dans une fenêtre de temps, suppression de fin excessive, perte d'image obligatoire, fuite d'espace réservé, spécifications de décodage et d'encapsulation) sont toujours exécutées comme des barrières strictes. Le script n'est responsable que de l'exécution mécanique et de la garantie du socle technique.
• La qualité sémantique et narrative (arc narratif, accroche d'ouverture, respiration son-image, cohérence factuelle) n'est pas évaluée par une note automatique. C'est à l'Agent de la maîtriser de manière autonome, en s'appuyant sur les preuves visuelles, la timeline audio originale et references/creative-editing-playbook.md, et d'effectuer la vérification audio-visuelle avant livraison.