akomlik/assemble-timeline

Atomic MCP 타임라인 어셈블리 및 검증 (/assemble-timeline)

옵션 A: FilmCraft MCP 실행 (filmcraft MCP 서버 — FilmCraft v0.17.0+ 필요)

1. 환경 및 브리지 확인

1. 먼저 python3 ./.agents/skills/assemble-timeline/scripts/check_filmcraft_env.py를 실행하여 FilmCraft $≥$ v0.17.0을 확인하고, filmcraft-cli를 FilmCraft.app과 자동 동기화하며, 새로 추가된 MCP 명령을 00_Archive_Indexes/filmcraft_capabilities.json에 표시합니다.
2. FilmCraft가 브리지 모드로 실행 중이고 캐시가 ~/Movies/Cache_And_Previews로 라우팅되는지 확인합니다.

   mkdir -p ~/Movies/Cache_And_Previews && cd ~/Movies/Cache_And_Previews
   open -a FilmCraft --args --control 9876
   

2. 라이브 시각 어셈블리 모드 (기본 및 권장)

열린 FilmCraft GUI에서 타임라인이 라이브로 조립되는 것을 지켜보면 총 소켓 실행 시간이 1.5초 미만으로 증가하며(로컬 브리지를 통한 호출은 $< 20) ms 소요), 즉각적인 시각적 검증을 제공합니다.

1. 0초에 빈 캔버스 열기: command_run ({"id": "file.open", "params": {"path": "<fcproj_path>"}}) 또는 sequence.new를 통해 FilmCraft에서 즉시 깨끗한 .fcproj 셸을 만들고 엽니다. 사용자는 0초에 빈 4K 시퀀스가 나타나는 것을 봅니다.
2. 스트리밍 미디어 인제스트: 선택한 모든 비디오 컷, 사진, 아카이브 자료 및 선택된 03_Audio_Library/01_Curated_BGM/ 트랙 (A2)의 절대 파일 경로와 함께 media_import를 호출합니다.
3. 라이브 씬별 스트림: 승인된 컷 테이블의 각 씬이 처리됨에 따라 9876 브리지를 통해 command_batch 호출을 라이브로 스트리밍합니다.
   • playhead.set: 플레이헤드를 씬 시작 시간코드로 이동합니다.
   • source.overwrite / timeline.insertClip: 시각적 클립을 V1(또는 오버레이/PIP의 경우 V2)에, 동기 오디오를 A1에 배치합니다.
   • motion.apply: 스틸 이미지에 Ken Burns EaseIn/EaseOut 스케일 및 팬 키프레임을 주입합니다(100% $→$ 108%, 또는 4:3 사진의 경우 134% $→$ 142%, 필러박스 크롭 방지).
   • audio.append: 1.5초 페이드인과 함께 A2 배경 음악을 드롭합니다.
   • voiceover.insert: 각 오디오 큐 합성이 완료되면 A4 보이스오버 세그먼트를 라이브 타임라인에 드롭합니다.
