Linux is a public Alpha on its way to Beta. Since 0.9.122 every
<version>-alpha.1 Linux AppImage has been published through the signed-in
videorc.com download under an owner waiver: no physical acceptance pass
was ever performed (docs/acceptance/linux-alpha/*.json, performed: false;
0.36.0 is the latest). The Beta bar, the supported desktops and the parity
matrix against macOS live in
plan 257. The L-phases below are the original
delivery history of the port; each has an implementation, and the status
column says what is still short.
| Area | Alpha baseline | Current status |
|---|---|---|
| Distribution | Ubuntu 24.04 LTS (the CI build and packaging box) | Shipped as an AppImage built on Ubuntu 24.04; supported desktops are the Tier table below |
| Architecture | x86_64 | x64 only; arm64 is not in Beta |
| Display session | Wayland first | Wayland is the Tier 1 session; X11 is best effort (global shortcuts work there, not on Wayland) |
| Screen/window capture | xdg-desktop-portal backed by PipeWire |
Works (L4). CPU copy into BGRA, no DMA-BUF; one stream, no resolution-change follow; no app scenes or Follow front app (no Wayland API) |
| Camera | V4L2 | Works, degraded (L3): an FFmpeg -f v4l2 child scales on the CPU (about 180 % CPU at idle with ogre's FaceTime camera, plan 257 audit); no hotplug until restart |
| Audio | PipeWire | Microphone through pipewire-pulse (L2). Desktop/system audio is missing. Live captions are not available yet |
| Preview | CPU composition and BMP transport | Works, degraded (L5): the Electron proof surface polls per-source BMPs on the CPU and Health reports "Fallback"; no live canvas on the Scene tab |
| H.264 encode | VAAPI hardware, OpenH264 software fallback | VAAPI is probed per render node, OpenH264 is the fallback (L1.5). The hardware acceptance evidence was never committed, so VAAPI is not yet the proven default; no NVENC arm |
| Packaging | AppImage | Shipped (L6), unsigned, public Alpha under owner waiver. No self-update: the app only shows a changelog notice |
| Videorc Camera (plan 214 D) | v4l2loopback: the user installs the module, the app loads it with pkexec modprobe … exclusive_caps=1 card_label="Videorc Camera" video_nr=42 and writes YUYV 1080p30 to the device found by name |
Written and compiled by the Linux CI job; hidden (PROVEN = false in virtual_camera_linux.rs) until spike P0c passes on a named box |
| Tier | Distro and desktop | Session | GPU and encoder |
|---|---|---|---|
| 1 (beta-supported, in acceptance) | Ubuntu 24.04 LTS, GNOME 46+ | Wayland | Intel iHD or AMD radeonsi VAAPI |
| 1 | Arch-family (Omarchy) with Hyprland 0.5x (ogre) | Wayland | Intel iHD VAAPI; OpenH264 fallback |
| 1 | Fedora 41+ KDE Plasma 6 | Wayland | VAAPI |
| 2 (best effort, bug reports accepted) | The same distros on X11; Sway and other wlroots; Debian 13; Linux Mint | Either | VAAPI, NVENC (after plan 257 S6), OpenH264 |
| Not supported | VMs, arm64, Ubuntu 22.04 and older (old PipeWire and portal) | n/a | n/a |
Minimums: PipeWire 1.0 or newer with pipewire-pulse, xdg-desktop-portal 1.18
or newer with the desktop's backend, a Secret Service (gnome-keyring or
KWallet), and the user in the video and render groups.
Ubuntu 24.04 GNOME Wayland is the packaging baseline and a Tier 1 desktop, but no Ubuntu box has ever run an acceptance pass (plan 257 D2, owner-owed). The encoder contract in L1.5 is distribution-independent and is accepted from any named physical Linux x64 box (see "Named tester boxes").
Wayland capture must go through the desktop portal rather than bypassing the user-consent boundary. PipeWire is required for screen capture and audio; V4L2 owns the first camera path. Exact portal, PipeWire, VAAPI, and window-system development packages should be added only when the phase that uses them proves the dependency is necessary.
Videorc ships an LGPL-only FFmpeg distribution. Linux must never select or
bundle libx264, because that would introduce GPL requirements incompatible
with the product's open-core distribution model.
The Linux encoder decision is:
- probe
/dev/dri/renderD*with the exact staged FFmpeg binary and select VAAPI only when a realh264_vaapiencode succeeds; and - use OpenH264 as a supported software fallback when automatic VAAPI probing fails.
VIDEORC_LINUX_H264_ENCODER=auto|vaapi|openh264 controls the selection. auto
is the default. Forced vaapi fails session startup if the probe fails; forced
openh264 chooses the software path directly. Automatic or explicit OpenH264
selection is logged and exposed in diagnostics without raising a health alert.
A VAAPI probe on the wrong GPU can hang the whole host (ogre, 2026-09-24: the amdgpu node lost its command stack, firmware recovery failed, and the session collapsed into an unclean reboot). The probe timeout cannot rescue a kernel GPU hang, so the policy keeps the app from touching a bad node at all:
VIDEORC_LINUX_VAAPI_DEVICE=/dev/dri/renderDNNNpins the probe to one node. With the pin set,autoandvaapiprobe that node only; a value that is not an existing render node is a typed startup error.- Before probing a node the backend writes
<app data>/linux-vaapi/probe-in-progress.json(node,driver,startedAt,ffmpegSha) and deletes it when the probe returns, pass or fail. A file still present at the next backend start means the previous backend died mid-probe (the host hung or was rebooted, the backend was killed): the node is appended to<app data>/linux-vaapi/quarantined.json, logged atwarn, listed in diagnostics, and never probed again unless the pin names it explicitly. A probe future dropped in-process (a cancelled session start, quit mid-probe) clears its own sentinel: the process is still alive, so the node did not hang the host. - A probe still running after 20 s is the same hang seen from inside the
process (#1027): FFmpeg is killed and reaped, the node is quarantined on
the spot with
timedOutAfterSecs, thecompatargument profile is never tried on it (a timeout is not an argument rejection), and no further node is probed in that backend lifetime, because the timed-out FFmpeg may still hold its GPU and the driver may be mid-reset. The nodes left over are listed asskippedand probed at the next start. cargo test -p videorc-backendnever probes a render node and never reads or writes the real quarantine: a unit test gets a throwaway quarantine directory under the temp dir unlessVIDEORC_DATABASE_PATHisolates one, and the resolver answers "unit tests never probe render nodes" unlessVIDEORC_LINUX_VAAPI_DEVICEnames the one node a test may use.- The backend probes once per lifetime per FFmpeg path and caches the
decision; sessions do not re-probe. A forced
openh264session does not invalidate the cached VAAPI decision. - The probe runs the session's real encode arguments and filter chain at the session's resolution, not a 128x72 black clip, so a probe pass predicts a session pass.
- Diagnostics list every render node with its driver (the basename of
/sys/class/drm/<node>/device/driver) and probe state:probed-ok,rejected,quarantined, orskipped. - The driver is evidence, not policy. There is no amdgpu or other driver blocklist; most amdgpu boxes encode fine through VAAPI. The quarantine file is box-local state.
| Box | Hardware | Distribution / session | Render nodes | Role |
|---|---|---|---|---|
| ogre | T2 MacBook Pro, Intel UHD 630 (Coffee Lake) + Radeon Pro 555X, FaceTime HD camera | Omarchy 4.0.4 (Arch family), Hyprland / Wayland, PipeWire + xdg-desktop-portal-hyprland |
renderD128 i915, allowed; renderD129 amdgpu, quarantined after the 2026-09-24 host hang |
Named physical tester for L1.5 through L5 |
Beta needs a second named Tier 1 box, an Ubuntu 24.04 x64 machine (plan 257 D2, owner-owed), for the AppImage and updater evidence; ogre does not substitute for it. Until that box exists AMD VAAPI, GNOME, KDE and Ubuntu's Secure Boot path cannot be accepted.
The binary pin lives in vendor/ffmpeg/linux-pin.json. Run
pnpm ffmpeg:fetch:linux on Linux x64 to download and stage it. The fetch step
checks the SHA-256, executes the binary, and fails closed unless the build is
LGPL-only, enables VAAPI and OpenH264, disables x264/x265/fdk-aac, and exposes
both h264_vaapi and libopenh264 encoders. Linux CI repeats this check.
Second ogre run (2026-09-24, on Plan 052): OpenH264 records in-app; the only
matrix gap was missing color_primaries/color_transfer in the OpenH264
bitstream, now closed by the SPS VUI rewrite. VAAPI on renderD128 rejects
the standard argument set with "Failed to end picture encode issue: 24"
while a plain CLI encode passes. The probe therefore tries a compat set
(CBR, no B-frames, no level pin) after the standard set fails on the same
node; that compat set is provisional until the bisect on the box confirms
which argument the iHD driver rejects (Plan 053, S3).
- Compile the backend natively on Ubuntu.
- Run clippy with warnings denied and the backend unit suite on every pull
request and push to
main; the main CI workflow owns platform-independent Rust formatting. - Keep shared geometry and pixel conversion outside Apple-only modules.
- Return explicit unsupported results for runtime paths with no Linux backend.
The Linux and Windows clippy gates run with warnings denied and no lint allow
list. Code that only one platform uses is fenced with cfg at its definition
rather than allowed crate-wide.
- Pin and verify the Linux x64 LGPL FFmpeg bundle.
- Select a probed VAAPI render node per session, with OpenH264 as the named software fallback.
- Preserve BT.709/video-range tags, profile/level, keyframe cadence, bounded rate control, and truthful backend diagnostics.
- Keep
libx264, GPL, and nonfree builds out of provisioning and runtime args.
The code and CI contract are implemented. A named physical Linux machine has never committed the evidence that proves both the VAAPI path and the software fallback (plans 052 and 053 still own it); the Alpha releases went out under owner waivers without it. Beta needs that evidence (plan 257 S5).
Run the hardware-only acceptance command on a named physical Linux x64 tester
box (the distribution is recorded in the evidence, not gated). It requires a
webcam, a VAAPI render node, and explicit tester/machine labels; it fetches
the pinned FFmpeg bundle, records 1080p30 through the real dev app once per
forced backend, checks the final artifacts and diagnostics, and writes
linux-encoder-acceptance.json beside the recordings. On a multi-GPU box set
VIDEORC_LINUX_VAAPI_DEVICE first; the pin is recorded too. Run the direct
matrix command from linux-dev-loop.md with the software backend before the
first acceptance attempt on a new box:
VIDEORC_LINUX_TESTER_NAME="<person>" \
VIDEORC_LINUX_TESTER_MACHINE="<specific box>" \
VIDEORC_LINUX_PHYSICAL_HARDWARE=1 \
pnpm smoke:linux-encoder-acceptance--backend=openh264 or --backend=vaapi may be used to diagnose one path,
but only the default two-backend run emits complete: true evidence and clears
the L1.5 hardware gate. CI runners and virtual machines are not substitutes.
The Linux camera is v4l2loopback (docs/linux-dev-loop.md has the tester
steps). No Mac compiles its cfg(target_os = "linux") writer, so the Linux
CI job is its compile gate and spike P0c on a named box is its behaviour
gate: ffmpeg -f v4l2 -i /dev/video42 reads 30 fps for 10 s and Chrome
Meet lists the camera only while the switch is on. Until P0c passes,
virtual_camera_linux::PROVEN is false, platform_sink answers
hidden_until_proven("Linux"), the status reports platformStep: unsupported and the Output page shows no section; flipping that one
constant turns it on. The pure half (module detection, the state table,
the V4L2 ABI mirror) is tested on every platform. The needs-setup
message is the distribution's install command alone (the page shows it as
one copyable line; absent when the distribution is unknown); a load the
kernel refuses under Secure Boot comes back as a failed step with the
Machine Owner Key words. No kernel module is bundled, built or signed
(D9). STOP (plan 214): if the baseline box cannot load the module under
Secure Boot, Linux ships guidance only.
This was the rule for building L2 onward: a named Linux tester and a specific
physical Linux x64 machine had to be recorded in "Named tester boxes" and the
L1.5 evidence had to be complete: true. L2 through L6 were then built and
shipped as an Alpha under owner waivers without that evidence. Beta removes the
waiver: virtual machines and CI runners still do not satisfy the gate, and both
Tier 1 boxes need a physical acceptance pass (plan 257 D11).
- Discover and ingest microphone audio through PipeWire.
- Preserve mute/gain, sample format, reconnect, and explicit unavailable-state behavior behind the shared source contracts.
- Prove the phase with deterministic tests and a real-device audio artifact.
- Discover and capture cameras through V4L2.
- Preserve stable source identity, format negotiation, switching, reconnect, and explicit unavailable-state behavior.
- Camera access depends on
videogroup membership (andrenderfor the encoder node); a missing group must surface as an explicit permission state with the fix named, never as a silent "no camera". - Prove a camera-only recording on the named tester hardware.
- Implement Wayland-first screen/window capture through
xdg-desktop-portaland PipeWire. - Model portal consent, cancellation, revoked sessions, missing sources, and reconnects as explicit states and diagnostics.
- Prove source switching and lifecycle behavior on the real Linux desktop.
- Status (Plan 0006, 2026-09-25): first cut landed.
linux_portal_capture.rs(state model, restore-token store, BGRA copy, device entries; unit-tested on every platform),linux_portal_session.rs(ashpd session runner) andlinux_pipewire_stream.rs(pipewire reader) feed the shared screen frame store;pnpm smoke:linux-portal-captureis the box gate. Reconnect after revoke is a restart with the saved token, not an in-place reconnect, and DMA-BUF import is not done.
- Reuse shared scene geometry in a Linux CPU compositor.
- Add the maintained JPEG preview transport with first-frame, liveness, backpressure, detach/reattach, and truthful fallback diagnostics.
- Prove composed recording and preview behavior without claiming a GPU-native preview surface.
- Status (Plan 0007, 2026-09-25): the Electron proof surface (uncompressed
latest-wins BMP per source,
electron-proof-surface/electron-browser-window) is the Linux preview, fed by the CPU compositor and the L4 portal screen store. Backend, supervisor, renderer and waiting copy name it "Linux CPU preview" and never a native surface;pnpm probe:preview-lifecycle:linux(VIDEORC_EXPECT_LINUX_PROOF=1) is the box gate.pnpm smoke:portal-preview-proofis the Phase D gate: grantedscreen:portal:monitor+ ScreenOnly must showsourcePixelsPresent=trueonelectron-proof-surface(not synthetic). A composed-frame (single BMP) transport is not done; the proof surface layers per-source BMPs like Windows.
-
Status: shipped as a public Alpha under owner waiver (
docs/acceptance/linux-alpha/).electron-builder.ymlhas a Linux AppImage+dir target;pnpm package:desktop:linux+preflight-linux-package.mjsstage the release backend and pinned LGPL FFmpeg..github/workflows/release-linux-alpha.ymlbuilds an unsigned Ubuntu 24.04 x64 AppImage and stores it as a private candidate undercandidates/linux-alpha/<releaseId>/<sourceCommit>/. There is no promote workflow: the release owner publishes the create-onlyreleases/linux-alpha/<releaseId>/release.json(with the commit-pinned owner-waiver record URL) and the videorc-web download manifest env, and the signed-in videorc.com download serves it. The in-app update is a changelog notice, not an updater: thelatest-linux.ymlfeed is not published, so Linux never self-updates. -
Still owed for Beta (plan 257): a promote workflow with a signature and
.sha256per release, AppImage self-update from a published feed, packaged smoke on a named Ubuntu 24.04 box, and a physical acceptance pass on both Tier 1 boxes with no waiver. -
Build an Ubuntu 24.04 x64 AppImage with the verified LGPL FFmpeg payload.
-
Use an isolated Linux lane under
releases/linux-alpha/; never reuse or mutate the macOS Beta or Windows Alpha manifests. -
Add packaged-app device, recording, streaming, updater, and cleanup smokes.
-
Beta publishes Linux only after dated real-device evidence on both Tier 1 boxes meets the same quality and lifecycle bar as the other shipping platforms; the Alpha lane has used an owner waiver instead.
The linux/phase0-compile branch of
ForrestKnight/videorc-linux
was used as a reference for identifying platform seams, including moving the
source-mask model out of the Metal implementation. Its stale branch is not
merged or cherry-picked: changes are re-derived against current Videorc code.
Its GPL libx264 encoder choice is explicitly rejected by this plan.
Contributor coordination and DCO confirmation are tracked in
#247.