Ajouter un B-Roll vidéo

Que fait Ajouter un B-Roll vidéo ?

Ajoutez un petit nombre de coupures visuelles justifiées par des preuves à une séquence de protocole de projet canonique comprise. Lisez broll-rules.md avant de planifier ou d'acquérir un média. Utilisez example-broll-plan.json comme référence de forme du plan.

Contrat non négociable

Respectez chaque règle éditoriale, de provenance, d'image fixe, de révision, de récupération et de livraison dans broll-rules.md. Opérationnellement :

• Utilisez les scripts fournis pour l'acquisition, la validation, la normalisation, l'application des reçus et la vérification. N'utilisez jamais un chemin de téléchargement brut ou une autre source de stock.
• Ne créez jamais d'autorité humaine. La révision par Agent nécessite une délégation explicite et un reçu d'Agent véridique.
• Les médias manquants, faibles ou rejetés par le téléchargeur deviennent skipped ; n'utilisez jamais de médias de secours aléatoires ou d'images fixes.

Exigences et entrées

Requiert Python, ffmpeg, ffprobe et Pillow. Pour Pexels, utilisez d'abord PEXELS_API_KEY depuis l'environnement, puis cherchez-la dans skills/video-add-b-roll/.env. Si les deux sont absents ou vides, arrêtez-vous et demandez à l'utilisateur d'ajouter PEXELS_API_KEY=<clé> à ce fichier, puis réessayez après qu'il ait confirmé. Demandez-lui de fournir la clé via le fichier .env local, jamais via le chat. Ne placez ni n'imprimez jamais la clé dans un argument de commande, un plan, une URL, un journal, un artefact de révision ou une réponse.

/video-understand est un prérequis. Exécutez-le d'abord pour que le B-roll utilise la transcription validée au niveau du mot et la chronologie canonique. Avant de commencer, vérifiez qu'il est installé. S'il ne l'est pas, avertissez l'utilisateur que ce prérequis manque et arrêtez-vous avant de traiter le média.

Exécutez depuis la racine du dépôt et résolvez la racine du projet séparée :

$RepoRoot = (Resolve-Path '.').Path
$ProjectRoot = (Resolve-Path 'chemin/vers/video-project').Path
$BrollEnv = Join-Path $RepoRoot 'skills/video-add-b-roll/.env'
if ([string]::IsNullOrWhiteSpace($env:PEXELS_API_KEY) -and (Test-Path -LiteralPath $BrollEnv)) {
  $PexelsKeyLine = Get-Content -LiteralPath $BrollEnv | Where-Object { $_ -match '^\s*PEXELS_API_KEY\s*=' } | Select-Object -Last 1
  if ($PexelsKeyLine) { $env:PEXELS_API_KEY = ($PexelsKeyLine -split '=', 2)[1].Trim().Trim('"').Trim("'") }
}
$BrollScripts = Join-Path $RepoRoot 'skills/video-add-b-roll/scripts'
$ProjectLib = Join-Path $RepoRoot 'skills/video-understand/scripts'
$ReviewVideo = & python -c "import sys; from pathlib import Path; sys.path.insert(0,sys.argv[2]); import projectlib; root=Path(sys.argv[1]); project=projectlib.load_json(root/'work/project.json'); assert project.get('render',{}).get('status') == 'verified', 'la livraison en amont actuelle n\"est pas vérifiée'; path=projectlib.resolve_project_path(root,project['render']['output']); assert path.is_file(), 'la livraison en amont actuelle est manquante'; print(path)" $ProjectRoot $ProjectLib
if ($LASTEXITCODE -ne 0) { throw 'Terminez la livraison active en amont avant la révision du B-roll.' }
$ReviewVideo = (Resolve-Path -LiteralPath $ReviewVideo).Path

Consommez ces entrées canoniques au lieu de retranscrire ou de réanalyser :

• work/project.json
• work/timeline.json
• work/understand/transcript.json
• work/understand/understanding.json
• une vidéo de révision en temps programme actuel dont les pixels incluent le travail actif de coupe et d'étalonnage

