Request music. Own everything.

Self-hosted music requests and discovery with a built-in library and download engine that drives your own clients. No Lidarr. One container.

Docs | Discord | Issues | Sponsor

Search the full MusicBrainz catalogue, request the album or the single track you actually want, and DroppedNeedle takes it from there: it drives your own download client, scores the candidates, verifies every file, and shelves the result in your library. Play it back from Jellyfin, Navidrome, Plex, or local files, or let any Subsonic or Jellyfin app play from you.

[!NOTE] DroppedNeedle only drives a download client you supply and run yourself over its local HTTP API. It never joins a P2P network, ships no indexers, and hosts no audio. What you fetch, and what your client shares back, is your call and your responsibility.

Contents

• See it
• Quick start
• What it does
• Download sources
• Configuration
• Troubleshooting
• For builders
• Support and license

See it

More screenshots

Quick start

You need Docker, a music library, and a download client. The example below uses slskd; SABnzbd with Newznab indexers or Prowlarr works too. DroppedNeedle runs neither for you. See slskd and Usenet.

1. Save this compose file

Images live on Docker Hub as droppedneedle/droppedneedle:latest.

services:
  droppedneedle:
    image: droppedneedle/droppedneedle:latest
    container_name: droppedneedle
    environment:
      - PUID=1000            # run `id` on your host to find your user/group ID
      - PGID=1000
      - UMASK=027            # secure default; 002 for trusted group-writable media
      - PORT=8688
      - TZ=Etc/UTC           # e.g. Europe/London, America/New_York
      - SLSKD_DOWNLOADS_PATH=/data/slskd/complete
    ports:
      - "8688:8688"
    volumes:
      - ./config:/app/config
      - ./cache:/app/cache
      - ./plugins:/app/plugins  # omit and installed plugins vanish on recreate
      # One shared parent mount keeps the library and completed downloads on one
      # boundary so imports move fast. Do not nest extra binds under /data.
      - /path/to/media:/data:rw
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8688/health"]
      interval: 30s
      timeout: 10s
      start_period: 10m

[!TIP] The full annotated compose, including an optional slskd sidecar, is docker-compose.example.yml.

2. Start it

docker compose up -d

Then open http://localhost:8688.

3. First run

1. Create the first admin account. This happens once.
2. Add your library path under Settings > Library, using the in-container path (e.g. /data/music).
3. Add your download client under Settings > Download Client, then Test and Save.
4. Hit Scan on Settings > Library. The scan reads and identifies files without renaming or retagging anything.
5. Search the catalogue, open an album, and Request it. Watch it land live on the Downloads page.

docker compose pull
docker compose up -d

What it does

How a request moves:

flowchart LR
    A[Request] --> B[Score candidates]
    B -->|confident| C[Your client downloads]
    B -->|shaky| P[Parked for review]
    C --> D[Verify files]
    D -->|clean| E[Library]
    D -->|bad| Q[Quarantined]
    Q -. excluded next time .-> B

The engine searches your client, ranks candidates, and auto-accepts a confident match. Close calls park for review instead of guessing. Every file is verified (readable tags, sane duration, optional fingerprint check) before it touches the library, and bad sources get quarantined so they stop winning.

Download sources

slskd

DroppedNeedle talks to your own running slskd over its local HTTP API (X-API-Key). You bring slskd; DroppedNeedle drives it.

• Use slskd 0.25.0 or newer (0.25.1 is the verified pin: slskd/slskd:0.25.1), with a Soulseek account inside it.
• Give DroppedNeedle the URL plus API key under Settings > Download Client, then Test and Save. The key is stored encrypted and never logged.

[!IMPORTANT] Soulseek bans clients that share nothing, so give slskd at least one shared folder or searches and downloads fail. Everything in a shared folder goes out to the network. Choose it like you mean it.

The downloads path is where most installs go wrong. Three rules:

1. Expose slskd's completed-downloads directory to DroppedNeedle read-write under one shared parent mount (e.g. library at /data/music, completions at /data/slskd/complete).
2. Point SLSKD_DOWNLOADS_PATH at that exact directory, not its parent.
3. Skip nested binds under /data. Each one is a new mount boundary, which drops imports to the slower copy fallback.