4. 방송 폴리시:
   • 동일 언어 라이브 다이얼로그 존중 법칙: 언어 $L$의 A4 보이스오버를 동일한 언어 $L$로 말해진 A1 라이브 카메라 다이얼로그 위에 절대 배치하지 않습니다(EN VO는 라이브 EN 다이얼로그를 존중하고, RU VO는 라이브 RU 다이얼로그를 존중하며, UA VO는 라이브 UA 다이얼로그를 존중합니다). A4 VO가 외국어 카메라 다이얼로그(edition_lang != clip_dialog_lang)가 포함된 클립을 번역하는 경우, 활성 VO 큐 동안 A1을 -12 dB만큼 덕킹합니다.
   • 자연스러운 1.00x 음성 속도, 1:1 V1 == A1 립싱크 및 오프닝 음악 인트로 법칙: 라이브 카메라 음성(A1) 또는 합성 보이스오버(A4)에 atempo > 1.0 또는 내부 일시 정지 제거(stop_periods=-1)를 절대 적용하지 않습니다. 항상 말하는 시각적 컷(V1)을 완전한 1.00x 음성 문장(src_in, dur)에 맞게 크기를 조정하여 V1과 A1이 프레임 및 샘플 동기화에서 1:1로 잠기도록 하고(atrim=start=...:end=...,asetpts=PTS-STARTPTS 사용, dynaudnorm=f=150:g=7:p=0.90이 amix 후 한 번 적용됨) 관련 없는 씬으로 넘치지 않도록 합니다. 항상 모든 타임라인과 렌더링된 .mp4를 첫 번째 보이스오버 큐가 시작되기 전에 1.5s–2.0s 음악 인트로로 시작합니다.
   • RMS 보정 음악 덕킹(음성 아래 평균 -28.5 dB): ffmpeg volumedetect(compute_bgm_ducked_gain_db)를 통해 각 A2 음악 트랙의 mean_volume을 측정하고 gain_db = -28.5 - raw_mean_db로 설정하여 덕킹된 BGM이 정규화된 -16.0 dB 평균 보이스오버 및 라이브 다이얼로그보다 12.5 dB 더 조용한 -28.5 dB 평균에 위치하도록 합니다(핫 마스터된 업비트 트랙에서도).
   • A4 보이스오버와 A1 다이얼로그를 Dialogue(clarity.eqPreset: "Balanced Voice")로 태그하고, A2 음악에 essentialSound.generateDucking(reduceDb: -6.0, fadeS: 0.45)을 실행합니다.
   • 마지막 시각적 클립에 기본 1.5초~2.0초 dip_to_black 전환을 적용합니다.
   • 필수 동기화 아웃트로 오디오 페이드: 마스터 오디오 출력([fullout])과 A2의 음악은 동기화된 2.0s–2.5s 반 사인 페이드아웃(afade=t=out:st=<TOTAL_DUR - FADE_DUR>:d=<FADE_DUR>:curve=hsin)을 실행하여 모든 오디오(음악, 카메라 노이즈, SFX 테일)가 마지막 프레임 이전 또는 동시에 완전한 무음(-infinity dB)에 도달하도록 합니다. .fcproj에서 트랙 A2는 EndAtCut 오디오 페이드 전환(from: Some(clip.id), to: None, align: "EndAtCut")을 반드시 포함해야 합니다. 사운드가 갑자기 끊겨서는 안 됩니다.
   • 다중 언어 자막 트랙을 enabled: false(burnCaptions: false 기본값)로 caption_tracks (C1)에 작성합니다.

3. 헤드리스 배치 폴백 (assemble_engine.py)

FilmCraft GUI가 실행 중이 아니거나 브리지 모드가 오프라인인 경우, assemble_engine.py를 통해 $< 1$초 만에 .fcproj를 직접 조립하고 filmcraft-cli를 통해 4K 마스터 MP4를 렌더링합니다.

• 저장소 위생 규칙: .agents/skills/assemble-timeline/scripts/는 범용 프로젝트에 구애받지 않는 엔진(assemble_engine.py, gpx_widgets.py, generate_voiceover.py, check_filmcraft_env.py) 전용으로 엄격히 유지합니다. 특정 프로젝트를 위해 사용자 정의 또는 프로젝트별 어셈블리 스크립트가 생성된 경우, 항상 해당 프로젝트의 git에서 무시된 카탈로그 폴더(04_Project_Catalog/YEAR/<project_name>/)에 저장하고 절대 .agents/skills/ 내부에 저장하지 마십시오.

4. 시각적 검증 및 마스터 렌더링

1. 세 가지 타임스탬프(Act 1 인트로, 중간점, 에필로그)에서 render_frame을 호출하여 프레이밍을 확인합니다.
2. 마스터 4K MP4를 ~/Movies/Exports/YEAR/<project_name>.mp4로 렌더링합니다.
3. 다국어 에디션이 요청된 경우(option_b), _UA.mp4 및 _RU.mp4 로컬라이즈된 스템과 함께 리먹싱합니다.

옵션 B: DaVinci Resolve Studio MCP 실행 (davinci-resolve)

1. 새 타임라인을 생성합니다(1920x1080 또는 3840x2160, 29.97 fps, DaVinci YRGB Color Managed Rec.709).
2. media_pool을 통해 선택한 미디어를 Selects 빈으로 가져오고, timeline_edit를 통해 V1/V2/A1에 클립을 추가하고 A2에 음악을 추가하며, transitions를 통해 Cross Dissolve 전환을 적용하고, keyframes를 통해 Ken Burns 줌 키프레임을 설정하고, audio / inspector를 통해 오디오 덕킹을 설정합니다.
3. 세 가지 타임스탬프에서 export_still을 호출하여 컷을 시각적으로 확인하고, .drp/.drt 백업을 04_Project_Catalog/YEAR/<project_name>/으로 내보내고, 최종 .mp4 렌더링을 ~/Movies/Exports/YEAR/에 대기시킵니다(render 통해).