video-add-b-roll

Agregar B-roll al Video

Agrega un pequeño número de cortes visuales respaldados por evidencia a una secuencia del Protocolo de Proyecto canónico comprendido. Lee broll-rules.md antes de planificar o adquirir cualquier metraje. Usa example-broll-plan.json como referencia de la estructura del plan.

Contrato No Negociable

Sigue cada regla editorial, de procedencia, de imagen fija, de revisión, de recuperación y de entrega en broll-rules.md. Operativamente:

• Usa los scripts proporcionados para adquisición, validación, normalización, aplicación de recibo y verificación. Nunca uses una ruta de descarga directa ni sustituyas otra fuente de stock.
• Nunca fabriques autoridad humana. La revisión del agente requiere delegación explícita y un recibo de agente veraz.
• El metraje faltante, débil o rechazado por el descargador se convierte en skipped; nunca uses metraje aleatorio o imágenes fijas de respaldo.

Requisitos y Entradas

Requiere Python, ffmpeg, ffprobe y Pillow. Para Pexels, primero usa PEXELS_API_KEY del entorno, luego búscalo en skills/video-add-b-roll/.env. Si ambos faltan o están en blanco, detente y pídele al usuario que agregue PEXELS_API_KEY=<clave> a ese archivo, luego reintenta después de que confirme. Pídele que proporcione la clave a través del archivo .env local, nunca a través del chat. Nunca la coloques ni la imprimas en un argumento de comando, plan, URL, registro, artefacto de revisión o respuesta.

/video-understand es un requisito previo. Ejecútalo primero para que el B-roll use el transcript validado a nivel de palabra y la línea de tiempo canónica. Antes de comenzar, verifica que esté instalado. Si no lo está, advierte al usuario que falta este requisito previo y detente antes de procesar el metraje.

Ejecuta desde la raíz del repositorio y resuelve la raíz del proyecto separada:

$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 'Completa la entrega ascendente activa antes de la revisión del B-roll.' }
$ReviewVideo = (Resolve-Path -LiteralPath $ReviewVideo).Path

Consume estas entradas canónicas en lugar de volver a transcribir o reanalizar:

• work/project.json
• work/timeline.json
• work/understand/transcript.json
• work/understand/understanding.json
• un video de revisión de tiempo de programa actual cuyos píxeles incluyan trabajo de corte y gradación de color activo

$ReviewVideo es esa entrega ascendente existente verificada, no un nombre de archivo para inventar ni una nueva renderización de B-roll. Debe coincidir ya con la duración, dimensiones y FPS de la línea de tiempo activa. Si está ausente o desactualizado, termina primero la entrega ascendente de corte/gradación de color, luego resuélvela y hashea antes de continuar.

La operación siempre depende de understanding, más cut y color-grade cuando esas operaciones están activas en la secuencia objetivo. Copia sus revisiones de enteros positivos actuales a based_on. Cuando la gradación de color está activa, registra tanto el plan de gradación como los hashes de LUT seleccionado; la normalización debe recibir esa LUT seleccionada exacta y pre-aplicarla a cada toma de B-roll seleccionada.

El orden canónico de la secuencia es:

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

La operación registrada debe tener changes_video_pixels: true, agregar la pista b-roll y dejar la línea de tiempo, geometría y audio sin cambios. broll_plan.register_operation() escribe este contrato; no construyas la operación manualmente.

Archivos Duraderos y Desechables

