Supysonic

Supysonic is a Python‑based implementation of the Subsonic media server API, designed to expose a rich set of audio streaming features while remaining lightweight enough for self‑hosting. At its core, Supysonic parses a user‑defined music library, builds an SQLite metadata store, and serves HTTP endpoints that mirror the Subsonic API specification (currently v1.12.0). The application handles file discovery, media transcoding on demand, and offers a variety of playback conveniences such as playlists, cover art retrieval, star/ratings management, and integration with external scrobbling services (Last.fm, ListenBrainz). A dedicated daemon can monitor the library for changes and trigger background tasks like jukebox mode, making it suitable for both static and dynamic collections.

Architecture

The codebase is organized around the supysonic.web package, which exposes a factory function (create_application()) that returns a Flask app. This pattern allows developers to embed Supysonic into larger Python services or to mount it behind reverse proxies like Nginx.

Core Capabilities

• Library Browsing – Exposes folder and tag‑based navigation; clients can request album/artist listings via standard Subsonic URLs.
• Streaming & Transcoding – Supports MP3, FLAC, OGG, AAC, and more; transcoding is performed lazily per request, ensuring low memory overhead.
• Playlist Management – Users can create static or random playlists; APIs expose CRUD operations for playlist metadata.
• Cover Art & Metadata – Extracts embedded images or fetches from external sources; exposes a dedicated endpoint for album art.
• Scrobbling Hooks – Implements Last.fm and ListenBrainz scrobbles via HTTP callbacks; developers can customize the payload or add new services.
• Jukebox Mode – A stateful mode that plays tracks in a random queue, optionally honoring user preferences; controlled via the daemon and exposed API endpoints.

Deployment & Infrastructure

Supysonic is intentionally minimalistic, making it ideal for single‑node deployments on Raspberry Pi, Docker hosts, or cloud VMs. Key deployment considerations include:

• Python ≥ 3.7 – All dependencies are available on PyPI; no native extensions beyond FFmpeg.
• FFmpeg – Must be installed system‑wide; Supysonic invokes it via the command line.
• Gunicorn – Recommended for production; supports multiple workers and can be configured with systemd or Docker Compose.
• SQLite – Suitable for small to medium libraries; for larger catalogs, consider migrating the metadata store to PostgreSQL or MySQL and adjusting the ORM layer.
• Containerization – A Dockerfile is included; images can be built locally or pulled from Docker Hub. The container exposes port 5722 by default and mounts a volume for the music library and database.

Integration & Extensibility

Supysonic’s API surface mirrors Subsonic, so any existing client (e.g., VLC, Plex clients) can consume it without modification. For developers wanting to extend functionality:

• Plugin Hooks – The application exposes a simple plugin registry where custom request handlers can be registered; useful for adding new scrobbling targets or analytics.
• Webhooks – Clients can subscribe to events such as “track started” or “playlist created” via HTTP callbacks, enabling real‑time integrations.
• Configuration – YAML/JSON config files allow fine‑grained control over transcoding presets, caching, and authentication backends (basic auth or OAuth via Flask extensions).
• Testing – The test suite uses unittest and can be extended with pytest for integration tests; third‑party services are mocked to avoid external calls.

Developer Experience

• Documentation – Comprehensive docs on ReadTheDocs cover API reference, setup guides, and developer notes. The API docs include full endpoint signatures and example payloads.
• Community – Active issue tracker on GitHub; contributors are welcomed via pull requests. The codebase is modular, with clear separation between API routes and business logic.
• Extensibility – The Flask application factory pattern makes it trivial to embed Supysonic into larger projects or to replace components (e.g., swap SQLite for PostgreSQL).
• Testing – Unit tests cover core logic, while integration tests hit real services (Last.fm, ListenBrainz). Developers can run these locally to validate changes.

Use Cases

1. Home Media Server – Run on a NAS or