Swing Music

SwingMusic is a high‑performance, self‑hosted audio streaming server that transforms a local music collection into a Spotify‑like web experience. The core of the application is a lightweight Go backend that scans a file system, normalizes metadata, and exposes a JSON‑based REST API. The UI is rendered entirely in the browser using modern web technologies (React + Tailwind), eliminating the need for a heavy desktop client and keeping memory usage minimal. The server runs on any OS that supports Go binaries (Linux, Windows, macOS) and can be containerized with Docker for cloud or edge deployments.

Key Features & Architecture

• Metadata Normalization – The backend parses ID3, Vorbis, and MP4 tags with the github.com/dhowden/tag library, then normalizes artist/album names and infers version labels (Deluxe, Remaster). Duplicate detection prefers the highest bitrate track.
• Real‑time Statistics – A lightweight in‑memory analytics layer tracks play counts, session duration, and daily mixes. These metrics are exposed through /api/stats and can be consumed by external dashboards or integrated with Last.fm scrobbling.
• Silence Detection & Cross‑fade – FFmpeg is invoked via Go’s os/exec to analyze track silences. The resulting timestamps are cached in the database, allowing the UI to skip silence or apply cross‑fade without re‑processing on each request.
• Multi‑user & Role Management – The server ships with a built‑in authentication system based on JSON Web Tokens (JWT). User data, playlists, and collections are stored in a SQLite database (swingmusic.db), which can be swapped for PostgreSQL or MySQL with minimal changes to the repository.
• Extensibility – A plugin architecture is in progress; current developers can extend the API by adding new endpoints or modifying the middleware stack. Webhooks for playlist changes and scrobble events are available, making it easy to hook into CI/CD pipelines or home automation systems.

Technical Stack

Deployment & Infrastructure

SwingMusic can be run as a single binary on any machine that hosts the music files. For production, Docker is recommended:

docker run -d \
  -p 1970:1970 \
  -v /mnt/music:/music \
  -v /var/lib/swingmusic:/data \
  swingmx/swingmusic:latest

The container automatically mounts the music directory and persists database state in /data. The application scales horizontally by running multiple instances behind a reverse proxy (NGINX, Traefik) with sticky sessions. Because the backend is stateless except for the database, adding replicas simply increases throughput for concurrent users.

Integration & Extensibility

Developers can consume SwingMusic’s REST API from custom clients or scripts. Endpoints such as /api/library, /api/playlists, and /api/artist/{id} provide JSON payloads that can be integrated into home automation (e.g., Home Assistant media players) or custom dashboards. The API is documented in the official guide (https://swingmx.com/guide/api.html), and sample clients are available in the android repository. Webhooks can be configured for events like “track finished” or “playlist updated,” enabling automated actions such as updating a Google Sheet or triggering a notification.

Developer Experience

• Configuration – Runtime flags (--port, --music-dir, --db-path) control the server without editing code. Environment variables are also supported for CI/CD pipelines.
• Documentation – The official docs cover installation, API usage, and advanced topics (FFmpeg tuning, database migration).
• Community – Active GitHub discussions, a dedicated subreddit, and sponsorship channels provide quick support. The codebase is open‑source under the MIT license, encouraging contributors to add features or fix bugs.

Use Cases

Advantages Over Alternatives

• Performance – Written in Go, SwingMusic uses minimal resources and serves thousands of concurrent streams on modest hardware.
• Flexibility – The database can be swapped, and the API is fully RESTful, allowing custom clients.
• Licensing – MIT license removes