콘텐츠로 이동
alpha2alpha2
Search limited to v0.4. Switch to the latest version for up-to-date results.

CLI

This content is for v0.4. Switch to the latest version for up-to-date documentation.

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

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

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

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

설치

섹션 제목: “설치”

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

타깃 종류
linux-x64, linux-arm64 bundled, thin
macos-arm64 bundled, thin
win-x64 bundled
  • **bundled**는 LGPL FFmpeg 공유 라이브러리를 포함하며 아카이브 안에서 불러옵니다.
  • **thin**은 FFmpeg를 포함하지 않고 시스템에 설치된 FFmpeg 8을 불러옵니다. Linux에서는 시스템 로더의 검색 경로에서, macOS에서는 /opt/homebrew/lib, /usr/local/lib, /opt/local/lib 순서로 찾습니다.
  1. 릴리스 페이지에서 플랫폼에 맞는 아카이브를 내려받습니다.
  2. checksums.sha256과 대조합니다.
  3. 압축을 풀고 bin/을 PATH에 추가하거나, 경로를 지정해 프로그램을 실행합니다.

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

alpha2-<version>-<target>-<kind>/
  bin/alpha2          the media command (alpha2.exe on Windows)
  bin/alpha2-host     the project renderer (alpha2-host.exe on Windows)
  lib/                the FFmpeg libraries (bundled, 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은 같은 아카이브를 공유 캐시에 내려받으며, 릴리스의 checksums.sha256과 대조합니다. cargo install alpha2-host(alpha2는 alpha2-native)는 대신 머신의 FFmpeg 8로 프로그램을 빌드합니다.

프로젝트 export하기

섹션 제목: “프로젝트 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>.alpha2-partial.<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 옵션은 다음과 같습니다.

플래그 동작
--loudness-target <LUFS> [--true-peak-ceiling <dBTP>] 오디오를 통합 라우드니스에 맞게 정규화합니다.
--proxy <source-id>=<path>, --media proxies 프록시가 있는 소스는 프록시로 export합니다.
--strategy prefer-copy 가능한 곳에서는 렌더링하지 않고 손대지 않은 소스 패킷을 복사합니다.
--video-encoder <ffmpeg-name> 인코더를 고정합니다.

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

섹션 제목: “렌더링 전에 미디어 확인하기”

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"}],"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된 텍스트와 픽셀 단위로 일치합니다.

이펙트와 LUT

섹션 제목: “이펙트와 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

섹션 제목: “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로 정합니다.

하드웨어 디코딩

섹션 제목: “하드웨어 디코딩”

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

모드 동작
software 모든 프레임을 CPU에서 디코딩합니다. macOS와 Windows의 기본값입니다.
auto 디바이스와 스트림이 허용하면 GPU에서, 아니면 CPU에서 디코딩합니다. Linux의 기본값입니다.
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)

섹션 제목: “소프트웨어 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은 쓸 수 있습니다. thin 아카이브는 시스템 FFmpeg에 libx264가 있으면 그것도 사용합니다.

alpha2로 미디어 파일 살펴보기

섹션 제목: “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는 손상된 입력을 건너뛰고 건너뛴 내용을 보고합니다.

다음 단계

섹션 제목: “다음 단계”