CLI

alpha2’s native programs come as one archive per platform. After reading this page you can install them, export a project from a shell, check a project’s media before rendering, and probe, transcode, thumbnail and inspect media files.

There are two programs:

• alpha2-host renders and exports projects. It is also the process @alpha2-sh/node and the Python package run, and it speaks the host protocol to any other language.
• alpha2 works on one media file at a time.

Both use FFmpeg 8 to decode and encode. This page covers common tasks; CLI reference lists every flag.

Install

Each GitHub release has one archive per target, alpha2-<version>-<target>-bundled.tar.gz (.zip on Windows), and checksums.sha256 with the SHA-256 of every archive.

Target	Runs on
linux-x64, linux-arm64	glibc 2.35 or later; not musl
macos-arm64	macOS 11 or later; an x64 process under Rosetta uses it too
win-x64	Windows x64

1. Download the archive for your platform from the release page.

2. Check its build provenance with the GitHub CLI before unpacking it:

   gh attestation verify alpha2-<version>-<target>-bundled.tar.gz --repo alpha2-sh/alpha2

   checksums.sha256 catches a damaged download but not a replaced one, since it comes from the same release. The attestation does.

3. Unpack it and put its bin/ on your PATH, or call the programs by path.

An archive unpacks into one directory:

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

Caution

Keep bin/ and lib/ together when you move the archive or package it into an application. The programs find the FFmpeg libraries relative to themselves (in lib/ on Linux and macOS, beside the programs in bin/ on Windows).

npx @alpha2-sh/node install and python -m alpha2 install download the same archive into a shared cache, checked against a SHA-256 the package pins. To build against a system FFmpeg 8 instead, run cargo install alpha2-host (or alpha2-native for alpha2) with FFmpeg 8 development files.

Export a project

alpha2-host export exports one project. It prints the result as JSON on standard output and progress on standard error.

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

• --asset <source-id>=<path> gives the file of one source. Repeat it for each source.
• The output must not exist yet, unless you pass --overwrite. The export writes <stem>.a2partial.<ext> beside it and moves that into place when it is finished. A finished file that cannot be moved there is kept beside it as <stem>.a2kept.<ext>.
• --start-ticks and --end-ticks choose the range (the whole timeline by default), and --frame-rate <num>/<den> the output rate (the project’s by default). Times are ticks, 120,000 per second.
• The output’s extension (.mp4, .mov, .mkv, .webm) or --container picks the container.
• --video-codec and --audio-codec pick the codecs. By default each container’s: H.264 and AAC, or VP9 and Opus for WebM.
• --video-quality takes a level (very-low, low, medium, high, very-high) or a bitrate in bits per second. --audio-quality works the same way.
• --no-audio leaves the audio out.

# Seconds 2 to 5 of a project, as 1080p WebM at 30 fps, high quality, no audio
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

Other export options:

Flag	Does
--alpha	Keeps transparency: VP9 in WebM or Matroska, or ProRes 4444.
--bit-depth 10	10-bit pictures, for HEVC, AV1, VP9 and ProRes.
--loudness-target <LUFS> [--true-peak-ceiling <dBTP>]	Normalizes the audio to an integrated loudness.
--proxy <source-id>=<path>, --media proxies	Exports from proxies where there are some.
--strategy prefer-copy	Copies untouched source packets instead of rendering, where it can.
--video-encoder <ffmpeg-name>	Pins an encoder.

The project, effects and .cube LUT files are read as UTF-8, with or without a byte order mark, or as UTF-16 when they start with its byte order mark (what Windows PowerShell 5.1’s Out-File writes).

Check media before rendering

alpha2-host conform reports what each source would read and what is missing or unusable, without rendering and without a GPU. It exits with status 1 when something blocks the export.

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 chooses what the media is read for: preview, preview-proxy, thumbnail, remote-edit, export-original (the default) or export-proxy. An export runs the same check first and fails with CONFORM_FAILED when the media is not ready.

Fonts

Text in captions, text generators, layouts and SVG draws with the fonts you give. Pass font files with --font, in fallback order. A project that shows text needs them.

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

Give the browser preview the same files (addFont in alpha2) and preview text matches exported text pixel for pixel. The result’s unmatchedFontFamilies lists font families the project names that no supplied font has; those texts draw in the fallback order.

