https://github.com/lowband21/ferrex
Media player and native desktop player
https://github.com/lowband21/ferrex
iced media media-player multimedia rust videos
Last synced: 4 days ago
JSON representation
Media player and native desktop player
- Host: GitHub
- URL: https://github.com/lowband21/ferrex
- Owner: Lowband21
- License: other
- Created: 2025-12-30T11:44:56.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-03-07T22:06:38.000Z (6 days ago)
- Last Synced: 2026-03-08T01:44:29.556Z (6 days ago)
- Topics: iced, media, media-player, multimedia, rust, videos
- Language: Rust
- Homepage: https://ferrex.lowband.me/
- Size: 43.2 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# Ferrex
Native media server + desktop player focused on zero‑copy HDR on Wayland and low‑latency animated browsing.
## What is Ferrex?
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.
## Why it exists
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.
## Who it’s for
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.2**). Windows and macOS may utilize mpv hand‑off or the alternate player backend that does not include any HDR passthrough or tone-mapping.
## Highlights
- 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.
## Quickstart
### Docker/Podman
- Docker + Docker Compose
- `TMDB_API_KEY` (required for metadata; leave blank to disable)
1) Create `.env` from the template and set at least `MEDIA_ROOT`:
```bash
cp .env.example .env
${EDITOR:-nano} .env
```
2) Start the stack (Postgres, Redis, Ferrex server):
```bash
docker compose up -d
```
Optional performance preset (huge pages + io_uring + larger Postgres buffers):
```bash
docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d
```
Unraid note: see `docs/unraid.md` for recommended paths and `PUID`/`PGID` support.
### Development (build from source)
- Rust toolchain (stable 1.90+, edition 2024)
- just (https://github.com/casey/just)
- Linux: GStreamer + FFmpeg development headers (see CI workflow)
```bash
just start
# equivalent: ferrexctl stack up
```
### And the player:
```bash
just run-player-release
```
More options (profiles, logging, tailscale, host vs docker server): see [Configuration](docs/configuration.md) and the [Contributing Guide](.github/CONTRIBUTING.md).
## Packaging and Release
Ferrex provides `ferrexctl` commands for packaging and release automation:
```bash
# Run preflight checks (fmt, clippy, tests, deny, audit)
ferrexctl package preflight --scope=workspace
# Create a release (builds binary, docker image, GitHub release)
ferrexctl package release-init 0.1.0-alpha --dry-run
# Package for Windows (cross-compilation with GStreamer bundling)
ferrexctl package windows --target=x86_64-pc-windows-gnu
# Build Flatpak bundle
ferrexctl package flatpak
```
See `ferrexctl --help` for all packaging options.
## Platform Support
- 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](ferrex-player/README.md).
- Other platforms: playback via the cross‑platform backend or "Open with MPV" from detail views.
### Compatibility
| 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 |
## Security notes
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](.github/SECURITY.md) for details.
## Architecture
See [Architecture](docs/architecture.md) for the diagram and component responsibilities (server, player, core, video backend, and UI stack).
## Configuration
See [Configuration](docs/configuration.md) for options and workflows, and [`.env.example`](.env.example) for the authoritative reference of environment variables.
## FAQ
See the [FAQ](docs/faq.md).
## Development
See the [Contributing Guide](.github/CONTRIBUTING.md) 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.
## Roadmap
See the [Changelog](CHANGELOG.md) for highlights and open issues/discussions for upcoming work.
## Contributing
Please read the [Contributing Guide](.github/CONTRIBUTING.md) and [Code of Conduct](.github/CODE_OF_CONDUCT.md) before opening PRs.
## License
Licensed under MIT OR Apache‑2.0.
## Acknowledgements
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](.github/TRADEMARKS.md).