zenstory-ai/video-recap

1. 포지셔닝 및 워크플로우

이 스킬은 독립된 비디오 해설 및 편집 프로덕션 스킬입니다. 비디오 이해, 스토리텔링, 화면 편집, 나레이션 작성, 더빙 합성 및 오디오-비디오 믹싱을 하나의 일관된 워크플로우로 통합합니다. 각 단계는 동일한 작업 디렉토리 work_dir 아래의 JSON 및 MP4 산출물을 공유합니다.

understand.py(비디오 이해) ─▶ Agent가 스토리/오디오-비디오 계획을 수립하고 clip_plan.json 또는 narration.json 작성 ─▶ [cut.py(편집 및 재출력 브리핑)] ─▶ validate.py(로컬 기준 검증) ─▶ voiceover.py(TTS 더빙) ─▶ assemble.py(믹싱 및 자막 렌더링)

일상적인 사용 시 진입점 scripts/recap.py를 직접 호출하여 전체 파이프라인을 자동으로 실행하고 창작 단계에서 일시 중지할 수 있습니다. 또는 필요에 따라 이 스킬의 scripts/ 디렉토리 아래 있는 단계별 진입점(understand.py, cut.py, validate.py, voiceover.py, assemble.py)을 개별적으로 호출할 수도 있습니다.

기존 완성 영상을 제작 참고 자료(production_reference.json)로 분해하는 것은 기본 프로덕션 체인에 포함되지 않습니다. 사용자가 영상 분해 학습을 요청하는 경우: 먼저 샘플 영상에 대해 understand.py를 실행하고(ASR_SEGMENT_SECONDS=5 설정 권장), 독립된 영상 분해 스킬을 사용하여 측정(measure), 주석, 검증(check) 및 내보내기(export)를 순차적으로 수행합니다. 내보낸 production_reference.json을 다음 실행의 work_dir에 복사하거나 리소스 라이브러리의 production_reference 템플릿으로 등록하고 --project를 통해 바인딩합니다. 메인 워크플로우는 자동으로 영상 분해를 실행하지 않으며, 새 완성 영상을 참조 영상과 기계적으로 비교하지 않습니다.

전체 워크플로우는 중단 지점부터 재개를 지원합니다: Agent가 clip_plan.json 또는 narration.json을 작성한 후 동일한 recap.py 명령을 다시 실행하면 다음 단계로 진행됩니다. 재개 시 스크립트는 recap_run_manifest.json에 기록된 소스 비디오 경로, 파일 크기, 수정 시간 및 실행 매개변수를 확인합니다. 작업 디렉토리가 다른 비디오 또는 다른 매개변수 조합에서 온 것임을 발견하면 재사용을 직접 거부합니다. 비디오 이해 캐시는 소스 영상과 구성이 완전히 일치하는 경우에만 적중합니다. 각 일시 중지 시 터미널에 출력되는 재개 명령은 원래 호출 방식을 유지하며, 비디오 및 경로 매개변수를 자동으로 절대 경로로 변환하고 --work-dir을 추가합니다. 복사하여 붙여넣기만 하면 어떤 디렉토리에서든 직접 실행할 수 있습니다.

화면 워크플로우 --edit-mode full|cut와 오디오 전략 --audio-mode narration|source-mix는 서로 독립적입니다: narration은 표준 해설 더빙 체인을 따르고, source-mix는 더빙을 생성하지 않고 원본 오디오와 선택적 배경 음악을 직접 혼합합니다. 시스템은 아래 표에 나열된 5가지 합법적인 경로만 지원합니다. 다른 조합은 시작 시 오류를 보고하고 차단합니다.

입력	--edit-mode	--audio-mode	Agent 일시 중지 지점	워크플로우	상세 정보
단일 비디오	full	narration	1회: narration.json 작성	이해 → 원고 작성 → 검증 → 더빙 → 합성	§4
단일 비디오	cut	narration	2회: 먼저 clip_plan.json 작성, 편집 후 완성 영상에 대해 narration.json 작성	이해 → 편집 → 재출력 시간 브리핑 → 원고 작성 → 검증 → 더빙 → 합성	§4
여러 비디오	cut	narration	2회: 위와 동일하며, 각 클립은 source_id를 포함해야 함	소스별 이해 → 편집 → 원고 작성 → 검증 → 더빙 → 합성	§4.5
단일 비디오	full	source-mix	일시 중지 없음	현재 전체 비디오를 직접 합성(이해 또는 TTS 실행 안 함)	§4.7
단일 / 여러 비디오	cut	source-mix	1회: clip_plan.json 작성	이해 → 편집 → 합성(나레이션 작성 안 함)	§4.7

2. 창작 책임

창작 결정권은 전적으로 Agent에게 있습니다. 작업을 시작하기 전에 먼저 이번 라운드의 창작 제어 모드(CREATE 자유 창작 / DIRECTED 지시 창작 / REVISION 최종 수정, --edit-mode와 독립적)를 결정하고, 더빙 및 렌더링에 들어가기 전에 동일한 창작 두뇌로서 5가지 판단을 일관되게 수행합니다.

1. 감독 판단: 시청자가 무엇을 보기 위해 클릭했는지, 누구의 시점(POV)을 따라가는지, 핵심 미스터리는 무엇인지, 감정이 어디서 시작되어 어디서 끝나는지, 그리고 어떤 비밀이 마지막에 공개될지 명확히 합니다.
2. 스토리 편집: 각 비트(beat)는 "상황에 어떤 실질적인 전환이 일어났는지"를 설명해야 하며, 절대 흐름식 장면 요약을 작성하지 않습니다.
3. 화면 편집: 가장 인상적인 동작, 표정 변화, 최적의 진입 및 종료 지점을 선택하고, 질질 끄는 과도 장면은 제거합니다.
4. 오디오/나레이션: 먼저 각 비트를 화면, 원본 오디오 대사, 동작 소리, 침묵 또는 나레이션이 주도할지 결정한 다음, "반 마디 깔기, 반 마디 비우기, 반 마디 받기" 규칙에 따라 단어를 작성합니다.
5. 시청자 검토: 처음 영상을 보는 시청자의 관점에서, 각각 나레이션을 끄고 화면만 보기, 눈을 감고 소리만 듣기, 그리고 처음과 끝의 약속 이행 여부를 자체 점검합니다.

세 가지 제어 모드의 역할 구분, REVISION 모드의 잠금 및 롤백 금지 규칙, 구체적인 편집 및 작성 기법, 그리고 recap_story_plan.json, visual_audio_board.json, style_card.json의 형식 사양에 대한 자세한 내용은 references/creative-editing-playbook.md를 참조하십시오. 이러한 JSON은 검토 가능한 창작 결정을 기록하여 샷 선택, 원본 오디오 여백 및 나레이션이 처음부터 끝까지 동일한 스토리 의도를 유지하도록 보장합니다.

3. 환경 및 원격 호출 설명

# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***

동일한 MIMO_API_KEY로 전체 기본 파이프라인을 구동할 수 있습니다. 데이터 흐름의 투명성을 보장하기 위해, 이 스킬과 관련된 원격 네트워크 호출 단계는 다음과 같습니다.

