Skip to content

linux.md

Latest commit

 

History

History
121 lines (82 loc) · 8.07 KB

linux.md

File metadata and controls

121 lines (82 loc) · 8.07 KB
Raw

Linux development

Beam records screens and windows on Linux through the XDG ScreenCast Portal, PipeWire and FFmpeg. Electron never enumerates desktop sources on Linux: the source selector represents the system picker, which opens once during preparation and remains attached across pause/resume.

Electron windows use X11 (--ozone-platform=x11) on Linux, including XWayland on a Wayland desktop. This restores global window placement; HUD popovers stay within compact bounds so transparent added space cannot block desktop clicks. Capture remains the Rust Portal/PipeWire backend, and desktop session environment variables remain intact.

Video editor export uses WebCodecs, independently of the native capture backend. See GPU drivers and WebCodecs export for driver packages, codec/buffer checks and measured Intel results.

Hyprland

When the portal cannot supply cursor metadata, monitor and region recording use Hidden cursor mode plus Hyprland IPC position sampling. The portal mapping ID selects the captured output, including fractional scaling, offsets and rotation. Older portals without a mapping ID require one monitor or a uniquely sized output; ambiguous outputs fail with a diagnostic rather than guessing from focus. IPC sampling runs outside the PipeWire frame callback and stops with the capture; stale positions are discarded. Native cursor shapes and separate-cursor window capture still require portal metadata. Clicks and shortcuts use the protected input helper independently.

Cinnamon on X11

Linux Mint's default Cinnamon/X11 session uses the XApp portal backend, which does not implement the ScreenCast interface. Installing or restarting xdg-desktop-portal or xdg-desktop-portal-xapp alone cannot make Beam record in that session. Beam currently has no direct X11 capture backend.

Use a desktop session with a working ScreenCast portal, such as GNOME or KDE Plasma, and restart Beam. A separately configured ScreenCast backend can also work if it exposes the interface in the active session. Check with:

gdbus introspect --session --dest org.freedesktop.portal.Desktop \
  --object-path /org/freedesktop/portal/desktop | grep org.freedesktop.portal.ScreenCast

Prerequisites

Interaction recording also requires Polkit: pkexec on Debian/Ubuntu, polkit on Fedora, and an authentication agent in the desktop session. Beam's DEB/RPM declare the corresponding runtime dependency. AppImage users install that prerequisite through their distribution. The protected input helper handles Wayland and X11 alike; startup errors are available in Beam Preferences and in Copy system information. Include the package format and whether the authorization dialog appeared when reporting a failure.

  • Node.js 22 or newer and Bun 1.4.2
  • Rust stable
  • Git
  • a C/C++ compiler, Clang development libraries and pkg-config
  • PipeWire development headers and runtime services
  • FFmpeg with the MP4 muxer and either the libx264 or libopenh264 encoder
  • XDG Desktop Portal and the backend for the active desktop environment
  • wl-clipboard on Wayland or xclip on X11 for persistent Quick Snip file copies

Install the native packages for your distribution. The commands below target GNOME; replace only the final portal backend package with xdg-desktop-portal-kde on KDE or xdg-desktop-portal-wlr on a compatible wlroots desktop. Do not install every backend indiscriminately.

Fedora

sudo dnf install \
  gcc clang-devel pkgconf-pkg-config pipewire-devel \
  ffmpeg-free pipewire wireplumber wl-clipboard xclip xdg-desktop-portal \
  xdg-desktop-portal-gnome

Fedora's ffmpeg-free package provides the supported libopenh264 encoder.

Debian and Ubuntu

sudo apt update
sudo apt install \
  build-essential clang libclang-dev pkg-config libpipewire-0.3-dev \
  ffmpeg pipewire wireplumber wl-clipboard xclip xdg-desktop-portal \
  xdg-desktop-portal-gnome

Arch Linux

sudo pacman -S --needed \
  base-devel clang pkgconf libpipewire pipewire wireplumber ffmpeg wl-clipboard xclip \
  xdg-desktop-portal xdg-desktop-portal-gnome

Install the project dependencies once after cloning or when bun.lock changes:

bun install --frozen-lockfile

Verify the native runtime before launching Beam:

pkg-config --modversion libpipewire-0.3
ffmpeg -hide_banner -muxers | grep -w mp4
ffmpeg -hide_banner -encoders | grep -E 'libx264|libopenh264'
systemctl --user --no-pager status pipewire wireplumber xdg-desktop-portal

FFmpeg must report:

  • the mp4 muxer;
  • either the libx264 or libopenh264 H.264 encoder.

Beam checks these capabilities before opening the Portal picker. If FFmpeg is installed outside PATH, set BEAM_FFMPEG_PATH to its executable. A missing executable reports ffmpeg-unavailable; a build without either supported encoder reports ffmpeg-encoder-unavailable.

Start Vite and Electron together in one terminal:

bun run dev

The command checks Cargo first. When Cargo is available, it builds both capture-engine and the filtered beam-input-helper, and stops if compilation fails. Without Cargo, it looks for the exact application version under packages/native-recorder/linux/x64/. If either native file is missing in an interactive terminal, confirm the verified download with Y; answer N to stop. Non-interactive execution never prompts and downloads only with the explicit BEAM_DOWNLOAD_CAPTURE_ENGINE=1 opt-in.

Run bun run dev in each worktree to test them in parallel. Chromium profiles and Vite ports are isolated automatically; projects, screenshots and preferences reuse the shared Videos/Beam/user/ library. Use bun run dev --session preview for another profile in the same worktree. Ctrl+C stops Electron and Vite together. See the session guide for storage locations and shortcut behavior.

The deterministic FFmpeg tests use a fake child process. The opt-in synthetic runtime smoke uses the actual system executable without opening the Portal picker:

cargo test -p capture --lib \
  screen::linux::ffmpeg_process_tests::system_ffmpeg_encodes_a_playable_mp4_segment \
  -- --ignored --exact

A real monitor/window smoke remains interactive and must be run manually because the Portal requires explicit user consent.

Quick Snip publishes completed files through wl-copy on Wayland and xclip on X11. These tools keep the clipboard selection alive independently of Beam's windows, with no expiration or single-paste limit; replacing the clipboard ends their ownership. DEB/RPM packages declare both dependencies. Development and AppImage installations need the appropriate tool on PATH. Missing tools or failed publication are shown as copy errors, with the exported file retained for retry.

On Wayland compositors without a data-control protocol, wl-copy obtains selection access through a temporary native surface. The compositor may briefly focus that surface. Beam bounds acquisition to ten seconds and reports failure if ownership cannot be obtained; this deadline never expires a successful copy.

Click and shortcut metadata also requires Polkit authorization. Enable interaction recording once in HUD preferences; Beam retains that choice and resumes the helper automatically, including after helper updates. Quick Snip recording starts the helper as part of preparation when it requests interactions. Cancelling authorization cancels preparation, and failures remain visible without erasing saved consent. On Linux, turning this setting off disables both keyboard shortcuts and click metadata for normal recordings. Do not add the developer account to the input group: that would grant the entire Electron process broad access to every raw input device. Development, AppImage, RPM and DEB use the same filtered helper protocol and write structured events to cursor/input.json.

Repository rules still apply to documentation and non-capture changes: