video-add-b-roll

Video Add B-Roll

이해된 표준 카메라 프로토콜 시퀀스에 소수의 증거 기반 시각적 컷어웨이를 추가합니다. 미디어를 계획하거나 획득하기 전에 reference/broll-rules.md를 읽으십시오. 계획 모양의 참조로 examples/example-broll-plan.json을 사용하십시오.

필수 계약

broll-rules.md의 모든 편집, 출처, 스틸, 검토, 복구 및 전달 규칙을 따르십시오. 운영상:

• 제공된 스크립트를 사용하여 미디어 획득, 검증, 정규화, 영수증 적용 및 확인을 수행하십시오. 절대 원시 다운로드 경로를 사용하거나 다른 스톡 소스를 대체하지 마십시오.
• 절대 인간의 권위를 조작하지 마십시오. 에이전트 검토는 명시적인 위임과 진실된 에이전트 영수증이 필요합니다.
• 누락되었거나, 약하거나, 다운로더가 거부한 미디어는 skipped가 됩니다. 절대 임의의 또는 스틸 대체 미디어를 사용하지 마십시오.

요구 사항 및 입력

Python, ffmpeg, ffprobe, Pillow가 필요합니다. Pexels의 경우, 먼저 환경에서 PEXELS_API_KEY를 사용하고, 그 다음 skills/video-add-b-roll/.env에서 찾으십시오. 둘 다 없거나 비어 있으면 중지하고 사용자에게 해당 파일에 PEXELS_API_KEY=<key>를 추가하도록 요청한 후, 사용자가 확인하면 재시도하십시오. 사용자에게 로컬 .env 파일을 통해 키를 제공하도록 요청하고, 채팅을 통해 제공하지 마십시오. 명령 인수, 계획, URL, 로그, 검토 결과물 또는 응답에 키를 배치하거나 인쇄하지 마십시오.

/video-understand가 선행되어야 합니다. 먼저 실행하여 B-roll이 검증된 단어 수준 대본과 표준 타임라인을 사용하도록 하십시오. 시작하기 전에 이것이 설치되어 있는지 확인하십시오. 설치되어 있지 않으면 이 필수 조건이 누락되었다고 사용자에게 경고하고 미디어 처리를 시작하기 전에 중지하십시오.

저장소 루트에서 실행하고 별도의 프로젝트 루트를 확인하십시오:

$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', '현재 업스트림 전달물이 검증되지 않았습니다'; path=projectlib.resolve_project_path(root,project['render']['output']); assert path.is_file(), '현재 업스트림 전달물이 없습니다'; print(path)" $ProjectRoot $ProjectLib
if ($LASTEXITCODE -ne 0) { throw 'B-roll 검토 전에 활성 업스트림 전달을 완료하십시오.' }
$ReviewVideo = (Resolve-Path -LiteralPath $ReviewVideo).Path

재전사하거나 재분석하는 대신 이러한 표준 입력을 사용하십시오:

• work/project.json
• work/timeline.json
• work/understand/transcript.json
• work/understand/understanding.json
• 활성 컷 및 컬러 그레이드 작업이 포함된 현재 프로그램 시간 검토 비디오

$ReviewVideo는 기존의 검증된 업스트림 전달물이며, 발명할 파일 이름이나 새로운 B-roll 렌더가 아닙니다. 이미 활성 타임라인의 길이, 크기 및 FPS와 일치해야 합니다. 없거나 오래된 경우 먼저 업스트림 컷/컬러 그레이드 전달을 완료한 다음, 확인하고 해시한 후 계속하십시오.

이 작업은 항상 understanding에 의존하며, 대상 시퀀스에서 해당 작업이 활성화된 경우 cut 및 color-grade에도 의존합니다. 현재 양의 정수 개정판을 based_on으로 복사하십시오. 컬러 그레이드가 활성화된 경우 그레이드 계획과 선택된 LUT 해시를 모두 기록하십시오. 정규화는 해당 정확한 선택된 LUT를 받아 선택된 모든 B-roll 샷에 미리 적용해야 합니다.

표준 시퀀스 순서는 다음과 같습니다:

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

등록된 작업은 changes_video_pixels: true여야 하고, b-roll 트랙을 추가하며, 타임라인, 지오메트리 및 오디오는 변경하지 않아야 합니다. broll_plan.register_operation()이 이 계약을 작성합니다. 작업을 직접 빌드하지 마십시오.

영구 및 임시 파일

