CLI

alpha2의 네이티브 프로그램은 플랫폼별 아카이브 하나로 제공됩니다. 이 페이지를 읽고 나면 프로그램을 설치하고, 셸에서 프로젝트를 export하고, 렌더링 전에 프로젝트의 미디어를 확인하고, 미디어 파일의 정보 확인, 트랜스코딩, 썸네일 생성, 분석을 할 수 있습니다.

프로그램은 두 가지입니다.

alpha2-host는 프로젝트를 렌더링하고 export합니다. @alpha2-sh/node와 Python 패키지가 실행하는 프로세스도 이것이며, 다른 언어와는 호스트 프로토콜로 통신합니다.
alpha2는 미디어 파일을 한 번에 하나씩 다룹니다.

둘 다 디코딩과 인코딩에 FFmpeg 8을 씁니다. 이 페이지는 자주 하는 작업을 다루며, 모든 플래그는 CLI 레퍼런스에 있습니다.

설치

각 GitHub 릴리스에는 타깃별 아카이브 alpha2-<version>-<target>-bundled.tar.gz(Windows는 .zip)와, 모든 아카이브의 SHA-256을 담은 checksums.sha256이 있습니다.

타깃	실행 환경
`linux-x64`, `linux-arm64`	glibc 2.35 이상. musl은 지원하지 않음
`macos-arm64`	macOS 11 이상. Rosetta로 실행하는 x64 프로세스도 이것을 사용
`win-x64`	Windows x64

릴리스 페이지에서 플랫폼에 맞는 아카이브를 내려받습니다.
압축을 풀기 전에 GitHub CLI로 빌드 출처(provenance)를 확인합니다.
터미널 창
```
gh attestation verify alpha2-<version>-<target>-bundled.tar.gz --repo alpha2-sh/alpha2
```
checksums.sha256은 같은 릴리스에서 오기 때문에 손상된 다운로드는 잡아내지만 바꿔치기된 파일은 잡아내지 못합니다. attestation은 이를 잡아냅니다.
압축을 풀고 bin/을 PATH에 추가하거나, 경로를 지정해 프로그램을 실행합니다.

아카이브는 디렉터리 하나로 풀립니다.

alpha2-<version>-<target>-bundled/
  bin/alpha2          the media command (alpha2.exe on Windows)
  bin/alpha2-host     the project renderer (alpha2-host.exe on Windows)
  lib/                the FFmpeg libraries (Linux and macOS)
  compliance/         FFmpeg runtime lock, build configuration, source location, notices
  licenses/           license texts of FFmpeg, its libraries and the Rust crates
  LICENSE.md

npx @alpha2-sh/node install과 python -m alpha2 install은 같은 아카이브를 공유 캐시에 내려받으며, 패키지에 고정된 SHA-256과 대조합니다. 대신 시스템의 FFmpeg 8로 빌드하려면 FFmpeg 8 개발 파일을 갖춘 상태에서 cargo install alpha2-host(alpha2는 alpha2-native)를 실행합니다.

프로젝트 export하기

alpha2-host export는 프로젝트 하나를 export합니다. 결과는 표준 출력에 JSON으로, 진행 상황은 표준 오류에 출력합니다.

alpha2-host export --project project.json --asset image-1=image.png --out tutorial.mp4

--asset <source-id>=<path>는 소스 하나의 파일을 지정합니다. 소스마다 반복해서 씁니다.
--overwrite를 주지 않으면 출력 파일이 아직 없어야 합니다. export는 출력 옆에 <stem>.a2partial.<ext>를 쓰고, 끝나면 제자리로 옮깁니다. 완성된 파일을 옮길 수 없으면 그 옆에 <stem>.a2kept.<ext>로 남겨 둡니다.
--start-ticks와 --end-ticks로 범위를(기본값은 타임라인 전체), --frame-rate <num>/<den>으로 출력 프레임 레이트를(기본값은 프로젝트 설정) 정합니다. 시간은 틱(tick) 단위이며 1초는 120,000틱입니다.
출력 확장자(.mp4, .mov, .mkv, .webm)나 --container로 컨테이너를 정합니다.
--video-codec과 --audio-codec으로 코덱을 정합니다. 기본값은 컨테이너마다 다르며 H.264와 AAC, WebM은 VP9와 Opus입니다.
--video-quality는 레벨(very-low, low, medium, high, very-high)이나 초당 비트 수로 된 비트레이트를 받습니다. --audio-quality도 같습니다.
--no-audio는 오디오를 빼고 export합니다.

# 프로젝트의 2초부터 5초까지를 1080p WebM, 30fps, 고화질, 오디오 없이 export
alpha2-host export --project project.json \
  --asset clip-a=a.mov --asset clip-b=b.mov \
  --start-ticks 240000 --end-ticks 600000 --frame-rate 30/1 \
  --out excerpt.webm --video-quality high --no-audio

