capcut-edit
버전 인식 저장소를 통해 CapCut / JianYing 드래프트를 편집하기 위한 CLI입니다. v0.11은 draft_content.json, draft_info.json, draft_meta_info.json 및 template-2.tmp에서 읽기 가능한 타임라인을 감지하고 동기화합니다.
프로젝트 위치
- macOS:
~/Movies/CapCut/User Data/Projects/com.lveditor.draft/<project>/ - Windows:
%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<project>\
핵심 원칙 — 결정론적 스크립트
capcut 호출을 두 번 이상 포함하거나, 산술 연산 또는 분기를 포함하는 모든 레시피는 scripts/ 디렉토리에 매개변수화된 셸 스크립트로 제공됩니다. Claude는 입력과 함께 스크립트를 호출하고, 스크립트는 고정된 시퀀스를 실행합니다. 레시피가 스크립트로 작성될 수 있다면 반드시 스크립트여야 하며, references/에 설명을 작성해서는 안 됩니다.
references/workflows.md는 호출할 스크립트와 그 이유를 문서화하며, 재구성 가능한 시퀀스는 절대 포함하지 않습니다.
점진적 공개
광범위하게 시작하여 필요한 부분으로 깊이 들어가십시오. 전체 프로젝트 JSON을 한 번에 덤프하지 마십시오.
capcut info <project> -H # 개요
capcut doctor -H # 설치된 미디어/전사 기능
capcut diagnose <project> -H # 표준 파일, 차이, 편집기 안전성
capcut tracks <project> -H # 모든 트랙
capcut materials <project> -H # 자료 요약
capcut segments <project> -H # 시간 정보가 포함된 세그먼트
capcut segment <project> <id> # 하나의 항목, 전체 세부 정보
출력 모드
- JSON (기본값):
jq로 파이프하거나 스크립트에 입력으로 제공합니다. -H: 사람이 읽기 쉬운 테이블.-q: 자동 모드, 종료 코드만 출력 — 스크립트 내 쓰기 명령에 사용합니다.
배치 쓰기
echo '{"cmd":"set-text","id":"a1b2c3","text":"수정됨"}
{"cmd":"volume","id":"d4e5f6","volume":0.5}' | capcut batch <project>
작업: set-text, shift, shift-all, speed, volume, opacity, trim.
배치는 트랜잭션 방식으로 작동합니다. 하나의 작업이 실패하면 아무것도 쓰지 않습니다. 사용자가 명시적으로 부분 커밋을 수락한 경우에만 --continue-on-error를 사용하십시오. 이 경우에도 종료 코드는 0이 아닙니다.
참고 자료 위치
references/api-reference.md— 모든 명령, 모든 플래그, 모든 값 형식(시간, 백분율, 각도), ID-접두사 규칙,.bak불변성.../../docs/command-reference.md— 생성된 명령 계약 v2로, 유형화된 위치 인자/옵션, 가변성, 전제 조건, 출력 형식 및 종료 코드를 포함합니다.references/workflows.md— 레시피 = 실행할scripts/X.sh와 그 이유.references/pitfalls.md— 프로젝트 먼저 닫기,.bak, 오디오의clip=null,speed를 사용한source_timerange계산, 알파 키프레임이 렌더링되지 않음(애니메이션 자료 사용) 등.- 열거형(Enum) 검색 —
capcut enums --<category>(또는 테이블의 경우-H)를 호출하여 모든 CapCut 슬러그를 나열합니다. 카테고리:--transitions,--masks,--image-intros,--image-outros,--image-combos,--text-intros,--text-outros,--text-loop-anims,--scene-effects,--character-effects,--audio-effects,--fonts.--jianying을 추가하여 네임스페이스를 전환합니다.enums.json번들은python3 scripts/extract-enums.py를 통해 한 번 생성됩니다. 런타임에는 Python이 필요하지 않습니다. scripts/— 클라이언트 라이브러리. 현재:anim.sh— 9개의 CapCut 인트로/아웃트로 애니메이션 중 하나를 연결합니다.fade-in.sh와fade-out.sh는 얇은 래퍼입니다.ken-burns.sh—capcut keyframe --batch를 통해 스케일 + 팬 키프레임 (모션 속성은 렌더링됨, 알파는 렌더링되지 않음 — 대신anim.sh fade-in사용).long-to-short.sh— 범위를 자르고, 제목 + CTA 텍스트를 스탬프합니다.stamp-cta.sh— 저장된 텍스트 템플릿을 적용합니다 (assets/examples/subscribe-cta.json참조)._test.sh— 픽스처에 대해 모든 래퍼를 실행합니다. 여기에서 변경 후 실행하십시오.
assets/examples/— 수동 편집을 위한 원시 JSON 스니펫.
불변성
- 편집 전에 CapCut에서 프로젝트를 닫고, 편집 후에 다시 여십시오.
- 모든 쓰기는 충돌이 확인되고, 원자적으로 준비되며, 모든 읽기 가능한 타임라인 대상에 동기화됩니다. 모든 대상은
.bak및 롤링 히스토리 스냅샷을 받습니다. - 사용자가 명시적으로 디스크 상 변경된 상태 또는 열린 편집기 덮어쓰기를 수락하지 않는 한
--force-write를 절대 전달하지 마십시오. - 오디오 세그먼트의
clip은null입니다 (불투명도/스케일 없음). capcut cut은--out에 쓰고, 소스를 절대 수정하지 않습니다.- ID: UUID의 처음 6자 이상이 접두사로 일치합니다.
- 시간 형식:
1.5s,500ms,+0.5s,-1s,1:30,0:05.5, 숫자만 = 초.
v0.11 고가치 경로
- 전체 드래프트:
capcut compile spec.json --check, 그 다음capcut compile spec.json --out <dir>. 스펙은 참조, 변환, 데코레이터, 템플릿, 캡션, 키프레임 및 페이드를 지원합니다. - 노래방:
capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke. - 프록시:
capcut render <project> --all-video-tracks --burn-captions; 먼저 FFmpeg 기능 플래그를 위해doctor를 실행하십시오. - 자동화:
capcut serve --workers N --retries N --timeout MS; 작업에 안정적인id필드를 제공하고 러너가 프로젝트별로 쓰기를 직렬화하도록 하십시오. - 에이전트 스키마:
capcut describe가 진실 공급원입니다. 도움말 텍스트를 긁거나 플래그를 발명하지 마십시오.