Documentation

General

Does DroppedNeedle download from Soulseek?

No. DroppedNeedle has no Soulseek protocol code and never joins or distributes on the Soulseek/P2P network. It orchestrates a user-provided slskd instance over slskd’s local HTTP API: it sends searches and download requests to slskd and imports the results. You supply, run, and are responsible for slskd and its shared folders.

Do I still need Lidarr?

No. DroppedNeedle ships a native library and download engine that replaces Lidarr entirely. There is no Lidarr installation, no coexistence option, and no toggle.

What do I need to run it?

  • Docker
  • A writable directory for your music library
  • Your own slskd 0.25.0+ instance with:
    • A Soulseek account configured
    • At least one shared folder (Soulseek bans leechers)
    • An API key configured

That is the full list. See Getting Started and slskd Setup.

Why must slskd’s downloads directory be on the same filesystem as the library?

DroppedNeedle imports finished downloads using an atomic os.rename. A rename across filesystems fails with EXDEV; the kernel refuses to move a file between two different filesystem mounts. If your music library and slskd’s downloads directory are on separate mounts, downloads complete in slskd but nothing arrives in your library. The fix is to bind-mount slskd’s downloads directory into the DroppedNeedle container from a host path that is on the same underlying filesystem as your music library. See slskd Setup.

Where can I stream music?

DroppedNeedle connects to Jellyfin (transcoded, configurable codec and bitrate), Navidrome (Subsonic API), Plex (direct-play, multi-library), local files mounted directly into the container, and YouTube (preview albums you haven’t downloaded yet). All sources feed the same built-in player. See Features for details.

Where can I scrobble?

ListenBrainz and Last.fm. Each user links their own accounts from their profile and toggles each service independently. A “now playing” update goes out when a track starts; a scrobble is submitted when it finishes.

Is it multi-user?

Yes. Every account has one of three roles: Admin, Trusted, or User. Admin and Trusted users’ requests start downloading immediately; standard User requests wait for admin approval. Users can sign in with a username and password, or via Jellyfin, Plex, or any OIDC-compatible provider (Authelia, Keycloak, Authentik, and so on). Sessions last 30 days.

Is it free?

DroppedNeedle is released under the AGPL-3.0 license.

Troubleshooting

Downloads complete in slskd but nothing imports

The slskd downloads bind-mount is missing or misconfigured. Check:

  1. The host path for slskd’s downloads is bind-mounted read-write into the DroppedNeedle container.
  2. That host path is on the same filesystem as your music library mount.
  3. SLSKD_DOWNLOADS_PATH is set to the in-container path of that mount (for example /slskd-downloads).

Settings > Download Client shows the mount status and the exact reason for any failure.

The download client shows DEGRADED

DroppedNeedle validates the downloads mount at startup (set, exists, writable, same filesystem). DEGRADED means at least one check failed. The status page shows the specific reason. Fix the bind-mount and restart the container.

401 errors from the download client

The URL or API key is wrong, or the API key is not configured in slskd.yml. Go to Settings > Download Client, check both values, and use the Test button.

Searches return nothing

Confirm slskd has at least one shared folder configured and has a healthy Soulseek connection. Soulseek disconnects and bans users who are not sharing.

Library scan is slow or MusicBrainz lookups are taking a long time

Expected behaviour on a first scan. The MusicBrainz API client is rate-limited to 1 request per second. A 10k-album library takes roughly 50 minutes when around 30% of files need a MusicBrainz lookup. Subsequent scans are incremental and far faster.

Files are going into the manual-review queue

The scanner could not confidently identify them through any of the four tiers (MBID tags, fuzzy text match, or AcoustID fingerprint). Resolve them from the Library > Manual Review page: accept the top candidate, supply an MBID, or reject.

AcoustID fingerprinting is not running (Tier 3 disabled)

fpcalc is bundled in the image, but the AcoustID API key is optional and must be set to enable Tier-3 identification. Add it under Settings > Library. Without it, the scanner uses Tier 1 (MBID in tags) and Tier 2 (fuzzy text) only.

Scrobbles are not appearing

Confirm you have linked your ListenBrainz or Last.fm account in Profile > Scrobbling & Discovery and that the toggle for that service is on. For Last.fm, an admin must first configure the app key and shared secret in Settings > Last.fm before any user can link their account.

The OIDC login button is not appearing

The OIDC provider is only shown on the login page after Settings > Security has a valid Issuer URL, Client ID, and Client Secret saved. Also confirm the redirect URI registered in your provider exactly matches https://your-droppedneedle-url/api/v1/auth/oidc/callback.