Overview

DroppedNeedle is a self-hosted music request and library manager: search the MusicBrainz catalogue, ask for an album or a single track, and it drives a download client you already run, scores the candidates, verifies the files and shelves the result in your library. It replaces the Lidarr-plus-indexer stack with one container — its own request queue, its own wanted list, its own player — while leaving the downloading to software you control.

Under the hood it is a Python application shipped as a droppedneedle/droppedneedle image on Docker Hub, listening on port 8688 with a SQLite-backed library index on a mounted volume. Everything user-editable lives in the web UI and lands in config/config.json; the environment is only for container basics (PUID, PGID, UMASK, PORT, TZ and the slskd downloads path). Upgrades happen in place: the first boot after a pull upgrades a copy of the database, validates it and only then swaps it in, keeping a backup under /app/cache/upgrade-backups and restoring it if validation fails.

Key Features

• Requests from MusicBrainz — whole albums or single tracks from the full catalogue, with an approval queue so guests on the User role can request without write access to the library.
• Wanted list — failed and partial requests are re-searched on their own until a verified copy turns up.
• Quality control — per-format quality floors, automatic upgrades when a better copy appears, storage caps and per-user quotas.
• Built-in player — queue, shuffle, a 10-band equaliser, embedded lyrics and live now-playing updates.
• Discovery — trending artists, charts, genre browsing, recommendations from your ListenBrainz and Last.fm history, and a weekly mix that can queue up to five missing albums.
• Following and release radar — new releases from the artists you follow with optional auto-download, release-type filters and sidebar badges, plus Ticketmaster and Skiddle gig alerts per user.
• Free Music — Internet Archive items under Creative Commons or public-domain licences, with the licence shown up front, no account or API key needed, off with a single toggle.
• Drop imports — drag in a zip or loose files from anywhere you buy music; they are identified, tagged and shelved, or held in a manual-match queue.
• Playlists — mix Jellyfin, Navidrome, Plex, local, YouTube and Spotify imports in one place and share them read-only with one toggle.
• Library management — optional Picard-style tagging, artwork and file organisation behind an admin preview with a dry run and typed confirmation, off until you enable it.

How a request moves

The engine searches your client, ranks the candidates and auto-accepts a confident match; close calls are parked for review instead of guessed. Every file is verified before it touches the library — readable tags, a sane duration and an optional acoustic fingerprint check — and sources that fail are quarantined so they stop winning the next search.

Download sources

Soulseek, through your own slskd instance: DroppedNeedle talks to it over the local HTTP API with an API key and needs slskd 0.25.0 or newer (0.25.1 is the verified pin) with a Soulseek account inside it. Soulseek bans clients that share nothing, so slskd needs at least one shared folder or searches and downloads fail. Usenet works through SABnzbd with Newznab-compatible indexers added one at a time or reached through an existing Prowlarr. Both can run side by side, with a source-priority control deciding who goes first. Mount the completed-downloads directory read-write under the same parent as the library (/data/music and /data/slskd/complete, for example), point SLSKD_DOWNLOADS_PATH at that exact directory and skip nested binds: each one is a new mount boundary that drops imports to the slower copy fallback.

What it does not do

DroppedNeedle never joins a peer-to-peer network, ships no indexers and hosts no audio — it only drives a client you supply and run yourself, and what that client shares back is your call and your responsibility. Playback is left to the tools you already have: the library is served to Jellyfin, Navidrome, Plex, local files or any Subsonic and Jellyfin client through the OpenSubsonic and Jellyfin APIs, so apps such as Symfonium, Finamp, Feishin, Amperfy and Jellify can play from your instance.

Requirements and Installation

Docker with the Compose plugin, a music library on disk and a download client. Save a compose file that mounts ./config, ./cache and ./plugins (installed plugins vanish on recreate without that mount) plus one shared parent for the library and the completions, set PUID and PGID from id on the host and a TZ, then run docker compose up -d and open port 8688. On the first run create the admin account once, add the library path using the in-container path, add the download client and press Test then Save, then Scan — the scan reads and identifies files without renaming or retagging anything. The project also publishes a :dev tag built from main on every push, which may break; pin a commit with the :dev- tag and the short SHA appended if you want to track it. Behind a reverse proxy, set TRUSTED_PROXY_IPS to the proxy’s addresses, listing every address family it arrives on.

Related: slskd is the Soulseek client DroppedNeedle drives, Lidarr is the stack it replaces, Prowlarr can supply the Usenet indexers, and Navidrome or Jellyfin play the library once it exists.