FilmCraft — 에이전트 작동법
FilmCraft는 기본 비디오 편집기(Rust 기반, Premiere Pro 수준)로, 에이전트 인터페이스가 내장되어 있습니다. 모든 동작은 ID가 있는 명령입니다. 메뉴, 단축키, 패널, 타임라인 제스처, CLI, 제어 채널, MCP 서버 및 GUI는 모두 하나의 엔진을 구동합니다. Windows와 Linux에서 0.10.0–0.13.0 버전으로 검증되었습니다.
머신 및 환경 경로
| 플랫폼 | 바이너리 | CLI | 기본 데이터 디렉터리 |
|---|---|---|---|
| Windows | C:\Program Files\FilmCraft\filmcraft.exe | C:\Program Files\FilmCraft\filmcraft-cli.exe | %LOCALAPPDATA%\FilmCraft |
| Linux | /usr/bin/filmcraft | /usr/bin/filmcraft-cli | ~/.local/share/filmcraft |
| macOS | /Applications/FilmCraft.app/Contents/MacOS/filmcraft | filmcraft-cli (~/.local/bin 또는 PATH) | ~/Library/Application Support/filmcraft |
- 로그 위치:
<data-dir>/Logs/filmcraft.log - 제어 포트: 루프백 전용 (
--control <port>또는FILMCRAFT_CONTROL_PORT, 예:9876,7991,50051) - 명령: 42개 네임스페이스에 710개
- 효과: 130개 비디오 효과, 112개 비디오 전환, 3개 오디오 전환
멘탈 모델
- 프로젝트(
.fcproj, JSON)는 빈과 항목(Movie,Audio,Image,Sequence,Multi-Camera Source Sequence)을 보관합니다.project_inspect는 트리,activeSequence및 더티 플래그를 반환합니다. 하나의 시퀀스가 활성화되어 있으며 명령은 이 시퀀스에 대해 동작합니다. - 시퀀스에는
video[]와audio[]트랙 배열이 있으며, 각각{id, name, items[], transitions[], muted, locked, ...}형식입니다. 클립은{clip, item, name, start, duration, startFrame, durationFrames, sourceIn, sourceOut, speed, reverse, enabled, link, gainDb, effects[]}— 모든 시간은 틱(ticks) 단위입니다. - 동영상을 배치하면 서로 다른 ID를 가진 두 개의 연결된 클립(비디오 + 오디오)이 생성되며,
link가 서로를 가리킵니다. 기본적으로 하나를 선택하면 둘 다 선택됩니다. - 시간은 정수 틱(ticks)으로, 1초에 254,016,000,000틱(48000×5292).
seconds와frame은 프레임 그리드에 스냅됩니다.frame과timecode(예:"00:00:02:12"또는 드롭 프레임의 경우;)는 정확하게 매핑됩니다. 정확한 컷이 필요할 때는frame을 선호하세요. - 명령은
{"id": "timeline.razor", "params": {...}}형식입니다.command_list는 ID와 매개변수 문서를 찾습니다.command_run은 하나를 실행하고(실행 취소 가능);command_batch는 여러 개를 실행합니다. 잘못된 매개변수 타입과 알 수 없는 명령은 실패합니다. 알 수 없는 매개변수 이름은 자동으로 무시됩니다(함정 참조). - 읽기로 확인합니다(
sequence_inspect,project_inspect,captions.list,media.status,jobs.list) 또는 렌더링(render_frame,file.exportFrame).null결과는 "실행됨"을 의미하며 "의도한 대로 동작함"을 의미하지는 않습니다.
두 가지 연결 모드
| 모드 | 시작 방법 | 용도 |
|---|---|---|
| 헤드리스 | filmcraft-cli mcp (--demo, --project p.fcproj, --data-dir d) | 창 없음, 일괄 빌드, 내보내기, 스크립트 |
| 앱 브리지 | filmcraft --control 50051 + filmcraft-cli mcp --bridge 127.0.0.1:50051 | 실제 창: UI 상태, 스크린샷, 클릭, 키보드, 드래그, GUI 전용 명령 |
사용자 요청 시 FilmCraft 실행 ("起動して" / "start FilmCraft")
사용자가 FilmCraft를 시작하거나 실행해 달라고 요청할 때(「FilmCraftを起動して」「立ち上げて」「開いて」「start FilmCraft」):
- 이미 실행 중인지 확인:
- Windows:
Get-Process filmcraft -ErrorAction SilentlyContinue - Linux / macOS:
pgrep filmcraft - 실행 중인 경우 제어 포트가 응답하는지 확인합니다(
filmcraft-cli --bridge 127.0.0.1:50051 inspect). - 제어 포트 없이 실행 중인 경우 사용자에게 알립니다: "FilmCraft가 현재 제어 포트 없이 실행 중입니다. 작업을 저장하고 다시 시작하거나,
--control 50051을 사용하여 종료 후 다시 실행하도록 허용해 주세요."
- Windows:
--control <port>(기본값:50051) 및 64자FILMCRAFT_CONTROL_TOKEN으로 실행:- Windows (PowerShell) —
scripts/launch.ps1을 사용하여 데스크톱 창이WinSta0\Default에 표시되도록 합니다:
(이 스크립트는 자동으로powershell -File scripts/launch.ps1 -Port 50051FILMCRAFT_CONTROL_TOKEN을 설정/유지하고, 포트를 구성하며, GUI가 백그라운드 세션에 숨겨지지 않고 로그인한 사용자에게 표시되도록 대화형 작업을 실행합니다). - Linux:
./scripts/launch.sh 50051 - macOS:
./scripts/launch.sh 50051
- Windows (PowerShell) —
- 연결 확인:
- 1–3초 기다린 후
filmcraft-cli --bridge 127.0.0.1:50051 inspect를 실행합니다. - 응답이 오면 FilmCraft가 활성화되어 포트 50051에서 수신 중이며 라이브 타임라인 편집 및 협업 명령이 준비되었음을 보고합니다.
- 1–3초 기다린 후
17개의 MCP 도구
| 도구 | 목적 |
|---|---|
command_list | 모든 명령 (filter, enabled_only) |
command_run | 하나의 {id, params} 실행 |
command_batch | {steps:[{id,params}], stop_on_error} 실행 → {completed, failed, results} |
doc_inspect | 단일 호출로 프로젝트 트리 + 활성 시퀀스 반환 |
project_inspect | 트리, 항목, 활성 시퀀스, 더티 플래그 |
sequence_inspect | 활성 시퀀스: 설정, 트랙, 클립, 전환, 마커 |
media_import | 절대 경로로 파일 가져오기 (paths, bin, image_sequence) |
render_frame | seconds(또는 재생 헤드) 위치의 PNG, max_side |
render_preview | render_frame과 동일 (브리지: 프로그램 모니터) |
ui_inspect | 창/UI 상태 (도구, 작업공간, 선택, 대화상자, 재생, 요소 개수) |
ui_elements | 화면 요소 (id, label, rect, prefix) |
ui_click | id 또는 x,y로 클릭 (button, count, modifiers) |
ui_drag | 지점 또는 요소 ID 간 누르기–이동–놓기 (steps) |
ui_key | 키 또는 단축키 (Space, Cmd+Z, Shift+Delete) |
ui_type | 포커스된 필드에 텍스트 입력 |
ui_screenshot | 창 또는 하나의 panel PNG |
ui_control | 모든 제어 방법: ui.set, ui.menu.list, ui.playback, ... |
리소스: filmcraft://document (48 KB JSON: 프로젝트 + 시퀀스) 및 filmcraft://commands (192 KB 카탈로그). 프롬프트는 없습니다.
표준 워크플로우
- 조사.
project_inspect/doc_inspect; 헤드리스는--demo또는--project가 없으면 비어 있는 상태로 시작합니다. 브리지 모드에서는 먼저ui_inspect를 실행합니다. - 빌드.
file.newProject→file.import(절대 경로) 또는file.importDemoFootage→file.newSequence→timeline.place. - 컷.
playhead.set+timeline.razor,timeline.trim,timeline.slip,timeline.move,edit.clear/edit.rippleDelete. - 스타일.
effects.apply+effects.setParam;sequence.applyVideoTransition;lumetri.applyPreset;graphics.newText;markers.add;captions.add. - 확인.
sequence_inspect/captions.list읽기; 특정 시간에render_frame을 실행하고 PNG를 확인합니다(이렇게 하면 잘못된 클립, 검은 프레임, 누락된 전환 등을 잡아낼 수 있습니다. 읽기 전용으로는 알 수 없는 문제입니다). - 내보내기.
wait:true와 함께file.exportMedia실행 (offlineMedia와 생성된 파일 확인); NLE 왕복을 위해file.exportInterchange실행. - 저장.
file.saveAs(디렉터리 생성? 아니요 — 상위 디렉터리가 반드시 존재해야 함); 그런 다음project_inspect.dirty를 다시 읽습니다(저장 후 false).
명령 찾기
command_list {filter:"razor"}는 id, 레이블, 메뉴 및 매개변수와 일치합니다. filmcraft-cli commands razor, describe <id> 및 filmcraft-cli inspect도 셸에서 동일한 작업을 수행합니다. 전체 701개 ID와 매개변수 문서는 references/commands.md에 있습니다. 검증된 단계별 JSON은 references/recipes.md에 있습니다.
다음 명령으로 시작하세요: file.newProject, file.import, file.newSequence, timeline.place, timeline.razor, timeline.trim, timeline.slip, timeline.move, timeline.select, edit.clear, edit.rippleDelete, edit.undo, effects.apply, effects.setParam, sequence.applyVideoTransition, sequence.setTransition, markers.add, captions.newTrack, captions.add, graphics.newText, file.exportMedia, file.exportInterchange, file.exportFrame, file.saveAs.
시간을 낭비하는 함정
- 명령 매개변수는 관대합니다 — 알 수 없는 키와 일부 잘못된 타입은 자동으로 무시됩니다.
timeline.trim {seconds:-1}는{"delta":0}을 반환합니다(키는delta입니다);timeline.place {seconds:"2"}는 0에 배치합니다;fps:"fast"는 23.976으로 대체됩니다. 일부 명령은 유효성 검사를 수행하지만(graphics.set,markers.add), 잘못된 매개변수를 오류로 잡아내는 데 의존하지 마십시오. 매개변수 문서를 읽은 다음 상태를 다시 읽으십시오. file.newSequence는 활성 시퀀스를 전환하고{sequence: id}를 반환합니다.sequence.open은{item: id}를 필요로 합니다 —sequence나 클립 id를 전달하면 오류가 발생합니다. 열기/새로 만들기 후에는 항상sequence_inspect를 다시 읽으십시오.- 전환은 클립에 있지 않습니다.
sequence_inspect.video[i].transitions[]에{id, effect, from, to, start, duration, align, reverse, params}로 존재합니다.sequence.removeTransition {transitions:[id]};sequence.setTransition은 duration/align/params를 편집합니다. - 캡션은
sequence_inspect에 없습니다.captions.list를 사용하세요; 큐에는id, start, end, text가 포함됩니다.captions.newTrack은 알 수 없는 포맷 문자열에 대해 자동으로Subtitle으로 대체됩니다. - 절대
file.exportMedia에 디렉터리를 전달하지 마십시오. 무기한 멈춥니다(두 번 재현, >3분, 출력 없음). 전체 파일 경로를 사용하십시오. - 포맷이 확장자보다 우선합니다.
out.mp4와 함께format:"gif"를 사용하면out.mp4.gif를 씁니다.out.mp4와 함께 ProRes를 사용하면out.mp4.mov를 씁니다. 결과의path가 권위적입니다. timeline.place에서duration이 소스보다 길면 경고 없이 클립의 나머지 부분에 대해 마지막 프레임을 유지합니다. 미디어를 고려하여 트림하십시오.- 마커 없이
range:"inOut"을 사용하면 전체 시퀀스를 내보냅니다, 자동으로.range:"custom"+startSeconds/endSeconds가 신뢰할 수 있는 하위 범위입니다. jobs.list는 도구가 아니라 명령입니다.command_run {id:"jobs.list"};jobs.cancel {job}은 부분 파일을 제거합니다.wait:false내보내기는{job, path, poll, cancel}을 반환합니다.- 데모 푸티지는 합성입니다. 데모 미디어의 상호 교환 내보내기(FCPXML/AAF/OMF)는 클립을 손실합니다. 실제 온디스크 미디어를 사용하면 왕복이 가능합니다(
references/formats-and-roundtrip.md참조). edit.clear(Backspace)는 간격을 남깁니다.edit.rippleDelete는 간격을 닫습니다.sequence.lift/extract는 선택이 아닌 시퀀스 인/아웃 마커가 필요합니다.lumetri.applyPreset은 이전 룩을 대체하지 않고 매번 새로운 Lumetri 효과를 추가합니다. 이전 효과를 제거하거나 매개변수를 직접 설정하십시오.- GUI 전용 명령은
command_list에 표시되지 않습니다:window.workspace.{editing,assembly,color,effects,audio},window.workspace.reset,window.toggleFullScreen,app.about. 브리지에만 존재합니다. - HEVC 내보내기는 여기서 사용할 수 없습니다("등록된 인코더 없음"). H.264, ProRes, DNxHR, MJPEG, MXF, 이미지 시퀀스 및 오디오는 모두 작동합니다.
- 헤드리스 세션의
prefs.set은 세션 범위입니다 — 두 개의--data-dir세션 간에 유지되지 않았습니다. 영구 환경설정에는 GUI를 사용하십시오. - MCP 도구 인수는 엄격합니다(알 수 없는 키 → JSON-RPC
-32602; 잘못된 타입 → 역직렬화 메시지와 함께isError). 그러나command_run.params는 변경 없이 전달됩니다.
참조 맵
| 파일 | 내용 |
|---|---|
references/recipes.md | 빌드, 컷, 효과, 컬러, 캡션, 그래픽, 프록시, 멀티캠, TTS, 내보내기, GUI에 대한 검증된 JSON |
references/commands.md | 전체 701개 명령, 네임스페이스별 그룹화, 매개변수 문서 포함 |
references/mcp-and-control.md | MCP 세부 정보, 오류 형태, 리소스, 제어 방법, GUI 전용 명령 |
references/cli.md | filmcraft-cli 하위 명령, 플래그, 종료 코드, 오프라인 미디어, 헤드리스 작업 |
references/formats-and-roundtrip.md | 내보내기 매트릭스 + 독립적 검증, 상호 교환 왕복 |
references/bugs-and-workarounds.md | 최소 재현 코드와 함께 재현된 모든 결함 |
references/maintenance.md | 버전 재확인, 명령 덤프, 이 스킬 새로 고침 |
scripts/probe.sh | MCP 핸드셰이크 + 도구 개수 + 버전 |
scripts/dump-commands.sh | 명령 카탈로그 재생성 |
scripts/smoke-test.sh | 빌드 → 렌더 → 내보내기 → 독립적 검증 |
커뮤니티: https://discord.gg/artcraft · https://getartcraft.com/apps/filmcraft · https://github.com/storytold/filmcraft.