CLI 레퍼런스
이 페이지는 릴리스 아카이브에 든 두 네이티브 프로그램의 모든 명령을 정리합니다. alpha2-host는 프로젝트를 렌더링해 export하고, alpha2는 미디어 파일 하나를 다룹니다. 프로그램을 받는 방법은 CLI를 참고하십시오. 둘 다 FFmpeg 8로 디코딩하고 인코딩합니다.
두 프로그램 모두 인자 없이 실행하면 사용법을 출력합니다. 인자는 UTF-8이어야 하며, 그렇지 않은 인자는 그 인자를 지목한 INVALID_INPUT으로 실패합니다.
alpha2-host
섹션 제목: “alpha2-host”alpha2-host servealpha2-host conform --project <project.json> --asset <source-id>=<path> ...alpha2-host export --project <project.json> --asset <source-id>=<path> ... --out <output>| 하위 명령 | 하는 일 |
|---|---|
export |
프로젝트를 렌더링해 MP4, MOV, Matroska, WebM 파일로 인코딩합니다. 결과는 JSON으로 표준 출력에, 진행 상황은 표준 오류에 씁니다. |
conform |
렌더링도 GPU도 없이 프로젝트의 미디어를 검사합니다. 보고서를 출력하고, export를 막는 것이 있으면 1로 종료합니다. |
serve |
표준 입력으로 요청을 받아 표준 출력으로 응답합니다. 한 줄에 JSON 객체 하나씩 오가는 호스트 프로토콜입니다. 플래그는 받지 않습니다. |
alpha2-host export
섹션 제목: “alpha2-host export”alpha2-host export --project project.json --asset image-1=image.png --out tutorial.mp4성공하면 표준 출력에 {"ok": true, "output": "<path>", "result": {...}}를 씁니다. result는 export 결과(프레임, 인코더, 레이트 컨트롤, 시간, 소스마다 읽은 미디어)이며, @alpha2-sh/node의 NativeExportResult 타입과 같습니다. 진행 줄(alpha2-host export: frames 12/30)은 표준 오류로 갑니다. 실패하면 메시지가 표준 오류로 가고 종료 상태가 0이 아닙니다.
--overwrite를 주지 않으면 출력 파일이 아직 없어야 합니다. export는 출력 옆에 <stem>.a2partial.<ext>를 쓰고, 완성되면 제자리로 옮깁니다. 완성된 파일을 옮기지 못하면 옆에 <stem>.a2kept.<ext>로 남깁니다.
| 플래그 | 값 | 기본값 | 의미 |
|---|---|---|---|
--project |
경로 | 필수 | 프로젝트 문서. UTF-8(BOM 유무 무관)로 읽고, UTF-16 BOM으로 시작하면 UTF-16으로 읽습니다. |
--asset |
<source-id>=<path> |
없음 | 소스 하나의 파일. export가 읽는 소스마다 반복합니다. |
--proxy |
<source-id>=<path> |
없음 | 소스 원본으로 만든 프록시. 여러 개면 선호 순서대로 반복합니다. |
--media |
original, proxies |
original |
proxies는 최신 프록시가 있으면 프록시를, 없으면 원본을 읽습니다. |
--frames |
<source-id>=<path>,<path>,... |
없음 | 이미지 시퀀스의 프레임 파일을 순서대로. 빈 경로는 빈 프레임입니다. |
--resource |
<source-id> <locator> <path>(값 세 개) |
없음 | SVG 소스의 <image href>나 Lottie 소스의 이미지 에셋이 가리키는 파일. 소스가 쓴 locator로 지정합니다. |
--effect-asset |
<resource-id>=<path> |
없음 | .cube LUT 같은 프로젝트 이펙트 리소스의 파일. |
--effects |
경로 | 없음 | 프로젝트가 내장 이펙트 외에 쓰는 런타임 이펙트 정의의 JSON 배열. |
--font |
경로 | 없음 | 자막, 텍스트, SVG 텍스트용 폰트 파일. 대체 순서대로 반복합니다. 텍스트를 보여 주는 프로젝트에는 하나 이상 필요합니다. |
범위와 프레임 레이트
섹션 제목: “범위와 프레임 레이트”| 플래그 | 값 | 기본값 | 의미 |
|---|---|---|---|
--start-ticks |
정수 | 0 |
범위의 시작, 틱 단위(1초에 120,000). |
--end-ticks |
정수 | 타임라인의 끝 | 범위의 끝. 기본값은 자막 큐를 포함해 타임라인에서 마지막으로 보이는 것이 끝나는 지점입니다. 아무것도 보이지 않는 프로젝트에서는 필수입니다. |
--frame-rate |
<num>/<den> |
프로젝트의 frame_rate |
출력 프레임 레이트. 예: 30000/1001. |
범위는 프레임 격자에 맞게 넓혀집니다.
| 플래그 | 값 | 기본값 | 의미 |
|---|---|---|---|
--out |
경로 | 필수 | 쓸 파일. --container가 없으면 확장자(.mp4나 .m4v, .mov, .mkv, .webm)가 컨테이너를 정하며, 둘은 일치해야 합니다. |
--overwrite |
꺼짐 | export가 완성되면 --out 자리의 일반 파일을 교체합니다. 실패하거나 취소된 export는 기존 파일을 그대로 둡니다. |
|
--container |
mp4, mov, mkv, webm |
확장자에서 | |
--no-audio |
오디오 켜짐 | 오디오 트랙을 뺍니다. (--include-audio로 다시 켭니다.) |
|
--video-codec |
h264, hevc, vp9, av1, mpeg4-part2, prores |
컨테이너 기본값 | 컨테이너가 지원하는 것(아래 표). prores는 422 HQ, --alpha와 함께면 4444입니다. |
--alpha |
꺼짐 | 투명도를 유지합니다. 프로젝트 배경 없이 그리고 알파 평면과 함께 씁니다. WebM이나 Matroska의 vp9, 또는 prores(4444)만 됩니다. |
|
--bit-depth |
8, 10 |
prores는 10, 그 외 8 |
hevc, av1, vp9, prores의 10비트 그림. |
--video-encoder |
FFmpeg 인코더 이름 | 호스트가 선택 | 인코더 고정. 예: openh264, h264_nvenc. capabilities가 그 코덱용으로 알려 주는 인코더여야 합니다. |
--video-quality |
very-low, low, medium, high, very-high, 또는 초당 비트 |
high |
단계를 주면 호스트가 코덱, 크기, 프레임 레이트에 맞는 비트레이트로 바꿉니다. 숫자는 비트레이트입니다. |
--video-quantizer |
정수, 0~255 | 없음 | 코덱 척도의 고정 양자화값. 대체값으로 --video-quality <bits-per-second>가 필요합니다. |
--audio-codec |
aac, opus |
컨테이너 기본값 | |
--audio-quality |
단계, 또는 초당 비트 | high |
|
--loudness-target |
LUFS, −60~0 | 없음 | 오디오를 이 통합 라우드니스로 정규화합니다(EBU R128 / ITU-R BS.1770-4). |
--true-peak-ceiling |
dBTP, −20~0 | -1 |
--loudness-target의 트루 피크 상한. 그 플래그와 함께만 씁니다. |
컨테이너는 주요 플레이어가 그 컨테이너에서 재생하는 코덱만 지원합니다. 각 칸의 첫 번째가 기본값입니다.
| 컨테이너 | 비디오 | 오디오 |
|---|---|---|
mp4 |
h264, hevc, vp9, av1, mpeg4-part2 |
aac, opus |
mov |
h264, hevc, mpeg4-part2, prores |
aac |
mkv |
h264, hevc, vp9, av1, mpeg4-part2 |
aac, opus |
webm |
vp9, av1 |
opus |
컨테이너가 지원하지 않거나 이 호스트가 인코딩할 수 없는 코덱은 아무것도 열기 전에 INVALID_INPUT으로 거부됩니다.
렌더링과 파이프라인
섹션 제목: “렌더링과 파이프라인”| 플래그 | 값 | 기본값 | 의미 |
|---|---|---|---|
--renderer |
auto, gpu, cpu |
ALPHA2_RENDERER, 없으면 auto |
auto는 하드웨어 GPU가 있으면 GPU로, 없으면 CPU로 렌더링하며 소프트웨어 어댑터는 쓰지 않습니다. gpu는 아무 어댑터나 쓰고 없으면 GPU_INIT_FAILED로 실패합니다. cpu는 그래픽 드라이버를 열지 않습니다. |
--video-decode |
software, auto, hardware-required |
ALPHA2_VIDEO_DECODE, 없으면 Linux·macOS는 auto, Windows는 software |
비디오 디코딩 방식. hardware-required는 CPU로 디코딩하는 대신 실패합니다. |
--input-policy |
auto, gpu-required, cpu-readback |
auto |
프레임이 인코더로 가는 방식. auto는 가능하면 GPU에 두고 아니면 리드백합니다. gpu-required는 그 대신 GPU_OUTPUT_UNAVAILABLE로 실패하고, cpu-readback은 항상 리드백합니다. |
--strategy |
render, prefer-copy, require-copy |
render |
prefer-copy는 범위가 소스를 손대지 않고 보여 주면 압축 패킷을 복사하고, 아니면 렌더링합니다. require-copy는 렌더링하는 대신 COPY_INELIGIBLE로 실패합니다. |
--render-cache |
디렉터리 | 없음 | 렌더링한 프레임을 보관해, 같은 호스트 빌드가 같은 GPU에서 같은 프로젝트·파일·이펙트를 다시 export할 때 재사용합니다. |
--render-cache-quota |
바이트 | 4 GiB | 캐시 크기 한도. --render-cache와 함께만 씁니다. |
--render-cache-backlog |
skip, wait |
skip |
캐시 기록기가 가득 찼을 때 skip은 그 프레임을 캐시하지 않고, wait은 기록기에 자리가 날 때까지 export를 기다리게 합니다. --render-cache와 함께만 씁니다. |
alpha2-host conform
섹션 제목: “alpha2-host conform”alpha2-host conform --project project.json --asset video-1=clip.mp4{"ok": <ready>, "result": {"catalog": ..., "report": ...}}를 출력합니다. 호스트가 소스마다 찾은 것과, 소스마다 용도에 따라 읽을 것과 그 문제점입니다. 미디어가 준비되면 0으로, 막는 문제가 있으면 표준 오류에 CONFORM_FAILED 메시지를 남기고 1로 종료합니다. GPU는 필요 없습니다.
| 플래그 | 값 | 기본값 | 의미 |
|---|---|---|---|
--project |
경로 | 필수 | export와 같습니다. |
--asset |
<source-id>=<path> |
없음 | export와 같습니다. |
--proxy |
<source-id>=<path> |
없음 | export와 같습니다. |
--frames |
<source-id>=<path>,... |
없음 | export와 같습니다. |
--purpose |
preview, preview-proxy, thumbnail, remote-edit, export-original, export-proxy |
export-original |
미디어를 읽는 용도. |
--video-decode |
software, auto, hardware-required |
export와 같음 |
conform은 export와 같은 플래그를 파싱하고, 나머지는 무시합니다.
alpha2-host serve
섹션 제목: “alpha2-host serve”alpha2-host serve는 플래그를 받지 않습니다. 먼저 {"protocolVersion":1,"type":"ready"}를 쓰고, 표준 입력이 끝날 때까지 capabilities, conform, export, still, cancel 요청에 응답합니다. 렌더러와 디코딩 방식은 ALPHA2_RENDERER와 ALPHA2_VIDEO_DECODE에서 정합니다. 호스트 프로토콜을 참고하십시오.
GPU 인코딩이 포함된 빌드에는 alpha2-host probe-gpu-encode [width] [height](기본값 1920×1080)도 있습니다. GPU 상주 인코딩 경로를 시험하고 결과를 알려 줍니다. 사용법 텍스트에는 나오지 않으며, 머신을 진단하는 용도입니다.
환경 변수
섹션 제목: “환경 변수”| 변수 | 의미 |
|---|---|
ALPHA2_RENDERER |
--renderer가 없을 때(그리고 serve에서는 항상) 쓰는 auto, gpu, cpu. |
ALPHA2_VIDEO_DECODE |
--video-decode가 없을 때 쓰는 software, auto, hardware-required. |
ALPHA2_RENDER_THREADS |
CPU 렌더러의 스레드 수. 기본값은 프로세스가 쓸 수 있는 모든 스레드입니다. |
ALPHA2_GPU_ADAPTER |
GPU가 여럿일 때 렌더링할 GPU. auto(Linux·macOS 기본값), performance(Windows 기본값), 숫자(어댑터 순번), 또는 어댑터 이름에 포함된 텍스트. 어떤 어댑터도 가리키지 않으면 어댑터 목록과 함께 INVALID_INPUT으로 실패합니다. |
ALPHA2_GPU_WATCHDOG_MS |
호스트가 가정하는 GPU 워치독, 기본값 2000ms. 디바이스 손실 직전에 그 절반 동안 GPU를 붙잡은 제출이 있으면 GPU_DEVICE_HUNG으로 실패합니다. |
ALPHA2_DECODER_SESSION_BYTES |
디코더 세션 예산, 기본값 4 GiB. |
ALPHA2_DECODER_SESSIONS |
예산 대신 지정하는 비디오 디코더 세션 수, 1~32. |
ALPHA2_OPENH264 |
0이면 호스트가 OpenH264를 쓰지 않습니다. |
ALPHA2_OPENH264_LIBRARY |
불러올 OpenH264 라이브러리 경로. ALPHA2_OPENH264_UNVERIFIED=1이 아니면 SHA-256이 Cisco의 것이어야 합니다. |
ALPHA2_VIDEO_ENCODER_HYBRID |
Windows에서 hardware로 두면 Media Foundation의 하드웨어 H.264 인코더를 요청합니다. |
ALPHA2_HOST_CACHE_DIR |
npx @alpha2-sh/node install과 python -m alpha2 install이 푸는 캐시. 호스트가 OpenH264를 찾는 곳이기도 합니다. |
종료 코드
섹션 제목: “종료 코드”| 상태 | 경우 |
|---|---|
0 |
성공. conform에서는 미디어가 준비됨. |
1 |
모든 실패: 잘못된 플래그나 입력, 없는 미디어, 실패한 export, CONFORM_FAILED. GPU 디바이스를 잃었거나 디코더·인코더 스레드가 멈춘 호스트도 응답한 뒤 1로 종료합니다. |
70 |
GPU_INIT_FAILED: 호스트가 GPU 디바이스를 만들지 못함. |
101 |
호스트 패닉(결함). |
128 + 시그널 |
Linux·macOS에서 시그널로 취소됨: SIGINT는 130, SIGTERM은 143. 실행 중인 export는 먼저 멈추고 부분 파일을 지웁니다. |
130, 143 |
Windows의 콘솔 제어 이벤트: 콘솔이 닫히는 중이면 143, 아니면 130. |
serve는 자신을 시작한 프로세스가 종료되어도 상태 143으로 종료합니다.
alpha2 프로그램
섹션 제목: “alpha2 프로그램”alpha2 probe <media>alpha2 thumbnail <media> <out.png> [--auto | --at <source-seconds>]alpha2 transcode <media> <out.mp4|.mov|.mkv|.webm> [--proxy half|quarter] [--video-codec <id>]alpha2 export-audio <media> <out.wav>alpha2 waveform <media> [bucket-ms] [levels]| 명령 | 하는 일 |
|---|---|
probe <media> |
컨테이너, 길이, 스트림(코덱, 크기, 프레임 레이트, 색)을 출력합니다. 길이는 틱 단위입니다. |
thumbnail <media> <out.png> [--at <seconds>] |
프레임 하나를 PNG로 씁니다. 소스 자체 타임라인의 특정 시점 프레임, 또는 기본값(--auto)으로 영상 전체에 퍼진 아홉 프레임 중 검거나 희지 않은 가장 선명한 프레임입니다. |
transcode <media> <out> [--proxy half|quarter] [--video-codec <id>] |
영상을 원래 크기로, 또는 프록시용으로 절반이나 4분의 1 크기로 다시 인코딩해, 출력 확장자가 가리키는 컨테이너에 씁니다. --video-codec이 없으면 런타임에 메모리의 프레임을 받는 인코더가 있을 때 컨테이너 기본 코덱(H.264, WebM은 VP9)을 쓰고, 없으면 컨테이너가 지원하는 다른 코덱을 쓰며 무엇을 썼는지 출력합니다. HDR 입력은 거부합니다. |
export-audio <media> <out.wav> |
오디오를 48kHz로 리샘플링해 소스의 0초부터 시작하는 WAV 파일로 디코딩합니다. |
waveform <media> [bucket-ms] [levels] |
파형 요약을 JSON으로 출력합니다. 샘플 버킷(기본값 10ms)마다 최소, 최대, RMS를 그 크기와, 직전의 네 배씩 굵어지는 단계(기본값 6단계)로 냅니다. |
사용법 텍스트에는 머신과 파일을 점검하는 명령도 있습니다. decode와 decode-audio(모든 프레임이나 샘플을 디코딩하고 개수를 출력), render <media> <out.png>(첫 비디오 프레임을 PNG로), probe-encoders [width] [height](어떤 비디오 인코더가 열리고 인코딩하는지, 기본값 1920×1080), 그리고 Linux의 probe-hwdecode <media> [frame-limit](Vulkan Video 디코딩, 기본값 120프레임)입니다.
--decode-policy
섹션 제목: “--decode-policy”디코딩하는 명령(decode, decode-audio, render, thumbnail, transcode, export-audio, waveform)은 --decode-policy strict|tolerant를 받습니다.
| 값 | 의미 |
|---|---|
strict |
처음 만난 손상된 입력에서 실패합니다. ALPHA2_DECODE_POLICY가 다르게 정하지 않으면 기본값입니다. |
tolerant |
손상된 입력을 건너뛰고, 명령이 끝날 때 건너뛴 것을 보고합니다. |
alpha2는 성공하면 0, 실패하면 1로 종료하며 메시지는 표준 오류로 갑니다.
관련 명령
섹션 제목: “관련 명령”클라이언트 패키지에도 작은 명령줄이 있습니다.
| 명령 | 하는 일 |
|---|---|
npx @alpha2-sh/node install [--openh264] [--force] |
패키지 버전의 alpha2-host 아카이브를 호스트 캐시에 내려받습니다. --openh264면 Cisco의 OpenH264를 내려받습니다. --force는 다시 내려받습니다. |
python -m alpha2 install [--openh264] [--force] |
Python에서 같은 캐시에 같은 일을 합니다. |
python -m alpha2 export <project> <output> |
--asset, --font, --start-ticks, --end-ticks, --no-audio, --video-codec, --video-quality, --json, --host와 함께 export합니다. |
python -m alpha2 still <project> <output.png> --at <seconds> |
프레임 하나를 PNG로 렌더링합니다. --asset, --font, --size <w> <h>, --overwrite, --json, --host를 받습니다. |
python -m alpha2 capabilities |
호스트가 디코딩·인코딩할 수 있는 것을 출력합니다. |
함께 보기
섹션 제목: “함께 보기”- CLI: 프로그램 받기와 첫 export.
- 호스트 프로토콜:
serve의 요청과 오류. - 서버에서 렌더링하기: 렌더러, 컨테이너, 큐.
- 플랫폼 지원