e1dred/filmcraft

filmcraft은(는) 무엇을 하나요?

업데이트: 이 폴더에 .installed-from 파일이 있는 경우 (저장소에서 복사할 때 기록됨), 세션당 한 번 git ls-remote https://gitlab.com/e1dred/agent-skills.git HEAD를 실행합니다. 정확히 HEAD로 끝나는 출력 줄의 해시를 가져와 파일의 해시와 비교합니다. 다르면 사용자에게 최신 버전이 존재한다고 알리고 업데이트를 제안합니다(https://gitlab.com/e1dred/agent-skills/-/blob/main/INSTALL.md의 "업데이트" 참조, 로컬 편집 내용 병합 가능). 묻지 않고 업데이트하지 마십시오. 공백을 제거한 후 해시를 비교합니다. 파일이 없거나, 클론/심볼릭 링크이거나, 네트워크가 없는 경우(빈 출력 또는 git ls-remote 오류) 조용히 건너뜁니다.

첫 번째 헤드리스 작업에서 얻은 현장 노트, FilmCraft 0.17.1(Linux AppImage)에서 마지막으로 테스트되었습니다. FilmCraft는 Rust로 작성된 얼리 알파, Premiere 스타일 비디오 편집기입니다. 모든 메뉴 항목과 버튼은 엔진 명령입니다. CLI, MCP 서버 및 앱의 제어 채널은 동일한 명령을 실행합니다. filmcraft-cli --version이 더 새로운 버전이라면, 여기의 어떤 내용이든 의존하기 전에 다시 확인하십시오.

설정

• CLI: AppImage에서 추출합니다(filmcraft.appimage --appimage-extract, usr/bin/filmcraft-cli를 안정적인 위치로 복사). 자체 포함되어 있으며 창이 필요 없습니다. AppImage 자체에서 --version을 실행하지 마십시오.
• 헤드리스: filmcraft-cli --project p.fcproj exec <id> key=value …. 스크립트는 JSON 라인 형식이며 하나의 세션을 유지합니다: filmcraft-cli --project p.fcproj run script.jsonl [--save] (라인: {"id":"…","params":{…}}) 또는 file.newProject 후 독립형 filmcraft-cli run. 하위 명령: commands, describe, inspect, import, export, render, probe.
• 라이브 앱: filmcraft --control 9876 (또는 FILMCRAFT_CONTROL_PORT). 리스너는 환경 변수에 FILMCRAFT_CONTROL_TOKEN(64자 16진수)이 필요합니다. 없으면 닫힌 상태로 유지됩니다. filmcraft-cli mcp --bridge 127.0.0.1:9876으로 브리지합니다.
• MCP: filmcraft-cli mcp (헤드리스) 또는 --bridge (라이브).

위치 정보

작업과 일치하는 파일을 읽으십시오. 각 파일은 포함된 섹션을 나열합니다. reference/에서 grep -n을 사용하여 명령 ID를 찾으십시오.

reference/의 파일	읽을 내용	섹션
projects-and-timeline.md	프로젝트, 미디어 가져오기, 시퀀스, 플레이헤드, 커터 및 트리밍, 마커, 저장, 전환, 비디오 효과 및 키프레임, 프레임 홀드, 프로젝트 노트	프로젝트 및 미디어; 시퀀스; 자르기 및 트리밍; 마커 및 저장; 전환; 비디오 효과 및 키프레임; 프레임 홀드, 선택 및 프로젝트 노트; 기타 편집 도구
titles-and-graphics.md	텍스트 및 셰이프 레이어, 작은 프레임의 크기/맞춤, 레이어 읽기, 세로 텍스트 및 가져온 이미지	제목; 크기 조정 및 맞춤; 레이어 속성; 기타 레이어 도구
audio-mixer.md	믹서 스트립, 값, 서브믹스, 인서트 및 샌드; 클립 게인 및 Essential Sound	믹서; 클립 오디오
captions.md	자막 트랙, 자막 추가/편집/이동, SRT 가져오기 및 내보내기	자막 트랙 및 SRT
export.md	내보내기 사전 설정 및 형식, 내보내기 큐, MP4/GIF 내보내기, 프레임 스틸, 교환 내보내기, 프로빙	사전 설정; 내보내기; 사전 설정 및 내보내기 큐; 스틸; 프로빙
command-catalogue.md	계열별 기타 모든 명령 ID(클립, 타임라인, 시퀀스, 트리밍, 그래픽, 편집, 파일, 프로젝트, 멀티캠, 소스, 환경설정, 단축키 등). 각각 확인됨(JSON 경로 이전 → 새로), 결과 반환, 실행 또는 이유와 함께 거부됨으로 표시. 선택 종속 명령을 활성화하는 설정	계열당 하나의 섹션
live-app.md	--bridge를 통해 실행 중인 앱 제어: ui_* 도구, 라이브에서만 작동하는 것, 숨겨진 디스플레이에서 실행	연결; 라이브 앱이 추가하는 것
newer-commands.md	각 버전에서 추가되거나 변경된 사항	0.17.0; 0.17.1
log.md	테스트된 날짜별 로그	로그

CLI 필수 사항 (확인됨)