Effects and LUTs

The built-in effects and transitions need nothing extra (see effects and compositions). Two flags supply the rest:

• --effects <effects.json> gives a JSON array of runtime effect definitions the project uses besides the built-in ones.
• --effect-asset <resource-id>=<path> gives the file of an effect resource, such as a .cube 3D LUT.

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

Caution

A runtime effect is WGSL that runs on the GPU. The CPU renderer cannot run one: an export that uses one on a CPU host fails with EFFECT_ERROR before any output is written. Render it with --renderer gpu.

GPU or CPU

--renderer chooses what draws the frames:

• auto (the default) renders on a hardware GPU when the machine has one, and otherwise on the CPU. It never takes a software GPU adapter (lavapipe, llvmpipe, WARP, SwiftShader).
• cpu renders on the CPU and opens no graphics driver at all. A CPU-only server, a container or a serverless function needs nothing but the archive.
• gpu renders on whatever GPU adapter it finds, software ones included, and fails with GPU_INIT_FAILED when there is none.

The CPU renderer draws the same render graph as the GPU, and its pictures are the same bytes on every machine for any number of threads (see determinism). ALPHA2_RENDER_THREADS sets its thread count. On a machine with several GPUs, ALPHA2_GPU_ADAPTER chooses one: auto, performance, an index, or text in the adapter’s name.

Hardware decode

--video-decode chooses how export and conform decode video:

Mode	Does
software	Decodes every frame on the CPU. The default on Windows.
auto	Decodes on the GPU where the device and the stream allow it, on the CPU otherwise. The default on Linux and macOS.
hardware-required	Fails instead of decoding a frame on the CPU.

ALPHA2_VIDEO_DECODE sets the mode for serve. Every export result reports the mode it ran (videoDecodeMode) and how frames reached the encoder (videoPipeline: readback, gpu-resident or packet-copy).

Render cache

--render-cache <dir> keeps rendered frames in a directory, so a later export of the same project, files and effects, by the same host build on the same GPU, takes them instead of rendering them again.

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

--render-cache-quota is in bytes (4 GiB by default). --render-cache-backlog is skip (the default) or wait.

Software H.264 (OpenH264)

The archives’ FFmpeg is LGPL and has no software H.264 encoder. H.264 comes from a hardware encoder (NVENC, VideoToolbox, Media Foundation, Vulkan Video or D3D12 Video) or from Cisco’s OpenH264, which you install yourself:

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

The command downloads Cisco’s OpenH264 2.7.0 from https://ciscobinary.openh264.org, checks it against pinned SHA-256s, and puts it in the host cache, where alpha2-host finds it. --video-encoder openh264 pins it, and ALPHA2_OPENH264=0 turns it off. VP9 (libvpx-vp9) and AV1 (libsvtav1) always encode in software, so a host without an H.264 encoder can still write WebM.

Note

OpenH264 is never part of anything alpha2 publishes: Cisco’s patent licence covers its binary only when the user downloads it from Cisco. In a container image, run the install during the image build, and do not copy the library into an image you publish.

Inspect media files with alpha2

alpha2 works on one file. Run it without arguments to print every command.

Probe

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(...)

It prints the container, its duration and its streams: codec, size, frame rate and color.

Thumbnails

alpha2 thumbnail clip.mp4 poster.png            # the sharpest of nine frames
alpha2 thumbnail clip.mp4 frame.png --at 1.5    # the frame at 1.5 s of the source

Without --at, it picks the sharpest of nine frames spread over the video that is neither black nor white.

Transcode and proxies

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

transcode encodes the video again at its own size, or at half or a quarter of it with --proxy half|quarter, into the container the output’s extension names. Without --video-codec it uses the container’s default codec when the runtime has an encoder for it, and otherwise another codec the container offers; it prints which.

Audio

alpha2 export-audio interview.mp4 interview.wav   # 48 kHz WAV from the source's time zero
alpha2 waveform interview.mp4 10 6                # JSON: min, max and RMS per 10 ms bucket, 6 levels

The commands that decode take --decode-policy strict|tolerant. strict (the default) fails at the first damaged input; tolerant skips damaged input and reports what it skipped.

Next

• CLI reference: every flag of both programs.
• Host protocol: drive alpha2-host serve from any language.
• Node.js and Python: the same host from a library.