Video-B-Roll hinzufügen

Video B-Roll hinzufügen

Fügen Sie einer verstandenen kanonischen Project-Protokoll-Sequenz eine kleine Anzahl belegbasierter visueller Einblendungen hinzu. Lesen Sie broll-rules.md, bevor Sie Medien planen oder beschaffen. Verwenden Sie example-broll-plan.json als Referenz für die Planform.

Nicht verhandelbarer Vertrag

Befolgen Sie jede redaktionelle, Provenienz-, Standbild-, Überprüfungs-, Wiederherstellungs- und Auslieferungsregel in broll-rules.md. Operativ:

• Verwenden Sie die bereitgestellten Skripte für Beschaffung, Validierung, Normalisierung, Quittungsanwendung und Verifizierung. Verwenden Sie niemals einen direkten Download-Pfad oder ersetzen Sie eine andere Stock-Quelle.
• Erfinden Sie niemals menschliche Autorität. Die Agentenüberprüfung erfordert eine explizite Delegation und eine wahrheitsgemäße Agentenquittung.
• Fehlende, schwache oder vom Downloader abgelehnte Medien werden zu skipped. Verwenden Sie niemals zufällige oder Standbild-Fallback-Medien.

Anforderungen und Eingaben

Erfordert Python, ffmpeg, ffprobe und Pillow. Für Pexels verwenden Sie zuerst PEXELS_API_KEY aus der Umgebung, dann suchen Sie danach in skills/video-add-b-roll/.env. Wenn beide fehlen oder leer sind, stoppen Sie und bitten Sie den Benutzer, PEXELS_API_KEY=<key> zu dieser Datei hinzuzufügen. Wiederholen Sie den Vorgang, nachdem der Benutzer dies bestätigt hat. Bitten Sie ihn, den Schlüssel über die lokale .env-Datei bereitzustellen, niemals über den Chat. Platzieren oder drucken Sie ihn niemals in einem Befehlsargument, Plan, einer URL, einem Log, einem Überprüfungsartefakt oder einer Antwort.

/video-understand ist eine Voraussetzung. Führen Sie es zuerst aus, damit B-Roll das validierte Transkript auf Wortebene und die kanonische Zeitleiste verwendet. Überprüfen Sie vor dem Start, ob es installiert ist. Wenn nicht, warnen Sie den Benutzer, dass diese Voraussetzung fehlt, und stoppen Sie, bevor Sie Medien verarbeiten.

Führen Sie vom Repository-Stammverzeichnis aus und ermitteln Sie das separate Projektstammverzeichnis:

$RepoRoot = (Resolve-Path '.').Path
$ProjectRoot = (Resolve-Path 'path/to/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', 'current upstream delivery is not verified'; path=projectlib.resolve_project_path(root,project['render']['output']); assert path.is_file(), 'current upstream delivery is missing'; print(path)" $ProjectRoot $ProjectLib
if ($LASTEXITCODE -ne 0) { throw 'Complete the active upstream delivery before B-roll review.' }
$ReviewVideo = (Resolve-Path -LiteralPath $ReviewVideo).Path

Verwenden Sie diese kanonischen Eingaben anstatt erneut zu transkribieren oder zu analysieren:

• work/project.json
• work/timeline.json
• work/understand/transcript.json
• work/understand/understanding.json
• ein aktuelles Programm-Zeit-Überprüfungsvideo, dessen Pixel aktive Schnitt- und Farbkorrekturarbeit enthalten

$ReviewVideo ist diese vorhandene verifizierte vorgelagerte Auslieferung, kein zu erfindender Dateiname oder eine neue B-Roll-Ausgabe. Es muss bereits mit der aktiven Zeitliniendauer, den Abmessungen und der Bildrate übereinstimmen. Wenn es fehlt oder veraltet ist, schließen Sie zuerst die vorgelagerte Schnitt-/Farbkorrektur-Auslieferung ab, ermitteln Sie dann und hashen Sie sie, bevor Sie fortfahren.

Der Vorgang hängt immer von understanding ab, plus cut und color-grade, wenn diese Vorgänge auf der Zielsequenz aktiv sind. Kopieren Sie deren aktuelle positive Integer-Revisionen in based_on. Wenn die Farbkorrektur aktiv ist, zeichnen Sie sowohl den Grading-Plan als auch die ausgewählten LUT-Hashes auf. Die Normalisierung muss diese exakte ausgewählte LUT erhalten und sie vorab auf jeden ausgewählten B-Roll-Shot anwenden.

Die kanonische Sequenzreihenfolge ist:

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

Der registrierte Vorgang muss changes_video_pixels: true haben, die b-roll-Spur hinzufügen und Zeitleiste, Geometrie und Audio unverändert lassen. broll_plan.register_operation() schreibt diesen Vertrag. Bauen Sie den Vorgang nicht von Hand.

Dauerhafte und wegwerfbare Dateien

work/b-roll/broll-plan.json                         # dauerhafter Domain-Plan
work/b-roll/presentation-decision.json               # dauerhafte Agent-Chat-Routenentscheidung
work/b-roll/broll-interaction.json                  # dauerhafte angewandte Quittung
work/b-roll/broll-selection.json                    # dauerhafte genehmigte exakte Auswahl und verbrauchte Seitenbindung
work/b-roll/speaker-inset-analysis.json             # dauerhaftes Szenen-/Beweispaket
work/b-roll/speaker-inset-agent-input.json          # dauerhafte Agent-ROI-Entscheidungen
work/b-roll/speaker-inset-preview.json              # dauerhafte exakte Vorschaubindungen
work/b-roll/speaker-inset-clearance.json            # dauerhafte Agent-Freigabeprüfung
work/b-roll/broll-revision-request-<UUID>.json      # dauerhafte nicht genehmigte Anfrage-Bytes
work/b-roll/candidate-search.json                   # dauerhafte Abfrage und Anbieterreihenfolge
work/b-roll/candidate-analysis.json                 # dauerhafte deterministische Beweise
work/b-roll/candidate-ranking.json                  # dauerhafte Agentenbewertung und Top 3
work/cache/b-roll/candidate-analysis/media/         # wegwerfbare Analysevarianten
work/cache/b-roll/candidate-analysis/frames/        # reproduzierbare Samples und Zuschnitte
work/cache/b-roll/candidates/                       # eingefrorene erworbene Medien
work/cache/b-roll/speaker-inset/                    # reproduzierbare Beweise und Vorschauen
work/cache/b-roll/normalized/                       # reproduzierbare stille Overlays
review/03-b-roll/candidate-analysis-<UUID>/          # unveränderliches Analysepaket
review/03-b-roll/candidate-analysis-<UUID>.md        # Analyse- und Basislinienzusammenfassung
review/03-b-roll/candidate-analysis-<UUID>/candidate-index.html
review/03-b-roll/b-roll-review-<UUID>.html          # unveränderliche Kandidatenüberprüfung
review/03-b-roll/b-roll-review.html                 # neuester Convenience-Alias
review/03-b-roll/stills/                            # erste/mittlere/letzte Verifikationsframes
review/03-b-roll/contact-sheet.jpg
review/03-b-roll/boundary-reel.mp4
review/03-b-roll/b-roll-summary.md

Halten Sie den Plan und die Quittung außerhalb von work/cache/. Behandeln Sie Kandidaten- und normalisierte Dateien als reproduzierbare, aber hash-gebundene Eingaben.

Arbeitsablauf

1. Aktuelle Abhängigkeiten ermitteln

Lesen Sie die aktive Sequenz, Vorgangsrevisionen, Zeitleiste, Transkript, Verständnis, aktiven Grading-Plan und ausgewählte LUT. Bestätigen Sie, dass das Überprüfungsvideo mit der Dauer, den Abmessungen und der rationalen Bildrate der aktiven Zeitleiste übereinstimmt. Hashen Sie das Transkript, die Zeitleiste, das Überprüfungsvideo und die aktiven Grading-Eingaben in input_hashes.

Verwenden Sie broll_plan.active_dependencies(project), um die genaue Abhängigkeitsliste abzuleiten. Eine geänderte Zeitleiste, ein geändertes Transkript, eine geänderte Abhängigkeitsrevision, ein geänderter Grading-Plan, eine geänderte LUT, ein geändertes Überprüfungsvideo, ein geändertes Kandidatenmanifest oder ein geändertes überprüftes Asset machen nachgelagerte Arbeit ungültig. Aktualisieren Sie den Plan und wiederholen Sie die Überprüfung, anstatt eine alte Quittung vorwärtszutragen.

2. Einen dynamisch-sozialen Plan erstellen

Erstellen Sie work/b-roll/broll-plan.json von Hand. Skripte führen Präzision aus, kein redaktionelles Urteil. Für jeden vorgeschlagenen Shot:

• wählen Sie einen positiven, halboffenen, nicht überlappenden Programmbereich in chronologischer Reihenfolge;
• mappen Sie ihn durch work/timeline.json in genaue source_ranges;
• bewahren Sie mindestens ein exakt gemapptes Transkriptwort mit Quell-/Programmbereichen und Clip-ID;
• geben Sie einen konkreten editorial_reason und visual_intent an;
• setzen Sie brief.search_context mit einem konkreten topic, visual_direction und 1-12 unique keywords;
• setzen Sie jede semantic_role auf direct, supportive oder atmospheric;
• schreiben Sie zwei oder drei geschichtete wörtliche englische Abfragen: eine direct subject/action-Abfrage, eine defensible context/process-Abfrage und, wenn eine dritte Abfrage nützlich ist, eine theme-enhancing variant;
• beginnen Sie mit planned, wechseln Sie zu candidates_ready nach der Beschaffung, oder verwenden Sie skipped, wenn kein relevanter Kandidat existiert.

Halten Sie brief.density gleich dynamic-social. Die geplante Abdeckung beginnt mit einem vollständigen A-Roll-Scan des gemappten Transkripts und der Zeitleiste, gefolgt von handgeschriebenen chronologischen, nicht überlappenden, redaktionell gültigen Bereichen. Behandeln Sie 0.40 bis 0.70 als weiches Ziel. Unter 0.40 nehmen Sie einen zweiten Durchgang und fügen nur verteidigbare Bereiche hinzu oder erweitern diese. Über 0.70 überprüfen Sie intern die A-Roll-Verdeckung. Fügen Sie niemals irrelevante Füllung hinzu oder schwächen Sie Relevanz, Rechte, Qualität oder ein anderes Zulassungskriterium, um das Ziel zu erreichen. Allgemeine thematische Begriffe wie tech oder entertainment dürfen nur eine Abfrage verfeinern. Sie ersetzen niemals die shotspezifische sichtbare Beziehung zwischen dem Kandidaten und der Transkriptaussage. Wenn kein Moment B-Roll verdient, ist ein genehmigter vollständig übersprungener Plan ein gültiger No-Op.

Fügen Sie während des Verfassens des Entwurfs keinen speaker_inset_style hinzu. Nach der Kandidatenbeschaffung wählt die explizite Agent-Chat-Präsentationsentscheidung den normalen oder den Speaker-Inset-Weg. Letzterer installiert automatisch den strengen projektweiten abgerundeten Rechteck-Stil: width_ratio: 0.39, grauer Rand, Seitenverhältnis, Eckenradius, Ränder und unterer untertitel-sicherer Bereich. Voreinstellung und Anker gehören nicht zum Stil. Der Agent zeichnet project_layout_strategy plus eine layout_recommendation pro Shot auf, nachdem er das exakt ausgewählte Medium inspiziert hat. Führen Sie niemals einen Gesichtsdetektor, ein Segmentierungsmodell, einen Cross-Cut-Identitäts-Tracker oder eine geschätzte ROI ein. Passen Sie die Speaker-ROI-Pixel mit seitenverhältnisbewahrender Cover-Skalierung in das Fenster ein. Strecken Sie sie niemals auf das konfigurierte Seitenverhältnis. Zentrieren Sie den Zuschnitt horizontal und verankern Sie ihn oben, sodass der vollständige Kopf und das Gesicht Vorrang vor der Unterkörperabdeckung haben.

Validieren Sie den Entwurf nach jeder wesentlichen Bearbeitung:

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 'B-roll plan valid'); raise SystemExit(bool(errors))" $ProjectRoot $BrollScripts