그 밖의 export 옵션은 다음과 같습니다.

플래그	동작
`--alpha`	투명도를 유지합니다. WebM이나 Matroska의 VP9, 또는 ProRes 4444.
`--bit-depth 10`	10비트 그림. HEVC, AV1, VP9, ProRes용.
`--loudness-target <LUFS> [--true-peak-ceiling <dBTP>]`	오디오를 통합 라우드니스에 맞게 정규화합니다.
`--proxy <source-id>=<path>`, `--media proxies`	프록시가 있는 소스는 프록시로 export합니다.
`--strategy prefer-copy`	가능한 곳에서는 렌더링하지 않고 손대지 않은 소스 패킷을 복사합니다.
`--video-encoder <ffmpeg-name>`	인코더를 고정합니다.

프로젝트, 이펙트, .cube LUT 파일은 바이트 순서 표식(BOM) 유무와 관계없이 UTF-8로 읽고, UTF-16 BOM으로 시작하면 UTF-16으로 읽습니다(Windows PowerShell 5.1의 Out-File이 이렇게 씁니다).

렌더링 전에 미디어 확인하기

alpha2-host conform은 렌더링하지 않고 GPU도 쓰지 않은 채, 각 소스가 무엇을 읽게 되는지와 무엇이 없거나 쓸 수 없는지 보고합니다. export를 막는 문제가 있으면 상태 코드 1로 종료합니다.

alpha2-host conform --project project.json --asset image-1=image.png

{"ok":false,"result":{"catalog":{...},"report":{"purpose":"export_original","ready":false,"sources":[{"issues":[{"blocking":true,"kind":"offline","path":"image.png"}],"selection":{"media":"unavailable"},"source_id":"image-1"}]}}}

--purpose는 미디어를 어떤 용도로 읽을지 정합니다. preview, preview-proxy, thumbnail, remote-edit, export-original(기본값), export-proxy 중 하나입니다. export도 먼저 같은 검사를 실행하며, 미디어가 준비되지 않았으면 CONFORM_FAILED로 실패합니다.

폰트

자막(caption), 텍스트 제너레이터, 레이아웃, SVG의 텍스트는 지정한 폰트로 그립니다. 폰트 파일은 --font로 폴백 순서대로 넘깁니다. 텍스트가 나오는 프로젝트에는 폰트가 필요합니다.

alpha2-host export --project titles.json --font fonts/HankenGrotesk.ttf --font fonts/NotoSansKR.otf --out titles.mp4

브라우저 프리뷰에도 같은 파일을 넘기면(alpha2의 addFont) 프리뷰 텍스트가 export된 텍스트와 픽셀 단위로 일치합니다. 결과의 unmatchedFontFamilies에는 프로젝트가 지정했지만 넘긴 폰트 중 어디에도 없는 폰트 패밀리가 나열되며, 해당 텍스트는 폴백 순서대로 그려집니다.

이펙트와 LUT

내장 이펙트와 트랜지션은 추가로 필요한 것이 없습니다(이펙트와 컴포지션 참고). 나머지는 두 플래그로 제공합니다.

--effects <effects.json>은 프로젝트가 내장 이펙트 외에 쓰는 런타임 이펙트 정의를 JSON 배열로 넘깁니다.
--effect-asset <resource-id>=<path>는 .cube 3D LUT 같은 이펙트 리소스의 파일을 지정합니다.

alpha2-host export --project graded.json --asset clip=clip.mov \
  --effect-asset film-look=luts/film.cube --out graded.mp4

GPU와 CPU

--renderer는 프레임을 무엇으로 그릴지 정합니다.

auto(기본값)는 머신에 하드웨어 GPU가 있으면 GPU에서, 없으면 CPU에서 렌더링합니다. 소프트웨어 GPU 어댑터(lavapipe, llvmpipe, WARP, SwiftShader)는 쓰지 않습니다.
cpu는 CPU에서 렌더링하며 그래픽 드라이버를 전혀 열지 않습니다. CPU 전용 서버, 컨테이너, 서버리스 함수에서도 아카이브만 있으면 됩니다.
gpu는 소프트웨어 어댑터를 포함해 찾은 GPU 어댑터를 무엇이든 쓰며, 어댑터가 없으면 GPU_INIT_FAILED로 실패합니다.

CPU 렌더러는 GPU와 같은 렌더 그래프를 그리며, 스레드 수와 관계없이 어느 머신에서나 바이트 단위로 같은 그림을 만듭니다(결정론 참고). 스레드 수는 ALPHA2_RENDER_THREADS로 정합니다. GPU가 여러 개인 머신에서는 ALPHA2_GPU_ADAPTER로 하나를 고릅니다. auto, performance, 인덱스, 또는 어댑터 이름에 들어 있는 텍스트를 줄 수 있습니다.

하드웨어 디코딩