filmcraft-cli commands --json                    # 716개 명령: id, label, menu, params, enabled
filmcraft-cli describe file.import               # 하나의 명령에 대한 파라미터 문서
filmcraft-cli --project p.fcproj inspect         # {project:{…}, sequence:{…}} JSON 형식
filmcraft-cli import clip.mp4 --project p.fcproj
filmcraft-cli --project p.fcproj export out.mp4 --scale 0.5 --quality 70
filmcraft-cli --project p.fcproj render --seconds 2 --out frame.png
filmcraft-cli probe clip.mp4                     # 종류, 지속 시간(틱), 비디오/오디오 스트림 세부 정보

• JSONL 스크립트는 상태를 유지합니다: file.newProject → file.import {"paths":["clip.mp4"]} → {"items":[1]} → file.newSequenceFromClip {"items":[1]} → {"clips":[6,7],"sequence":4} → … → file.saveAs {"path":"p.fcproj"}.
• 이후 모든 CLI 호출에 --project를 전달하십시오. 그렇지 않으면 각 호출이 새로운 세션입니다.

함정

• 시간은 프레임이 아니라 틱입니다: 시퀀스는 3초에 대해 762,048,000,000을 보고합니다(254,016,000,000틱/초). playhead.set은 seconds, frame, time 또는 timecode를 허용하며 가장 가까운 프레임으로 스냅됩니다(1.5초 → 프레임 37).
• 기본 크기의 텍스트 레이어는 작은 프레임에서 오버플로우됩니다. graphics.newText 기본값은 100px입니다. 320×180 시퀀스에서 "Hello FilmCraft"의 size:48는 x=40에서 너비 334.7px로 그려져 오른쪽 가장자리에서 잘렸습니다. size를 설정하여 맞추십시오(~32 → 너비 223px; 렌더링에서 확인됨). box:[w,h]를 사용한 단락 텍스트는 줄바꿈되지만, 상자는 높이에 맞지 않는 줄을 자릅니다. box:[240,60]에 size 40에서는 "Hello"만 표시되었습니다(두 번째 줄이 잘림). 따라서 모든 줄에 충분히 높은 상자를 만드십시오(줄당 약 1.3 × size).
• 리플 편집은 동기화 잠금 트랙에서 실패합니다: timeline.trim을 mode:"ripple"로 실행하면 V2에 제목이 있을 때 "이 편집은 동기화를 깨뜨립니다: V2가 동기화 잠금 상태이며 방해가 되는 클립이 있습니다"라는 응답을 받았습니다. 다른 트랙을 잠금/잠금 해제하거나 리플 없이 트리밍하십시오.
• probe --image-sequence는 번호가 매겨진 스틸만 허용합니다. 동영상에서는 오류가 발생합니다.
• effects.addKeyframe 헤드리스에서 raw mediaTime으로 실행하면 아무 작동도 하지 않았습니다 ({added:false, mediaTime:0}; 0.17.0). 그러나 라이브 앱에서 {clip, effect:"opacity", param:"opacity", seconds:1.5, value:40}는 하나를 추가했습니다(키프레임 5 → 6; 시간은 프레임으로 스냅됩니다: 624699432000). 헤드리스에서는 플레이헤드를 이동하고 effects.toggleAnimation을 사용하거나 제목 속성에 대해 graphics.set {…,"keyframe":true}를 사용하십시오.
• mixer.addInsert에는 실제 오디오 효과 ID(hard_limiter, effects.list {"kind":"Audio"}에서 가져옴)가 필요하며, volume과 같은 레이블이 아닙니다. mixer.addSend는 동일한 실행에서 mixer.addSubmix의 서브믹스 ref가 필요합니다.
• graphics.* 명령은 동일한 세션에 제목이 필요합니다: 먼저 동일한 스크립트에서 graphics.newText를 실행한 다음, graphics.alignFrame.*, nudge*, fontSize*, leading*가 헤드리스에서 작동합니다(graphics.list {clip} → layers[0]). 제목이 없으면 "그래픽 클립 없음" 응답을 받습니다. graphics.deleteLayer는 라이브에서만 허용되었습니다(읽어오기 없음).
• 선택 상태는 저장/재열림 시 유지되지 않습니다: 선택이 필요한 명령과 동일한 스크립트에 project.select {items:[id]} / timeline.select를 넣으십시오("프로젝트 패널에서 항목을 선택하십시오", "선택된 클립 없음").
• FCPXML 내보내기는 제목을 놓칠 수 있습니다: file.exportInterchange {"format":"fcpxml"}는 파일을 쓰는 동안 그래픽 클립이 "지원되지 않음"이라고 보고했습니다. 교환 내보내기를 신뢰하기 전에 보고서를 읽으십시오.
• --demo는 내장된 데모 프로젝트를 엽니다. 검사하고 렌더링합니다(1초에 1920×1080 프레임). 테스트한 한도 내에서 내보내기는 정상이었습니다. --allow-offline이 허용하지 않으면 누락된 미디어는 자리 표시자 프레임으로 내보내집니다.
• file.exportMedia는 "wait":false가 아닌 한 파일을 기다립니다. CLI export는 항상 기다립니다.

보고하기 전에 확인

inspect sequence(클립 시작/끝(프레임), 트랙, 전환, 효과), 내보낸 파일의 지속 시간 및 코덱에 대한 probe, 그리고 중요한 시점의 프레임을 render하여 확인하십시오. 프레임 수: 25fps에서 3초 = 75프레임. -10 프레임의 리플 트리밍은 65프레임을 제공했습니다.