video-add-captions

동영상 자막 추가(Video Add Captions)

종속성(Dependencies)

/video-understand가 선행되어야 합니다. 먼저 실행하여 자막이 검증된 단어 수준 전사 및 표준 타임라인을 사용하도록 하세요. 시작하기 전에 설치되어 있는지 확인하세요. 설치되어 있지 않으면 사용자에게 이 필수 구성 요소가 없음을 경고하고 미디어 처리를 중단하세요.

PATH에 ffmpeg/ffprobe가 필요하며, Python(Pillow 필요), Node.js >= 22(.mjs 스크립트 및 npx hyperframes 필요시 가져오기)가 필요합니다. hyperframes render/snapshot은 헤드리스 Chrome을 구동합니다 — 자체 chrome-headless-shell을 관리하며, 캐시된 것을 사용할 수 없을 때 시스템 Chrome으로 대체합니다(CHROME 설정을 통해 재정의 가능). 미디어를 처리하기 전에 이러한 사항을 확인하세요.

범위(Scope)

이 스킬은 자막 그룹화, 스타일 선택, 검토 및 투명 자막 트랙을 담당합니다. 전사, 자르기, 시간 재조정, 그레이딩, 프레임 재구성 또는 전달 오디오 정책을 선택하지 않습니다.

콘텐츠 카드 및 그래픽 모션보다 자막을 먼저 실행하세요(둘 중 하나라도 선택된 경우). 승인된 자막 레이아웃은 예약된 자막 영역을 설정하며, 이후 두 작업 모두 이 영역을 비워두어야 합니다. 이 상대적 순서는 한 쌍만 활성화된 경우에도 적용됩니다.

먼저 video-understand를 사용하세요. 자르기가 있는 경우 활성 프로그램 타임라인에 자막을 적용하고, 소스 전사 초를 프로그램 초로 취급하지 마세요.

프로토콜 입력(Protocol Inputs)

필수:

• work/project.json
• work/understand/transcript.json (단어 수준 소스 타임스탬프 포함)
• work/understand/media.json
• work/timeline.json
• work/project.json에 지정된 소스 비디오

타임라인은 유일한 소스-프로그램 매핑입니다. 모든 범위는 반개방 [start_s, end_s)입니다. scripts/build_captions.py는 공유 projectlib.map_transcript_to_timeline을 사용하며, 드롭된 소스 범위의 단어는 사라지고, 유지된 단어는 프로그램 시간으로 이동하며, 큐는 항상 클립 경계에서 끊어집니다.

지속적 출력(Durable Outputs)

