Native media server + desktop player focused on zero‑copy HDR on Wayland and low‑latency animated browsing.
A Rust‑native media server and player focused on delivering a smooth and low latency experience with hardware‑accelerated playback. Ferrex isn’t a cloud service or web app—it’s a tightly integrated native server + desktop player optimized for high‑refresh UI, zero‑copy video, and smooth animated poster grids.
- Feels local, because it is: batched rendering of custom UI primitives keeps latency spikes in check as you fling through high‑DPI posters.
- Zero‑copy HDR on Wayland: a Wayland‑subsurface path makes use of bleeding edge GStreamer HDR developments to preserve metadata and avoid expensive copies.
- Pragmatic elsewhere: on other platforms, Ferrex can hand off to mpv.
Status: pre-alpha (0.1.0-alpha). Expect rapid changes while core surfaces continue to stabilize.
Existing home media tools are flexible but often not fast in the ways that feel satisfying and enjoyable to use. Ferrex is an experiment in interactive performance as a first class feature.
Self‑hosters and performance‑minded enthusiasts who value a fluid desktop experience and want to make use of their hardware efficiently—especially on Wayland, where full HDR zero‑copy playback relies on the GStreamer 1.27.x development series for correct HDR metadata passthrough (tested with GStreamer 1.27.50 as of 2025-12-30). Windows and macOS may utilize mpv hand‑off or the alternate player backend that does not include any HDR passthrough or tone-mapping.
- Responsive UI across sorting, filtering, and searching large libraries.
- Animated poster grids that stream in as fast as your GPU can swallow textures.
- Keyboard driven and animated UI navigation/scrolling.
- Wayland HDR pipeline with a subsurface strategy tailored for native output.
- mpv hand‑off with watch status tracking maintained.
- Visit the showcase at ferrex.lowband.me.
- Fastest way to try it: see Demo Mode to seed a disposable library.
- Docker + Docker Compose
- Rust toolchain (stable 1.90+, edition 2024)
- just (https://github.com/casey/just)
- Linux: GStreamer + FFmpeg development headers (see the CI workflow for the current package list)
- mpv (optional; currently required on windows for playback)
# from repo root
just start
# equivalent: ferrexctl stack upjust run-player-releaseThis bootstraps configuration, generates strong Postgres credentials into .env in the project root, and launches Postgres, Redis, and the Ferrex server. Keep .env backed up—it contains generated passwords.
More options (profiles, logging, tailscale, host vs docker server): see Configuration and the Contributing Guide.
-
Linux / Wayland: primary target. Zero‑copy HDR pipeline via GStreamer (dev 1.27.x) and Wayland subsurfaces.
- Tested environment: Arch Linux (Hyprland WM). Please report results for GNOME/KDE/wlroots compositors.
- Player specifics and platform notes: see ferrex-player/README.md.
-
Other platforms: playback via the cross‑platform backend or "Open with MPV" from detail views.
| Platform | Playback path | HDR passthrough | Zero‑copy | Status |
|---|---|---|---|---|
| Linux (Wayland) | GStreamer + subsurface | Yes (1.27.x) | Yes | Primary, supported |
| Linux (Xorg) | Alt backend / mpv hand‑off | No | No | Works, less ideal |
| Windows | Alt backend / mpv hand‑off | No (today) | No | Experimental |
| macOS | Alt backend / mpv hand‑off | No (today) | No | Experimental |
Ferrex is under active development.
- Prefer running on an internal network, behind a reverse proxy, or via the Tailscale sidecar.
- Avoid exposing the server directly to the public Internet for now.
See Security Policy for details.
See Architecture for the diagram and component responsibilities (server, player, core, video backend, and UI stack).
See Configuration for options and workflows, and .env.example for the authoritative reference of environment variables.
See the FAQ.
Track and report issues at: https://github.com/Lowband21/ferrex/issues
See the Contributing Guide for local setup, commands, and contribution guidelines.
Dependency updates are handled by Dependabot weekly (Mon 04:00 UTC) across the Cargo workspace, GitHub Actions, and Dockerfiles in docker/. Updates are grouped to keep PR noise low—details in the Contributing Guide.
See the Changelog for highlights and open issues/discussions for upcoming work.
Please read the Contributing Guide and Code of Conduct before opening PRs.
Licensed under MIT OR Apache‑2.0.
Standing on the shoulders of giants—especially the Iced and GStreamer communities, whose work makes native UI and high‑fidelity video possible.
Attribution: This product uses the TMDB API but is not endorsed or certified by TMDB. See Trademarks.