Skip to content
SomniusPublic

About

Self-hosted music server and player: web, Windows, Linux and Android clients, radio and classic Winamp skins. Early scaffold (Rust).

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Mus-Eq logo

Mus-Eq

Rust edition 2024 axum 0.8 tokio 1.54 SQLite rusqlite 0.41 Symphonia 0.6 TypeScript 7.0 Vite 8.3 Webamp 2.3 OpenAPI 3.1.0 Docker Containerfile

A self-hosted music server and player. One headless server (Docker or Podman) holds your library, serves it over one API, and thin clients talk to it. The web player uses Webamp, so the first skin is the classic Winamp look. An Android app exists in an early form (see below); desktop clients are planned, not built yet.

Status: early, still changing. The server and the web player work. We have tried them on localhost, in a headless browser, and from one phone over a home network; not yet with Podman or on a large library. Phases 0 to 3d and most of phase 5 (library radio, transcoding) of the roadmap are built, and phase 4 (clients) is partly done: an early Android app, no desktop client. Fetching single tracks exists but is off by default and has only been tested against fakes, never against the real services.

What works today

  • Library: scan a folder, read tags, search tracks (accent and case insensitive, Greek included), stream files with Range support
  • Web player: Webamp, login, library search, playlists, skin upload and picker, and a session that other tools can read and control
  • Playlists that extend themselves: when a playlist ends, new tracks by artists not yet in it, with the same genre, are added from your own library
  • Duplicates: detection by audio fingerprint (and by exact hash), with a proposed keeper. Nothing is ever deleted; a merge only changes the database
  • Metadata suggestions: MusicBrainz search for tracks with missing tags, and AcoustID lookup if you bring your own key. A suggestion changes the database only when you accept it; audio files are never rewritten
  • Radio stations: a station list (a Greek list is included in data/stations/) with search and a liveness check, played in the browser
  • A control API, described in docs/openapi.yaml, so widgets and other apps can drive the player
  • Android app (early, in android/): search, playlists, library radios and stations, background playback with lock-screen controls, and offline pins that are checked against the server's size and SHA-256. See "Android app" below
  • A radio made from your own files, and transcoding to opus, mp3 or aac (these need ffmpeg, which Mus-Eq downloads only after you confirm; see below)

What is planned

  • Native clients for Windows and Linux; the Android app is early (see below)
  • Fetching playlists and albums (single tracks exist, see below)
  • A live channel from a phone's mic
  • Discogs tag suggestions, a web page for duplicates and suggestions (API only for now), and more skins

Try what exists

The server needs an owner token (at least 16 characters) and a folder of music.

cp .env.example .env            # then edit the token (.env is git-ignored)
mkdir -p music                  # put some audio files in here
docker compose up --build

Open http://127.0.0.1:8080/ for the web player and log in with the token. Or use the API:

export T=<your token>
curl -XPOST -H "Authorization: Bearer $T" -H 'content-type: application/json' -d '{"kind":"scan"}' http://127.0.0.1:8080/v1/jobs
curl -H "Authorization: Bearer $T" 'http://127.0.0.1:8080/v1/tracks?q=something'

GET /v1/health is open. Everything else needs a login or Authorization: Bearer <token>. The port is published on localhost only; change that in compose.yaml on purpose if you want LAN or Tailscale access. Compose reads MUSEQ_TOKEN and MUSEQ_MUSIC_DIR (default ./music) from .env. Podman should work with the same Containerfile, but it is untested.

From source (recent Rust toolchain, and Node for the web client): MUSEQ_TOKEN=... MUSEQ_LIBRARY=./music cargo run -p museq-server. Settings:

  • MUSEQ_TOKEN or MUSEQ_TOKEN_FILE: the owner token (one is required)
  • MUSEQ_BIND: listen address, default 127.0.0.1:8080
  • MUSEQ_LIBRARY: the music folder, MUSEQ_DB: the SQLite file, MUSEQ_SKINS_DIR: where uploaded skins go
  • MUSEQ_WEB_DIR: a built web client to serve at / (the container image includes one)
  • MUSEQ_STATIONS_SEED: comma-separated station list files to import at startup
  • MUSEQ_ALLOW_PRIVATE_STATIONS=1: allow radio stations on your own network (refused by default)
  • MUSEQ_ACOUSTID_KEY: your own AcoustID application key, to identify tracks by audio (off without it)
  • MUSEQ_CONTACT: contact shown to MusicBrainz in the User-Agent

Fetching tracks (off by default)

The server can fetch one track at a time from a YouTube Music link or a Spotify track link, through your own copy of yt-dlp, and file it in your library with a note of where it came from. It is off by default and stays off until you switch it on yourself.

Read the terms of service of YouTube, YouTube Music and Spotify first, and only fetch what you are allowed to store. Whether that is the case depends on where you live and what you fetch; this project does not decide it for you, and nothing here has been checked against those terms. Enabling it means you did that reading:

MUSEQ_FETCH=on
MUSEQ_FETCH_ACK=i-have-read-the-terms-and-fetch-only-what-i-may-store
MUSEQ_FETCH_YTDLP=/absolute/path/to/yt-dlp     # optional: your own binary. Without it, the copy installed from the Programs panel (below) is used

Then GET /v1/fetch/status tells you whether it is on (and if not, why), and POST /v1/jobs with {"kind":"fetch","input":{"url":"https://music.youtube.com/watch?v=..."}} starts a job. Playlists and albums are refused. Optional: MUSEQ_FETCH_INBOX (default <library>/_fetched), MUSEQ_FETCH_MAX_BYTES, MUSEQ_FETCH_TIMEOUT_S, and MUSEQ_FETCH_COOKIES (a Netscape cookies file with permissions 600, used only when the service asks for a sign-in; the server works on a copy and never writes to your file).

