cli-anything-shotcut

cli-anything-shotcut은(는) 무엇을 하나요?

MLT XML 형식을 기반으로 구축된 비디오 편집을 위한 상태 기반 명령줄 인터페이스입니다. GUI 없이 Shotcut 프로젝트를 만들고 편집해야 하는 AI 에이전트 및 고급 사용자를 위해 설계되었습니다.

설치

이 CLI는 cli-anything-shotcut 패키지의 일부로 설치됩니다:

pip install cli-anything-shotcut

사전 요구 사항:

• Python 3.10+
• melt (MLT CLI) — 렌더링 및 재생에 필요
• ffmpeg / ffprobe — 미디어 프로빙에 필요
• shotcut이 시스템에 설치되어 있어야 함

사용법

기본 명령어

# 도움말 보기
cli-anything-shotcut --help

# 대화형 REPL 모드 시작
cli-anything-shotcut

# 새 프로젝트 생성
cli-anything-shotcut project new -o project.json

# JSON 출력으로 실행 (에이전트 사용 용)
cli-anything-shotcut --json project info -p project.json

REPL 모드

하위 명령어 없이 호출하면 undo/redo를 지원하는 대화형 REPL 세션이 시작됩니다:

cli-anything-shotcut
# 또는 프로젝트와 함께:
cli-anything-shotcut --project my_project.mlt

REPL 명령어

워크플로우: 항상 media import를 먼저 실행하여 clip_id를 얻은 후, add-clip을 사용하여 타임라인에 배치합니다.

프로젝트 및 세션:

• new [profile] — 새 프로젝트 생성 (기본값: hd1080p30)
• open <path> — .mlt 파일 열기
• save [path] — 프로젝트 저장
• info — 프로젝트 정보 표시
• xml — 원시 MLT XML 출력
• status — 세션 상태 표시
• undo / redo — 작업 기록 탐색

미디어 (2단계 모델):

• media import <file> [--caption name] — 파일을 프로젝트 빈으로 가져오고, clip_id 반환 (예: clip0)
• media — 가져온 모든 미디어 나열
• probe <file> — 미디어 파일 분석

타임라인:

• add-track <video|audio> [name] — 트랙 추가
• tracks — 모든 트랙 나열
• show — 시각적 타임라인 개요
• add-clip <clip_id> <track> [in] [out] [--at time] — 가져온 클립을 트랙에 배치
• clips <track> — 트랙의 클립 나열
• remove-clip <track> <clip> — 클립 제거
• trim <track> <clip> [--in tc] [--out tc] — 클립 트림
• split <track> <clip> <at> — 지정된 타임코드에서 클립 분할

필터:

• list-filters [video|audio] — 사용 가능한 필터 탐색
• filter-info <name> — 필터 세부 정보 표시
• add-filter <name> [--track n] [--clip n] [key=val ...] — 클립, 트랙 또는 전체에 필터 추가
• filters [--track n] [--clip n] — 활성 필터 나열
• remove-filter <idx> [--track n] [--clip n] — 인덱스로 필터 제거
• set-filter <idx> <param> <value> [--track n] [--clip n] — 필터 매개변수 설정
• volume-envelope [--track n] [--clip n] TIME=LEVEL ... — 키프레임 볼륨 (예: 00:00:00.000=1.0 00:00:03.000=0.35)
• duck [--track n] [--clip n] START..END ... — 덕킹 엔벨로프 (예: 00:00:06.000..00:00:09.000)

내보내기:

• presets — 내보내기 사전 설정 목록
• render <output> [--preset name] — 비디오 파일로 렌더링

명령어 그룹

프로젝트

프로젝트 관리: 새로 만들기, 열기, 저장, 정보.

명령어	설명
new	새 빈 프로젝트 생성
open	기존 .mlt 프로젝트 파일 열기
save	현재 프로젝트 저장
info	상세 프로젝트 정보 표시
profiles	사용 가능한 비디오 프로필 나열
xml	현재 프로젝트의 원시 MLT XML 출력

타임라인

타임라인 작업: 트랙, 클립, 트리밍.

