{"id":46698650,"url":"https://github.com/lowband21/ferrex","last_synced_at":"2026-04-02T22:44:00.059Z","repository":{"id":331098386,"uuid":"1125247447","full_name":"Lowband21/ferrex","owner":"Lowband21","description":"Media player and native desktop player","archived":false,"fork":false,"pushed_at":"2026-03-07T22:06:38.000Z","size":45249,"stargazers_count":1,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-08T01:44:29.556Z","etag":null,"topics":["iced","media","media-player","multimedia","rust","videos"],"latest_commit_sha":null,"homepage":"https://ferrex.lowband.me/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Lowband21.png","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","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Lowband21","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-12-30T11:44:56.000Z","updated_at":"2026-03-07T19:41:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Lowband21/ferrex","commit_stats":null,"previous_names":["lowband21/ferrex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Lowband21/ferrex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lowband21%2Fferrex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lowband21%2Fferrex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lowband21%2Fferrex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lowband21%2Fferrex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lowband21","download_url":"https://codeload.github.com/Lowband21/ferrex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lowband21%2Fferrex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30284631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["iced","media","media-player","multimedia","rust","videos"],"created_at":"2026-03-09T06:02:59.212Z","updated_at":"2026-03-09T06:03:03.336Z","avatar_url":"https://github.com/Lowband21.png","language":"Rust","funding_links":["https://github.com/sponsors/Lowband21"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Ferrex\n\n\u003cp\u003e\u003cem\u003eNative media server + desktop player focused on zero‑copy HDR on Wayland and low‑latency animated browsing.\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n![player grid](https://media.lowband.me/images/grid_fallback.png)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"MSRV\" src=\"https://img.shields.io/badge/MSRV-1.90%2B-orange?logo=rust\u0026logoColor=white\u0026style=flat\" /\u003e\n  \u003cimg alt=\"Rust edition\" src=\"https://img.shields.io/badge/edition-2024-orange?logo=rust\u0026logoColor=white\u0026style=flat\" /\u003e\n  \u003ca href=\"#license\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-informational?style=flat\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://lowband21.github.io/ferrex/\"\u003e\u003cimg alt=\"Docs\" src=\"https://img.shields.io/badge/docs-github%20pages-0078D4?style=flat\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/Lowband21/ferrex/actions/workflows/ci.yml\"\u003e\n    \u003cimg alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/Lowband21/ferrex/ci.yml?branch=main\u0026label=CI\u0026logo=githubactions\u0026style=flat\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/Lowband21/ferrex/graphs/commit-activity\"\u003e\n    \u003cimg alt=\"Commit activity\" src=\"https://img.shields.io/github/commit-activity/m/Lowband21/ferrex?style=flat\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## What is Ferrex?\nA 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.\n\n- Feels local, because it is: batched rendering of custom UI primitives keeps latency spikes in check as you fling through high‑DPI posters.\n- Zero‑copy HDR on Wayland: a Wayland‑subsurface path makes use of bleeding edge GStreamer HDR developments to preserve metadata and avoid expensive copies.\n- Pragmatic elsewhere: on other platforms, Ferrex can hand off to mpv.\n\nStatus: pre-alpha (0.1.0-alpha). Expect rapid changes while core surfaces continue to stabilize.\n\n## Why it exists\n\nExisting 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.\n\n## Who it’s for\n\nSelf‑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.\n\n## Highlights\n\n- Responsive UI across sorting, filtering, and searching large libraries.\n- Animated poster grids that stream in as fast as your GPU can swallow textures.\n- Keyboard driven and animated UI navigation/scrolling.\n- Wayland HDR pipeline with a subsurface strategy tailored for native output.\n- mpv hand‑off with watch status tracking maintained.\n\n## Quickstart\n\n### Docker/Podman\n\n- Docker + Docker Compose\n- `TMDB_API_KEY` (required for metadata; leave blank to disable)\n\n1) Create `.env` from the template and set at least `MEDIA_ROOT`:\n\n```bash\ncp .env.example .env\n${EDITOR:-nano} .env\n```\n\n2) Start the stack (Postgres, Redis, Ferrex server):\n\n```bash\ndocker compose up -d\n```\n\nOptional performance preset (huge pages + io_uring + larger Postgres buffers):\n\n```bash\ndocker compose -f docker-compose.yml -f docker-compose.perf.yml up -d\n```\n\nUnraid note: see `docs/unraid.md` for recommended paths and `PUID`/`PGID` support.\n\n### Development (build from source)\n\n- Rust toolchain (stable 1.90+, edition 2024)\n- just (https://github.com/casey/just)\n- Linux: GStreamer + FFmpeg development headers (see CI workflow)\n\n```bash\njust start\n# equivalent: ferrexctl stack up\n```\n\n### And the player:\n\n```bash\njust run-player-release\n```\n\nMore options (profiles, logging, tailscale, host vs docker server): see [Configuration](docs/configuration.md) and the [Contributing Guide](.github/CONTRIBUTING.md).\n\n## Packaging and Release\n\nFerrex provides `ferrexctl` commands for packaging and release automation:\n\n```bash\n# Run preflight checks (fmt, clippy, tests, deny, audit)\nferrexctl package preflight --scope=workspace\n\n# Create a release (builds binary, docker image, GitHub release)\nferrexctl package release-init 0.1.0-alpha --dry-run\n\n# Package for Windows (cross-compilation with GStreamer bundling)\nferrexctl package windows --target=x86_64-pc-windows-gnu\n\n# Build Flatpak bundle\nferrexctl package flatpak\n```\n\nSee `ferrexctl --help` for all packaging options.\n\n## Platform Support\n\n- Linux / Wayland: primary target. Zero‑copy HDR pipeline via GStreamer (dev 1.27.x) and Wayland subsurfaces.\n  - Tested environment: Arch Linux (Hyprland WM). Please report results for GNOME/KDE/wlroots compositors.\n  - Player specifics and platform notes: see [ferrex-player/README.md](ferrex-player/README.md).\n\n- Other platforms: playback via the cross‑platform backend or \"Open with MPV\" from detail views.\n\n### Compatibility\n\n| Platform          | Playback path              | HDR passthrough | Zero‑copy | Status             |\n|-------------------|----------------------------|-----------------|-----------|--------------------|\n| Linux (Wayland)   | GStreamer + subsurface     | Yes (1.27.x)    | Yes       | Primary, supported |\n| Linux (Xorg)      | Alt backend / mpv hand‑off | No              | No        | Works, less ideal  |\n| Windows           | Alt backend / mpv hand‑off | No (today)      | No        | Experimental       |\n| macOS             | Alt backend / mpv hand‑off | No (today)      | No        | Experimental       |\n\n## Security notes\n\nFerrex is under active development.\n\n- Prefer running on an internal network, behind a reverse proxy, or via the Tailscale sidecar.\n- Avoid exposing the server directly to the public Internet for now.\n\nSee [Security Policy](.github/SECURITY.md) for details.\n\n## Architecture\n\nSee [Architecture](docs/architecture.md) for the diagram and component responsibilities (server, player, core, video backend, and UI stack).\n\n## Configuration\n\nSee [Configuration](docs/configuration.md) for options and workflows, and [`.env.example`](.env.example) for the authoritative reference of environment variables.\n\n## FAQ\n\nSee the [FAQ](docs/faq.md).\n\n## Development\n\nSee the [Contributing Guide](.github/CONTRIBUTING.md) for local setup, commands, and contribution guidelines.\n\nDependency 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.\n\n## Roadmap\n\nSee the [Changelog](CHANGELOG.md) for highlights and open issues/discussions for upcoming work.\n\n## Contributing\n\nPlease read the [Contributing Guide](.github/CONTRIBUTING.md) and [Code of Conduct](.github/CODE_OF_CONDUCT.md) before opening PRs.\n\n## License\n\nLicensed under MIT OR Apache‑2.0.\n\n## Acknowledgements\n\nStanding on the shoulders of giants—especially the Iced and GStreamer communities, whose work makes native UI and high‑fidelity video possible.\n\nAttribution: This product uses the TMDB API but is not endorsed or certified by TMDB. See [Trademarks](.github/TRADEMARKS.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flowband21%2Fferrex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flowband21%2Fferrex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flowband21%2Fferrex/lists"}