3. Kandidaten analysieren, bewerten und einfrieren

Die Kandidatenanalyse ist beratender Beweis vor candidates_ready. Sie wählt kein Medium aus, genehmigt keinen Shot, fügt keine Quittung hinzu oder ändert den Lebenszyklus. Behalten Sie die vorhandenen zwei oder drei wörtlichen Abfragen für jeden Shot.

Für lokale Videos schreiben Sie eine wahrheitsgemäße Provenienz und importieren Sie es über den vorhandenen Beschaffungspfad:

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"

Kopieren Sie den zurückgegebenen Datensatz in die candidates des Shots. Die Kandidatenanalyse liest diese exakte eingefrorene Cache-Datei. Sie kopiert sie nicht in ein anderes Provider- oder Analysesystem. Verwenden Sie --local-only, wenn der Plan Pexels nicht abfragen soll.

Sammeln Sie Pexels-Ergebnisse mit Round-Robin-Abfragezusammenführung, Provider-ID-Deduplizierung und maximal acht eindeutigen Provider-Videos pro Shot. Wählen Sie die Ausrichtung, die zur Zeitleiste passt:

$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

Für die lokale Analyse fügen Sie --local-only hinzu. Der Suchdatensatz bewahrt jede wörtliche Abfrage, ihre ursprüngliche Anbieterreihenfolge, die Round-Robin-Reihenfolge und beide Pexels-Varianten auf. Die Analysevariante ist die kleinste ausrichtungsangepasste Datei, deren kurze Kante mindestens 480 Pixel beträgt, oder die größte gültig passende Datei, wenn keine qualifiziert ist. Die Auslieferungsvariante bleibt die hochauflösendste ausrichtungsangepasste Datei.