• 비디오 이해(understand.py): 분할된 오디오 창을 MiMo ASR(mimo-v2.5-asr)로 보내고, 추출된 JPEG 프레임과 background_research.json 요약을 MiMo VLM(mimo-v2.5)으로 보냅니다. 작업 디렉토리에 이미 전체 분석 산출물이 있는 경우, --brief-only 또는 --edited-storyboard-only를 전달하면 로컬에서만 실행되며 네트워크 요청을 전혀 시작하지 않습니다.
• 나레이션 더빙(voiceover.py): --tts-provider(기본값 auto는 먼저 구성된 MiMo를 선택하고, 다음으로 Fish Audio를 선택하며, 절대 자동으로 index-tts를 선택하지 않음)에 따라 해설 텍스트를 해당 TTS 서비스로 보냅니다.
  • mimo-tts: MiMo TTS(mimo-v2.5-tts)로 전송합니다. --voice-ref <audio>가 명시적으로 전달된 경우, 해당 참조 오디오 클립도 mimo-v2.5-tts-voiceclone으로 전송합니다(사용 전 음성 사용 권한을 확인하십시오).
  • fish-audio: FISH_API_KEY를 구성해야 합니다. 각 해설 텍스트 조각과 FISH_TTS_REFERENCE_ID를 FISH_TTS_API_URL(기본값 https://api.fish.audio/v1/tts)로 전송합니다.
  • index-tts: --tts-provider index-tts가 명시적으로 지정된 경우에만 활성화됩니다. 텍스트와 INDEX_TTS_VOICE를 사용자 자체 호스팅 INDEX_TTS_ENDPOINT(자세한 내용은 references/index-tts.md 참조)로 전송합니다.
• 해설 검증(validate.py), 비디오 편집(cut.py, shot_review.py) 및 오디오-비디오 합성(assemble.py): 순수 로컬 결정적 로직과 ffmpeg / ffprobe 호출이며, 네트워크 요청을 전혀 시작하지 않습니다.

tp-로 시작하는 Token Plan 키는 기본적으로 중국 본토 클러스터로 전송됩니다. MIMO_TOKEN_PLAN_CLUSTER를 사용하여 클러스터를 전환할 수 있습니다. 전체 구성 항목은 references/config-playbook.md를, 모든 중간 산출물 형식은 references/data-schema.md를 참조하십시오. 아래의 scripts/...는 이 스킬 디렉토리를 기준으로 한 상대 경로입니다.

4. 일관된 창작 및 편집 워크플로우

4.1 배경 조사 및 비디오 이해

파일 이름이나 사용자 지시에서 영화 제목, 시리즈 이름 또는 과학 주제를 식별할 수 있는 한, 실행 전에 먼저 references/research-guide.md에 따라 캐릭터 관계와 이전 상황을 조사하여 work_dir/background_research.json에 기록합니다. 이렇게 하면 이후 화면 분석을 실행할 때 캐릭터 이름을 정확히 부르고 함축된 의미를 이해할 수 있으며, 화면 전체에 "검은 옷을 입은 남자", "젊은 여자"와 같은 설명만 가득 채우지 않게 됩니다. 여러 비디오를 연결하여 편집하는 경우에도 프로젝트 루트 work_dir 아래에 작성하며, 스크립트가 자동으로 각 소스 하위 디렉토리 sources/<source_id>/에 동기화합니다.

그런 다음 이해 및 오케스트레이션 진입점을 시작합니다.

python3 scripts/recap.py <video> --work-dir <work_dir> --context "배경"

스크립트는 오디오 추출, 무음 및 문장 끝 일시 정지 앵커 포인트 감지(speech_boundary_anchors.json), 장면 분할, VLM 프레임 분석 및 ASR 전사를 완료한 후, 스토리보드 콜라주 storyboard/storyboard_*.jpg와 창작 브리핑 agent_narration_brief.md를 생성하고 자동으로 일시 중지됩니다.

4.2 감독 의도 및 샷 선택 계획(cut 1단계)

agent_narration_brief.md를 완전히 읽고 스토리보드 추출 프레임 이미지를 직접 확인한 후, 먼저 recap_story_plan.json(최소 2개의 후보 계획을 나열하고 메인 POV, 시작 훅, 감정 호 및 여백 비밀 선택)과 visual_audio_board.json(각 비트별로 어떤 순간을 선택할지, 진입 및 종료 이유, 오디오 주도권 결정)을 작성합니다.

cut 모드 1단계에서는 **원본 영상 타임라인(SOURCE)**을 기반으로 work_dir/clip_plan.json을 작성합니다(이 시점에서는 narration.json을 작성하지 않습니다).

{
  "target_duration": "3m",
  "clips": [
    {
      "start": 12.0,
      "end": 38.0,
      "reason": "b01 | hook | knowledge: unknown→threat | POV=沈曼 | 撞见未婚夫搂着千金谈联姻 | 入点=推门看清两人动作 | 出点=转身攥紧户口本"
    }
  ],
  "required_evidence": {
    "nodes": [
      {"id": "e1", "source": "/abs/source.mp4", "start": 14.2, "end": 18.6, "track": "video", "content": "推门撞见两人拥抱"}
    ],
    "before": []
  }
}

샷 선택 및 컷 포인트는 다음 기준을 엄격히 준수해야 합니다.

• reason 7부분 구조: 순서대로 beat_id | 내러티브 기능 | 상황 상태 변화(A→B) | POV=캐릭터 | 이 부분의 실질적인 볼거리 | 진입점=특정 동작/오디오 앵커 | 종료점=특정 반응/종착점을 기재하여 각 화면 부분이 스토리 전개에 기여하도록 강제합니다.
• 필수 화면 및 오디오 증거(required_evidence): 유지해야 할 하이라이트 동작, 표정 변화 순간 또는 핵심 오디오 질문/응답을 결정하고, 최상위 required_evidence에 기록합니다(nodes는 id/source 절대 경로/start/end/track/content를 등록하고, before는 순서를 바꿀 수 없는 쌍을 등록). 경계 흡착 시 필수 구간이 잘리거나 순서가 변경되면 스크립트가 직접 오류를 보고하고 차단합니다.
• 늦은 시작 및 샷 선택: 기본적으로 시간 순서대로 "늦게 시작"합니다(갈등 폭발, 터무니없는 대비 또는 핵심 동작에서 직접 시작하고, 문을 열고 들어가기, 인사 등 느린 도입부는 제거). 정순 갈등이 너무 늦게 나타나는 경우에만 <= 2.5s의 차가운 시작 서스펜스 샷을 허용하며, 설명 없이도 이해할 수 있고, 본편과 동일한 카메라 구도를 반복하지 않으며, 서스펜스만 남기고 반전 결과를 미리 스포일러하지 않아야 합니다. 나레이션이 원본 오디오를 낮출 때는, 시청자 표정 변화, 동작 디테일 또는 정적 샷을 우선 선택하고, 입을 크게 벌리고 말하는 캐릭터의 정면 클로즈업이 음소거된 화면을 나레이션 아래에 깔지 않도록 합니다. 동일한 고개 끄덕임 또는 멍하니 바라보는 반응 샷을 두 번 이상 반복하지 않습니다.
• 문장 끝 안전 컷 포인트 및 호흡 여백: 컷 포인트는 원본 영상의 시작/끝, 문장 끝 일시 정지 앵커 포인트 또는 무음 창 내에 위치하거나, 동일한 소스의 인접 클립 간 끊김 없는 순차 연결에 속해야 합니다. 문장 끝에 흡착할 때는 일시 정지 창 내에 최대 0.30s의 반응/호흡 여백을 자동으로 예약하며, 하드 컷 포인트를 절대 넘지 않으며, 클립의 최소 길이는 0.8s 이상이어야 합니다. 영상의 마지막 비트는 종료 동작 또는 대사가 끝난 후 1.5–2.5s의 표정 여운을 남기고, 다음 장면으로 넘어가기 전에 깔끔하게 마무리되어야 합니다. 원본 대사 중간에 진입하면 unsafe_clip_sentence_boundary 차단이 트리거되고 nearest_safe가 제공됩니다. 하드 컷 흡착으로 롤백할 때 동시에 <= 0.20s 플래시 프레임과 잘린 대사가 노출되면, 직접 shot_speech_conflict 차단이 보고됩니다.
• 고주파 빠른 컷 및 짧은 샷 검사: cut.py가 edited_source.mp4를 렌더링한 후 자동으로 shot_review.py를 호출하여 shot_review.json을 생성하고, 지속 시간이 <= 0.20s(약 1–5프레임)인 매우 짧은 잔여 샷 플래시 프레임(flash_slivers)에 대해 직접 하드 차단합니다. 액션 장면이나 빈번한 리버스 샷을 다룰 때는, ffmpeg -i <video> -vf "select='gt(scene,0.35)',showinfo" -f null - 또는 읽기 전용 도구 scripts/shot_review.py(사용법은 references/shot-review.md 참조)를 수동으로 실행하여 높은 점수의 컷 포인트를 찾을 수 있습니다. 그러나 원본 영상 자체의 컷 포인트와 이번 편집으로 생성된 컷 포인트를 구분해야 합니다. 전자의 경우, 원본 영상의 무관한 짧은 샷 전체를 삭제하거나 컷 포인트를 빠른 컷 클러스터 외부로 이동합니다. 후자의 경우(예: 하드 컷 가장자리에 이웃 샷의 몇 프레임이 남아 있거나, 깨진 리버스 샷), 진입/종료 지점을 확장하거나 동일한 소스의 인접 클립을 병합하며, 전환 효과로 결함을 가리는 것을 엄격히 금지합니다.

clip_plan.json을 작성한 후 recap.py를 다시 실행하면, 스크립트가 cut.py를 호출하여 3단계 경계 흡착(샷 하드 컷 흡착 → 문장 끝 무음 흡착 및 여백 → 프레임 그리드 정렬)을 완료하고, 일정한 프레임 속도의 edited_source.mp4를 렌더링하고 플래시 프레임 검사를 완료한 다음, ASR, VLM 및 문장 끝 앵커 포인트를 완성 영상 출력 타임라인(speech_boundary_anchors_output.json, storyboard/edited_storyboard.*)에 다시 매핑하고, 해설 대기를 위해 다시 일시 중지됩니다.

4.3 해설 대본 및 원본 오디오 여백 창작(full / cut 2단계)

원고 작성 단계에 들어간 후(full 모드는 첫 번째 일시 중지, cut 모드는 edited_source.mp4 편집 후 두 번째 일시 중지), 먼저 편집된 스토리보드를 확인하고, visual_audio_board.json의 완성 영상 출력 시간을 보완하며, 필요에 따라 style_card.json을 작성한 다음, work_dir/narration.json을 작성합니다.

[
  {
    "start": 0.2,
    "end": 5.0,
    "narration": "5년간 사귀며 호적부를 들고 프러포즈하러 간 선만, 문을 열자 약혼자가 재벌 딸과 결혼 얘기하는 꼴을 목격한다.",
    "pause_after_ms": 250,
    "overlaps_speech": true
  }
]

참고: cut 모드에서는 narration.json이 편집된 완성 영상의 OUTPUT 타임스탬프(0 .. 완성 영상 총 재생 시간)를 직접 입력해야 합니다.(검증기를 별도로 호출할 때는 validate.py --mode cut_output 전달). 작성 시 9가지 핵심 작성 철칙을 따릅니다(상세 규칙과 긍정/부정 예시는 references/creative-editing-playbook.md 참조).

1. 처음 2.5초 이내에 훅이나 오디오 하이라이트를 제시하고, 직접 구체적인 대비 동작이나 핵심 미스터리를 던집니다. 캐릭터 이력, 날짜 브리핑 또는 인사말로 시작하지 마십시오; 2.5s 이상 나레이션과 원본 오디오 대사가 모두 없는 차가운 시작은 weak_cold_open_silence 차단을 트리거합니다.
2. 배경, 캐릭터 관계 및 인과 관계를 명확히 하고, 지명 밀도를 제어하며, "그림 설명"을 거부합니다: background_research.json에 캐릭터 이름이 제공된 경우, "검은 옷을 입은 남자", "젊은 여자"와 같은 일반적인 외모 단어를 사용하는 것을 엄격히 금지합니다(위반 시 generic_character_label 차단). 60초 이내 짧은 영상에서는 최대 1–2명의 핵심 캐릭터만 지명합니다(첫 문장에서 최대 1명을 지명하고 신분을 함께 밝힘). 나머지 보조 캐릭터는 관계/신분 호칭(예: "전 여자친구", "그녀의 상사", "어의")으로 통일하고, 모든 문장은 "상황 → 행동 → 즉각적인 결과" 순서로 진행합니다.
3. 시청각 대응 "반 마디 깔기, 반 마디 비우기, 반 마디 받기" 및 강한 시각적 요소는 반드시 동기화: 하이라이트 원본 대사, 뺨 때리는 소리, 침묵하는 표정 변화 전에果断하게 입을 닫고 자리를 내주며, 원본 오디오가 끝난 후 반 마디로 함축된 의미를 드러냅니다. 화면에 키스, 뺨 때리기, 무릎 꿇기, 기절, 증표 보여주기 등 강한 시각적 동작이 나타날 때는, 반드시 원본 오디오를 유지하거나 인접한 나레이션으로 인과 관계를 정면으로 설명해야 하며, 각자 따로 노는 것을 금지합니다. 전체 영상에서 연속으로 5.0s 이상 나레이션과 원본 오디오 대사가 모두 없는 죽은 공백이 발생해서는 안 됩니다(위반 시 excessive_dead_air 차단).
4. 원본 오디오 진입 및 복귀 이중 레드라인 엄수: 원본 오디오를 낮추고 나레이션을 시작할 때(overlaps_speech: true), start는 문장 끝 앵커 포인트 또는 무음 구역에 밀착해야 합니다(위반 시 interrupts_source_sentence 차단). 나레이션이 끝나고 원본 오디오로 복귀할 때도 캐릭터가 말하는 중간에 갑자기 볼륨을 회복해서는 안 됩니다(위반 시 검증 및 합성 단계에서 각각 unsafe_source_release / unsafe_source_handoff 차단).
5. 시간 창 내 단어 수 예산 엄격히 제어, 자연스러운 말하기 속도 유지, 완전한 문장으로 마무리: 각 단락은 완전한 문장 끝 구두점으로 마무리해야 합니다(불완전한 문장은 incomplete_sentence 하드 차단). 간결한 단어 수로 시간 창에 맞추고, 고속 재생에 의존하여 억지로 채우지 마십시오; full 모드에서 예산의 1.25배를 초과하면 직접 over_budget 차단이 보고되며, 검증기는 절대 Agent를 대신하여 단어를 삭제하지 않습니다.
6. 의견 제시 및 전보체 어조 제거, 결말은 화면이 연기하도록 둠: 자연스럽고 일관된 구어체의 길고 짧은 문장을 쓰고, 단어 하나하나 끊어지는 깨진 문장을 쓰지 마십시오. "이것은 의미한다...", "이것은 ...에 관한 대결이다", "권력과 자존심을 퇴장시키라", "운명의 톱니바퀴" 등 독해형 평가 및 상투적 표현을 엄격히 금지합니다(editorial_commentary_tone 경고 트리거). 스토리 결말은 반드시 화면과 원본 오디오가 즉석에서 연기하도록 해야 하며, 결말이 실현된 후에 요약이나 승화를 위한 나레이션을 덧붙이지 말고, 마무리 나레이션 후에 동일한 결과를 반복하는 원본 오디오 꼬리를 끌지 마십시오.
7. 구체적인 화면 증거 고정 및 순수 기악 배경 음악 규율: 보이는 눈빛, 소품, 동작 디테일로 말하고, 화면 밖의 심리 활동을 캐릭터를 대신하여 지어내지 마십시오. 외부 배경 음악(BGM_PATH)을 선택하는 경우, 순수 기악(인성 가사 없음)을 사용해야 하며, 원본 영상에 피할 수 없는 높은 볼륨의 인성 삽입곡이 있는 경우 외부 배경 음악을 추가로 쌓지 마십시오. 여러 트랙의 인성이 서로 충돌하는 것을 방지하기 위함입니다.
8. 원본 오디오 여백 자막 승인: 원본 영상 자막 마스크가 활성화되고 원본 오디오 하이라이트 부분이 남아 있는 경우, work_dir/original_subtitles.json에 완성 영상 시간에 따라 교정된 원본 대사를 동시에 작성하고, ASR의 동음이의어 오류를 수정합니다.
9. 작성 후 먼저 3번 자체 점검 수행: 먼저 전체 텍스트를 읽어 스토리 라인이 매끄러운지, 사실이 원본 영상과 일치하는지 확인한 다음, 시간 창을 확인하여 말을 가로채거나 단어 수를 초과하는 부분이 없는지 확인하고, 마지막으로 validate.py를 실행합니다(또는 recap.py를 직접 다시 실행). 외부 홍보 제목, 커버 프레임 및 자막 아트 계획(packaging_plan.json)을 작성해야 하는 경우, 반드시 본편 스토리가 잠긴 후 references/promotional-copy.md에 따라 실행합니다.

4.4 더빙 합성 및 오디오-비디오 믹싱 렌더링

narration.json을 작성한 후 동일한 recap.py 명령을 다시 실행합니다.

1. 로컬 결정적 검증(validate.py): narration_lint.json을 생성하고, 시간 중복, 범위 초과, 단어 수 예산 초과, 불완전한 문장, 시작 콜드 오픈, 5초 초과 데드 에어, 원본 대사 가로채기, 중간에 원본 오디오 복귀, 일반적인 캐릭터 대명사 및 플레이스홀더 누설에 대해 하드 게이트 검사를 수행합니다. 오류가 존재하면 즉시 중단됩니다.
2. TTS 더빙(voiceover.py): 음성을 구간별로 합성하고 tts_segments/와 tts_meta.json에 기록합니다. 캐시는 텍스트, 음색, 모델 및 참조 오디오 지문으로 정확히 적중합니다. 특정 오디오 세그먼트의 지속 시간이 정상적인 말하기 속도 하한(TTS_MIN_SPEECH_RATE)보다 짧아 모델 환각 읽기가 의심되는 경우, 자동으로 재시도하고 *.rejected.wav를 저장소에 거부합니다.
3. 오디오-비디오 합성(assemble.py): 화면, 구간별 나레이션, 낮춰진 후 문장 끝에서 다시 올라오는 원본 오디오(자세한 내용은 references/data-schema.md의 source_handoff_status 설명 참조), 선택적 BGM(BGM_PATH), 선택적 장식용 전환 효과음 및 정교한 시각적 패키징(work_dir/packaging_plan.json 지원: 9:16 세로 버전 스테이지/시리즈 이중 골드 라인 화면비, 16:9 시네마 스탬프 및 미색 종이 느낌 자막 바, @2x 업샘플링 캐릭터 명판/데이터 카드/캘리그래피 자막 아트, 이중 소프트 포커스 키워드 하이라이트 자막; 또는 packaging_layers.json 정적 이미지), 엔딩 부드러운 페이드 아웃(기본값 350ms)을 모두 함께 믹싱하여 최종 MP4로 렌더링하고, 백엔드 독립적인 timeline.json을 출력합니다(--export-jianying 전달 시 Jianying 초안도 동시에 내보낼 수 있음).

나레이션 세그먼트가 허용되는 약간의 가속 상한 내에서도 사용 가능한 시간 창에 맞지 않으면, 합성기는 직접 no_safe_fit 오류를 보고하고 차단합니다. 나레이션 끝음을 절대 자르지 않습니다. 더 많은 오디오 모드, 오디오 라우팅 및 외부 시각적 패키징 사양에 대해서는 각각 references/audio-modes.md, references/audio-routing.md 및 references/packaging.md를 참조하십시오.

4.5 여러 비디오 연결 편집 및 리소스 라이브러리

여러 비디오 입력은 cut 모드만 지원합니다. 프로젝트 수준 브리핑에는 각 비디오의 고정된 source_id가 나열됩니다. clip_plan.json을 작성할 때 각 클립은 속한 source_id를 명시해야 합니다.

python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep

단일 에피소드의 이해 결과를 로컬 디렉토리에 저장하여 에피소드 간 재사용하려는 경우, 경량 파일 자료 라이브러리(--material-library-dir .video-materials --save-materials 및 --use-materials)를 활성화하고, grep을 사용하여 JSON/MD 파일을 직접 검색할 수 있습니다. 동일한 라이브러리 루트 디렉토리 아래에는 재사용 가능한 제작 리소스(BGM, 효과음, 음색, 글꼴, 스티커), 채택 기록이 있는 템플릿(subtitle_style, packaging, production_reference) 및 샘플 영상을 등록할 수 있습니다. scripts/library.py check|list|show를 통해 쿼리하고, --project recap_project.json을 사용하여 현재 실행에 한 번에 바인딩합니다. 각 합성 완료 후 work_dir/resource_lock.json에 실제 사용된 리소스와 라이선스 상태를 기록합니다. 자세한 내용은 references/resource-library.md를 참조하십시오.

원본 영상의 하드 자막 세로 픽셀 범위를 측정하여 정확한 마스크를 활성화해야 하는 경우, 전체 소스 저장소에서 tools/measure_subtitle.py <video>를 실행하거나, 추출된 프레임 이미지를 직접 보고 상하 경계를 측정한 다음, --subtitle-y-top 및 --subtitle-y-bot을 전달합니다.

4.6 최종 시청 및 납품 검토

스크립트 지표, 컷 점수, 추출된 프레임 콜라주 및 자동 QC 보고서는 직접 눈으로 보고 귀로 듣는 것을 대체할 수 없습니다. 각 납품 준비 전에 반드시 이번 라운드에서 최종적으로 사용자에게 전달할 완성 영상 파일을 직접 열고 5단계 검토를 완료합니다.

1. 정상 속도로 처음부터 끝까지 시청: 처음부터 끝까지 배속 없이, 건너뛰지 않고 보면서 눈에 거슬리거나 끊기는 모든 부분을 기록합니다.
2. 각 컷 포인트 개별 확인: 각 컷 포인트 전후 0.5–1초를 꺼내어 플래시 프레임, 반쪽 디졸브, 동작 점프 컷 및 잘린 반쪽 원본 대사가 없는지 확인합니다.
3. 눈을 감고 소리만 듣기: 화면을 보지 않고 소리만 들으며, 나레이션이 튀는 전보체로 부서지지 않았는지, 전환 부분의 사운드가 매끄러운지, 핵심 원본 대사가 명확한지 확인합니다.
4. 세 가지 주요 장면 개별 확인: 처음 5초의 시작 훅, 중간 감정 폭발 지점 및 영상의 마지막 장면을 개별적으로 다시 보고, 진입 타이밍, 감정 체류 및 끝맺음의 여운이 모두 제대로 잡혔는지 확인합니다.
5. 수정 대조 및 사양 최종 확인: REVISION 모드에서는 먼저 "수정 요청한 사항이 실제로 제대로 반영되었고, 요청하지 않은 잠금 항목은 조금도 변경되지 않았는지"를 하나씩 확인한 다음, 마지막으로 final_qc.json의 디코딩 완전성, 총 재생 시간, 잔여 프레임 검사 및 오디오-비디오 코딩 사양(--require-final-qc 기본 활성화, 차단 항목은 종료 코드를 직접 결정함. 디버깅 시에만 --no-require-final-qc 전달 가능)을 확인합니다.

납품 시 final_qc.json의 metadata.warnings를 반드시 확인하십시오. 비어 있지 않은 경우(예: 부분 오류 허용 후 partial_tts 누락 구간 발생, 또는 로컬 ffmpeg에 libass가 없어 subtitle_burn_degraded가 트리거되어 외부 .srt로 다운그레이드된 경우) 반드시 사용자에게如实告知해야 하며, 단순히 "렌더링 성공"이라고만 보고해서는 안 됩니다.

4.7 해설이 필요 없는 원본 오디오 완성 영상

# 현재 전체 입력 비디오를 직접 믹싱 및 합성; 이해, ASR 또는 TTS를 암시적으로 실행하지 않음
python3 scripts/recap.py locked_picture.mp4 --work-dir source_work --audio-mode source-mix
# cut 워크플로우에 따라 편집 계획 생성, 편집 후 직접 원본 오디오 완성 영상 합성, narration.json 대기 위해 일시 중지하지 않음
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --work-dir cut_work --audio-mode source-mix

source-mix는 전체 믹싱, 엔딩 부드러운 페이드 아웃 및 오디오 재인코딩을 수행합니다. 오디오 모드를 전환할 때는 반드시 새로운 작업 디렉토리를 사용해야 합니다. 자세한 내용은 references/audio-routing.md를 참조하십시오.

5. 자가 진단 및 읽기 전용 대시보드

python3 scripts/doctor.py
python3 scripts/dashboard_server.py --root <디렉토리> [--port 0] [--open]

doctor.py는 로컬 ffmpeg / ffprobe, 자막 필터 및 각 원격 서비스 키의 연결 상태를 확인합니다. dashboard_server.py는 로컬 127.0.0.1에서 엄격한 읽기 전용의 미니멀 심사 대시보드를 시작합니다(GET 및 HEAD만 응답). --root 아래의 완성 영상 작업 디렉토리와 library.json을 자동으로 스캔하여 완성 영상 재생, 해설 대본 및 샷 동기화 비교, 자료 라이브러리 미리보기를 직관적으로 표시합니다.

6. 출력 및 매개변수

핵심 전달물:

• recap_<video>.mp4: 최종 해설 또는 원본 오디오 완성 영상.
• subtitles.srt / subtitles.ass: 생성된 자막 파일.
• work_dir/: 전체 중간 분석, 계획 및 검증 산출물. 필드 규약은 references/data-schema.md 참조.
• work_dir/recap_story_plan.json 및 visual_audio_board.json: Agent가 확정한 감독 의도 및 스토리보드 오디오-비디오 결정.

전체 명령줄 매개변수는 python3 scripts/recap.py --help 및 각 단계별 스크립트 --help 출력을 기준으로 합니다. 그중 --style은 원고 작성 Agent에게 그대로 전달되는 자유 텍스트 요청이며, 고정된 프리셋이나 열거형 스위치가 아닙니다.

7. 능력 범위

• 로컬 결정적 기준 검증(잔여/깨진 샷, 대사 잘림, 나레이션이 대사 누름, 시간 창 내 단어 수 하드 상한, 초과 길이 끝 자름, 필수 화면 손실, 플레이스홀더 누설, 디코딩 및 패키징 사양)은 항상 하드 게이트로 실행됩니다. 스크립트는 기계적 실행 및 엔지니어링 바닥 방어만 담당합니다.
• 스토리 아크, 시작 훅, 오디오-비디오 호흡감 및 사실 일관성과 같은 의미 및 내러티브 품질에는 모델 점수 게이트가 설정되지 않습니다. Agent가 화면 증거, 원본 오디오 타임라인 및 references/creative-editing-playbook.md를 참조하여自主적으로 제어하고 납품 전 시청 검토를 완료해야 합니다.