The Problem
Music collections often exceed tens of thousands of files, making metadata indexing, fast searching, and multi‑device streaming difficult to implement from scratch. Existing solutions either lack performance on large libraries or require heavyweight infrastructure.
What This Does
Polaris is a self‑hosted streaming server written in Rust that indexes audio files, generates waveform thumbnails, and exposes a REST API (see src/server/axum/api.rs). The core indexing pipeline lives in src/app/index/ – e.g., search.rs handles per‑field queries, while storage.rs persists the index. The UI is served from test-data/web/index.html and static assets under res/. Server startup is defined in src/main.rs, which builds the App struct (src/app.rs) and launches the Axum server (src/server/axum.rs).
How To Use It
Setup – Build the binary with Cargo (the only declared package manager). The repository ships a Unix Makefile (res/unix/Makefile) that invokes the standard release flow:
Clone and build
git clone https://github.com/agersant/polaris.git cd polaris make -C res/unix release # runs cargo build --release
If you prefer a direct Cargo call:
cargo build --release
The resulting executable appears at target/release/polaris.
Configuration – Runtime settings are read from a TOML file (src/app/config/.rs parses config.toml). A minimal example is provided in test-data/config.toml. Typical keys include:
[server] port = 5050 bind = "0.0.0.0"
[paths] music_root = "/path/to/your/music"
Place your configuration at ~/.config/polaris/config.toml or supply --config /path/to/file.toml (the CLI flag is implemented in src/options.rs).
Running it – Start the server with the built binary, pointing at the config if you did not use the default location:
./target/release/polaris --config test-data/config.toml
The server listens on the port defined in the config (default 5050). API docs are available at http://localhost:5050/api-docs/; the web UI can be opened at http://localhost:5050/.
Real‑World Use
A home‑assistant container could launch Polaris on boot:
services: polaris: image: ghcr.io/agersant/polaris:latest volumes: /media/music:/music:ro ./polaris-config.toml:/config.toml:ro command: ["polaris", "--config", "/config.toml"]
Clients (mobile apps, browsers, VLC) then stream via http://<host>:5050/stream/<track-id> using the documented OpenAPI spec.
Code Health & Issues
Low – Missing explicit license header in source files – only a top‑level LICENSE exists; individual files lack SPDX identifiers (src/app/.rs). Medium – Limited error handling in file I/O – src/app/scanner.rs and src/app/thumbnail.rs propagate std::io::Error without contextual messages, which can make troubleshooting index failures harder. Low – Platform‑specific release scripts not invoked by CI – CI workflow (.github/workflows/build.yml) runs cargo build --release but does not use res/unix/Makefile or the Windows PowerShell script, leaving potential packaging gaps. Low – Test coverage is present but some modules lack direct tests – e.g., src/app/ddns.rs and src/app/peaks.rs have no associated test files, raising the risk of regressions in optional features. Low – Configuration validation is minimal – src/app/config.rs parses TOML directly; malformed user config will cause a panic at startup rather than a graceful error.
Overall, the repository includes a full CI pipeline, a lockfile (Cargo.lock), and >70 unit/integration tests, indicating a mature development process.
The Bottom Line
Polaris delivers a high‑performance, Rust‑based streaming server with strong support for large libraries and a ready‑to‑use web UI. It is well‑tested and CI‑validated, though production deployments should add a wrapper that validates configuration and handles missing error context. Ideal for technically inclined users or teams needing a self‑hosted solution without external dependencies.