work/b-roll/broll-plan.json                         # plan de dominio duradero
work/b-roll/presentation-decision.json               # decisión de ruta de chat de agente duradera
work/b-roll/broll-interaction.json                  # recibo aplicado duradero
work/b-roll/broll-selection.json                    # selección exacta aprobada y vinculación de página consumida duradera
work/b-roll/speaker-inset-analysis.json             # paquete de escena/evidencia duradero
work/b-roll/speaker-inset-agent-input.json          # decisiones de ROI de agente duraderas
work/b-roll/speaker-inset-preview.json              # vistas previas exactas vinculadas duraderas
work/b-roll/speaker-inset-clearance.json            # verificación de obstrucción de agente duradera
work/b-roll/broll-revision-request-<UUID>.json      # bytes de solicitud de revisión no aprobados duraderos
work/b-roll/candidate-search.json                   # consulta y orden del proveedor duradero
work/b-roll/candidate-analysis.json                 # evidencia determinista duradera
work/b-roll/candidate-ranking.json                  # ranking de agente y Top 3 duradero
work/cache/b-roll/candidate-analysis/media/         # variantes de análisis desechables
work/cache/b-roll/candidate-analysis/frames/        # muestras y recortes reproducibles
work/cache/b-roll/candidates/                       # metraje adquirido congelado
work/cache/b-roll/speaker-inset/                    # evidencia y vistas previas reproducibles
work/cache/b-roll/normalized/                       # superposiciones silenciosas reproducibles
review/03-b-roll/candidate-analysis-<UUID>/          # paquete de análisis inmutable
review/03-b-roll/candidate-analysis-<UUID>.md        # resumen de análisis y línea base
review/03-b-roll/candidate-analysis-<UUID>/candidate-index.html
review/03-b-roll/b-roll-review-<UUID>.html          # revisión de candidatos inmutable
review/03-b-roll/b-roll-review.html                 # alias de conveniencia más reciente
review/03-b-roll/stills/                            # fotogramas de verificación primero/medio/último
review/03-b-roll/contact-sheet.jpg
review/03-b-roll/boundary-reel.mp4
review/03-b-roll/b-roll-summary.md

Mantén el plan y el recibo fuera de work/cache/. Trata los archivos de candidatos y normalizados como reproducibles pero vinculados por hash.

Flujo de Trabajo

1. Establecer Dependencias Actuales

Lee la secuencia activa, las revisiones de operación, la línea de tiempo, el transcript, el entendimiento, el plan de gradación activo y la LUT seleccionada. Confirma que el video de revisión coincida con la duración, dimensiones y FPS racional de la línea de tiempo activa. Hashea el transcript, la línea de tiempo, el video de revisión y las entradas de gradación activas en input_hashes.

Usa broll_plan.active_dependencies(project) para derivar la lista de dependencias exacta. Una línea de tiempo, transcript, revisión de dependencia, plan de gradación, LUT, video de revisión, manifiesto de candidatos o activo revisado cambiado hace que el trabajo posterior quede obsoleto; actualiza el plan y repite la revisión en lugar de llevar un recibo antiguo.

2. Autoría de un Plan Social Dinámico

Autoría manual de work/b-roll/broll-plan.json; los scripts realizan precisión, no juicio editorial. Para cada toma propuesta:

• elige un rango de programa positivo, semiabierto, no superpuesto en orden cronológico;
• mapealo a través de work/timeline.json a source_ranges exactos;
• conserva al menos una palabra de transcript mapeada exacta con rangos de fuente/programa e ID de clip;
• declara un editorial_reason concreto y visual_intent;
• establece brief.search_context con un topic concreto, visual_direction y 1-12 palabras clave únicas;
• asigna cada semantic_role a direct, supportive o atmospheric;
• escribe dos o tres consultas literales en inglés en capas: una consulta de direct subject/action, una consulta de defensible context/process y, cuando una tercera consulta sea útil, una theme-enhancing variant;
• comienza en planned, pasa a candidates_ready después de la adquisición, o usa skipped cuando no exista un candidato relevante.

Mantén brief.density igual a dynamic-social. La cobertura planificada comienza con un escaneo completo de A-roll del transcript y la línea de tiempo mapeados, seguido de rangos cronológicos, no superpuestos y editorialmente válidos, escritos manualmente. Trata 0.40 a 0.70 como un objetivo suave. Por debajo de 0.40, haz una segunda pasada y solo agrega o extiende rangos defendibles. Por encima de 0.70, revisa internamente el ocultamiento de A-roll. Nunca agregues relleno irrelevante ni debilites la relevancia, derechos, calidad u otra puerta de elegibilidad para alcanzar el objetivo. Términos temáticos genéricos como tech o entertainment pueden refinar una consulta solo; nunca reemplazan la relación visible por toma entre el candidato y la afirmación del transcript. Si ningún momento merece B-roll, un plan aprobado completamente saltado es una no operación válida.