--video-decode는 export와 conform이 동영상을 디코딩하는 방식을 정합니다.

모드	동작
`software`	모든 프레임을 CPU에서 디코딩합니다. Windows의 기본값입니다.
`auto`	디바이스와 스트림이 허용하면 GPU에서, 아니면 CPU에서 디코딩합니다. Linux와 macOS의 기본값입니다.
`hardware-required`	CPU에서 프레임을 디코딩하는 대신 실패합니다.

serve의 모드는 ALPHA2_VIDEO_DECODE로 정합니다. 모든 export 결과는 실행된 모드(videoDecodeMode)와 프레임이 인코더에 전달된 방식(videoPipeline: readback, gpu-resident, packet-copy)을 보고합니다.

렌더 캐시

--render-cache <dir>는 렌더링한 프레임을 디렉터리에 보관합니다. 이후 같은 호스트 빌드가 같은 GPU에서 같은 프로젝트, 파일, 이펙트를 export하면 다시 렌더링하지 않고 보관된 프레임을 씁니다.

alpha2-host export --project project.json --asset clip=clip.mov --out v1.mp4 \
  --render-cache .alpha2-cache --render-cache-quota 8000000000

--render-cache-quota는 바이트 단위입니다(기본값 4 GiB). --render-cache-backlog는 skip(기본값) 또는 wait입니다.

소프트웨어 H.264 (OpenH264)

아카이브에 들어 있는 FFmpeg는 LGPL이며 소프트웨어 H.264 인코더가 없습니다. H.264는 하드웨어 인코더(NVENC, VideoToolbox, Media Foundation, Vulkan Video, D3D12 Video)나, 직접 설치하는 Cisco의 OpenH264로 인코딩합니다.

python -m alpha2 install --openh264      # 또는: npx @alpha2-sh/node install --openh264

이 명령은 https://ciscobinary.openh264.org에서 Cisco OpenH264 2.7.0을 내려받아 고정된 SHA-256과 대조한 뒤, alpha2-host가 찾을 수 있도록 호스트 캐시에 넣습니다. --video-encoder openh264로 고정할 수 있고, ALPHA2_OPENH264=0으로 끌 수 있습니다. VP9(libvpx-vp9)와 AV1(libsvtav1)은 항상 소프트웨어로 인코딩하므로, H.264 인코더가 없는 호스트도 WebM은 쓸 수 있습니다.

`alpha2`로 미디어 파일 살펴보기

alpha2는 파일 하나를 다룹니다. 인수 없이 실행하면 모든 명령을 출력합니다.

미디어 정보 확인

alpha2 probe clip.mp4

format: mov,mp4,m4a,3gp,3g2,mj2
duration_ticks: 240000
selected_video: Some(0)
selected_audio: None
stream 0 Video codec=mpeg4 duration_ticks=240000 dimensions=Some((1280, 720)) rate=Some(FrameRate { num: 30, den: 1 }) color=Some(...)

컨테이너, 길이, 스트림(코덱, 크기, 프레임 레이트, 색상)을 출력합니다.

썸네일

alpha2 thumbnail clip.mp4 poster.png            # 프레임 아홉 개 중 가장 선명한 것
alpha2 thumbnail clip.mp4 frame.png --at 1.5    # 소스의 1.5초 지점 프레임

--at이 없으면 동영상 전체에 고르게 퍼진 프레임 아홉 개 중 검은색도 흰색도 아닌 가장 선명한 프레임을 고릅니다.

트랜스코딩과 프록시

alpha2 transcode camera.mov edit.mp4
alpha2 transcode camera.mov proxy.mp4 --proxy half
alpha2 transcode camera.mov web.webm --video-codec vp9

transcode는 동영상을 원래 크기로, 또는 --proxy half|quarter로 절반이나 4분의 1 크기로 다시 인코딩해, 출력 확장자가 가리키는 컨테이너에 담습니다. --video-codec이 없으면 런타임에 인코더가 있는 경우 컨테이너의 기본 코덱을, 없으면 컨테이너가 지원하는 다른 코덱을 쓰며, 어느 코덱을 썼는지 출력합니다.

오디오

alpha2 export-audio interview.mp4 interview.wav   # 소스의 0초부터 48 kHz WAV로
alpha2 waveform interview.mp4 10 6                # JSON: 10 ms 구간별 최솟값, 최댓값, RMS, 6단계

디코딩하는 명령은 --decode-policy strict|tolerant를 받습니다. strict(기본값)는 손상된 입력을 처음 만나면 실패하고, tolerant는 손상된 입력을 건너뛰고 건너뛴 내용을 보고합니다.

다음 단계

CLI 레퍼런스: 두 프로그램의 모든 플래그.
호스트 프로토콜: 어떤 언어에서든 alpha2-host serve를 제어합니다.
Node.js와 Python: 같은 호스트를 라이브러리로 사용합니다.