Ajouter des légendes à une vidéo

Que fait Ajouter des légendes à une vidéo ?

Dépendances

/video-comprendre est un prérequis. Exécutez-le d'abord pour que les légendes utilisent la transcription validée au niveau du mot et la timeline canonique. Avant de commencer, vérifiez qu'il est installé. Dans le cas contraire, prévenez l'utilisateur que ce prérequis est manquant et arrêtez-vous avant de traiter le média.

Nécessite ffmpeg/ffprobe dans le PATH, Python avec Pillow, et Node.js >= 22 (pour les scripts .mjs et npx hyperframes, téléchargé à la demande). hyperframes render/snapshot utilise un Chrome headless — il gère son propre chrome-headless-shell et utilise un Chrome système (définissez CHROME pour le remplacer) lorsque le cache est inutilisable. Vérifiez tout cela avant de traiter le média.

Portée

Cette compétence gère le regroupement des légendes, la sélection du style, la révision et la piste de légende transparente. Elle ne transcrit pas, ne coupe pas, ne retiming pas, n'étalonne pas, ne recadre pas et ne choisit pas la politique audio de diffusion.

Exécutez les légendes avant les cartes de contenu et les animations graphiques lorsque l'une ou l'autre est sélectionnée. La disposition approuvée des légendes établit une zone de sous-titres réservée que les deux opérations ultérieures doivent garder libre. Cet ordre relatif s'applique également lorsqu'une seule paire est active.

Utilisez d'abord video-comprendre. Si une coupe existe, légendez la timeline du programme actif ; ne traitez pas les secondes de la transcription source comme des secondes du programme.

Entrées du protocole

Requis :

• work/project.json
• work/understand/transcript.json, avec les horodatages source au niveau du mot
• work/understand/media.json
• work/timeline.json
• la vidéo source nommée par work/project.json

La timeline est la seule correspondance source-programme. Toutes les plages sont semi-ouvertes [start_s, end_s). scripts/build_captions.py utilise le projectlib.map_transcript_to_timeline partagé ; les mots des plages source supprimées disparaissent, les mots conservés passent au temps programme, et les répliques se coupent toujours aux limites des clips.

Sorties durables