work/b-roll/broll-plan.json                         # 영구 도메인 계획
work/b-roll/presentation-decision.json               # 영구 에이전트 채팅 라우팅 결정
work/b-roll/broll-interaction.json                  # 영구 적용된 영수증
work/b-roll/broll-selection.json                    # 영구 승인된 정확한 선택 및 소비된 페이지 바인딩
work/b-roll/speaker-inset-analysis.json             # 영구 장면/증거 패킷
work/b-roll/speaker-inset-agent-input.json          # 영구 에이전트 ROI 결정
work/b-roll/speaker-inset-preview.json              # 영구 정확한 미리보기 바인딩
work/b-roll/speaker-inset-clearance.json            # 영구 에이전트 폐색 검사
work/b-roll/broll-revision-request-<UUID>.json      # 영구 승인되지 않은 요청 바이트
work/b-roll/candidate-search.json                   # 영구 쿼리 및 공급자 순서
work/b-roll/candidate-analysis.json                 # 영구 결정적 증거
work/b-roll/candidate-ranking.json                  # 영구 에이전트 순위 및 상위 3개
work/cache/b-roll/candidate-analysis/media/         # 임시 분석 변형
work/cache/b-roll/candidate-analysis/frames/        # 재현 가능한 샘플 및 크롭
work/cache/b-roll/candidates/                       # 동결된 획득 미디어
work/cache/b-roll/speaker-inset/                    # 재현 가능한 증거 및 미리보기
work/cache/b-roll/normalized/                       # 재현 가능한 무음 오버레이
review/03-b-roll/candidate-analysis-<UUID>/          # 불변 분석 패킷
review/03-b-roll/candidate-analysis-<UUID>.md        # 분석 및 기준 요약
review/03-b-roll/candidate-analysis-<UUID>/candidate-index.html
review/03-b-roll/b-roll-review-<UUID>.html          # 불변 후보 검토
review/03-b-roll/b-roll-review.html                 # 최신 편의 별칭
review/03-b-roll/stills/                            # 첫 번째/중간/마지막 확인 프레임
review/03-b-roll/contact-sheet.jpg
review/03-b-roll/boundary-reel.mp4
review/03-b-roll/b-roll-summary.md

계획과 영수증은 work/cache/ 외부에 보관하십시오. 후보 및 정규화된 파일은 재현 가능하지만 해시에 바인딩된 입력으로 취급하십시오.

워크플로우

1. 현재 종속성 확인

활성 시퀀스, 작업 개정판, 타임라인, 대본, 이해, 활성 그레이드 계획 및 선택된 LUT를 읽으십시오. 검토 비디오가 활성 타임라인의 길이, 크기 및 합리적인 FPS와 일치하는지 확인하십시오. 대본, 타임라인, 검토 비디오 및 활성 그레이드 입력을 input_hashes로 해시하십시오.

broll_plan.active_dependencies(project)를 사용하여 정확한 종속성 목록을 파생하십시오. 변경된 타임라인, 대본, 종속성 개정판, 그레이드 계획, LUT, 검토 비디오, 후보 매니페스트 또는 검토된 자산은 다운스트림 작업을 무효화합니다. 이전 영수증을 그대로 사용하는 대신 계획을 새로 고치고 검토를 반복하십시오.

2. 동적-소셜 계획 작성

work/b-roll/broll-plan.json을 직접 작성하십시오. 스크립트는 정밀도를 수행하며, 편집 판단은 수행하지 않습니다. 제안된 각 샷에 대해:

• 시간 순서대로 양수인 절반 개방, 겹치지 않는 프로그램 범위를 선택하십시오.
• work/timeline.json을 통해 정확한 source_ranges로 매핑하십시오.
• 소스/프로그램 범위와 클립 ID가 포함된 정확히 매핑된 대본 단어를 하나 이상 유지하십시오.
• 구체적인 editorial_reason과 visual_intent를 명시하십시오.
• 구체적인 topic, visual_direction 및 1-12개의 고유 키워드를 포함한 brief.search_context를 설정하십시오.
• 각 semantic_role을 direct, supportive 또는 atmospheric으로 설정하십시오.
• 두세 개의 계층적 리터럴 영어 쿼리를 작성하십시오: 직접 주제/동작 쿼리, 방어 가능한 맥락/프로세스 쿼리, 세 번째 쿼리가 유용한 경우 테마 강화 변형.
• planned에서 시작하여, 획득 후 candidates_ready로 이동하거나 관련 후보가 없을 때 skipped를 사용하십시오.

brief.density를 dynamic-social로 유지하십시오. 계획된 커버리지는 매핑된 대본 및 타임라인의 완전한 A-roll 스캔으로 시작하며, 그 다음 직접 작성된 시간 순서, 겹치지 않으며 편집적으로 유효한 범위가 뒤따릅니다. 0.40에서 0.70을 소프트 목표로 처리하십시오. 0.40 미만인 경우 두 번째 패스를 수행하고 방어 가능한 범위만 추가하거나 확장하십시오. 0.70 이상인 경우 내부적으로 A-roll 가림을 검토하십시오. 목표를 달성하기 위해 관련 없는 필러를 추가하거나 관련성, 권리, 품질 또는 기타 자격 게이트를 약화시키지 마십시오. tech 또는 entertainment와 같은 일반적인 주제별 용어는 쿼리를 구체화하는 데만 사용할 수 있습니다. 후보와 대본 주장 간의 샷별 가시적 관계를 대체하지 않습니다. 어떤 순간도 B-roll을 얻을 자격이 없으면 승인된 전부 건너뛰기 계획이 유효한 무작동입니다.

