CLI reference

This page lists every command of the two native programs in the release archives: alpha2-host, which renders and exports projects, and alpha2, which works on one media file at a time. For how to get them, see CLI. Both use FFmpeg 8 to decode and encode.

Run either program without arguments to print its usage. Arguments must be UTF-8: an argument that is not fails with INVALID_INPUT naming it.

alpha2-host

alpha2-host serve
alpha2-host conform --project <project.json> --asset <source-id>=<path> ...
alpha2-host export  --project <project.json> --asset <source-id>=<path> ... --out <output>

Subcommand	What it does
export	Renders a project and encodes it to an MP4, MOV, Matroska or WebM file. Prints the result as JSON on standard output and progress on standard error.
conform	Checks a project’s media without rendering and without a GPU. Prints a report and exits 1 when something blocks the export.
serve	Reads requests on standard input and answers on standard output, one JSON object per line: the host protocol. Takes no flags.

alpha2-host export

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

On success it prints {"ok": true, "output": "<path>", "result": {...}} on standard output, where result is the export result (frames, encoder, rate control, timing, which media each source read; typed as NativeExportResult in @alpha2-sh/node). Progress lines (alpha2-host export: frames 12/30) go to standard error. On failure the message goes to standard error and the exit status is not 0.

The output must not exist yet unless you pass --overwrite. The export writes <stem>.alpha2-partial.<ext> beside it and renames that into place when it is complete.

Inputs

Flag	Value	Default	Meaning
--project	path	required	The project document, as UTF-8 JSON.
--asset	<source-id>=<path>	none	The file of one source. Repeat for each source the export reads.
--proxy	<source-id>=<path>	none	A proxy made from a source’s original. Repeat for several, in order of preference.
--media	original, proxies	original	proxies reads fresh proxies where there are some, and originals elsewhere.
--frames	<source-id>=<path>,<path>,...	none	The frame files of an image sequence, in order. An empty path is a gap.
--resource	<source-id> <locator> <path> (three values)	none	A file an SVG source’s <image href> or a Lottie source’s image assets name, by the locator the source writes.
--effect-asset	<resource-id>=<path>	none	The file of one of the project’s effect resources, such as a .cube LUT.
--effects	path	none	A JSON array of runtime effect definitions the project uses besides the built-in ones.
--font	path	none	A font file for captions, text and SVG text. Repeat in fallback order. A project that shows text needs at least one.

Range and rate

Flag	Value	Default	Meaning
--start-ticks	integer	0	Start of the range, in ticks (120,000 per second).
--end-ticks	integer	the timeline’s end	End of the range. By default, where the last thing on the timeline ends, caption cues included. Required for a project that shows nothing.
--frame-rate	<num>/<den>	the project’s frame_rate	The output frame rate, for example 30000/1001.

The range is widened to the frame grid.

Output

Flag	Value	Default	Meaning
--out	path	required	The file to write. Its extension (.mp4 or .m4v, .mov, .mkv, .webm) names the container unless --container does, and must match it.
--overwrite		off	Replace a regular file at --out once the export is whole. A failed or cancelled export leaves it as it was.
--container	mp4, mov, mkv, webm	from the extension
--no-audio		audio on	Leave the audio track out. (--include-audio turns it back on.)
--video-codec	h264, hevc, vp9, av1, mpeg4-part2	the container’s	One the container offers (table below).
--video-encoder	FFmpeg encoder name	chosen by the host	Pin an encoder, for example openh264 or h264_nvenc. It must be one capabilities reports for the codec.
--video-quality	very-low, low, medium, high, very-high, or bits per second	high	A level, which the host turns into a rate for the codec, size and frame rate, or a bitrate.
--video-quantizer	integer, 0 to 255	none	A constant quantizer on the codec’s scale. Needs --video-quality <bits-per-second> as its fallback.
--audio-codec	aac, opus	the container’s
--audio-quality	a level, or bits per second	high
--loudness-target	LUFS, −60 to 0	none	Normalize the audio to this integrated loudness (EBU R128 / ITU-R BS.1770-4).
--true-peak-ceiling	dBTP, −20 to 0	-1	The true-peak ceiling for --loudness-target. Only with it.