work/captions/
|-- captions-plan.json
|-- caption-spatial-context.json (uniquement pour les composites B-roll éligibles)
`-- caption-interaction.json
work/cache/captions/
|-- preview-project/
|-- preview-snapshots/
|-- overlay-project/
`-- overlay-frames/frame_000001.png ...
review/05-captions/
|-- captions.srt
|-- captions-style-review-<UUID>.html
|-- captions-style-review.html
|-- captions-review.html
|-- preview-early.png
|-- preview-middle.png
|-- preview-late.png
|-- preview-no-caption.png
|-- captions-evidence.json
`-- captions-summary.md

Le HTML généré, les fichiers d'exécution copiés, les images source extraites et les images de superposition sont du cache. Le plan, le contexte spatial optionnel, le SRT, le récépissé de décision et les preuves de révision sont durables.

Plan de légende

work/captions/captions-plan.json est le plan de légende canonique, cible overlay et utilise le temps programme. Il enregistre :

• timeline_id, program_duration_s et le chemin de la transcription source ;
• les paramètres de regroupement des répliques ;
• le style approuvé, le mode de décision, la justification, le choix de la galerie et le style résolu complet ;
• les preuves de révision basées sur la source et l'acteur d'approbation ;
• les répliques avec les champs de compatibilité start, end, text, lines et words ;
• program_range et source_ranges sur chaque réplique ;
• les plages programme/source et clip_id sur chaque mot mappé ;
• une recette de rendu locale avec FPS rationnelles exactes et actifs d'exécution hachés.

Le générateur accepte également l'ancien tableau de répliques de premier niveau. Il s'agit uniquement d'un adaptateur de compatibilité autonome ; il ne peut pas exprimer la provenance de la timeline ni régénérer une contribution de protocole approuvée.

Standard est le mode de présentation par défaut. Les plans Standard n'ont pas besoin d'un champ presentation et ne doivent pas être migrés uniquement pour en ajouter un. Expressif est un mode de présentation explicite, pas un préréglage : demandez-le avec --presentation-mode expressive. L'étape de construction ajoute ensuite des ID de répliques stables, des valeurs semantic_role par défaut pour les mots et une coquille de planification presentation préliminaire ; elle ne devine pas les variantes de disposition.

Expressif ne prend en charge que bottom-standard et center-emphasis. Lisez reference/caption-rules.md avant de remplir la coquille. Le rendu existant consomme uniquement les presentation.layout_beats complétés ; il n'infère pas les positions ni ne change la disposition à l'intérieur d'un temps.

Les répliques Expressives peuvent également définir une hero_line contiguë au niveau de la phrase. Utilisez le level: hero canonique ; il rend la phrase en doré sur sa propre ligne à 1.5x. L'ancien level: strong reste accepté comme alias d'entrée et rend à l'identique, mais les nouveaux plans rédigés par un Agent ne doivent pas l'émettre. Les rôles de mots maintenus keyword, number et contrast utilisent chacun 1.22x ; normal reste 1.0x. Ces traitements sont orthogonaux aux préréglages et ne créent pas de nouveaux ID de style. Lisez reference/caption-rules.md pour le schéma, la politique de débordement et les règles de Karaoké.

Lorsqu'une opération B-roll active approuvée en révision contient des composites d'incrustation d'intervenant approuvés ou vérifiés, les légendes peuvent dériver caption-spatial-context.json du plan figé en amont, des preuves, des composites normalisés et du display_mode explicite du sous-plan. Cela ne modifie ni ne resélectionne la disposition du B-roll. Cela aligne les limites des répliques avant la planification Expressive et ne résout que les placements maintenus preset-bottom, frame-center, panel-center et panel-bottom (limite uniquement). panel-bottom n'est autorisé que pour un unsplittable_word_boundary adjacent à un panneau centré en bas ; il centre la réplique stable dans la bande réservée sous le rectangle d'intervenant structuré. Une telle réplique est vérifiée par rapport à chaque contexte visuel qu'elle intersecte, et pas seulement le contexte contenant le milieu du mot. Sans ce contexte, tout comportement de placement Standard et Expressif existant reste inchangé.

Styles

Les préréglages maintenus sont clean, minimal, social-bold, pill, boxed, stroked et shorts. Les ID de combinaison de galerie ajoutent des thèmes maintenus, par exemple pill-yellow, stroked-blue et shorts-green. Le karaoké est une option, pas un préréglage séparé.

Choix délégué par défaut : clean, Karaoké désactivé. Choisissez un préréglage plus expressif uniquement lorsque la destination ou les images le justifient. Stockez les modifications spécifiques au travail dans un fichier JSON de remplacement ; ne modifiez pas le générateur pour un retour de style ordinaire.

Expressif prend en charge à la fois semantic-only (Karaoké désactivé) et semantic-plus-karaoke (Karaoké activé). L'emphase sémantique persiste pendant toute la réplique dans les deux configurations. En mode coexistence, l'emphase sémantique et le mot Karaoké actif utilisent style.wordHighlight.activeColor comme couleur de premier plan dans chaque mode de surbrillance ; une surbrillance d'arrière-plan reste un effet supplémentaire. L'échelle effective est max(échelle sémantique, échelle karaoké active), jamais leur produit. Expressif ne rend jamais de soulignement, y compris pour le rôle sémantique compatible contrast.

Le contrat de révision existant continue d'utiliser semantic-only comme preuve Expressive principale et lie semantic-plus-karaoke séparément. Le champ de charge utile de compatibilité reste nommé experimental_comparison ; ne le renommez pas sans une migration du protocole d'approbation.

Lisez :

• reference/caption-rules.md avant de modifier les limites de regroupement ;
• reference/caption-style-themes.md pour le vocabulaire de style ;
• reference/caption-feedback-mapping.md pour le mapping des remplacements.

Modes de décision

Deux modes honnêtes partagent la même machine d'état liée au hachage :

• human : transmettez le résumé exact copié de la galerie à select, affichez toutes les preuves de prévisualisation réelles et transmettez le résumé exact copié d'approbation ou de révision à confirm ou adjust. Les commandes liées à la page de révision n'acceptent pas les phrases d'approbation nues.
• agent : utilisez uniquement lorsque l'utilisateur délègue explicitement les décisions de légendes. Commencez par une note de délégation non vide, puis utilisez agent-select et agent-confirm avec des justifications non vides.

Les commandes humaines échouent en mode agent et les commandes agent échouent en mode humain. Standard sans contexte spatial nécessite les quatre images maintenues provenant de la source ; les révisions Expressives et composites utilisent leurs contrats de preuve dynamiques. Une modification de la source, du plan, de la timeline, du style, du remplacement, des métadonnées du projet, de la page de révision ou des preuves invalide l'approbation ; le contexte spatial, la révision du B-roll en amont ou les modifications du composite lié font de même. Reconstruisez les artefacts affectés et révisez-les à nouveau.

Flux de travail canonique

Exécutez depuis la racine du dépôt. Définissez les chemins du projet :

$RepoRoot = (Resolve-Path ".").Path
$SkillRoot = Join-Path $RepoRoot "skills\video-add-captions"
$ProjectRoot = (Resolve-Path "<project-root>").Path
$Work = Join-Path $ProjectRoot "work"
$SourceVideo = "<absolute path from work/project.json>"
$Plan = Join-Path $Work "captions\captions-plan.json"
$SpatialContext = Join-Path $Work "captions\caption-spatial-context.json"
$SpatialArgs = @()
$SpatialReviewArgs = @()
$Receipt = Join-Path $Work "captions\caption-interaction.json"
$Review = Join-Path $ProjectRoot "review\05-captions"
$Cache = Join-Path $Work "cache\captions"
$PreviewProject = Join-Path $Cache "preview-project"
$ComparisonProject = Join-Path $Cache "preview-project-expressive-karaoke"
$OverlayProject = Join-Path $Cache "overlay-project"
$OverlayFrames = Join-Path $Cache "overlay-frames"
New-Item -ItemType Directory -Force -Path (Split-Path $Plan),$Review,$Cache | Out-Null

Avant de construire le plan de légende, demandez à l'utilisateur de choisir le mode de présentation sauf si la demande actuelle en sélectionne déjà un explicitement. Formulez la question dans la langue de conversation actuelle de l'utilisateur tout en gardant les identifiants Standard et Expressive non traduits. Conservez le texte source anglais ci-dessous dans ce fichier, présentez le choix localisé dans la session actuelle, puis Présentez + STOP :

Choisissez le mode de présentation des légendes :

1. Standard : Utilise un placement conventionnel stable et convient à la plupart des contenus.
2. Expressif : Alterne entre placement bas et centré selon le sens et met en évidence les mots-clés et les chiffres.

Répondez avec Standard, Expressif, ou "Utiliser le défaut (Standard)."

N'exécutez pas build_captions.py tant que l'utilisateur n'a pas répondu. Si l'utilisateur délègue explicitement le choix dans n'importe quel libellé, sélectionnez Standard. Indiquez que Standard a été sélectionné comme défaut préservant la compatibilité avant de construire le plan.

Construisez les répliques en temps programme et le SRT de révision :

python "$SkillRoot\scripts\build_captions.py" `
  "$Work\understand\transcript.json" `
  $Plan `
  "$Review\captions.srt" `
  --timeline "$Work\timeline.json" `
  --source-transcript "understand/transcript.json" `
  --max-chars 42 --max-lines 2 --max-dur 6 --gap 0.6

Après que l'utilisateur a sélectionné Standard, la commande ci-dessus produit le plan Standard inchangé. Après que l'utilisateur a sélectionné Expressif, exécutez la même commande avec :

  --presentation-mode expressive

Après la génération des répliques préliminaires, inspectez l'opération B-roll active et son plan lié en lecture seule. Activez le placement composite uniquement lorsque l'opération est active, son statut est approved ou verified, review.status est approved, les liaisons d'analyse/entrée-agent/prévisualisation/autorisation de l'incrustation d'intervenant sont complètes, et au moins un plan vérifié ou normalisé a une disposition composite maintenue. Le constructeur spatial utilise le display_mode: enabled explicite du sous-plan pour la géométrie de l'intervenant ; pure_broll et l'absence de preuve d'intervenant n'impliquent jamais un rectangle d'intervenant.

Lorsque c'est éligible, alignez les répliques préliminaires sur chaque limite visuelle du B-roll avant de remplir les layout_beats ou hero_line Expressifs. L'alignement ne coupe qu'aux espaces entre les mots et réécrit de manière atomique ; une limite à l'intérieur d'un mot garde le mot entier et enregistre une preuve de révision obligatoire :

python "$SkillRoot\scripts\caption_spatial_context.py" align `
  --project-root $ProjectRoot --plan $Plan --out-plan $Plan