work/captions/
|-- captions-plan.json
|-- caption-spatial-context.json (적격 B-roll 합성물에만 해당)
`-- 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

생성된 HTML, 복사된 런타임 파일, 추출된 소스 프레임 및 오버레이 프레임은 캐시입니다. 계획, 선택적 공간 컨텍스트, SRT, 결정 수신 및 검토 증거는 지속적입니다.

자막 계획(Caption Plan)

work/captions/captions-plan.json은 표준 자막 계획으로, overlay를 대상으로 하며 프로그램 시간을 사용합니다. 다음을 기록합니다:

• timeline_id, program_duration_s 및 소스 전사 경로
• 큐 그룹화 설정
• 승인된 스타일, 결정 모드, 근거, 갤러리 선택 및 완전한 해석 스타일
• 소스 기반 검토 증거 및 승인 주체
• 호환성 필드 start, end, text, lines 및 words를 포함한 큐
• 모든 큐에 대한 program_range 및 source_ranges
• 모든 매핑된 단어에 대한 프로그램/소스 범위 및 clip_id
• 정확한 합리적 FPS 및 해시된 런타임 자산을 포함한 로컬 렌더러 레시피

생성기는 이전 최상위 큐 배열도 허용합니다. 이는 독립형 호환성 어댑터일 뿐이며, 타임라인 출처를 표현하거나 승인된 프로토콜 기여를 재생성할 수 없습니다.

표준(Standard)이 기본 프레젠테이션 모드입니다. 표준 계획은 presentation 필드가 필요 없으며, 추가하기 위해 마이그레이션되어서는 안 됩니다. 표현적(Expressive)은 명시적 프레젠테이션 모드로, 사전 설정이 아닙니다: --presentation-mode expressive로 요청하세요. 빌드 단계에서 안정적인 큐 ID, 기본 단어 semantic_role 값 및 초안 presentation 계획 셸을 추가하며, 레이아웃 변형을 추측하지 않습니다.

Expressive는 bottom-standard 및 center-emphasis만 지원합니다. 셸을 채우기 전에 reference/caption-rules.md를 읽으세요. 기존 렌더러는 완료된 presentation.layout_beats만 소비하며, 비트 내에서 위치를 추론하거나 레이아웃을 변경하지 않습니다.

Expressive 큐는 또한 하나의 연속적인 구문 수준 hero_line을 정의할 수 있습니다. 표준 level: hero를 사용하세요. 구문을 자체 줄에 금색으로 1.5x 크기로 렌더링합니다. 레거시 level: strong은 입력 별칭으로 계속 허용되고 동일하게 렌더링되지만, 새로운 에이전트 작성 계획은 이를 내보내서는 안 됩니다. 유지되는 단어 역할 keyword, number 및 contrast는 각각 1.22x를 사용하며, normal은 1.0x를 유지합니다. 이러한 처리는 사전 설정과 직교하며 새 스타일 ID를 생성하지 않습니다. 스키마, 오버플로 정책 및 가라오케 규칙에 대해서는 reference/caption-rules.md를 읽으세요.

활성화되고 검토 승인된 B-roll 작업에 승인되거나 확인된 화자 삽입 합성물이 포함된 경우, 자막은 동결된 업스트림 계획, 증거, 정규화된 합성물 및 명시적 서브샷 display_mode에서 caption-spatial-context.json을 파생시킬 수 있습니다. 이는 B-roll 레이아웃을 수정하거나 재선택하지 않습니다. Expressive 계획 전에 큐 경계를 정렬하고 유지되는 preset-bottom, frame-center, panel-center 및 경계 전용 panel-bottom 배치만 해결합니다. panel-bottom은 구조화된 화자 사각형 아래 예약된 스트립 내에서 안정적인 큐를 중앙에 배치하기 위해 unsplittable_word_boundary가 하단 중앙 집중 패널에 인접한 경우에만 허용됩니다. 이러한 큐는 단어 중간점을 포함하는 컨텍스트뿐만 아니라 교차하는 모든 시각적 컨텍스트에 대해 확인됩니다. 이 컨텍스트가 없으면 모든 기존 Standard 및 Expressive 배치 동작은 변경되지 않습니다.

스타일(Styles)

유지되는 사전 설정은 clean, minimal, social-bold, pill, boxed, stroked 및 shorts입니다. 갤러리 조합 ID는 유지되는 테마를 추가합니다(예: pill-yellow, stroked-blue, shorts-green). 가라오케는 옵션이며 별도의 사전 설정이 아닙니다.

기본 위임 선택: clean, 가라오케 끄기. 대상 또는 푸티지가 정당화하는 경우에만 더 표현적인 사전 설정을 선택하세요. 작업별 변경 사항을 재정의 JSON에 저장하고, 일반 스타일 피드백을 위해 생성기를 편집하지 마세요.

Expressive는 semantic-only(가라오케 끄기) 및 semantic-plus-karaoke(가라오케 켜기)를 모두 지원합니다. 의미론적 강조는 두 구성 모두에서 전체 큐 동안 지속됩니다. 공존 모드에서 의미론적 강조와 활성 가라오케 단어는 모든 강조 모드에서 전경색으로 style.wordHighlight.activeColor를 사용합니다. 배경 강조는 추가 효과로 남아 있습니다. 유효 배율은 max(의미론적 배율, 가라오케 활성 배율)이며, 곱이 아닙니다. Expressive는 호환 가능한 contrast 의미론적 역할을 포함하여 밑줄을 렌더링하지 않습니다.

기존 검토 계약은 기본 Expressive 증거로 semantic-only를 계속 사용하고 semantic-plus-karaoke를 별도로 바인딩합니다. 호환성 페이로드 필드는 experimental_comparison으로 이름이 유지됩니다. 승인 프로토콜 마이그레이션 없이 이름을 바꾸지 마세요.

읽기:

• 그룹화 제한을 변경하기 전에 reference/caption-rules.md
• 스타일 용어집은 reference/caption-style-themes.md
• 재정의 매핑은 reference/caption-feedback-mapping.md

결정 모드(Decision Modes)

두 가지 정직한 모드는 동일한 해시 바운드 상태 머신을 공유합니다:

• human: 정확히 복사된 갤러리 요약을 select에 전달하고, 모든 실제 미리보기 증거를 표시하며, 정확히 복사된 승인 또는 수정 요약을 confirm 또는 adjust에 전달합니다. 검토 페이지 바운드 명령은 단순 승인 구문을 허용하지 않습니다.
• agent: 사용자가 자막 결정을 명시적으로 위임하는 경우에만 사용합니다. 비어 있지 않은 위임 메모로 시작한 다음 비어 있지 않은 근거와 함께 agent-select 및 agent-confirm을 사용하세요.

인간 명령은 에이전트 모드에서 실패하고 에이전트 명령은 인간 모드에서 실패합니다. 공간 컨텍스트가 없는 표준은 네 가지 유지되는 소스 기반 이미지를 필요로 합니다. Expressive 및 합성물 인식 검토는 동적 증거 계약을 사용합니다. 소스, 계획, 타임라인, 스타일, 재정의, 프로젝트 메타데이터, 검토 페이지 또는 증거의 변경은 승인을 무효화합니다. 공간 컨텍스트, 업스트림 B-roll 개정 또는 바운드 합성물 변경도 마찬가지입니다. 영향을 받는 아티팩트를 다시 빌드하고 다시 검토하세요.

표준 워크플로우(Canonical Workflow)

저장소 루트에서 실행하세요. 프로젝트 경로 설정:

$RepoRoot = (Resolve-Path ".").Path
$SkillRoot = Join-Path $RepoRoot "skills\video-add-captions"
$ProjectRoot = (Resolve-Path "<project-root>").Path
$Work = Join-Path $ProjectRoot "work"
$SourceVideo = "<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

자막 계획을 빌드하기 전에, 현재 요청에서 이미 명시적으로 하나를 선택하지 않는 한 사용자에게 프레젠테이션 모드를 선택하도록 요청하세요. Standard 및 Expressive 식별자는 번역하지 않은 상태로 유지하면서 사용자의 현재 대화 언어로 질문을 렌더링하세요. 이 파일에 아래 영어 소스 프롬프트를 유지하고, 현재 세션에 지역화된 선택 사항을 제시한 다음 제시 + 중지하세요:

Choose the caption presentation mode:

1. Standard: Uses stable conventional placement and suits most content.
2. Expressive: Switches between bottom and center placement based on meaning and emphasizes keywords and numbers.

Reply with Standard, Expressive, or "Use the default (Standard)."

사용자가 응답할 때까지 build_captions.py를 실행하지 마세요. 사용자가 어떤 표현으로든 선택을 명시적으로 위임하는 경우 Standard를 선택하세요. 계획을 빌드하기 전에 호환성을 유지하는 기본값으로 Standard가 선택되었다고 명시하세요.

프로그램 시간 큐 및 검토 SRT 빌드:

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

사용자가 Standard를 선택한 후 위 명령은 변경되지 않은 Standard 계획을 생성합니다. 사용자가 Expressive를 선택한 후 동일한 명령을 다음 옵션과 함께 실행하세요:

  --presentation-mode expressive

초안 큐 생성 후 활성 B-roll 작업 및 바운드 계획을 읽기 전용으로 검사하세요. 합성물 인식 배치는 작업이 활성화되고, 상태가 approved 또는 verified이며, review.status가 approved이고, 화자 삽입 분석/에이전트 입력/미리보기/클리어런스 바인딩이 완료되고, 적어도 하나의 확인되거나 정규화된 샷이 유지되는 합성물 레이아웃을 가질 때만 활성화하세요. 공간 빌더는 화자 지오메트리에 대해 명시적 서브샷 display_mode: enabled를 사용합니다. pure_broll 및 누락된 화자 증거는 결코 화자 사각형을 암시하지 않습니다.

적격한 경우 Expressive layout_beats 또는 hero_line을 채우기 전에 초안 큐를 모든 B-roll 시각적 경계에 정렬하세요. 정렬은 단어 간격에서만 분할되며 원자적으로 다시 작성됩니다. 단어 내부의 경계는 단어를 온전하게 유지하고 필수 검토 증거를 기록합니다:

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

적격 프로젝트의 경우 이후 모든 게이트에서 사용되는 선택적 인수를 준비하세요:

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

적격 합성물이 없으면 네 가지 공간 명령을 모두 건너뛰고 $SpatialArgs 및 $SpatialReviewArgs를 비워 두세요. 빈 컨텍스트를 생성하거나 첨부하지 마세요.

스타일 선택 또는 미리보기 생성을 시작하기 전에 에이전트는 한 번에 전체 Expressive 프로그램을 계획해야 합니다:

1. 전사, 사용 가능한 이해 아티팩트, 표준 타임라인, 생성된 자막 큐 및 레이아웃 변경을 정당화하는 데 필요한 실제 소스 프레임 증거를 읽습니다.
2. 모든 presentation.layout_beats를 채우고, 예외적인 단어 semantic_role 값에 주석을 달고, 필요할 때 큐에 최대 하나의 연속적인 hero_line을 표준 level: hero로 추가하고, 비트/히어로 라인당 하나의 근거를 작성하고, 전체 presentation.planner.rationale을 작성합니다.
3. 모든 큐가 정확히 한 번 포함된 후에만 presentation.planning_status를 complete로 설정합니다.
4. 미리보기 생성 전에 완료된 계획의 유효성을 검사합니다:

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

적격 합성물의 경우 최종 큐 ID 및 Expressive 후보가 완료된 후에만 컨텍스트를 빌드, 검증 및 첨부합니다. 이는 업스트림 레이아웃을 보존하고 현재 개정 및 해시를 자막 계획에 바인딩합니다:

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

사용자에게 큐별로 위치를 선택하도록 요청하지 마세요. 사용자는 기존 HTML 증거를 검토하고 소수의 비정상적인 비트만 수정합니다. 계획 후 상호 작용을 시작하면 기존 자막 계획 해시 바인딩이 신뢰할 수 있는 상태로 유지됩니다.

하나의 결정 모드를 시작하세요. 인간 모드의 경우 사용자에게 파일을 찾도록 요청하지 않고 유지되는 오프라인 갤러리를 프로젝트 검토 디렉토리에 게시하세요:

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

…[번역을 위해 잘렸습니다]