Platform support

This page lists where alpha2 0.4 runs and what it needs there. Every target runs the same rendering code, so a project renders the same on each.

Platforms

Platform	GPU	Hardware decode and encode	Archive
Browser	WebGPU; WebGL2 when drawing on a canvas without WebGPU	by the application (WebCodecs)	none
Linux x64, arm64	Vulkan	Vulkan Video	linux-x64, linux-arm64
macOS (Apple silicon)	Metal	VideoToolbox	macos-arm64
Windows x64	Direct3D 12	D3D12VA	win-x64 (bundled only)

Everywhere, the engine also has a CPU renderer for machines without a usable GPU. It draws the same render graph as the GPU, and its pictures are the same bytes on every machine and for any number of threads. It draws every built-in effect and transition; only runtime WGSL effects need a GPU. Natively, --renderer auto (the default) uses it when there is no hardware GPU. In the browser, WebEffectRegistry.createCpu(canvas) makes it, and a render worker’s "auto" renderer falls back to it when there is neither WebGPU nor WebGL2.

The native auto never renders on a software GPU adapter (lavapipe, llvmpipe, WARP, SwiftShader): those draw the same pictures many times slower than the CPU renderer.

Native archives

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

• bundled carries the LGPL FFmpeg 8 shared libraries the programs load. Every target has one.
• thin carries no FFmpeg and loads an FFmpeg 8 installed on the system: on Linux from the system loader’s search path, on macOS from /opt/homebrew/lib, /usr/local/lib or /opt/local/lib. Linux and macOS only.
• Other platforms: build the host from source with cargo install alpha2-host, against a system FFmpeg 8, and point the clients at it with ALPHA2_HOST_PATH.

The alpha2 Python package installs the host as a platform wheel of the same version on Linux x86_64 and aarch64, macOS arm64 and Windows x64. A Linux older than the wheel’s glibc baseline cannot install it.

Decoding

alpha2-host decodes video in one of three modes: software, auto (on the GPU where the device and the stream allow it, on the CPU otherwise) or hardware-required.

Platform	Default	Hardware decoder
Linux	auto	Vulkan Video
macOS	software	VideoToolbox, with --video-decode auto
Windows	software	D3D12VA, with --video-decode auto

Encoding

Native exports encode on the GPU wherever the device and codec allow it. The FFmpeg runtime in the archives also encodes on the CPU with libvpx-vp9 (VP9), libsvtav1 (AV1), mpeg4 (MPEG-4 Part 2), aac and libopus (Opus), so a host without a GPU encoder still writes VP9 or AV1.

The runtime is LGPL and has no software H.264 encoder. H.264 and HEVC come from:

Platform	Encoders
Linux	Vulkan Video (h264_vulkan, on the GPU-resident path only); NVENC (h264_nvenc, hevc_nvenc, av1_nvenc) on NVIDIA GPUs that have an encoder, with driver 530.41.03 or newer
macOS	VideoToolbox
Windows	Media Foundation’s h264_mf (a software transform unless ALPHA2_VIDEO_ENCODER_HYBRID=hardware); D3D12 Video on the GPU-resident path; NVENC with driver 531.61 or newer
Everywhere	Cisco’s OpenH264, when installed

NVENC is offered only after it has encoded a test frame on the machine, so an NVIDIA GPU without an encoder (A100, H100) or a container without the driver’s video capability gets a clear refusal instead of a failed export.

On a machine with no H.264 encoder (CPU-only servers, serverless, arm64 servers, NVIDIA datacenter GPUs), install OpenH264: npx @alpha2-sh/node install --openh264 or python -m alpha2 install --openh264. It downloads Cisco’s binary from Cisco, which is what Cisco’s patent licence requires; alpha2 never ships it. The capabilities request reports encode.h264.status (available, gpu-only or unavailable) with a reason and a remedy.

Windows N and Windows Server

Windows N and KN editions without the Media Feature Pack, and Windows Server without Media Foundation, have no default software H.264 encoder. Install OpenH264 (install --openh264), or export on a GPU with a D3D12 or NVENC encoder.

Browsers

	Minimum
Chrome	96
Firefox	89
Safari	16.4

• Serve .wasm files as application/wasm. Otherwise the loader falls back to a slower way of compiling them and warns.
• Audio preview needs a cross-origin isolated page: Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp. Editing and video preview do not.
• Export encodes with the browser’s WebCodecs encoders, so which codecs a browser exports is the browser’s to say. canEncodeVideoTrack in alpha2/mediabunny (or bridge.videoEncoders() in the editor) asks before an export.
• Without WebGPU or WebGL2 (acceleration turned off, a blocklisted GPU), the CPU renderer draws the preview on the canvas’s 2D context.

This browser:

Languages and frameworks

Package	Needs
@alpha2-sh/node	Node.js 20 or later. Also runs in an Electron main process.
alpha2 (Python)	Python 3.11 or later
@alpha2-sh/react	React 18 or later
@alpha2-sh/editor/react	React 19.3 or a later 19
alpha2 (Rust crate)	Rust 1.88 or later
alpha2 (npm)	The browsers above. TypeScript projects that use alpha2/mediabunny: see Troubleshooting.

Note

Other languages drive alpha2-host serve over its stdio host protocol: any language that can start a process and read and write lines of JSON.

See also

• CLI reference: --renderer, --video-decode and the environment variables.
• Render on a server: containers and CPU rendering.
• Troubleshooting