Pour un projet éligible, préparez les arguments optionnels utilisés par chaque étape ultérieure :

$SpatialArgs = @("--spatial-context", $SpatialContext)
$SpatialReviewArgs = @("--spatial-context", $SpatialContext, "--project-root", $ProjectRoot)

Lorsqu'aucun composite éligible n'existe, sautez les quatre commandes spatiales et laissez $SpatialArgs et $SpatialReviewArgs vides. Ne créez ni n'attachez de contexte vide.

Avant de commencer la sélection de style ou la génération d'un aperçu, l'Agent doit planifier l'ensemble du programme Expressif en une seule passe :

1. Lisez la transcription, les artefacts de compréhension disponibles, la timeline canonique, les répliques de légendes générées et toute preuve d'image source réelle nécessaire pour justifier les changements de disposition.
2. Remplissez tous les presentation.layout_beats, annotez les valeurs semantic_role exceptionnelles des mots, ajoutez au plus une hero_line contiguë avec level: hero canonique à une réplique lorsque cela est justifié, écrivez une justification par temps/ligne héroïque et écrivez la presentation.planner.rationale globale.
3. Définissez presentation.planning_status sur complete uniquement après que chaque réplique est couverte exactement une fois.
4. Validez le plan complété avant la génération de l'aperçu :