Keep slskd's incomplete directory on the same mount as its downloads directory: slskd can report a transfer Completed before a cross-mount move between the two finishes, so a split mount risks verifying half-copied files.

soulseek:
  username: your-soulseek-username
  password: your-soulseek-password

shares:
  directories:
    - /data/share   # required: share something or the network bans you

directories:
  downloads: /downloads   # the sidecar path; bind its host dir into DroppedNeedle too

web:
  authentication:
    api_keys:
      droppedneedle:
        key: choose-a-long-random-key

Usenet

The second source is Usenet through SABnzbd. For searching, either add Newznab-compatible indexers one by one (NZBGeek, NZBPlanet, NZB.su, Slug, and others) or point at a Prowlarr that already has them. The engine searches your chosen side, enqueues NZBs in your SABnzbd, and imports finished files through the same scoring, verification, and quarantine pipeline as slskd.

1. Expose SABnzbd's completed-downloads directory read-write, ideally under the same shared parent mount as the library so the mount rules hold. In SABnzbd, point its Downloads folder setting at the matching path (e.g. /data/sabnzbd/complete).
2. Under Settings > Download Client, enable Usenet and enter your SABnzbd URL and API key.
3. Under Settings > Indexers / Prowlarr, pick one search backend: add each indexer's URL plus API key, or enter your Prowlarr URL plus API key. Then Test and Save.

slskd and Usenet can run side by side; the source priority control picks who goes first.

Configuration

Everything user-editable lives in the web UI and lands in config/config.json. Environment is only for container basics:

The app answers on IPv4 and IPv6, but Docker still has to publish the port on both. docker port droppedneedle should list 0.0.0.0:8688 and [::]:8688; if only the first appears, turn on IPv6 for the daemon ("ipv6" and "ip6tables" in /etc/docker/daemon.json). Pinning BIND_HOST to one interface IP answers only there: the upgrade readiness probe follows the pin automatically, but the container HEALTHCHECK still uses localhost, so keep a wildcard or loopback value unless you check that address yourself.

Where things live in the UI:

Link Last.fm from Profile > Scrobbling & Discovery after the admin saves the instance app key; link ListenBrainz with the token from your ListenBrainz profile. Artist images come from AudioDB (on by default, free key rate limits apply) with proxying and TTLs under Settings > Advanced.

Users and roles

The first account is always admin. Later accounts are created by an admin or automatically on first Jellyfin, Plex, or OIDC sign-in (all start as User). Every login method toggles in the UI; no environment variables involved. Sessions last 30 days and die with the account if an admin deletes it.

Troubleshooting

• Downloads finish in the client but never import: SLSKD_DOWNLOADS_PATH must point at the exact completions directory, visible read-write. The Download Client page shows the path status and the reason.
• Separate-mount warning: imports still work through copy-and-remove, which briefly needs room for both copies. One shared /data parent with no nested binds restores fast moves.
• Client connection fails or returns 401: wrong URL or API key. Re-enter both under Settings > Download Client and Test.
• Searches return nothing or the network drops you: slskd needs shared folders and a healthy Soulseek connection. Leechers get banned.
• Scan finds nothing or files pile into manual review: check the library path is readable. Untagged files with no fingerprint match need a human.

For builders

Interactive API docs (Swagger UI) live at /api/v1/docs on your instance. Every /api/v1/* route takes a Bearer token or the session cookie, everything under /api/v1/settings/* also needs Admin, and /health stays public for the container check.

Plugins are stable (api_version = 1, v0 still loads): Python running in-process with your server's full privileges and no sandbox. Install from a GitHub URL or a copied folder, read the code before you enable it. Nothing is bundled. Contract: PLUGINS.md. Walkthrough: docs/PLUGIN-CREATION.md.

Bug reports and feature requests go to Issues, code via PRs. Dev setup, tests, and style rules are in CONTRIBUTING.md.

Support and license

Docs: droppedneedle.com. Chat: Discord. Bugs and ideas: GitHub Issues.

DroppedNeedle is AGPL-3.0. Copyright (c) 2025 DroppedNeedle and contributors. For commercial licensing, write to contact@droppedneedle.com.