명령어	설명
show	타임라인 개요 표시
tracks	모든 트랙 나열
add-track	타임라인에 새 트랙 추가
remove-track	인덱스로 트랙 제거
add-clip	clip_id로 가져온 클립을 트랙에 추가; --at으로 절대 배치 지원
remove-clip	트랙에서 클립 제거
move-clip	트랙 간 또는 위치 간 클립 이동
trim	클립의 in/out 지점 트리밍
split	지정된 타임코드에서 클립을 둘로 분할
clips	트랙의 모든 클립 나열
add-blank	트랙에 빈 간격 추가
set-name	트랙 표시 이름 설정
mute	트랙 음소거 또는 음소거 해제
hide	비디오 트랙 숨기기 또는 숨기기 해제

필터 그룹

필터 작업: 추가, 제거, 효과 구성.

명령어	설명
list-available	사용 가능한 모든 필터 나열
info	필터 및 해당 매개변수에 대한 상세 정보 표시
add	클립, 트랙 또는 전체에 필터 추가
remove	인덱스로 필터 제거
set	필터 매개변수 설정
list	대상의 활성 필터 나열
volume-envelope	트랙 또는 클립에 키프레임 볼륨 엔벨로프 생성 또는 교체
duck	하나 이상의 시간 창에 실용적인 덕킹 엔벨로프 구축

미디어

미디어 작업: 프로브, 목록, 파일 확인.

명령어	설명
import	미디어 파일을 프로젝트 빈으로 가져오기
probe	미디어 파일 속성 분석
list	현재 프로젝트의 모든 미디어 클립 나열
check	모든 미디어 파일 존재 여부 확인
thumbnail	비디오 파일에서 썸네일 생성

내보내기

내보내기/렌더링 작업.

명령어	설명
presets	사용 가능한 내보내기 사전 설정 나열
preset-info	내보내기 사전 설정 세부 정보 표시
render	프로젝트를 비디오 파일로 렌더링

전환 그룹

전환 작업: 디졸브, 와이프 및 기타 전환.

명령어	설명
list-available	사용 가능한 모든 전환 유형 나열
info	전환 유형에 대한 상세 정보 표시
add	두 트랙 사이에 전환 추가
remove	인덱스로 전환 제거
set	전환 매개변수 설정
list	타임라인의 모든 전환 나열

컴포지트 그룹

합성: 블렌드 모드, PIP, 불투명도.

명령어	설명
blend-modes	사용 가능한 모든 블렌드 모드 나열
set-blend	트랙의 블렌드 모드 설정
get-blend	트랙의 현재 블렌드 모드 가져오기
set-opacity	트랙의 불투명도 설정 (0.0-1.0)
pip	클립의 화면 속 화면 위치 설정

세션

세션 관리: 상태, 실행 취소, 다시 실행.

명령어	설명
status	현재 세션 상태 표시
undo	마지막 작업 실행 취소
redo	마지막 실행 취소 작업 다시 실행
save	세션 상태를 디스크에 저장
list	저장된 모든 세션 나열

미리보기

반복 편집 검토를 위한 미리보기 번들 및 라이브 미리보기 세션.

명령어	설명
preview recipes	미리보기 레시피 나열
preview capture	저해상도 미리보기 번들 렌더링
preview latest	가장 최근 번들 반환
preview live start	라이브 미리보기 세션 시작 및 첫 번째 번들 게시
preview live push	라이브 세션에 새 번들 게시
preview live status	렌더링 없이 현재 라이브 세션 상태 조회
preview live stop	아티팩트 삭제 없이 라이브 세션 중지

일반적인 quick 번들 내용:

• preview.mp4
• 여러 샘플 프레임
• 중간 지점 hero.png
• 프로젝트 정보가 포함된 summary.json

폴 모드가 지원됩니다:

cli-anything-shotcut --json --project edit.mlt preview live start --recipe quick --mode poll --source-poll-ms 500

preview live status --json에는 세션 참조와 간결한 trajectory_summary가 포함되어 있어 에이전트가 최근 게시물 몇 개를 저렴하게 이해할 수 있습니다.

뷰어 명령어:

cli-hub previews inspect /path/to/bundle-or-session
cli-hub previews html /path/to/bundle-or-session -o page.html
cli-hub previews watch /path/to/session --open
cli-hub previews open /path/to/bundle-or-session

예제

새 프로젝트 만들기