python "$SkillRoot\scripts\build_captions.py" --validate-plan $Plan

Pour un composite éligible, construisez, validez et attachez le contexte uniquement après que les ID de répliques finaux et les candidats Expressifs sont complets. Cela préserve la disposition en amont et lie sa révision actuelle et ses hachages dans le plan de légende :

python "$SkillRoot\scripts\caption_spatial_context.py" build `
  --project-root $ProjectRoot --plan $Plan --out $SpatialContext

python "$SkillRoot\scripts\caption_spatial_context.py" validate `
  --project-root $ProjectRoot --plan $Plan --context $SpatialContext

python "$SkillRoot\scripts\caption_spatial_context.py" attach `
  --project-root $ProjectRoot --plan $Plan --context $SpatialContext

Ne demandez pas à l'utilisateur de choisir une position réplique par réplique. L'utilisateur examine les preuves HTML existantes et ne corrige qu'un petit nombre de temps anormaux. Commencer l'interaction après la planification maintient la liaison de hachage du plan de légende existante comme faisant autorité.

Démarrez un mode de décision. Pour le mode humain, publiez la galerie maintenue hors ligne dans le répertoire de révision du projet sans demander à l'utilisateur de localiser un fichier :

$StartOutput = node "$SkillRoot\scripts\caption_interaction.mjs" start `
  --state $Receipt --source $SourceVideo ...

Pour le mode agent, passez directement à agent-select avec une justification.