FilmCraft — Claude가 제어하는 영상 편집
이 PC에 설치
| 항목 | 위치 |
|---|---|
| 앱 + CLI (portable 0.13.0) | %LOCALAPPDATA%\Programs\FilmCraft\ (filmcraft.exe, filmcraft-cli.exe, 데이터는 data\) |
| 런처 (제어 채널 127.0.0.1:9876 + 토큰) | {{DEPOT}}\filmcraft-mcp\launcher\FilmCraftClaude.exe (바탕화면 바로가기 "FilmCraft") |
| 제어 채널 토큰 | %LOCALAPPDATA%\FilmCraft-Claude\control.token (절대 표시하거나 다른 곳에 복사하지 마세요) |
| MCP 컴패니언 (Python, uv) | {{DEPOT}}\filmcraft-mcp\server\ |
| FilmCraft 소스 (문서) | {{DEPOT}}\filmcraft\docs\ (agents.md, control-protocol.md, captions.md, graphics.md) |
시작 (항상 이 순서로)
filmcraft_status(MCP filmcraft-assist).running=false→filmcraft_launch(files=.fcproj프로젝트 또는 필요한 미디어).- 지연된 MCP 도구가 있다면 로드: ToolSearch
+filmcraft(두 서버). - 사용자의 작업을 데모 프로젝트에 마운트하지 마세요:
command_run file.newProject {name}후file.saveAs {path}(프로젝트 폴더 내) 또는file.open {path}.
두 MCP
| 필요 | 도구 |
|---|---|
| 상태 / 앱 실행 | filmcraft_status, filmcraft_launch (assist) |
| 프로젝트, ID 읽기 | doc_inspect, project_inspect, sequence_inspect (filmcraft) |
| 작업 실행 | command_run {id, params}, command_batch {steps, stop_on_error}, media_import (filmcraft) |
| 명령어 찾기 | command_list {filter} 또는 references/commands.md에서 grep |
| 결과 보기 | render_frame {seconds}, ui_screenshot {panel?} (filmcraft); contact_sheet (assist) 후 이미지 Read |
| 러프컷 전 분석 | media_probe → VFR이면 media_conform (assist) |
| 단어 단위 전사 (한국어) | transcribe_media (assist) — 절대 transcript.generate 사용 금지 (whisper-base, 한국어 성능 낮음) |
| 음악에 맞추기 | music_beats {add_markers, every, offset_seconds} (assist) |
| 최종 품질 검사 | export_qc {path, platform} (assist) |
MCP 외에도 CLI를 Bash에서 사용 가능 (headless, 창 없이): filmcraft-cli --project p.fcproj --save exec <id> key=value, filmcraft-cli --project p.fcproj export out.mp4 --preset "YouTube 1080p Full HD".
작업 루프
- 검사 (
sequence_inspect) → 클립/요소 ID 획득. ID는 razor 후 변경됨: 다시 검사. - 명시적 타겟 (
clips: [id],item: id)으로 작업 (선택 항목 대신). - 확인:
render_frame(핵심 지점),scopes.read(색보정),contact_sheet(리듬). - 잘못되었으면:
command_run edit.undo. 자주 저장:file.save.
오류 방지 규칙
- 시간: 틱 (254 016 000 000 / s). 대부분의 명령어는
seconds,frame또는timecode허용 →seconds선호.markers.add와sequence.addEdit는time을 틱 단위로 요구. - 시퀀스 = 출력 형식:
file.newSequence {name, width, height, fps, sampleRate: 48000}방송 규격에 맞춤 (16:9 1920×1080, 9:16 1080×1920, 1:1 1080×1080), 프레임률 = 컨폼된 러프컷의 프레임률. - 프랑스어 언어 태그:
transcript.removeFillers는 기본적으로 영어 목록 사용 → 항상fillers전달 (transcribe_media가 반환). - 긴 내보내기:
file.exportMedia {…, wait: true}. 항상export_qc후contact_sheet로 내보낸 파일 확인. - PATH의 ffmpeg는 2013년 버전: assist 도구(ffmpeg 8 WinGet) 또는
%LOCALAPPDATA%\Microsoft\WinGet\Links\ffmpeg.exe사용. - 명령어 거부 "not available right now": 조건 누락 (시퀀스 미열림, 잘못된 클립 타입, 타겟 없음).
command_list {filter: "<id>"}→enabled필드 확인.
레시피
정확한 매개변수가 포함된 상세 레시피: references/recipes.md.
- A. 튜토리얼 / 얼굴 카메라: probe → 컨폼 → 전사 → '음' 및 빈 구간 제거 → 깨끗한 음성 → 자막 → 색보정 → -14 LUFS 내보내기 → QC.
- B. 세로 숏폼 9:16: 1080×1920 시퀀스, 크롭, 크고 짧은 자막, "Social Vertical 1080×1920" 프리셋.
- C. 음악에 맞춘 편집:
music_beats→ 마디 마커 → 마커에서 컷 → 덕킹. - D. 색보정: Lumetri (실제 매개변수는
references/effects.md, 효과lumetri), 샷 매칭lumetri.applyMatch, 확인scopes.read. - E. 믹싱: Essential Sound (대화/음악), 덕킹, Mix 트랙에 true peak 리미터.
- F. 내보내기 + QC:
references/export-presets.md의 프리셋,loudnessLufs,captionSidecar,burnCaptions.
참조
references/recipes.md— 레시피 A~F의 단계별 JSON 페이로드.references/commands.md— 계열별 710개 명령어 (grep:`timeline.,`captions.,`lumetri.,`essentialSound.,`export.,`transcript.).references/effects.md— 303개 효과/전환, 매개변수 ID, 범위 및 선택 (grep`lumetri`,`hard_limiter`,`cross_dissolve`).references/export-presets.md— 39개 내보내기 프리셋.scripts/gen_reference.py— FilmCraft 업데이트 후 세 참조 파일 재생성:python -I scripts/gen_reference.py.
FilmCraft 업데이트
github.com/storytold/filmcraft/releases에서 filmcraft-<버전>-windows-x64-portable.zip 다운로드 (SHA256SUMS.txt 확인), FilmCraft 종료, %LOCALAPPDATA%\Programs\FilmCraft\에서 filmcraft.exe와 filmcraft-cli.exe 교체 (data\와 portable.txt 유지), scripts/gen_reference.py 재실행.