No agregues speaker_inset_style mientras autorías el borrador. Después de la adquisición de candidatos, la decisión de presentación explícita del agente en el chat selecciona la ruta ordinaria o de recuadro del orador. Esta última instala automáticamente el estilo estricto de rectángulo redondeado a nivel de proyecto: width_ratio: 0.39, borde gris, relación de aspecto, radio de esquina, márgenes y área inferior segura para subtítulos. El preajuste y el ancla no pertenecen al estilo. El agente registra project_layout_strategy más una layout_recommendation por toma después de inspeccionar el metraje exacto seleccionado. Nunca introduzcas un detector de rostros, modelo de segmentación, rastreador de identidad de corte transversal o ROI adivinado. Ajusta los píxeles de ROI del orador en la ventana con escalado de cubrimiento que preserva la relación de aspecto; nunca los estires a la relación de aspecto configurada. Centra el recorte horizontalmente y anclalo a la parte superior para que la cabeza y la cara completas tengan prioridad sobre la cobertura de la parte inferior del cuerpo.

Valida el borrador después de cada edición material:

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. Analizar, Clasificar y Congelar Candidatos

El análisis de candidatos es evidencia de asesoría antes de candidates_ready. No selecciona metraje, aprueba una toma, agrega un recibo ni cambia el ciclo de vida. Mantén las dos o tres consultas literales existentes para cada toma.

Para video local, escribe procedencia veraz e impórtalo a través de la ruta de adquisición existente:

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"

Copia el registro devuelto en los candidates de la toma. El análisis de candidatos lee ese archivo de caché congelado exacto; no lo copia a otro sistema de proveedor o análisis. Usa --local-only cuando el plan no deba consultar Pexels.

Recopila resultados de Pexels con fusión de consultas round-robin, deduplicación de ID de proveedor y un máximo de ocho videos de proveedor únicos por toma. Elige la orientación que coincida con la línea de tiempo:

$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

Para análisis solo local, agrega --local-only. El registro de búsqueda conserva cada consulta literal, su orden original de proveedor, el orden round-robin y ambas variantes de Pexels. La variante de análisis es el archivo más pequeño que coincida con la orientación cuyo borde corto tenga al menos 480 píxeles, o el archivo válido de mayor tamaño que coincida cuando ninguno califique. La variante de entrega sigue siendo el archivo de mayor resolución que coincida con la orientación.

Descarga y decodifica solo variantes de análisis, muestrealas al 10/30/50/70/90 por ciento y escribe evidencia de máquina determinista:

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"

El análisis contiene verificaciones estrictas, advertencias objetivas, hashes de fotogramas muestreados y recorte central, hojas de contacto, evidencia de luminancia/recorte/borde/movimiento y evidencia de duplicados. Conserva el rechazo exacto local de la toma y el umbral perceptual estricto, luego agrega identidad exacta a nivel de proyecto, grupos perceptuales estrictos y sugerencias de possible_series no supresoras. El rechazo estricto se limita a las fallas objetivas en reference/broll-rules.md.

Inspecciona la evidencia exacta del transcript, cinco fotogramas, simulaciones de recorte, advertencias y evidencia de duplicados. Escribe work/cache/b-roll/candidate-ranking-input.json con esta estructura:

{
  "schema_version": 1,
  "analysis_sha256": "<SHA-256 canónico de candidate-analysis.json>",
  "mode": "agent",
  "actor": "<nombre real del agente>",
  "timestamp": "<marca de tiempo con zona horaria>",
  "overall_rationale": "<fundamento no vacío>",
  "near_duplicate_groups": [{
    "group_id": "<id de grupo estable>",
    "match_type": "same_series",
    "actor": "<nombre real del agente>",
    "timestamp": "<marca de tiempo con zona horaria>",
    "members": [
      {"shot_id": "<id de toma>", "candidate_id": "<id de candidato>"},
      {"shot_id": "<id de otra toma>", "candidate_id": "<id de otro candidato>"}
    ],
    "rationale": "<repetición visible específica entre los dos momentos del transcript>"
  }],
  "shots": [{
    "shot_id": "<id de toma>",
    "candidates": [{
      ...
    }]
  }]
}

... (el resto del JSON continúa con la misma estructura de clasificación y selección)