$ReviewVideo est cette livraison vérifiée existante en amont, pas un nom de fichier à inventer ni un nouveau rendu B-roll. Elle doit déjà correspondre à la durée, aux dimensions et au FPS de la chronologie active. Si elle est absente ou obsolète, terminez d'abord la livraison de coupe/étalonnage en amont, puis résolvez-la et hachez-la avant de continuer.

L'opération dépend toujours de understanding, plus cut et color-grade lorsque ces opérations sont actives sur la séquence cible. Copiez leurs révisions entières positives actuelles dans based_on. Lorsque l'étalonnage est actif, enregistrez à la fois le plan de grade et les hachages du LUT sélectionné ; la normalisation doit recevoir ce LUT sélectionné exact et le pré-appliquer à chaque plan B-roll sélectionné.

L'ordre canonique de la séquence est :

cut -> color-grade -> b-roll -> captions -> content-cards -> graphic-motion

L'opération enregistrée doit avoir changes_video_pixels: true, ajouter la piste b-roll, et laisser la chronologie, la géométrie et l'audio inchangés. broll_plan.register_operation() écrit ce contrat ; ne construisez pas l'opération manuellement.

Fichiers durables et jetables

work/b-roll/broll-plan.json                         # plan de domaine durable
work/b-roll/presentation-decision.json               # décision de routage de chat Agent durable
work/b-roll/broll-interaction.json                  # reçu appliqué durable
work/b-roll/broll-selection.json                    # sélection exacte approuvée et liaison de page consommée durables
work/b-roll/speaker-inset-analysis.json             # paquet scène/preuve durable
work/b-roll/speaker-inset-agent-input.json          # décisions ROI de l'Agent durables
work/b-roll/speaker-inset-preview.json              # liaisons de prévisualisation exactes durables
work/b-roll/speaker-inset-clearance.json            # vérification d'obstruction de l'Agent durable
work/b-roll/broll-revision-request-<UUID>.json      # octets de demande non approuvés durables
work/b-roll/candidate-search.json                   # requête et ordre du fournisseur durables
work/b-roll/candidate-analysis.json                 # preuves déterministes durables
work/b-roll/candidate-ranking.json                  # classement de l'Agent et Top 3 durables
work/cache/b-roll/candidate-analysis/media/         # variantes d'analyse jetables
work/cache/b-roll/candidate-analysis/frames/        # échantillons et recadrages reproductibles
work/cache/b-roll/candidates/                       # médias acquis gelés
work/cache/b-roll/speaker-inset/                    # preuves et prévisualisations reproductibles
work/cache/b-roll/normalized/                       # superpositions silencieuses reproductibles
review/03-b-roll/candidate-analysis-<UUID>/          # paquet d'analyse immuable
review/03-b-roll/candidate-analysis-<UUID>.md        # résumé de l'analyse et de la ligne de base
review/03-b-roll/candidate-analysis-<UUID>/candidate-index.html
review/03-b-roll/b-roll-review-<UUID>.html          # révision immuable des candidats
review/03-b-roll/b-roll-review.html                 # alias de commodité le plus récent
review/03-b-roll/stills/                            # images de vérification première/milieu/dernière
review/03-b-roll/contact-sheet.jpg
review/03-b-roll/boundary-reel.mp4
review/03-b-roll/b-roll-summary.md

Gardez le plan et le reçu en dehors de work/cache/. Traitez les fichiers candidats et normalisés comme reproductibles mais liés par hachage.

Flux de travail

1. Établir les dépendances actuelles

Lisez la séquence active, les révisions d'opération, la chronologie, la transcription, la compréhension, le plan de grade actif et le LUT sélectionné. Confirmez que la vidéo de révision correspond à la durée, aux dimensions et au FPS rationnel de la chronologie active. Hachez la transcription, la chronologie, la vidéo de révision et les entrées de grade actives dans input_hashes.

Utilisez broll_plan.active_dependencies(project) pour dériver la liste de dépendances exacte. Une chronologie, une transcription, une révision de dépendance, un plan de grade, un LUT, une vidéo de révision, un manifeste candidat ou un actif révisé modifiés rendent le travail en aval obsolète ; rafraîchissez le plan et répétez la révision plutôt que de reporter un ancien reçu.

2. Créer un plan social dynamique