새 Shotcut 프로젝트 파일을 생성합니다.

cli-anything-shotcut project new -o myproject.json
# 또는 프로그래매틱 사용을 위한 JSON 출력
cli-anything-shotcut --json project new -o myproject.json

대화형 REPL 세션

undo/redo를 지원하는 대화형 세션을 시작합니다.

cli-anything-shotcut
# 대화형으로 명령어 입력
# 'help'를 입력하여 사용 가능한 명령어 보기
# 'undo' 및 'redo'로 기록 탐색

프로젝트 내보내기

프로젝트를 최종 출력 형식으로 내보냅니다.

cli-anything-shotcut --project myproject.json export render output.mp4 --overwrite

결정론적 타임라인 재구성

재구성 시 추가 전용 클립 삽입보다 절대 배치를 선호합니다:

cli-anything-shotcut --project myproject.mlt media import intro.mp4
cli-anything-shotcut --project myproject.mlt timeline add-clip clip0 \
  --track 1 --in 00:00:00.000 --out 00:00:04.000 --at 00:00:00.000

cli-anything-shotcut --project myproject.mlt media import broll.mp4
cli-anything-shotcut --project myproject.mlt timeline add-clip clip1 \
  --track 1 --in 00:00:10.000 --out 00:00:16.000 --at 00:00:08.000

• --at은 대상 시간이 빈 공간에 있을 때 자동으로 빈 간격을 삽입합니다.
• CLI는 기존 클립과의 겹침을 거부합니다.
• 나중에 절대 배치가 모호하지 않도록 명시적인 --in 및 --out 값을 선호하세요.

오디오 자동화

cli-anything-shotcut --project myproject.mlt filter volume-envelope \
  --track 2 \
  --point 00:00:00.000=1.0 \
  --point 00:00:03.000=0.35 \
  --point 00:00:05.000=1.0

cli-anything-shotcut --project myproject.mlt filter duck \
  --track 2 \
  --window 00:00:06.000..00:00:09.000 \
  --window 00:00:15.000..00:00:18.000 \
  --normal 1.0 --duck 0.25

CLI는 다음과 함께 세션 상태를 유지합니다:

• Undo/Redo: 최대 50단계 기록
• 프로젝트 영속성: JSON으로 프로젝트 상태 저장/불러오기
• 세션 추적: 수정 사항 및 변경 사항 추적

출력 형식

모든 명령어는 이중 출력 모드를 지원합니다:

• 사람이 읽을 수 있는 (기본값): 표, 색상, 서식이 지정된 텍스트
• 기계가 읽을 수 있는 (--json 플래그): 에이전트 사용을 위한 구조화된 JSON

# 사람 출력
cli-anything-shotcut project info -p project.json

# 에이전트용 JSON 출력
cli-anything-shotcut --json project info -p project.json

AI 에이전트용

이 CLI를 프로그래매틱하게 사용할 때:

1. 항상 --json 플래그를 사용하여 파싱 가능한 출력을 얻으세요.
2. 반환 코드를 확인하세요 - 0은 성공, 0이 아니면 오류입니다.
3. 실패 시 stderr를 파싱하여 오류 메시지를 확인하세요.
4. 모든 파일 작업에 절대 경로를 사용하세요.
5. 내보내기 작업 후 출력 파일이 존재하는지 확인하세요.
6. 알려진 편집을 재생성할 때는 timeline add-clip --at을 선호하세요.
7. 키프레임 볼륨 또는 덕킹 변경 후 최종 렌더링을 검토하세요.
8. preview capture 또는 preview live ...를 사용하여 페이스, 컷 및 필터 효과를 시각적으로 검증하세요.
9. 반환된 아티팩트 경로(예: hero.png 및 preview.mp4)를 읽으세요. JSON 페이로드는 디스크의 파일을 참조합니다.
10. 전체 trajectory.json을 읽기 전에 preview live status --json을 사용하세요.
11. cli-hub previews ...는 기존 번들이나 라이브 세션을 검사하거나 여는 데만 사용하세요.

추가 정보

• 전체 문서: 패키지 내 README.md 참조
• 테스트 범위: 패키지 내 TEST.md 참조
• 방법론: cli-anything-plugin 내 HARNESS.md 참조

버전

1.0.0