Audioserve

Audioserve is a lightweight, self‑hosted audio streaming server written in Rust that exposes a modern PWA front‑end built with TypeScript and Svelte, while still supporting legacy web and Android clients. At its core, the application crawls a user‑supplied directory tree, parses audio metadata (ID3, Vorbis comments, etc.), and exposes a RESTful API (docs/api.md) that allows clients to query collections, playlists, and playback positions. The server serves raw audio files directly over HTTP/2, but it also supports on‑the‑fly transcoding (via FFmpeg) for devices that require specific codecs or sample rates, such as iOS.

Architecture

• Backend: Rust 1.70+, using the actix-web framework for asynchronous HTTP handling, tokio runtime, and sqlx‑based SQLite for lightweight metadata caching. The library scanner runs as a background task, periodically re‑indexing the filesystem and updating an in‑memory BTreeMap that backs the API.
• Frontend: A PWA implemented with SvelteKit. It registers a Service Worker that caches static assets and audio segments, enabling offline playback. The client communicates with the server via a typed API (generated from OpenAPI spec) and supports WebSocket‑based real‑time playback position sync.
• Transcoding: Optional FFmpeg integration; the server spawns child processes for transcoding requests and caches the output in a dedicated directory. The cache is automatically pruned based on LRU policy.
• Security: The application can be exposed behind any reverse proxy (NGINX, Caddy) and supports TLS termination there. It also includes built‑in rate limiting, CORS configuration, and an optional Basic Auth middleware.

Core Capabilities

• File Discovery & Metadata: Automatic detection of single‑file audiobooks and multi‑track collections, with support for chapter metadata extraction.
• Playlist & Collection API: Endpoints to create, read, update, and delete playlists; collections are exposed as hierarchical JSON with lazy loading.
• Playback Position Sync: Clients can POST the current position; the server stores it per user in SQLite and pushes updates over WebSocket.
• Transcoding API: /transcode endpoint accepts target format, bitrate, and sample rate; the response streams transcoded audio while caching it for future requests.
• Webhooks: Optional HTTP callbacks can be configured to notify external services on events such as new media added or playback finished.

Deployment & Infrastructure

Audioserve ships a pre‑built Docker image (izderadicka/audioserve) that can be run with a single volume mount for media and an optional configuration file. The image is statically linked, so it runs on any Linux distribution without native dependencies. For larger deployments, the server can be horizontally scaled behind a load balancer; the SQLite cache is read‑only after initialization, so multiple instances can safely share a common filesystem mount. The built‑in HTTP/2 support and response compression (gzip/deflate) make it efficient over both local networks and the public internet.

Integration & Extensibility

Developers can extend Audioserve in several ways:

• Plugin System: By exposing a simple trait (MediaProvider) the community has already implemented an S3 provider and a local network share scanner.
• Custom API Routes: The actix-web service can be extended with additional scopes; the source code is modular, so adding a new route only requires a few lines.
• Event Bus: Internal events (e.g., MediaAdded, PlaybackEnded) are emitted via a lightweight async channel, allowing external services to subscribe with minimal coupling.
• CLI Hooks: The command‑line interface accepts custom scripts that run before or after indexing, enabling integration with external media managers.

Developer Experience

The project follows Rust’s conventions: comprehensive unit tests, CI on GitHub Actions (rust_check.yml), and a detailed docs/api.md. The API is fully typed, and the source repository includes example clients (web, Android) that can be used as starting points. Community support is active on GitHub Discussions and the project’s Discord server, where contributors frequently discuss performance tuning and feature requests. Documentation is split into quick‑start guides (docs/deploy.md), advanced configuration, and a reference for the API.

Use Cases

• Personal Audiobook Server: A home media enthusiast can host a private library, stream to any browser or Android device, and keep playback positions synced across devices.
• Educational Institutions: Libraries can expose a curated collection of lecture recordings with fine‑grained chapter metadata and secure access controls.
• Podcasters & Content Creators: The transcoding cache allows serving multiple formats (AAC, MP3) without storing duplicates, ideal for low‑bandwidth environments.
• Enterprise Intranet: With Basic Auth and reverse proxy TLS, the server can be integrated into an internal network to provide on‑demand audio training material.

Advantages

• Performance: Rust’s async runtime and zero‑copy file serving mean low latency even on modest hardware.
• Simplicity: No external database required; the embedded SQLite cache keeps the footprint small.
• Licensing: Apache‑2.0 licensed, allowing commercial use without royalties.
• Extensibility: Modular architecture and plugin hooks make it easy to adapt the server to new storage backends or integrate with existing media workflows.
• Security: Built‑in rate limiting, CORS support, and the ability to run behind a