Each container offers the codecs its mainstream players decode there. The first of each is the default:

Container	Video	Audio
mp4	h264, hevc, vp9, av1, mpeg4-part2	aac, opus
mov	h264, hevc, mpeg4-part2	aac
mkv	h264, hevc, vp9, av1, mpeg4-part2	aac, opus
webm	vp9, av1	opus

A codec the container does not offer, or one this host cannot encode, is refused with INVALID_INPUT before anything opens.

Rendering and pipeline

Flag	Value	Default	Meaning
--renderer	auto, gpu, cpu	ALPHA2_RENDERER, else auto	auto renders on a hardware GPU when there is one and otherwise on the CPU, never on a software adapter. gpu takes any adapter and fails with GPU_INIT_FAILED without one. cpu opens no graphics driver.
--video-decode	software, auto, hardware-required	ALPHA2_VIDEO_DECODE, else auto on Linux, software on macOS and Windows	How video is decoded. hardware-required fails instead of decoding a frame on the CPU.
--input-policy	auto, gpu-required, cpu-readback	auto	How frames reach the encoder: auto stays on the GPU where it can and reads back otherwise; gpu-required fails with GPU_OUTPUT_UNAVAILABLE instead; cpu-readback always reads back.
--strategy	render, prefer-copy, require-copy	render	prefer-copy copies the sources’ compressed packets when the range shows them untouched, and renders otherwise. require-copy fails with COPY_INELIGIBLE instead of rendering.
--render-cache	directory	none	Keep rendered frames there, so a later export of the same project, files and effects by the same host build on the same GPU reuses them.
--render-cache-quota	bytes	4 GiB	The cache’s size limit. Only with --render-cache.
--render-cache-backlog	skip, wait	skip	When the cache writer is full, skip leaves the frame out of the cache and wait holds the export until the writer has room. Only with --render-cache.

alpha2-host conform

alpha2-host conform --project project.json --asset video-1=clip.mp4

Prints {"ok": <ready>, "result": {"catalog": ..., "report": ...}}: what the host found for each source, and per source what the purpose reads and its issues. It exits 0 when the media is ready and 1 when an issue blocks, with a CONFORM_FAILED message on standard error. It needs no GPU.

Flag	Value	Default	Meaning
--project	path	required	As for export.
--asset	<source-id>=<path>	none	As for export.
--proxy	<source-id>=<path>	none	As for export.
--frames	<source-id>=<path>,...	none	As for export.
--purpose	preview, preview-proxy, thumbnail, remote-edit, export-original, export-proxy	export-original	What the media is read for.
--video-decode	software, auto, hardware-required	as for export

conform parses the same flags as export and ignores the others.

alpha2-host serve

alpha2-host serve takes no flags. It answers capabilities, conform, export and still requests until its standard input ends. Its renderer and decode mode come from ALPHA2_RENDERER and ALPHA2_VIDEO_DECODE. See Host protocol.

Diagnostics

Builds with GPU encoding also have alpha2-host probe-gpu-encode [width] [height] (1920×1080 by default), which tries the GPU-resident encode path and reports what it finds. It is not in the usage text and is meant for diagnosing a machine.

Environment variables

Variable	Meaning
ALPHA2_RENDERER	auto, gpu or cpu, when --renderer is not given (and always for serve).
ALPHA2_VIDEO_DECODE	software, auto or hardware-required, when --video-decode is not given.
ALPHA2_RENDER_THREADS	Threads of the CPU renderer. By default, every thread the process may run on.
ALPHA2_GPU_ADAPTER	On Windows, which GPU renders on a machine with several: default (or unset; the first in high-performance order), encoder (the first that encodes H.264 on the GPU), a number (the adapter’s position), or text the adapter’s name contains. A value that names no adapter refuses to start.
ALPHA2_DECODER_SESSION_BYTES	The decoder session budget, 4 GiB by default.
ALPHA2_DECODER_SESSIONS	The number of video decoder sessions, 1 to 32, instead of the budget.
ALPHA2_OPENH264	0 keeps the host from using OpenH264.
ALPHA2_OPENH264_LIBRARY	Path of an OpenH264 library to load. Its SHA-256 must be Cisco’s unless ALPHA2_OPENH264_UNVERIFIED=1.
ALPHA2_VIDEO_ENCODER_HYBRID	On Windows, hardware asks Media Foundation for its hardware H.264 encoder.
ALPHA2_HOST_CACHE_DIR	The cache that npx @alpha2-sh/node install and python -m alpha2 install unpack into, and where the host looks for OpenH264.