This has been tested only against a fake yt-dlp and a fake Spotify page. No real request to either service has been made from this code yet, so the first real run may find something the fakes did not.

Programs Mus-Eq downloads

Mus-Eq does not include ffmpeg, yt-dlp or deno, and the container image does not either. They are separate programs under their own licences, and the server fetches one only when you ask for it and confirm.

  • GET /v1/tools lists them. For each it says what it is for, the exact address and host, the size, the pinned SHA-256, its licence, whether the server already found one, and a ready-to-show message.
  • POST /v1/tools/ffmpeg/install with {"confirm": "install ffmpeg n8.1.3"} starts the download. Without that exact phrase nothing is downloaded and the answer is the same message. GET /v1/tools shows progress; DELETE /v1/tools/ffmpeg removes it. The server enforces the phrase; showing the message to a person is the client's job (the web client shows it before its confirm button).
  • The download must come from the pinned address over HTTPS (redirects may only go to GitHub's own download hosts), must match the SHA-256 pinned in this release, and must run and identify itself (for ffmpeg, also list the encoders Mus-Eq uses), or nothing is installed. An installed file that is later replaced no longer matches its install record and is not used. A download that takes too long is stopped. The files go in MUSEQ_TOOLS_DIR (default: a tools folder next to the database, /data/tools in the container). The folder must belong to the user the server runs as; if Mus-Eq creates it, it is made private (mode 700), and a folder you point to keeps its permissions.
  • A program you already have is used as before and needs no download: set MUSEQ_FFMPEG to its path, or have ffmpeg on PATH. MUSEQ_TOOLS_DOWNLOADS=off forbids downloads altogether.
  • This release pins ffmpeg n8.1.3 (a BtbN LGPL build, which has what Mus-Eq uses: libopus, libmp3lame and the native AAC encoder), yt-dlp 2026.10.26 and deno 2.9.8, for Linux on x86_64 and aarch64. Other systems install the programs themselves. The builds need glibc, so Alpine and Termux are not covered. Pins are updated by new Mus-Eq releases, and the upstream project may remove an old build, in which case the install fails with a clear message.
  • deno is a JavaScript runtime. yt-dlp's own documentation says it needs one for full YouTube support (deno is the one it recommends and enables by default). If you install deno here, the server tells yt-dlp where it is (--js-runtimes deno:<path>); without it, yt-dlp looks for a runtime itself, for example a deno on the server's PATH. Only the fetch feature uses it.
  • Installing yt-dlp does not turn on the fetch feature, which stays off until you set it up (see above). Once fetch is on, it uses the installed yt-dlp unless MUSEQ_FETCH_YTDLP names another; it never looks for yt-dlp on PATH.

Android app

An early debug build, built from android/. It has been tried on one phone (a OnePlus 13) over a home network, not on others.

cd android
./gradlew :app:assembleDebug          # needs JDK 17 and the Android SDK (platform 36)
adb install -r app/build/outputs/apk/debug/app-debug.apk

Open the app, enter the server address and the owner token, and tap "Connect and search". Tap a track to play it. Long-press a track to pin it for offline use, or long-press a playlist to pin all of it. "Check pinned copies" on the Pinned view compares each stored file with the size and SHA-256 the server recorded at its last library scan, and downloads again any that differ (the old copy stays until the new one checks out). If a file in your library was replaced and not rescanned, its numbers are stale until you scan again.

  • Battery: on many phones the system stops a playing app after a while with the screen off. Tap "Allow background playback" in the app and allow it. On OnePlus also set Settings, Apps, Mus-Eq, Battery to unrestricted; the app cannot change that one. With the exemption on, one run played about 35 minutes with the screen off before it was cut short for an unrelated reason; a full hour has not been run.
  • HTTP and HTTPS: the app accepts both. With plain http:// the owner token travels unencrypted, so use it on a trusted network only and the app says so. For HTTPS put a reverse proxy that terminates TLS in front of the server; that has not been tried against a real certificate.
  • Redirects: downloads and API calls never follow a redirect. The player does follow one, so if a proxy in front of the server ever redirected a stream to a different host, the token would go along with the request. The server itself does not redirect.
  • Token storage: the token is stored encrypted, with an AES-GCM key held by the Android Keystore (the key needs no unlock, because the playback service reads the token while the phone is locked). An older plaintext copy is migrated and removed only after the encrypted copy has been read back correctly; if the key is ever lost, the app asks for the token again instead of failing. Tried on one phone; not tried on others, and not tried with the service restarting while the phone is locked.
  • Not built yet: skins, a polished interface, the live mic channel. Offline pins have no change manifest beyond the check above.

Layout

crates/museq-server/   the server (Rust, axum)
web/                   the web client (TypeScript, Vite, Webamp)
android/               the Android app (Kotlin, Media3)
docs/                  spec, roadmap, decisions, openapi.yaml
data/stations/         radio station lists (credit inside)
scripts/               checks and helper scripts
contrib/               small extras, such as a now-playing script for status bars
Containerfile, compose.yaml

Docs

Contributing

Issues are open for bugs, feature ideas and station suggestions. See CONTRIBUTING.md. Discussions are switched off on purpose, please use issues.

Credits

The Greek station list comes from Tray-FM by Constantinos (Unlicense).

License

Mus-Eq is licensed under either of

at your option. Third-party software and its licences are listed in docs/THIRD_PARTY.md; the licence questions we could not settle ourselves are in docs/LEGAL-REVIEW.md.

Unless you say otherwise, a contribution you send is licensed as above, with no extra terms. See CONTRIBUTING.md.

About

Self-hosted music server and player: web, Windows, Linux and Android clients, radio and classic Winamp skins. Early scaffold (Rust).

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages