FF00-vwm

FF00-vwm is a graphical per-monitor video wallpaper manager for Linux X11. Pick an output, choose a local video with the system file dialog, select a display mode, and apply it. The wallpaper continues running after the configuration window closes.

Alpha software: 0.1.0-alpha.1 is the first public preview. It is intended for testing on personal X11 desktops, not unattended or production systems. Configuration and packaging details may change before 1.0.0.

Features

• Independent video assignments for connected XRandR outputs.
• A native GTK4 interface and system file chooser.
• Fit, Fill, Stretch, and Center display modes.
• Detached wallpaper processes using mpv, without xwinwrap.
• Saved assignments and optional restore at X11 login.
• Targeted process ownership checks that leave unrelated mpv processes alone.
• GUI and headless lifecycle controls.
• No telemetry, accounts, network service, or automatic downloads.

Supported environment

The first alpha supports Linux x86_64 in an X11 session. i3 is the primary tested window manager. Wayland, Flatpak, ARM, network videos, audio playback, playlists, and animated-image formats are not supported in this release.

FF00-vwm requires mpv 0.36.0 or newer. Native builds also require the GTK4 and X11 runtime libraries supplied by the operating system. The Nix package provides the tested runtime dependencies itself.

Try it with Nix

After the release tag is available on the GitHub mirror:

nix run 'github:crimsonvariable/ff00-vwm?ref=v0.1.0-alpha.1'

From a local checkout:

nix --extra-experimental-features 'nix-command flakes' run .

The Nix package includes mpv on the application's runtime path. It does not change system configuration or enable login restoration.

Native archive

Download the archive and SHA256SUMS from the matching prerelease, verify it, extract it, and run the user-local installer:

sha256sum --check SHA256SUMS
tar -xzf ff00-vwm-0.1.0-alpha.1-x86_64-linux.tar.gz
cd ff00-vwm-0.1.0-alpha.1-x86_64-linux
./install.sh

The default destination is ~/.local. Ensure ~/.local/bin is on PATH, then run ff00-vwm. The archive does not bundle mpv or modify the system package manager. Install mpv and GTK4 through the distribution first.

To install under another user-controlled prefix:

./install.sh --prefix /absolute/path

To remove exactly the files recorded by the installer:

~/.local/bin/ff00-vwm-uninstall

The native archive uses Debian 12 as its build baseline. It may not run on an older distribution; use the Nix package or build from source in that case.

Usage

Launch ff00-vwm without arguments for the graphical interface. Choose a video for each connected output, select its display mode, and apply it. Login restore is opt-in and can be enabled or disabled in the application.

The headless commands are:

ff00-vwm apply    # apply saved assignments to connected outputs
ff00-vwm refresh  # rediscover geometry and reapply assignments
ff00-vwm status   # show dependency, output, assignment, and renderer state
ff00-vwm stop     # stop only renderers owned by FF00-vwm

Configuration follows the XDG base-directory convention. On a typical Linux desktop it is stored at ~/.config/ff00-vwm/config.toml. Runtime ownership records are kept below the user runtime directory and are not shared between users.

Building from source

The reference development environment is the locked Nix flake:

nix --extra-experimental-features 'nix-command flakes' develop
cargo build --locked

A conventional Cargo build needs Rust 1.85 or newer, GTK4 development files, pkg-config, and X11/XRandR development files. Run the release checks with:

cargo fmt --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-features
cargo audit
cargo deny check
nix --extra-experimental-features 'nix-command flakes' flake check

Roadmap

The first update after 0.1.0-alpha.1 is lifecycle hardening: serialize controller operations with a dedicated runtime lock, reconcile stale and orphaned renderer ownership without broad process matching, and isolate the mpv renderer with --no-config. Static-image sources, including presentation-only rotation and mirroring, follow that reliability milestone.

See TODO.md for the ordered acceptance checklist and docs/ARCHITECTURE.md for the reasoning and safety boundaries.

Safety and privacy

FF00-vwm passes video paths directly to mpv as arguments and does not interpolate them into a shell command. It records and validates the renderer processes that it owns before signalling them. It does not send selected filenames, display details, analytics, or other data over the network.

See SECURITY.md for private reporting instructions. As with any alpha release, back up important configuration and review the known limitations in the release notes before use.

Repositories and contributions

Forgejo is the canonical development repository and source of truth. GitHub is a public release mirror. Issues, design discussions, and contributions belong on Forgejo; GitHub pull requests are not merged.

Read CONTRIBUTING.md before proposing a change. Contributions require an executed Contributor Copyright Assignment Agreement.

License

FF00-vwm is licensed under AGPL-3.0-or-later. Copyright and dual-licensing authority are documented in COPYRIGHT.md. Third-party projects remain subject to their own terms; see THIRD_PARTY_NOTICES.md and THIRD_PARTY_LICENSES.txt. Typeface attribution is recorded in TYPEFACE_CREDITS.md.

This project is independent and is not affiliated with or endorsed by mpv, GTK, the Rust project, X.Org, i3, NixOS, or any Linux distribution.