Créez manuellement work/b-roll/broll-plan.json ; les scripts effectuent la précision, pas le jugement éditorial. Pour chaque plan proposé :

• choisissez une plage de programme positive, demi-ouverte et non chevauchante dans l'ordre chronologique ;
• mappez-la via work/timeline.json en source_ranges exactes ;
• conservez au moins un mot de transcription mappé exact avec les plages source/programme et l'ID de clip ;
• indiquez une editorial_reason et une visual_intent concrètes ;
• définissez brief.search_context avec un topic, une visual_direction et 1-12 mots-clés uniques concrets ;
• définissez chaque semantic_role sur direct, supportive ou atmospheric ;
• écrivez deux ou trois requêtes littérales en anglais en couches : une requête direct subject/action, une requête defensible context/process et, lorsqu'une troisième requête est utile, une theme-enhancing variant ;
• commencez par planned, passez à candidates_ready après l'acquisition, ou utilisez skipped lorsqu'aucun candidat pertinent n'existe.

Gardez brief.density égal à dynamic-social. La couverture prévue commence par un balayage complet du A-roll de la transcription et de la chronologie mappées, suivi de plages chronologiques, non chevauchantes et éditorialement valides créées manuellement. Traitez 0.40 à 0.70 comme un objectif souple. En dessous de 0.40, effectuez un deuxième passage et n'ajoutez ou n'étendez que des plages défendables. Au-dessus de 0.70, examinez en interne le masquage du A-roll. N'ajoutez jamais de remplissage non pertinent et n'affaiblissez pas la pertinence, les droits, la qualité ou une autre porte d'éligibilité pour atteindre l'objectif. Des termes thématiques génériques tels que tech ou entertainment peuvent affiner une requête uniquement ; ils ne remplacent jamais la relation visible par plan entre le candidat et l'affirmation de la transcription. Si aucun moment ne mérite un B-roll, un plan approuvé entièrement skipped est un no-op valide.

N'ajoutez pas speaker_inset_style lors de la création du brouillon. Après l'acquisition des candidats, la décision explicite de présentation du chat Agent sélectionne la route ordinaire ou speaker-inset. Cette dernière installe automatiquement le style strict de rectangle arrondi au niveau du projet : width_ratio: 0.39, bordure grise, rapport d'aspect, rayon de coin, marges et zone inférieure de sous-titres sûre. Le préréglage et l'ancre n'appartiennent pas au style. L'Agent enregistre project_layout_strategy plus une layout_recommendation par plan après inspection du média exact sélectionné. N'introduisez jamais de détecteur de visage, de modèle de segmentation, de suivi d'identité inter-coupe ou de ROI deviné. Ajustez les pixels ROI du locuteur dans la fenêtre avec un redimensionnement couvrant préservant l'aspect ; ne les étirez jamais au rapport d'aspect configuré. Centrez le recadrage horizontalement et ancrez-le en haut afin que la tête et le visage complets aient la priorité sur la couverture du bas du corps.

Validez le brouillon après chaque modification matérielle :

python -c "import sys; from pathlib import Path; root=Path(sys.argv[1]); sys.path.insert(0,sys.argv[2]); import broll_plan,projectlib; plan=projectlib.load_json(root/'work/b-roll/broll-plan.json'); timeline=projectlib.load_json(root/'work/timeline.json'); transcript=projectlib.load_json(root/'work/understand/transcript.json'); project=projectlib.load_json(root/'work/project.json'); errors=broll_plan.validate_plan(plan,timeline,transcript,project=project,project_root=root,verify_files=True); print('\n'.join(errors) if errors else 'Plan B-roll valide'); raise SystemExit(bool(errors))" $ProjectRoot $BrollScripts

3. Analyser, classer et geler les candidats

L'analyse des candidats est une preuve consultative avant candidates_ready. Elle ne sélectionne pas le média, n'approuve pas un plan, n'ajoute pas de reçu ni ne modifie le cycle de vie. Conservez les deux ou trois requêtes littérales existantes pour chaque plan.

Pour la vidéo locale, écrivez une provenance véridique et importez-la via le chemin d'acquisition existant :

python "$BrollScripts/pexels.py" import-local `
  "$ProjectRoot/input/example-owned-footage.mp4" `
  "$ProjectRoot/work/cache/b-roll/candidates/example-owned-footage.mp4" `
  "$ProjectRoot/work/b-roll/example-local-provenance.json"

Copiez l'enregistrement retourné dans les candidates du plan. L'analyse des candidats lit ce fichier de cache gelé exact ; elle ne le copie pas dans un autre fournisseur ou système d'analyse. Utilisez --local-only lorsque le plan ne doit pas interroger Pexels.

Collectez les résultats Pexels avec un fusionnement de requêtes round-robin, une déduplication par ID de fournisseur et un maximum de huit vidéos uniques par fournisseur par plan. Choisissez l'orientation qui correspond à la chronologie :

$CandidateAnalysis = Join-Path $BrollScripts 'candidate_analysis.py'
python $CandidateAnalysis search `
  $ProjectRoot `
  "$ProjectRoot/work/b-roll/broll-plan.json" `
  "$ProjectRoot/work/b-roll/candidate-search.json" `
  --orientation portrait `
  --per-page 8

Pour une analyse locale uniquement, ajoutez --local-only. L'enregistrement de recherche préserve chaque requête littérale, son ordre de fournisseur d'origine, l'ordre round-robin et les deux variantes Pexels. La variante d'analyse est le plus petit fichier correspondant à l'orientation dont le bord court est d'au moins 480 pixels, ou le plus grand fichier correspondant valide lorsqu'aucun ne se qualifie. La variante de livraison reste le fichier correspondant à l'orientation de la plus haute résolution.

Téléchargez et décodez complètement uniquement les variantes d'analyse, échantillonnez-les à 10/30/50/70/90 pour cent, et écrivez des preuves machine déterministes :

python $CandidateAnalysis analyze `
  $ProjectRoot `
  "$ProjectRoot/work/b-roll/broll-plan.json" `
  "$ProjectRoot/work/b-roll/candidate-search.json" `
  "$ProjectRoot/work/timeline.json" `
  "$ProjectRoot/work/b-roll/candidate-analysis.json"

L'analyse contient des vérifications strictes, des avertissements objectifs, des hachages d'image échantillonnée et de recadrage central, des feuilles de contact, des preuves de luminance/écrêtage/bord/mouvement et des preuves de doublon. Elle préserve le rejet exact au niveau du plan et le seuil perceptif strict, puis ajoute une identité exacte au niveau du projet, des groupes perceptifs stricts et des indices possible_series non suppresseurs. Le rejet strict est limité aux échecs objectifs dans reference/broll-rules.md.

Inspectez les preuves exactes de la transcription, cinq images, les simulations de recadrage, les avertissements et les preuves de doublon. Écrivez work/cache/b-roll/candidate-ranking-input.json avec cette forme :

{
  "schema_version": 1,
  "analysis_sha256": "<SHA-256 canonique de candidate-analysis.json>",
  "mode": "agent",
  "actor": "<nom réel de l'Agent>",
  "timestamp": "<horodatage tenant compte du fuseau horaire>",
  "overall_rationale": "<justification non vide>",
  "near_duplicate_groups": [{
    "group_id": "<identifiant de groupe stable>",
    "match_type": "same_series",
    "actor": "<nom réel de l'Agent>",
    "timestamp": "<horodatage tenant compte du fuseau horaire>",
    "members": [
      {"shot_id": "<identifiant du plan>", "candidate_id": "<identifiant du candidat>"},
      {"shot_id": "<autre identifiant du plan>", "candidate_id": "<autre identifiant du candidat>"}
    ],
    "rationale": "<répétition visible spécifique entre les deux moments de la transcription>"
  }],
  "shots": [{
    "shot_id": "<identifiant du plan>",
    "candidates": [{
      "candidate_id": "<identifiant du candidat>",
      "origin": "pexels" | "local",
      "provenance": { ... },
      "score": <0-100>,
      "strengths": ["<force listée>"],
      "weaknesses": ["<faiblesse listée>"],
      "required_modifications": ["<modification requise listée>"],
      "alternatives": ["<autre identifiant du candidat>"],
      "near_duplicate_of": ["<identifiant du candidat dans un autre plan>"]
    }],
    "recommendation": "<recommandation textuelle pour le plan>"
  }]
}

4. Sélectionner les candidats et lier des pages Pexels

Choisissez au plus un candidat par plan. Enregistrez la sélection exacte dans work/b-roll/broll-selection.json. Les champs selected_candidate et human_chosen doivent être présents. Si human_chosen est true, attendez la confirmation humaine. Sinon, procédez avec la sélection de l'Agent.

Pour les candidats Pexels, liez leur page de détail dans l'entrée provenance. N'utilisez jamais de lien de téléchargement direct dans le plan, le reçu ou tout artefact de révision. Le lien de page doit pointer vers https://www.pexels.com/video/....

5. Acquérir des médias et vérifier

Téléchargez et normalisez chaque candidat sélectionné :

python $BrollScripts/pexels.py download `
  "$ProjectRoot" `
  "$ProjectRoot/work/b-roll/broll-plan.json" `
  "$ProjectRoot/work/b-roll/broll-selection.json" `
  --delivery-variant

Cela écrit dans work/cache/b-roll/candidates/. Normalisez ensuite :

python $BrollScripts/normalize.py `
  "$ProjectRoot" `
  "$ProjectRoot/work/b-roll/broll-plan.json" `
  "$ProjectRoot/work/b-roll/broll-selection.json" `
  --apply-grade-lut

Cela écrit dans work/cache/b-roll/normalized/. Vérifiez que les fichiers normalisés correspondent au plan en termes de durée, dimensions et FPS.

6. Réviser et approuver

Générez des artefacts de révision :

python $BrollScripts/generate_review.py `
  "$ProjectRoot" `
  "$ProjectRoot/work/b-roll/broll-plan.json" `
  "$ProjectRoot/work/b-roll/broll-selection.json" `
  "$ProjectRoot/work/b-roll/candidate-analysis.json" `
  --output-dir "review/03-b-roll"