Laden Sie nur Analysevarianten herunter und dekodieren Sie diese vollständig. Samplen Sie sie bei 10/30/50/70/90 Prozent und schreiben Sie deterministische maschinelle Beweise:

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"

Die Analyse enthält strenge Prüfungen, objektive Warnungen, gehashte Sample-Frames und Center-Crops, Kontaktbögen, Luma/Clipping/Edge/Motion-Beweise und Duplikatbeweise. Sie bewahrt die shotspezifische exakte Zurückweisung und strenge perzeptuelle Schwelle, fügt dann projektweite exakte Identität, strenge perzeptuelle Gruppen und nicht unterdrückende possible_series-Hinweise hinzu. Die harte Zurückweisung ist auf die objektiven Fehler in reference/broll-rules.md beschränkt.

Inspizieren Sie die exakten Transkriptbeweise, fünf Frames, Zuschnittsimulationen, Warnungen und Duplikatbeweise. Schreiben Sie work/cache/b-roll/candidate-ranking-input.json mit dieser Form:

{
  "schema_version": 1,
  "analysis_sha256": "<canonischer SHA-256 von candidate-analysis.json>",
  "mode": "agent",
  "actor": "<echter Agentenname>",
  "timestamp": "<zeitzonenbewusster Zeitstempel>",
  "overall_rationale": "<nicht-leere Begründung>",
  "near_duplicate_groups": [{
    "group_id": "<stabile Gruppen-ID>",
    "match_type": "same_series",
    "actor": "<echter Agentenname>",
    "timestamp": "<zeitzonenbewusster Zeitstempel>",
    "members": [
      {"shot_id": "<Shot-ID>", "candidate_id": "<Kandidaten-ID>"},
      {"shot_id": "<andere Shot-ID>", "candidate_id": "<andere Kandidaten-ID>"}
    ],
    "rationale": "<spezifische sichtbare Wiederholung über die beiden Transkriptmomente hinweg>"
  }],
  "shots": [{
    "shot_id": "<Shot-ID>",
    "candidates": [

...

[truncated]