초안을 작성하는 동안 speaker_inset_style을 추가하지 마십시오. 후보 획득 후, 명시적 에이전트 채팅 표현 결정이 일반 또는 발언자 삽입 경로를 선택합니다. 후자는 자동으로 엄격한 프로젝트 수준의 둥근 사각형 스타일을 설치합니다: width_ratio: 0.39, 회색 테두리, 종횡비, 모서리 반경, 여백 및 자막 안전 하단 영역. 사전 설정과 앵커는 스타일에 속하지 않습니다. 에이전트는 정확히 선택된 미디어를 검사한 후 project_layout_strategy와 샷별로 하나의 layout_recommendation을 기록합니다. 얼굴 감지기, 분할 모델, 교차 컷 신원 추적기 또는 추측된 ROI를 도입하지 마십시오. 발언자 ROI 픽셀을 종횡비 유지 커버 스케일링으로 창에 맞추고 구성된 종횡비로 늘리지 마십시오. 크롭을 수평으로 중앙에 배치하고 상단에 고정하여 완전한 머리와 얼굴이 하체 커버리지보다 우선하도록 하십시오.

모든 중요한 편집 후 초안의 유효성을 검사하십시오:

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 계획 유효'); raise SystemExit(bool(errors))" $ProjectRoot $BrollScripts

3. 후보 분석, 순위 지정 및 확정

후보 분석은 candidates_ready 이전의 자문 증거입니다. 미디어를 선택하거나, 샷을 승인하거나, 영수증을 추가하거나, 라이프사이클을 변경하지 않습니다. 모든 샷에 대해 기존의 두세 개의 리터럴 쿼리를 유지하십시오.

로컬 비디오의 경우 진실된 출처를 작성하고 기존 획득 경로를 통해 가져오십시오:

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"

반환된 레코드를 샷의 candidates에 복사하십시오. 후보 분석은 해당 정확한 동결된 캐시 파일을 읽습니다. 다른 공급자나 분석 시스템으로 복사하지 않습니다. 계획이 Pexels를 쿼리하지 않아야 하는 경우 --local-only를 사용하십시오.

라운드 로빈 쿼리 병합, 공급자 ID 중복 제거 및 샷당 최대 8개의 고유 공급자 비디오로 Pexels 결과를 수집하십시오. 타임라인과 일치하는 방향을 선택하십시오:

$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

로컬 전용 분석의 경우 --local-only를 추가하십시오. 검색 레코드는 모든 리터럴 쿼리, 원래 공급자 순서, 라운드 로빈 순서 및 두 Pexels 변형을 보존합니다. 분석 변형은 짧은 쪽이 480픽셀 이상인 가장 작은 방향 일치 파일이거나, 해당하는 파일이 없을 때 가장 큰 유효한 일치 파일입니다. 전달 변형은 가장 높은 해상도의 방향 일치 파일로 유지됩니다.

분석 변형만 다운로드하여 완전히 디코딩하고, 10/30/50/70/90%로 샘플링한 후 결정적 기계 증거를 작성하십시오:

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"

분석에는 하드 검사, 객관적 경고, 샘플링된 프레임 및 중앙 크롭 해시, 연락 시트, 휘도/클리핑/에지/모션 증거 및 중복 증거가 포함됩니다. 샷별 정확한 거부 및 엄격한 지각 임계값을 보존한 다음, 프로젝트 전체 정확한 ID, 엄격한 지각 그룹 및 비억제 possible_series 힌트를 추가합니다. 하드 거부는 reference/broll-rules.md의 객관적 실패로 제한됩니다.

정확한 대본 증거, 5개 프레임, 크롭 시뮬레이션, 경고 및 중복 증거를 검사하십시오. 다음 모양으로 work/cache/b-roll/candidate-ranking-input.json을 작성하십시오:

{
  "schema_version": 1,
  "analysis_sha256": "<표준 candidate-analysis.json의 SHA-256>",
  "mode": "agent",
  "actor": "<실제 에이전트 이름>",
  "timestamp": "<시간대 인식 타임스탬프>",
  "overall_rationale": "<비어 있지 않은 근거>",
  "near_duplicate_groups": [{
    "group_id": "<안정적인 그룹 ID>",
    "match_type": "same_series",
    "actor": "<실제 에이전트 이름>",
    "timestamp": "<시간대 인식 타임스탬프>",
    "members": [
      {"shot_id": "<샷 ID>", "candidate_id": "<후보 ID>"},
      {"shot_id": "<다른 샷 ID>", "candidate_id": "<다른 후보 ID>"}
    ],
    "rationale": "<두 대본 순간에 걸친 특정 가시적 반복>",
  }],
  "shots": [{
    "shot_id": "<샷 ID>",
    "candidates": [

…

[번역을 위해 잘림]