Cela crée b-roll-review.html et b-roll-summary.md dans review/03-b-roll/. Examinez la révision avec l'utilisateur. Apportez les modifications nécessaires et répétez la sélection, l'acquisition et la révision jusqu'à approbation.

7. Appliquer le reçu et rendre

Une fois approuvé, appliquez le reçu d'interaction :

python $BrollScripts/apply_receipt.py `
  "$ProjectRoot" `
  "$ProjectRoot/work/b-roll/broll-plan.json" `
  "$ProjectRoot/work/b-roll/broll-selection.json" `
  "$ProjectRoot/work/b-roll/broll-interaction.json"

Cela met à jour broll-interaction.json avec l'état final. Ensuite, rendez le projet avec le B-roll appliqué :

python $ProjectLib/render.py `
  "$ProjectRoot" `
  --operation "b-roll" `
  --output "work/b-roll/render.mp4"

Vérifiez le rendu :

python $BrollScripts/verify_render.py `
  "$ProjectRoot" `
  "work/b-roll/render.mp4" `
  "$ProjectRoot/work/timeline.json"

Si la vérification réussit, marquez la livraison comme vérifiée dans work/project.json.

Dépannage

• Problème : La clé API Pexels est manquante ou incorrecte. Solution : Demandez à l'utilisateur de fournir la clé via le fichier .env comme décrit ci-dessus.

• Problème : Pas de candidats Pexels disponibles pour une requête. Solution : Vérifiez l'orthographe des mots-clés et la largeur de la requête. Utilisez des termes plus généraux si nécessaire. Le plan peut marquer le plan comme skipped.

• Problème : Média local introuvable ou fichier corrompu. Solution : Vérifiez le chemin et l'intégrité du fichier. L'importation locale échouera avec une erreur claire.

• Problème : La chronologie ou la transcription a changé depuis la dernière analyse. Solution : Régénérez les dépendances (video-understand) et recommencez la planification du B-roll.

• Problème : La vidéo de révision est obsolète ou ne correspond pas. Solution : Terminez d'abord le travail de coupe/étalonnage en amont et assurez-vous que la vidéo de révision est vérifiée et correspond à la chronologie active.