명령줄 인터페이스
OpenShot을 명령줄 작업 흐름에 통합하세요. 영상 소스를 가져오고, 클립을 자르고 배열하며, 효과를 적용하고, 키프레임으로 속성을 애니메이션화하고, 터미널에서 비디오를 내보낼 수 있습니다. 몇 가지 명령으로 반복 편집을 자동화하거나, 반복 프로젝트를 위한 스크립트를 작성하거나, AI 에이전트가 비디오를 조립하고 다듬도록 도울 수 있습니다.
명령줄은 편집기와 동일한 프로젝트를 사용합니다. 열린 편집기를 제어하며 변경 사항을 실시간으로 검토하거나, 창을 열지 않는 헤드리스 세션에서 작업할 수 있습니다. 세션은 편집, 실행 취소 기록, 내보내기 작업을 포함하여 명령 사이에 프로젝트를 열어 둡니다. 나중에 편집을 계속하려면 언제든지 .osp 프로젝트로 저장하세요.
시작하기
설치된 OpenShot 실행 파일 뒤에 --cli를 붙여 사용하세요. 세션, 편집, 애니메이션, 저장에 대한 간단한 안내는 intro로 시작하고, 명령 개요는 help를 사용하세요. 이 명령들은 활성 세션이 필요하지 않습니다. 아래 예제는 명령줄 편집 기능이 포함된 OpenShot 빌드가 필요합니다.
리눅스 AppImage
다운로드한 AppImage가 있는 디렉터리에서:
./OpenShot.AppImage --cli intro
./OpenShot.AppImage --cli help
OpenShot.AppImage를 다운로드한 파일명으로 바꾸세요. AppImageLauncher가 데스크톱 통합 대화상자를 표시하면, 명령 실행 전에 APPIMAGELAUNCHER_DISABLE=1을 설정하세요:
APPIMAGELAUNCHER_DISABLE=1 ./OpenShot.AppImage --cli intro
스크립트나 반복 명령을 위해 현재 셸에서 한 번 설정하세요:
export APPIMAGELAUNCHER_DISABLE=1
./OpenShot.AppImage --cli session start
변수는 AppImage 실행 전에 설정해야 합니다: AppImageLauncher가 OpenShot이 --cli를 받기 전에 이를 가로챌 수 있습니다. 상대 미디어 경로와 @batch.json 파일은 작업 디렉터리에서 해석됩니다. 세션이나 내보내기가 실행되는 동안 AppImage 파일을 유지하세요.
리눅스 Snap
OpenShot Snap을(를) 사용하려면:
snap run openshot-qt --cli intro
snap run openshot-qt --cli help
snap run openshot-qt --cli session start
Snap의 파일 권한은 명령줄 편집에도 적용됩니다. 미디어, 프로젝트, 내보내기 파일을 Snap이 접근할 수 있는 위치(예: 홈 폴더)에 보관하세요. 외장 드라이브 접근을 허용하려면 removable-media 권한을 연결하세요:
sudo snap connect openshot-qt:removable-media
윈도우
중요
윈도우에서 명령줄 편집에는 openshot-qt-cmd.exe를 사용하세요. 이 콘솔 실행 파일은 터미널에 명령 결과, 도움말, 오류를 표시합니다. 데스크톱 실행 파일인 openshot-qt.exe는 대화형 터미널에서 표준 출력을 표시하지 않아 명령에 대한 피드백이 보이지 않고 CLI 사용이 어렵습니다.
PowerShell에서 OpenShot 설치 디렉터리에서:
& .\openshot-qt-cmd.exe --cli intro
& .\openshot-qt-cmd.exe --cli help
& .\openshot-qt-cmd.exe --cli session start
다른 디렉터리에 있다면 openshot-qt-cmd.exe의 전체 경로를 사용하세요. 실행 파일 이름 뒤에 --cli를 유지하세요.
macOS
Applications에 설치된 경우:
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli intro
"/Applications/OpenShot Video Editor.app/Contents/MacOS/openshot-qt" --cli help
명령 찾기
이 가이드 전체에서 openshot-cli는 위 설치 명령의 축약형으로, 예를 들어 snap run openshot-qt --cli 또는 ./OpenShot.AppImage --cli를 의미합니다. 일부 설치는 openshot-cli 명령을 직접 제공합니다. 소스에서 실행할 때는 OpenShot의 Python 환경에서 python3 src/launch.py --cli를 사용하세요.
단순한 --cli, --cli help, --cli --help는 동일한 개요를 보여줍니다. 명령을 탐색할수록 도움말이 더 구체적으로 표시됩니다:
openshot-cli clip help
openshot-cli clip keyframe help
openshot-cli clip keyframe set help
openshot-cli edit help
openshot-cli text help
openshot-cli effects list
openshot-cli effects audiovisualization help
openshot-cli effects audiovisualization help --property background
그룹 도움말은 예제와 함께 작업 흐름을 설명하고, 작업 도움말은 인수와 동작을 설명합니다. --help는 끝에 help를 붙인 것과 같습니다. 모든 도움말 명령은 편집 세션 없이 작동합니다.
effects list는 사용 가능한 효과를 간단한 설명과 함께 보여줍니다. 효과 도움말은 속성, 기본값, 선택 사항, 범위를 설명합니다. effects instances는 클립에 이미 적용된 효과와 부모 클립 ID를 나열합니다. 클래스 이름, 표시 이름, 밑줄 별칭은 동일한 효과를 식별합니다.
스크립트 및 AI 에이전트와 작업하기
Codex 및 Claude Code와 같은 AI 코딩 에이전트는 CLI를 사용하여 터미널 명령으로 OpenShot 프로젝트를 검사하고 편집할 수 있습니다. 에이전트에 OpenShot 실행 파일 경로, 작업할 미디어 또는 프로젝트, 원하는 결과(길이, 크기, 애니메이션 스타일, 출력 위치)를 제공하세요. 시작 전에 --cli intro를 읽도록 요청하세요. 동일한 명령은 직접 입력하거나 스크립트에서 실행할 때도 작동합니다.
intro로 시작한 후 필요에 따라 명령별 도움말을 사용하세요. 유용한 작업 흐름은 세션을 선택하고, 프로젝트를 검사하며, 소규모 변경을 하고, 결과를 검토한 뒤 저장하는 것입니다. 명령은 구조화된 JSON을 반환하여 스크립트와 에이전트가 화면 출력을 해석하지 않고도 객체 ID와 결과를 직접 사용할 수 있습니다.
편집 전에 검사하세요. 이름, 트랙 번호, 타이밍을 추측하지 말고 반환된 ID와 속성 정보를 사용하세요. 프로젝트가 둘 이상 열려 있을 때는 세션을 명확히 선택하세요.
반복 편집을 그룹화하세요. 연속 변경에는
edit apply를, 선택한 클립에 템플릿을 적용할 때는edit bulk를 사용하세요. 배치를 적용하기 전에--dry-run으로 검증하세요.애니메이션 확인. 좌표 공간을 선택하고, 몇 개의 키프레임으로 시작하며, 익숙한 모션을 위해 이징 프리셋을 사용하세요.
keyframe preview는 곡선을 샘플링하여 내보내기 전에 일시 중지나 점프를 발견할 수 있게 합니다. 렌더링된 모션도 검토하세요; 단순한 컨택트 시트만으로는 애니메이션의 느낌을 알 수 없습니다.저장 및 내보내기 추적. 프로젝트를 명시적으로 저장하고 출력물을 완성된 것으로 간주하기 전에 내보내기 작업의 상태를 확인하세요. 요청이 시간 초과되면 편집을 반복하기 전에 상태를 점검하세요.
아래 섹션에서는 이러한 작업 흐름과 타이밍 규칙을 설명합니다.
세션 및 출력
세션 시작 또는 찾기
헤드리스 세션 하나 시작하기 (편집기 창 없이):
openshot-cli session start
시작 시 기존 프로젝트를 열려면 --project "/path/project.osp" 를 추가하세요. 성공한 JSON 응답에는 result.session_id 가 포함됩니다. 해당 값을 복사하세요. OpenShot이 이미 실행 중이거나 ID를 잊어버렸다면, 사용 가능한 세션을 다음 명령으로 찾으세요:
openshot-cli session list
편집하려는 프로젝트의 세션을 선택하세요. 각 명령마다 새 세션을 시작할 필요는 없습니다.
세션 선택
팁
OPENSHOT_SESSION을 한 번 설정한 후 명령을 정상적으로 실행하세요. 터미널이 선택한 세션을 기억하므로 모든 명령에 --session 을 전달할 필요가 없습니다. 아래 PowerShell 또는 Bash 예제를 사용하세요.
아래의 SESSION_ID 를 session start 또는 session list 가 반환한 session_id 로 바꾸세요.
Windows PowerShell:
$env:OPENSHOT_SESSION = "SESSION_ID"
& .\openshot-qt-cmd.exe --cli timeline view
& .\openshot-qt-cmd.exe --cli export start "C:\path\test.mp4" --wait
Linux Bash:
export OPENSHOT_SESSION="SESSION_ID"
./OpenShot.AppImage --cli timeline view
./OpenShot.AppImage --cli export start "/path/test.mp4" --wait
macOS에서는 동일한 export 구문을 사용하세요. macOS 또는 Snap 명령의 경우, 시작하기에서 설치한 실행 파일로 대체하세요. 선택은 이 터미널과 여기서 실행된 명령에 유효합니다. 새 터미널에서 다시 설정하거나 다른 세션으로 전환할 때 업데이트하세요.
나머지 편집 및 내보내기 예제는 OPENSHOT_SESSION이 설정된 상태를 가정합니다. 다음 하위 섹션에서는 스크립트용 ID 자동 캡처 방법을 보여줍니다.
한 명령에 대해서만 다른 세션을 지정하려면 --session 을 사용하세요. 이는 터미널의 선택을 변경하지 않고 OPENSHOT_SESSION 을 무시합니다:
openshot-cli --session OTHER_SESSION_ID project get
패키지된 실행 파일에서는 이 무시 옵션을 --cli 뒤, 명령 그룹 앞에 넣으세요: --cli --session OTHER_SESSION_ID project get.
자동 선택은 접근 가능한 세션이 정확히 하나일 때만 작동합니다. session_required 가 표시되면 session list 를 실행하고 의도한 세션을 명시적으로 선택하세요. 더 이상 목록에 없으면 다시 시작하고 새 ID를 사용하세요. 도움말, intro, 세션 검색은 선택된 세션이 필요하지 않습니다.
세션 ID 자동 캡처
스크립트는 session start 가 반환한 JSON에서 result.session_id 를 직접 읽고 이후 명령에 대해 OPENSHOT_SESSION 을 설정할 수 있습니다. ID를 수동으로 복사하거나 로그 파일을 읽을 필요가 없습니다. 반환된 ID를 사용하기 전에 시작이 성공했는지 확인하세요.
Windows PowerShell (설치한 실행 파일 경로 설정):
$openshot = "C:\Program Files\OpenShot Video Editor\openshot-qt-cmd.exe"
$reply = & $openshot --cli session start
if ($LASTEXITCODE -ne 0) { throw "OpenShot session startup failed" }
$session = $reply | ConvertFrom-Json
if (-not $session.ok -or -not $session.result.session_id) {
throw "OpenShot did not return a session ID"
}
$env:OPENSHOT_SESSION = $session.result.session_id
& $openshot --cli timeline view
Linux Bash (JSON 읽기에 jq 필요):
openshot="/full/path/to/OpenShot.AppImage"
export APPIMAGELAUNCHER_DISABLE=1
if reply=$("$openshot" --cli session start) &&
session_id=$(printf '%s' "$reply" | jq -er 'select(.ok == true) | .result.session_id | strings | select(length > 0)'); then
export OPENSHOT_SESSION="$session_id"
"$openshot" --cli timeline view
else
echo "OpenShot session startup failed" >&2
fi
환경 변수는 이 터미널에서 실행된 명령에 대한 세션을 선택하며, 시스템 전체 설정을 변경하지 않습니다. 세션 시작은 변수를 자동으로 설정하지 않습니다. 세션을 중지한 후에는 PowerShell에서 Remove-Item Env:OPENSHOT_SESSION 또는 Bash에서 unset OPENSHOT_SESSION 으로 선택을 해제하세요.
세션 표시 및 중지
선택한 세션을 편집기에서 표시하려면:
openshot-cli session show
데스크톱에서는 session show 가 동일 프로세스에서 편집기를 생성하고 라이브 프로젝트, ID, 기록, 내보내기 작업 및 연결을 유지합니다. 반복 호출 시 기존 창을 활성화합니다. session start --show 는 즉시 엽니다. 디스플레이 없이 시작되었거나 QT_QPA_PLATFORM=offscreen/minimal 로 시작된 세션은 나중에 데스크톱 창을 표시할 수 없습니다. 해당 세션에서는 프로젝트를 저장하고 새 데스크톱 세션에서 여세요. 표시된 후에는 편집기 창에서 세션을 닫으세요.
전역 옵션(--session, --timeout)은 명령 앞에 위치합니다. session serve 는 감독자를 위해 포그라운드에 머무르며; session start 는 백그라운드 호스트 등록 후 반환합니다. session stop 은 저장되지 않은 변경 사항과 활성 내보내기를 거부합니다. 저장되지 않은 편집을 의도적으로 버릴 때만 --discard 를 사용하세요.
명령 출력
결과는 기본 텍스트 타임라인 뷰를 제외하고 stdout에 JSON으로 출력됩니다. 오류는 stderr에 JSON으로 출력되며 종료 상태는 1, 인수 파서 오류는 2입니다. 변경 작업은 inspect 명령으로 간결한 요약을 반환합니다. get 은 네이티브 객체 JSON을 반환합니다. 프로젝트 응답에는 리비전이 포함되며, 효과 카탈로그 응답은 세션이 필요하지 않습니다. 헤드리스 세션의 로그는 레지스트리 기록 옆에 저장됩니다. OPENSHOT_SESSION_DIR 은 기본 ~/.openshot_qt/sessions 디렉터리를 대체합니다.
세션은 컴퓨터에서 로컬로 명령을 수락합니다. 편집 세션에 접근하는 데 사용되는 자격 증명이 포함되어 있으므로 세션 레지스트리를 비공개로 유지하세요. 내보내기는 스냅샷에서 작동하므로 작업이 실행되는 동안에도 편집을 계속할 수 있습니다.
프로젝트 열기 및 저장
OpenShot 프로젝트(.osp)는 편집 가능한 타임라인을 저장합니다. 내보내기는 완성된 비디오를 생성하며, 프로젝트 저장은 나중에 클립, 효과 및 키프레임으로 돌아갈 수 있게 합니다. 비디오를 내보낼 때도 프로젝트를 별도로 저장하세요.
프로젝트 열기
기존 프로젝트로 세션 시작:
openshot-cli session start --project "/home/me/Videos/My Project.osp"
--show를 추가하여 편집기 창도 엽니다. 이미 실행 중인 편집기를 사용하려면 session list로 찾으세요. 반환된 세션 ID를 OPENSHOT_SESSION에 설정한 후 프로젝트를 열거나 검사합니다:
openshot-cli project open "/home/me/Videos/My Project.osp"
openshot-cli project get
예시 경로를 자신의 경로로 바꾸고 공백이 포함된 경로는 따옴표로 감싸세요. project open은 선택된 세션의 현재 프로젝트를 대체합니다. 명시적으로 --discard를 추가하지 않으면 저장되지 않은 편집을 버리지 않습니다; 유지하려면 먼저 편집을 저장하세요. CLI를 통한 열기는 대화형 누락 미디어 대화상자를 표시하지 않으므로 프로젝트의 원본 미디어를 유지하세요.
새 빈 프로젝트의 경우 --project 없이 session start를 사용한 후, 편집 섹션에 설명된 대로 미디어를 가져오고 클립을 추가하세요.
프로젝트 또는 복사본 저장
새 파일로 저장하거나 변경하기 전에 별도의 버전을 만드세요:
openshot-cli project save "/home/me/Videos/My Project v2.osp"
기존 파일을 업데이트하려면 명시적으로 교체를 허용하세요:
openshot-cli project save "/home/me/Videos/My Project v2.osp" --overwrite
항상 대상 경로를 지정하세요. .osp 저장은 모든 원본 영상을 해당 파일에 패키징하지 않습니다; 프로젝트를 이동하거나 다시 열 때 참조된 미디어를 유지하세요.
비디오 내보내기
스크립트나 AI 에이전트에서 프로젝트 설정을 사용하거나 각 렌더링마다 다른 출력 프로필을 선택하여 렌더링 및 내보내기를 자동화하세요. 내보내기 작업은 백그라운드에서 실행하거나 완료될 때까지 대기할 수 있습니다. 프로젝트의 해상도와 프레임 속도를 사용하여 MP4를 렌더링하려면:
openshot-cli export start "/home/me/Videos/video.mp4" --wait
기본적으로 OpenShot은 H.264 비디오와 AAC 오디오를 사용합니다. 예시 경로를 기존 폴더와 새 파일 이름을 사용하여 대상 경로로 바꾸세요. 기존 출력 파일은 절대 덮어쓰지 않습니다. 내보내기는 편집 가능한 .osp 프로젝트를 저장하지 않습니다; 편집 작업을 유지하려면 별도로 project save를 사용하세요.
--wait 옵션은 내보내기가 완료되거나 실패를 보고할 때까지 명령을 계속 실행합니다. 공유하기 전에 완성된 비디오를 검토하세요.
내보내기 진행 상황 확인
백그라운드에서 내보내기를 시작하려면 --wait를 빼세요. 응답에는 진행 상황을 확인할 수 있는 작업 ID가 포함됩니다:
openshot-cli export start "/home/me/Videos/video.mp4"
openshot-cli export status JOB_ID
openshot-cli export status JOB_ID --wait
openshot-cli export list
JOB_ID를 반환된 ID로 바꾸세요. 대기 시간이 초과되면 내보내기는 계속 실행됩니다; 다른 내보내기를 시작하지 말고 동일한 작업을 확인하세요. 작업을 중지하려면 export cancel JOB_ID를 사용하세요. 각 작업은 시작 시 타임라인을 캡처하므로 이후 편집은 이미 진행 중인 내보내기에 영향을 주지 않습니다.
대기 시간 기본값은 600초이며, --wait-timeout으로 조정할 수 있습니다. 이는 전역 요청별 --timeout과 별개입니다. 내보내기 실패, 취소 및 대기 시간 초과 시 상태 1로 종료하며 작업 세부 정보를 포함합니다.
여러 프로필로 내보내기
각 출력에 대해 내보내기 프로필을 선택하여 동일한 타임라인을 다른 해상도나 종횡비로 내보내세요. 내보내기 프로필은 해당 작업에만 적용되며 편집 프로젝트의 프로필을 변경하지 않습니다. 프로필은 크기, 프레임 속도 및 종횡비를 설정하며, 내보내기 프리셋은 MP4/H.264와 같은 인코딩 설정을 선택합니다.
사용 가능한 프로필을 찾고 설정을 확인하세요:
openshot-cli profile list --search 720
openshot-cli profile list --search 1080
openshot-cli profile get builtin:01280x0720p0030_16-09
예를 들어, 720p 및 1080p의 가로형 버전을 내보내고, 1080x1080의 정사각형 버전을 내보내세요. 이 프로필들은 모두 30fps를 사용합니다:
openshot-cli export start "/home/me/Videos/video-720p.mp4" --profile builtin:01280x0720p0030_16-09 --wait
openshot-cli export start "/home/me/Videos/video-1080p.mp4" --profile builtin:01920x1080p0030_16-09 --wait
openshot-cli export start "/home/me/Videos/video-square.mp4" --profile builtin:01080x1080p0030_01-01 --wait
각 버전에 대해 다른 출력 파일 이름을 사용하세요. 일치하는 버전을 원할 때 작업 간 편집을 변경하지 마세요. 종횡비 변경은 구도를 바꿀 수 있으므로 각 출력을 검토하세요, 특히 제목과 애니메이션 대상. 별도로 구성된 정사각형 또는 세로형 버전은 프로젝트 복사본을 저장하고, 프로젝트 프로필을 변경한 후 클립을 조정하고 내보내세요. 사용자 정의 프로필 및 인코딩 옵션은 아래 프로필 및 내보내기 설정을 참조하세요.
여러 프로젝트 일괄 내보내기
헤드리스 세션 하나를 재사용하여 여러 저장된 프로젝트를 순차적으로 렌더링하세요. 프로젝트를 열고 --wait와 함께 내보낸 다음 다음 프로젝트를 엽니다. 아래 예시는 각 프로젝트의 해상도와 프레임 속도를 사용하며 .osp 파일 옆에 MP4 파일을 생성합니다. 모든 프로젝트에 하나의 출력 프로필을 사용하려면 내보내기 명령에 --profile PROFILE_ID를 추가하세요.
먼저 위의 자동 세션-ID 예제를 같은 터미널에서 성공적으로 실행하세요. 이 예제는 openshot 을 정의하고 새 세션을 선택합니다. 아래 프로젝트 경로를 자신의 경로로 바꾸세요. 이미 존재하지 않는 고유한 출력 이름을 사용하세요; 예제는 배치를 시작하기 전에 모든 대상지를 확인합니다.
Windows PowerShell:
$projects = @(
"C:\VideoProjects\First.osp",
"C:\VideoProjects\Second.osp"
)
foreach ($project in $projects) {
if (-not (Test-Path -LiteralPath $project -PathType Leaf)) {
throw "Project not found: $project"
}
$output = [System.IO.Path]::ChangeExtension($project, ".mp4")
if (Test-Path -LiteralPath $output) { throw "Output already exists: $output" }
}
foreach ($project in $projects) {
$output = [System.IO.Path]::ChangeExtension($project, ".mp4")
& $openshot --cli project open $project
if ($LASTEXITCODE -ne 0) { throw "Could not open: $project" }
& $openshot --cli export start $output --wait --wait-timeout 86400
if ($LASTEXITCODE -ne 0) { throw "Export needs attention: $output" }
}
& $openshot --cli session stop
if ($LASTEXITCODE -ne 0) { throw "Could not stop the session" }
Remove-Item Env:OPENSHOT_SESSION
Linux Bash (괄호는 오류 처리를 배치 내에서만 국한시킵니다):
(
set -e
: "${OPENSHOT_SESSION:?Run the session startup example first}"
projects=(
"/home/me/VideoProjects/First.osp"
"/home/me/VideoProjects/Second.osp"
)
for project in "${projects[@]}"; do
test -f "$project" || { echo "Project not found: $project" >&2; exit 1; }
output="${project%.osp}.mp4"
test ! -e "$output" || { echo "Output already exists: $output" >&2; exit 1; }
done
for project in "${projects[@]}"; do
"$openshot" --cli project open "$project"
"$openshot" --cli export start "${project%.osp}.mp4" --wait --wait-timeout 86400
done
"$openshot" --cli session stop
) && unset OPENSHOT_SESSION
두 방법 모두 명령 실패 시 배치를 중단하고 세션을 검사할 수 있도록 남겨둡니다. 여기서 대기 제한은 내보내기당 24시간입니다. 대기 시간 초과 시 렌더링은 계속 실행됩니다: 재시도 전에 export list 와 export status JOB_ID --wait 를 사용하세요. 완료된 비디오는 디스크에 남아 있습니다; 재개하기 전에 완료된 프로젝트를 배치에서 제거하세요. 실패를 해결한 후에는 세션을 중지하고 환경 변수를 지우세요.
프리셋 및 인코딩 설정 선택
설치된 내보내기 프리셋과 지원되는 설정을 확인하세요:
openshot-cli export preset list
openshot-cli export preset get builtin:format_mp4_x264
openshot-cli export capabilities
openshot-cli export start /tmp/reel.mp4 --preset builtin:format_mp4_x264 --quality med --wait
Export 는 선택적 --create-custom 과 함께 --from-file FILE_ID 도 허용합니다. 설정은 다음 순서로 적용됩니다: 프로젝트 기본값, 프리셋, 고급 JSON, 명시적 프로필/품질/범위 플래그. 고급 JSON은 비디오/오디오 코덱과 비트레이트, 오디오 레이아웃/샘플링률/채널, 네이티브 코덱 옵션, 하드웨어 장치 설정, 스레드 수를 노출합니다.
예를 들어, 고급 JSON을 통해 인코더 옵션을 선택하세요:
openshot-cli export start /tmp/small.mp4 --profile builtin:00640x0360p0030_16-09 --json '{"video_options":{"preset":"fast"}}' --wait
내보내기 설정 검증
렌더링 시작 전에 설정을 확인하세요:
openshot-cli export validate /tmp/reel.mp4 --preset builtin:format_mp4_x264
기능 보고서는 컴파일된 코덱 가용성을 나타내며, 물리적 GPU 가용성을 나타내지 않습니다. 검증은 더 나아가서, 별도의 프로세스에서 파일을 쓰지 않고 정확한 설정으로 인코더(하드웨어 인코더 포함)와 컨테이너를 엽니다. 컨테이너가 지원하지 않는 조합은 incompatible_export 오류와 FFmpeg의 설명, 변경할 설정(details.cause.path)과 함께 실패합니다:
openshot-cli export validate /tmp/song.mp3 --json '{"mode":"audio","format":"mp3","audio_codec":"aac"}'
내보내기 작업자는 렌더링 전에 동일한 검사를 수행합니다.
프레임 범위 렌더링
타임라인의 일부를 렌더링하려면 --start-frame 과 --end-frame 을 사용하세요. 범위는 포함 범위이며 내보내기 프로필의 FPS 기준으로 1부터 시작합니다. 예를 들어, 30fps에서 처음 90프레임(3초)을 렌더링합니다:
openshot-cli export start /tmp/excerpt.mp4 --profile builtin:01280x0720p0030_16-09 --start-frame 1 --end-frame 90 --wait
오디오 전용 내보내기 및 이미지 시퀀스
고급 JSON으로 출력 모드를 선택하세요:
openshot-cli export start /tmp/music.wav --json '{"mode":"audio","format":"wav","audio_codec":"pcm_s16le"}' --wait
openshot-cli export start /tmp/frames --json '{"mode":"image_sequence","format":"png"}' --end-frame 3 --wait
이미지 시퀀스는 새 출력 디렉터리가 필요합니다. 기존 출력은 절대 덮어쓰지 않습니다.
편집
클립 및 효과 추가
import/add/list 에서 반환된 ID를 사용하고, project get 으로 레이어 번호를 확인하세요:
openshot-cli file import /absolute/path/video.mp4
openshot-cli clip add FILE_ID --layer 2000000 --position 3 --start 10 --end 17 --volume 0
openshot-cli clip set CLIP_ID --json '{"volume":0.5}'
openshot-cli clip keyframe set CLIP_ID --property volume --frame 301 --value 0
openshot-cli clip keyframe set CLIP_ID --property volume --frame 331 --value 1
openshot-cli effects add CLIP_ID saturation
openshot-cli effects set EFFECT_ID --json '{"saturation":1.2}'
openshot-cli project save /absolute/path/edit.osp
가능하면 프로젝트 프로필을 일찍 선택하세요; 이미 내용이 있는 프로젝트는 기존 FPS 변환 및 실행 취소 시스템을 통해 프로필 변경도 지원합니다. 클립 생성 시 --audio-only 는 비디오를 억제하며, 음악 파일에 포함된 커버 아트도 포함됩니다. 대신 해당 클립을 오디오 시각화에 사용하려면 비디오와 오디오를 활성화하고, 효과 도움말을 참고하여 투명 오버레이와 레이어 배치를 설정하세요.
클립 타이밍 이해하기
예제 키프레임은 30fps 프로젝트와 소스 10초에서 트리밍된 클립을 가정합니다. 위치는 타임라인 초 단위이며, 시작/끝은 소스 초 단위이고 끝은 제외입니다. 프레임은 1부터 시작합니다. 파일 썸네일 프레임은 소스 FPS를 사용합니다. 타임라인 프레임은 프로젝트 FPS를 사용합니다. 클립 키프레임은 프로젝트 FPS 기준 소스 좌표를 사용하므로, 클립을 트리밍해도 첫 번째 보이는 키프레임이 프레임 1로 이동하지 않습니다.
속성 변경
set 은 최상위 속성을 병합합니다. 스칼라는 키프레임 속성을 상수로 변환합니다. 제공된 중첩 곡선은 해당 곡선을 대체하며, 한 점만 변경하려면 keyframe set 을 사용하세요. JSON 인수는 인라인 JSON, @file.json 또는 표준 입력용 - 을 허용합니다. 속성 이름, 유형, 열거형, 키프레임, 참조 및 타이밍은 프로젝트 편집 전에 검증됩니다. 오류는 필드, 예상 값, 받은 값 및 가능한 수정 사항을 식별합니다. 엔진이 범위를 초과하는 값을 지원하는 경우 GUI 슬라이더 범위는 참고용입니다.
페이드 추가
clip fade ID --in 0.5 --out 0.5 는 소스 트림 키프레임 좌표를 자동으로 계산합니다. 알파 곡선을 대체하며, --property volume --value 0.25 는 대신 0.25 최대 게인의 오디오 페이드를 생성합니다. 지속 시간은 첫 번째와 마지막 보이는 프레임 사이에 맞아야 하며, 페이드 아웃은 마지막 프레임에서 0에 도달합니다.
클립 분할
clip split ID --at 6.5 는 타임라인 초를 사용하며, 가장 가까운 프로젝트 프레임에 스냅하고 양쪽 절반을 유지합니다. 소스 좌표 곡선을 유지하고 오른쪽 절반에 새 ID로 효과를 복제하며, 편집기의 분할 동작을 따릅니다. 왼쪽 절반은 ID를 유지합니다. 응답은 요청된/실제 분할 시간과 두 요약을 보고하며, 명명된 배치 결과는 {"$ref":"cut.right.id"} 를 지원합니다. 분할은 끝점과 잠긴 트랙을 거부합니다. 실행 취소는 한 번의 트랜잭션으로 원본 클립을 복원합니다.
텍스트 추가 및 스타일 지정
text add 는 텍스트를 생성하여 클립으로 배치하며, 편집기의 텍스트 도구와 동일한 텍스트를 사용합니다. 생략한 옵션은 편집기의 기본 스타일을 사용합니다:
openshot-cli text add --text "Opening Night" --layer 5000000 --position 2 --duration 4 \
--place lower-third --font "Noto Sans" --size 72 --bold --color "#ffffff" \
--background "#80000000" --background-padding 16 --background-corner 12
openshot-cli text get CLIP_ID
openshot-cli text set CLIP_ID --stroke black --stroke-width 3
openshot-cli text set CLIP_ID --text $'Two\nlines' --line-spacing 1.4
openshot-cli text fonts --search noto
openshot-cli text list --search opening
단어, 글꼴, 크기, 정렬, 박스 너비 및 기본 색상은 프로젝트 파일 내 텍스트에 속하며 편집기와 마찬가지로 이를 사용하는 모든 클립에서 공유됩니다. 한 클립에서 text set 을 하면 모두 변경되고 changed_clip_ids 에 나열됩니다; --this-clip-only 는 해당 클립에 먼저 자체 복사본을 제공합니다. clip add FILE_ID 는 text list 에서 텍스트의 다른 클립을 배치합니다. 크기는 프로젝트 해상도의 픽셀 단위이며, 색상은 #RRGGBB, #AARRGGBB (알파 포함), CSS 이름 또는 transparent 입니다. --place 는 박스를 중앙, 가장자리 또는 모서리, 또는 하단 3분의 1 위치에 배치합니다. --line-spacing 은 줄 간격의 배수이며 (1이 기본), --background-corner 는 배경과 테두리 모서리를 해당 픽셀 수만큼 둥글게 만듭니다.
텍스트 클립은 일반 클립입니다. 위치, 크기, 회전, 불투명도, 타이밍, 페이드, 모션 프리셋 및 효과는 모두 일반 clip 명령을 사용합니다. 글꼴 크기, 패딩, 박스 너비, 글자 및 줄 간격은 텍스트 박스 크기를 설정하므로 키프레임을 지정할 수 없습니다; 텍스트 크기를 애니메이션하려면 클립의 크기에 키프레임을 지정하세요. 각 클립은 다른 속성과 동일한 키프레임 명령으로 자체 텍스트 색상, 외곽선 및 테두리 너비를 애니메이션할 수 있습니다:
openshot-cli clip keyframe list CLIP_ID
openshot-cli clip keyframe set CLIP_ID --property text_color.alpha --space clip --unit seconds --at 0 --value 0
openshot-cli clip keyframe set CLIP_ID --property text_color.alpha --space clip --unit seconds --at 1 --value 255
애니메이션 가능한 속성은 text_color, text_background, text_stroke 및 text_border (색상, .red, .green, .blue, .alpha 0~255 포함), 그리고 text_stroke_width, text_border_width, text_background_corner 입니다. 클립 자체 애니메이션이 공유 스타일보다 우선하며, text get 은 클립이 애니메이션하는 스타일을 나열합니다. text reset CLIP_ID 는 클립을 기본 스타일로 되돌리며, 텍스트 → 스타일 초기화 와 같습니다; --keyframes-only 는 클립 자체 애니메이션만 제거합니다. 여러 텍스트를 한 번에 스타일링하려면 {"text":true} 로 선택하세요:
openshot-cli edit bulk --select '{"text":true}' --json '[{"method":"text.set","params":{"font_family":"Noto Sans","stroke_width":2}}]'
일괄 편집 적용
edit apply --json @edits.json --expect-revision 12 는 최대 256개의 순서 있는 변경 명령을 받아들이며, clip.set 및 effects.add 와 같은 점(.)으로 구분된 명령 이름을 사용합니다 (이전 effect.add 철자도 작동합니다):
[
{"method":"project.profile.set","params":{"id":"builtin:01280x0720p0024_16-09"}},
{"method":"file.import","as":"media","params":{"path":"/tmp/video.mp4"}},
{"method":"clip.add","as":"shot","params":{"file_id":{"$ref":"media.id"},"layer":1000000,"start":10,"end":15}},
{"method":"clip.fade","params":{"id":{"$ref":"shot.id"},"fade_in":0.5,"fade_out":0.5}}
]
선택적 as 는 동일 배치 내 후속 명령을 위해 결과를 바인딩합니다. {"$ref":"shot.id"} 객체는 해당 결과의 필드를 대체합니다. 참조는 이전 이름만 해결하며, 오타, 미래 참조, 중복 이름은 라이브 업데이트 전에 실패합니다. 응답에는 순서 있는 간결한 결과와 실제 ID의 refs 맵이 포함됩니다. 성공한 배치의 모든 변경 사항은 하나의 실행 취소/재실행 단계가 됩니다. project.profile.set 은 채워진 타임라인도 지원합니다. 열기, 저장, 내보내기 및 검사 명령은 편집 배치 외부에 유지됩니다. 각 명령의 도움말에는 쉘 플래그의 밑줄 표기법을 포함한 JSON 매개변수 이름이 나열됩니다 (예: --fps-num 은 fps_num 으로 변환).
배치 검증 및 오류 처리
편집 배치의 모든 명령은 라이브 업데이트 전에 분리된 프로젝트에서 사전 검사됩니다. 잘못된 입력은 라이브 프로젝트와 리비전을 변경하지 않습니다. 유효한 배치는 하나의 실행 취소 그룹을 형성합니다. 예상치 못한 런타임 실패도 부분 변경을 일으킬 수 있으며, 오류는 완료된 작업을 보고합니다. 타임아웃은 취소를 의미하지 않으므로 변경을 다시 시도하기 전에 상태를 확인하세요.
정밀 키프레임 편집
clip, transition, effects 는 keyframe list, set, remove, clear, transform, copy, paste 를 지원합니다. 속성 경로는 크로마 키 효과의 color.red 와 같은 중첩 곡선을 지정할 수 있습니다. 중첩 곡선 편집은 형제 채널을 보존합니다. 속성 없이 keyframe list ID 를 실행하여 곡선 경로와 점 수를 확인하세요. 발견 및 점 목록에는 트림/위치 타이밍 컨텍스트가 포함되며, 점 목록은 네이티브 프레임 좌표도 보고합니다. get 과 properties 는 완전한 네이티브 객체 및 속성 메타데이터를 노출합니다. 오류는 잘못된 필드를 식별하고, 유사한 속성 이름을 제안하며, 좌표 수정 방법을 설명합니다.
--space native|clip|timeline 와 --unit frames|seconds 로 좌표를 명확히 선택하세요. 모든 프레임은 프로젝트 FPS를 사용하며 1부터 시작합니다; 초는 0부터 시작하며 가장 가까운 프레임에 맞춰집니다. Native 는 기존 엔진 키프레임 좌표(소스 트림 포함)입니다. 클립 좌표는 보이는 클립 인포인트에서 시작하며, 타임라인 좌표는 프로젝트 시간 0에서 시작합니다. 첨부된 효과는 부모 클립의 타이밍을 사용합니다. 이 좌표들은 애니메이션 시간을 나타내며, 시간 재매핑 곡선으로 선택된 미디어 프레임이 아닙니다.
30fps 프로젝트에서 5초에 위치하고 2초에 트리밍된 클립의 경우, 클립 프레임 1, 타임라인 프레임 151, 네이티브 프레임 61이 동일한 지점을 가리킵니다. 위치와 트림은 프로젝트 프레임 그리드에 독립적으로 스냅됩니다. 전체 곡선을 나열하면 음수 또는 0인 클립/타임라인 좌표를 가진 숨겨진 점도 포함될 수 있습니다. 이전 --frame 옵션은 여전히 네이티브 프레임을 의미하며 --at과 함께 사용할 수 없습니다.
예시:
openshot-cli clip keyframe set CLIP --property location_x --space clip --unit seconds --at 0 --value -1
openshot-cli clip keyframe set CLIP --property location_x --space clip --unit seconds --at 1 --value 0 --interpolation bezier --handles '{"handle_left":{"X":0.2,"Y":0.9}}'
openshot-cli effects keyframe set EFFECT --property color.red --space clip --at 31 --value 200
openshot-cli clip keyframe list CLIP --property location_x --space clip --unit seconds
openshot-cli clip keyframe transform CLIP --property location_x --space clip --start 1 --end 31 --scale 2 --offset 15
openshot-cli clip keyframe copy TARGET --property location_x --source-id SOURCE --space clip --start 1 --end 31 --at 1 --mode merge
openshot-cli clip keyframe remove CLIP --property location_x --space clip --at 31
openshot-cli clip keyframe clear CLIP --property location_x --value 0
보간, 이징 및 미리보기
보간은 목적지 점으로의 구간을 설명합니다. 선형은 점들 사이에 일정한 속도를 제공합니다. 상수는 목적지까지 이전 값을 유지하다가 갑자기 변경됩니다. 기본 네이티브 베지어는 각 구간 양 끝에서 이징을 처리합니다. 중간 점을 추가하면 의도치 않은 속도 저하가 발생할 수 있으므로, 하나의 이징된 움직임은 두 끝점으로 시작하는 것이 좋습니다. 일반적으로 핸들은 그대로 두고 특정 스타일을 위한 이름 있는 프리셋을 선택하세요.
세션 없이 편집기 메뉴에서 사용하는 동일한 이징 프리셋을 확인하세요:
openshot-cli clip keyframe presets
목적지를 설정하여 들어오는 구간에 프리셋을 적용하세요:
openshot-cli clip keyframe set CLIP --property scale_x --space clip --unit seconds --at 0 --value 1
openshot-cli clip keyframe set CLIP --property scale_x --space clip --unit seconds --at 4 --value 1.2 --easing ease-in-out
이징 옵션은 베지어를 의미합니다. 이전 점의 나가는 핸들과 목적지 점의 들어오는 핸들을 함께 설정하며, 다른 핸들과 점 값은 유지됩니다. 이전 점이 반드시 존재해야 합니다. 사용자 지정 핸들이나 다른 보간과 함께 사용하지 마세요. 프리셋은 배치 및 대량 템플릿에서 작동합니다. GUI 프리셋 ease(“Ease (Default)”)는 기본 베지어 보간에 사용되는 네이티브 핸들과 다릅니다. 백 프리셋은 끝점 값을 초과할 수 있습니다.
네이티브 곡선 평가기를 사용하여 렌더링 전에 모션을 검사하세요:
openshot-cli clip keyframe preview CLIP --property scale_x --space clip --unit seconds --start 0 --end 4
openshot-cli clip keyframe preview CLIP --property scale_x --space clip --unit seconds --at 2
미리보기는 읽기 전용이며 효과와 전환에 동일하게 작동합니다. 즉시 인접한 프레임에서 계산된 속성 단위 초당 값과 부호가 있는 들어오는 속도/나가는 속도를 반환합니다. 이는 해석적 미분이 아닌 유한 차분입니다. 네이티브 프레임 1에서는 들어오는 속도가 0입니다. 인접 프레임 속도는 요청된 범위 밖도 검사할 수 있습니다. 내부 점 주변의 거의 0에 가까운 속도는 일시 정지를 나타내며, 다른 속도는 속도 변화를 나타냅니다. 상수 보간은 목적지에서 점프를 나타냅니다.
범위가 없으면 미리보기는 곡선의 첫 번째와 마지막 점을 포함합니다. 범위는 포함 범위이며 기본적으로 17개의 균등 간격 샘플을 사용합니다(–count: 2–256). 범위 내의 키프레임과 인접한 점도 포함되어 적은 샘플 수가 키프레임 정지를 숨기지 않습니다. 최대 샘플 수는 1024이며, 더 큰 요청은 더 좁은 범위를 필요로 합니다. –at는 한 프레임을 샘플링합니다. 미리보기는 요청된 공간 좌표와 실제 네이티브 프레임을 보고하며, 초 단위는 편집 시처럼 프로젝트 프레임에 스냅됩니다.
고급 사용자 지정 핸들의 경우 X와 Y 모두 구간에 정규화됩니다: X는 프레임 범위의 일부이고, Y는 값 변화의 일부입니다. 첫 번째 제어점은 이전 점의 handle_right에서, 두 번째는 목적지의 handle_left에서 옵니다. 기본 네이티브 값은 right=(0.5, 0), left=(0.5, 1)이며 평평한 끝점 접선을 가집니다. handle_type만 변경해도 주변 점을 통한 연속 접선이 재계산되지 않습니다. 점을 이동할 때 기존 핸들은 유지됩니다.
키프레임 범위는 클립 선택 시간 범위와 달리 포함 범위입니다. 목록은 요청된 좌표 공간/단위를 사용하는 co.X 값을 가진 points를 출력합니다. 해당 배열을 동일한 공간/단위로 keyframe paste --json @points.json에 전달하고 --mode merge``(일치하는 프레임 교체, 나머지 유지) 또는 ``--mode replace``(전체 곡선 교체)를 선택하세요. ``copy는 동일한 객체 종류의 소스와 선택적 --source-property를 받아들이며, 첫 번째 선택된 소스 점을 대상의 --at 위치에 고정합니다. 다른 곡선과 소스 객체는 변경되지 않습니다.
transform은 첫 번째 선택된 점 또는 --pivot을 중심으로 양의 시간 배율을 적용하며, 선택한 단위로 부호가 있는 --offset이 뒤따릅니다. 중복 좌표를 생성하는 프레임 스냅은 선택 범위 밖 점과의 충돌을 포함하여 거부됩니다. 네이티브 좌표는 최소 1 이상이어야 합니다. 네이티브 정규화 베지어 핸들과 보간은 각 점과 함께 이동하며, 핸들은 절대 프레임 좌표가 아닙니다. set --handles는 제공된 핸들만 변경합니다. 보간은 목적지 점에 속합니다.
clear는 네이티브 프레임 1에서 일정한 기준점을 유지합니다: --value를 지정하거나 --at(기본값 네이티브 프레임 1)으로 기존 곡선을 샘플링하세요. 마지막 점을 제거해도 일정한 기준점이 유지되어 이후 키프레임 추가가 유효합니다.
여러 클립 선택 및 편집
프로젝트를 변경하지 않고 배치를 검증하려면 edit apply --dry-run을 사용하세요. 선택한 각 클립에 대해 작은 명령 템플릿을 반복하고 모든 변경 사항을 하나의 실행 취소 단계로 그룹화하려면 edit bulk를 사용하세요.
먼저 선택 항목을 미리보기:
openshot-cli edit select --json '{"layer":1000000,"start":5,"end":20,"effect":"Saturation"}'
선택기는 ids (고유 클립 ID 배열), layer, start/end (타임라인 초), file_id, effect (클래스 이름 또는 별칭), 그리고 text (true는 텍스트 클립 선택)를 지원합니다. 필터는 AND로 결합됩니다. 시간 범위는 [start, end)와 겹치는 클립을 선택하며, 클립을 자르지 않습니다. 결과는 위치, 레이어, ID 순으로 정렬되며 ID, 요약, 잠금 상태, 현재 리비전을 포함합니다. 알 수 없는 ID는 오류입니다. 빈 선택기는 거부되며, 모든 클립에 대해 명시적으로 {"all":true}를 사용해야 합니다. 선택은 256개 클립으로 제한되며 조용히 잘리지 않습니다.
예를 들어, 이 배열을 templates.json 으로 저장하세요:
[
{"method":"clip.adjust","params":{"values":{"position":{"add":2},"volume":{"multiply":0.5}}}},
{"method":"effects.add","as":"look","params":{"type":"Saturation"}},
{"method":"effects.keyframe.set","params":{"id":{"$ref":"look.id"},"property":"saturation","space":"clip","at":1,"value":0}},
{"method":"effects.keyframe.set","params":{"id":{"$ref":"look.id"},"property":"saturation","space":"clip","at":31,"value":1.2}}
]
이를 검증한 후 선택에서 반환된 리비전에 적용하세요:
openshot-cli edit bulk --select '{"ids":["CLIP_A","CLIP_B"]}' --json @templates.json --dry-run
openshot-cli edit bulk --select '{"ids":["CLIP_A","CLIP_B"]}' --json @templates.json --expect-revision 42
기존 클립 명령은 id를 상속하며, effects.add는 clip_id를 상속합니다. 템플릿에서는 이러한 대상 매개변수를 생략하세요. 효과 편집은 이전에 명명된 결과를 참조해야 합니다. 이름은 각 선택된 클립에 국한되므로 look.id는 각 클립마다 다른 효과를 가리킵니다. 명시적 ID로 기존 효과 인스턴스를 변경하려면 계속해서 edit apply를 사용하세요. 선택된 ID 집합은 확장 전에 고정되며, 위치나 효과 변경은 나머지 대상에 영향을 주지 않습니다.
clip set은 절대 속성을 적용하며, clip adjust는 숫자 속성이나 곡선의 모든 값에 대해 multiply 후 add를 적용하여 점 타이밍, 보간, 정규화된 핸들을 유지합니다. 결과 값은 0 이상의 위치와 볼륨을 포함해 검증됩니다. 구조 필드는 보호됩니다.
대량 작업은 빈 선택, 잠긴 대상 트랙, 256개 초과 확장 명령을 거부합니다. 모든 확장 작업은 라이브 편집 전에 분리된 사전 점검을 통과합니다. 드라이 런은 생성된 ID를 예약하지 않습니다. --expect-revision을 사용해 오래된 선택을 거부하세요. 성공한 배치는 저장/재열기 후에도 하나의 실행 취소 단계입니다. GUI 새로 고침은 일괄 처리됩니다. 예기치 않은 런타임/리스너 오류가 부분 트랜잭션을 남길 수 있으며, 오류는 완료된 작업을 보고하고 실행 취소는 해당 그룹을 되돌립니다 (edit apply와 동일).
프로필
프로필을 발견하고 ID를 추측하지 않고 가져온 비디오와 일치시키기:
openshot-cli profile list --search 720
openshot-cli profile get builtin:01280x0720p0024_16-09
openshot-cli profile match --file FILE_ID
openshot-cli project profile get
openshot-cli project profile set --from-file FILE_ID
openshot-cli project profile set builtin:01280x0720p0024_16-09
openshot-cli project profile set --json '{"width":640,"height":352,"display_ratio":{"num":20,"den":11},"fps":{"num":24000,"den":1001}}'
카탈로그 항목에는 안정적인 ID, 설명, 크기, 유리수 FPS, 종횡비, 스캔 설정이 포함됩니다. 목록/검색은 페이지로 구분됩니다. 소스 매칭은 정확한 ID와 명확한 차이가 있는 순위별 대안을 반환합니다. 파일에서 설정할 때 --create-custom이 지정되지 않으면 정확한 일치가 필요하며, 근접한 프로필을 조용히 선택하지 않습니다. 정지 이미지 및 오디오 전용 소스는 비디오 프로필을 정의할 수 없습니다. 매칭은 선언된 소스 FPS를 사용합니다.
사용자 설정은 유리수 비율을 포함하여 저장된 프로젝트에 내장되어 있어, 다시 열 때 별도의 프로필 파일 설치가 필요 없습니다. 프로젝트 프로필 변경은 기존 프레임 속도 변환과 하나의 실행 취소 트랜잭션을 사용합니다. 실행 취소/다시 실행은 반올림에 민감한 위치를 포함해 클립 타이밍과 키프레임을 복원합니다. 내보내기는 프로젝트를 변경하지 않고 독립적으로 프로필을 선택할 수 있습니다.
저장된 실행 취소 기록은 편집기의 기록 제한 설정을 따릅니다. 제한은 소프트 작업 예산으로, 유지되는 트랜잭션에 속한 모든 기록이 보존되어 저장 시 큰 배치를 부분 실행 취소 작업으로 자르지 않습니다. 0은 저장된 기록을 비활성화합니다. 별도의 256명령 배치 요청 제한은 여전히 적용됩니다.
미디어 및 타임라인 검사
클립 타이밍과 트랙 레이아웃을 텍스트 또는 JSON으로 검사하거나, 내보내기 전에 구성과 구도를 검토하기 위해 이미지를 렌더링하세요.
타임라인 요약
빠른 개요를 위해 텍스트 뷰를 사용하거나 스크립트 및 에이전트를 위해 구조화된 JSON을 사용하세요:
openshot-cli timeline view --start 5 --end 12
openshot-cli timeline view --start 5 --end 12 --format json
openshot-cli timeline overview --start 5 --end 12
timeline view는 사용된 트랙, 객체 ID, 타임라인/소스 구간, 스트림 상태, 게인, 간격/중첩을 포함한 간결한 텍스트를 기본으로 합니다. 세부 사항 선택에는 --detail summary|clips|full, 구조화된 컨텍스트에는 --format json, 결과 집중에는 --start/--end, --layer, 페이지 매김을 사용하세요.
timeline overview는 이미지 바이트 없이 간결한 구조화된 컨텍스트를 제공합니다: 정렬된 ID, 트랙별 순서, 타임라인/소스 구간, 보이는 트림 범위, 프레임 좌표, 오디오/비디오 상태, 효과, 인접 간격 또는 중첩. 구간과 프레임 범위는 끝 제외이며, 프레임 번호는 1부터 시작합니다. 소스 프레임은 소스 FPS를 사용하고, 타임라인 및 키프레임 좌표는 프로젝트 FPS를 사용합니다. 집중에는 --layer와 --start/--end, 페이지 매김에는 --limit/--offset (기본 100, 최대 500개 항목)을 사용하세요. 시간 재매핑된 클립은 추론된 소스 매핑을 명시적으로 보류합니다. 반환된 리비전은 edit apply --expect-revision과 함께 사용하세요.
프레임 미리보기 및 콘택트 시트
thumbnail으로 단일 프레임을 렌더링하거나 strip으로 범위를 샘플링하세요. 효과와 레이어드 클립을 포함한 합성 비디오를 검사하려면 file로 소스 미디어를, timeline으로 검사하세요:
openshot-cli file thumbnail FILE_ID --frame 301 --output /tmp/source.png
openshot-cli file strip FILE_ID --start 10 --end 20 --count 12 --output /tmp/source-strip.png
openshot-cli timeline thumbnail --frame 91 --output /tmp/timeline-frame.png
openshot-cli timeline strip --start 0 --end 20 --count 12 --output /tmp/timeline-strip.png
프레임 이미지는 기본 320x180 픽셀이며, 콘택트 시트는 타일당 기본 160x90 픽셀과 타임코드 레이블을 포함합니다. 출력 픽셀 선택에는 --width와 --height를 사용하세요. 응답에는 정확한 샘플/프레임 메타데이터가 포함됩니다. 콘택트 시트는 시퀀스 전체의 구성을 검토하는 데 도움이 되며, 키프레임 미리보기와 렌더링된 비디오로 샘플 간 움직임을 평가하세요.
타임라인 이미지
편집기의 눈금자, 썸네일, 효과, 전환 및 파형을 포함한 트랙 레이아웃을 캡처합니다:
openshot-cli timeline view --start 0 --end 20 --pixels-per-second 80 --output /tmp/tracks.png
--output 을 지정하면 이미지 형식을 선택하며, --format image 도 명시적으로 선택합니다. 캡처는 편집기의 뷰포트나 프로젝트를 변경하지 않습니다. 응답에는 클립 ID와 타이밍, 픽셀 경계가 포함됩니다.
이미지는 기본적으로 너비 1280 픽셀이며, 높이는 사용된 트랙에 맞게 조정됩니다. 레이아웃 조정을 위해 --width, --height, 또는 --all-tracks 를 사용하고, 트랙과 레이블 조정을 위해 --track-size 또는 --track-label-width 를 사용하세요. 시작/종료 범위가 줌을 결정하며, --pixels-per-second 는 시간 범위에서 너비를 계산합니다.
오디오 파형 보기
타임라인에서 오디오 엔벨로프를 검사하려면 --mode waveforms 를 선택하세요:
openshot-cli timeline view --start 5 --end 12 --mode waveforms --output /tmp/waves.png
--mode auto 는 기존 캐시된 파형 표시를 사용하며, --mode thumbnails 는 대신 썸네일을 표시합니다. 파형은 오디오 효과나 믹싱 전에 클립 볼륨과 타이밍 조정을 포함한 소스 피크/RMS 레벨을 나타냅니다.
캐시되지 않은 파형 추출은 전체 소스를 디코딩하며, 소스당 600초, 요청당 1200 소스-초로 제한됩니다. 표시 범위를 좁혀도 디코딩 작업이 줄어들지 않습니다. 더 긴 소스는 먼저 편집기에서 파형을 생성하거나 썸네일 모드를 사용하세요. 이후 요청은 캐시된 파형을 재사용할 수 있습니다.
이미지 출력 및 제한
이미지 경로는 기존 디렉터리에 새 PNG 파일이어야 합니다. 이미지는 축당 4096 픽셀, 총 8,388,608 픽셀, 64개의 컨택트 시트 샘플로 제한됩니다. 이 제한을 초과하는 요청은 렌더링 전에 실패합니다.
이미지는 파일로 저장되며, JSON 응답에는 경로와 image_bytes 크기가 포함됩니다. 검사는 이미지 완료를 기다리며, 큰 요청은 잠시 편집기를 점유할 수 있습니다.
명령 시간 초과 처리
요청 시간 초과가 변경 실패를 의미하지는 않습니다. 재시도 전에 오류에 있는 작업 ID를 사용하여 operation get ID 를 실행하세요. operation list 는 최근 변경 사항과 상태, 수정본, 결과를 확인합니다. 완료된 작업은 반환된 객체 ID를 포함하여 충분히 작으면 결과를 유지합니다. 저장소는 100개 작업과 4MiB로 제한되며, 개별 결과 본문은 256KiB 이상일 경우 생략됩니다. 이 기록은 실행 중인 세션에만 지속되며, 충돌 후 프로젝트를 복구하거나 반복 명령이 동일한 편집을 다시 적용하는 것을 방지하지 않습니다. 내보내기 작업은 별도의 상태/목록 명령을 가집니다.