Skip to content
alpha2alpha2

Platform support

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

Platforms

Section titled “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 (glibc 2.35 or later; not musl) Vulkan Vulkan Video linux-x64, linux-arm64
macOS 11 or later (Apple silicon; x64 under Rosetta uses the arm64 host) Metal VideoToolbox macos-arm64
Windows x64 Direct3D 12 D3D12VA win-x64
Windows on ARM not supported none

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 the "auto" renderer mode falls back to it.

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

Native archives

Section titled “Native archives”

Each release has one archive per target, alpha2-<version>-<target>-bundled.tar.gz (.zip on Windows), with alpha2-host, alpha2 and the LGPL FFmpeg 8 shared libraries they load. Every archive has a build provenance attestation (gh attestation verify <archive> --repo alpha2-sh/alpha2).

  • Linux: glibc 2.35 or later. Musl systems such as Alpine are refused by the installers, and a host started there fails with HOST_LOAD_FAILED.
  • macOS: an archive downloaded with a browser is quarantined, and the clients refuse it with HOST_QUARANTINED. Run xattr -dr com.apple.quarantine <unpacked dir>, or download with curl -LO.
  • Other platforms: build the host from source with cargo install alpha2-host, against a system FFmpeg 8 (libavutil 60, libavcodec 62), 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 (glibc 2.35 or later) x86_64 and aarch64, macOS arm64 and Windows x64.

Decoding

Section titled “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 auto VideoToolbox
Windows software (measured exports decode no faster on the GPU) D3D12VA, with --video-decode auto

Encoding

Section titled “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

Section titled “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

Section titled “Browsers”
Minimum
Chrome 96
Firefox 89
Safari 26
  • 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

Section titled “Languages and frameworks”
Package Needs
@alpha2-sh/node Node.js 22.21 or later (24.5 or later on Node 24). Also runs in an Electron main process.
alpha2 (Python) Python 3.11.4 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.

See also

Section titled “See also”