Exit codes

Status	When
0	Success. For conform, the media is ready.
1	Any failure: invalid flags or input, missing media, a failed export, CONFORM_FAILED. Also a host whose GPU device was lost or whose decoder or encoder thread got stuck, which exits after answering.
70	GPU_INIT_FAILED: the host could not create its GPU device.
101	The host panicked (a defect).
128 + signal	Cancelled by a signal on Linux and macOS: 130 for SIGINT, 143 for SIGTERM. A running export stops and removes its partial file first.
130, 143	On Windows, a console control event: 143 when the console is closing, else 130.

Note

The error code (INVALID_INPUT, MISSING_INPUT, EFFECT_ERROR and so on) is in the message on standard error. Through serve and the Node.js and Python clients it is a field of the error. See Validation and errors.

The alpha2 program

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]

Command	What it does
probe <media>	Prints the container, its duration and its streams (codec, size, frame rate, color). Durations are in ticks.
thumbnail <media> <out.png> [--at <seconds>]	Writes one frame as PNG: the frame at a time on the source’s own timeline, or by default (--auto) the sharpest of nine frames spread over the video that is neither black nor white.
transcode <media> <out> [--proxy half|quarter] [--video-codec <id>]	Encodes the video again at its own size, or at half or a quarter of it for a proxy, into the container the output’s extension names. Without --video-codec it uses the container’s default codec (H.264, or VP9 for WebM) when the runtime has an encoder for it that takes frames from memory, and otherwise another codec the container offers; it prints which. HDR input is refused.
export-audio <media> <out.wav>	Decodes the audio, resampled to 48 kHz, into a WAV file that starts at the source’s time zero.
waveform <media> [bucket-ms] [levels]	Prints a waveform summary as JSON: the minimum, maximum and RMS of each bucket of samples (10 ms by default), at that size and at coarser levels each four times the last (6 levels by default).

The usage text also lists commands for checking a machine and a file: decode and decode-audio (decode every frame or sample and print counts), render <media> <out.png> (the first video frame as PNG), probe-encoders [width] [height] (which video encoders open and encode, at 1920×1080 by default) and, on Linux, probe-hwdecode <media> [frame-limit] (Vulkan Video decoding, 120 frames by default).

--decode-policy

The commands that decode (decode, decode-audio, render, thumbnail, transcode, export-audio, waveform) take --decode-policy strict|tolerant:

Value	Meaning
strict	Fail at the first damaged input. The default, unless ALPHA2_DECODE_POLICY says otherwise.
tolerant	Skip damaged input and report what was skipped when the command ends.

alpha2 exits 0 on success and 1 on any failure, with the message on standard error.

Related commands

The client packages have their own small command lines:

Command	What it does
npx @alpha2-sh/node install [--thin | --openh264] [--force]	Downloads the alpha2-host archive of the package’s version into the host cache, or Cisco’s OpenH264 with --openh264. --thin takes the archive that loads the system’s FFmpeg 8 (not on Windows). --force downloads again.
python -m alpha2 install [--thin | --openh264] [--force]	The same, from Python, into the same cache.
python -m alpha2 export <project> <output>	Exports with --asset, --font, --start-ticks, --end-ticks, --no-audio, --video-codec, --video-quality, --json and --host.
python -m alpha2 still <project> <output.png> --at <seconds>	Renders one frame to PNG, with --asset, --font, --size <w> <h>, --overwrite, --json and --host.
python -m alpha2 capabilities	Prints what the host can decode and encode.

See also

• CLI: getting the programs and a first export.
• Host protocol: serve’s requests and errors.
• Render on a server: renderers, containers and queues.
• Platform support