DroppedNeedle is a self-hosted music request and discovery app with a native library and download engine. This page covers what it does; the Native Engine page covers how the download and import pipeline works internally.

Search and requests

Search the full MusicBrainz catalogue by artist or album. Request a whole album or an individual track. Requests are queued and tracked on a dedicated page with retry and cancel support.

Role-based request handling:

Native library and download engine

DroppedNeedle replaces Lidarr entirely with a built-in engine. No Lidarr installation, no coexistence, no toggle. The engine:

• Scans your music library and identifies files through a four-tier strategy (MBID tags, fuzzy text match, AcoustID fingerprint, manual review)
• Drives downloads through your own slskd instance over its HTTP API. DroppedNeedle itself has no Soulseek protocol code and never joins the P2P network.
• Scores and ranks candidates before picking one to download
• Verifies downloaded files (tag readability, duration tolerance, optional fingerprint match)
• Imports good files atomically into the library; quarantines known-bad sources
• Writes MusicBrainz tags and applies a configurable naming template on import

See Native Engine for the full pipeline detail.

Built-in player

The player supports multiple playback sources per track and can mix them in a single queue.

Playback sources

Jellyfin: transcoded audio streaming. Codec (AAC, MP3, FLAC, Opus, Vorbis, ALAC, WAV, WMA) and bitrate (32 to 320 kbps) are configurable. Playback start, progress, and stop events are reported back to Jellyfin.

Navidrome: streaming via the Subsonic API.

Plex: direct-play audio streaming from Plex Media Server, proxied so your Plex token never reaches the browser. Supports multi-library setups. Native Plex scrobbling is included and can be toggled.

Local files: served directly from the mounted music directory inside the container, without transcoding.

YouTube: inline playback for albums you haven’t downloaded yet. Links can be auto-generated with a YouTube API key or added manually. Treat it as a preview source, not a primary one; reliability depends on the embedded player.

Player controls

Queue management, shuffle, seek, volume control, and a 10-band equalizer with presets.

Discovery and recommendations

The home page surfaces trending artists, popular albums, recently added, genre quick-links, weekly ListenBrainz exploration playlists, and “Because You Listened To” carousels personalised to your listening history.

The Discover page adds a recommendation queue drawn from similar artists, library gaps, fresh releases, global charts, and your patterns across ListenBrainz and Last.fm. Each album expands to show the full tracklist and artwork before you request or skip it. You can also browse by genre and view trending and popular charts across different time ranges.

Discovery rows that require listening history stay hidden until you link ListenBrainz or Last.fm.

Library management

Browse the native library by artist or album. Search, filter, sort, paginate. View recently added albums and library statistics. From the UI: resolve unmatched files in the manual-review queue, edit tags, rescan albums, and remove albums. Jellyfin, Navidrome, Plex, and local-file sources each get their own library view with play, shuffle, and queue actions.

Scrobbling

Per-user scrobbling to 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. Plays are also saved to a local listening history inside DroppedNeedle, which feeds the Recently Played row.

Setting up Last.fm requires one admin step (register an app at last.fm/api/account/create to get an API key and shared secret) and then each user authorises their own account. ListenBrainz needs only a user token from listenbrainz.org/profile.

Playlists

Create playlists from any mix of sources: Jellyfin, Navidrome, Plex, local files, and YouTube tracks in the same list. Drag to reorder. Set custom cover art. Play through the same player.

Playlists are private by default. Toggle one to public and it appears read-only for every signed-in user under “Shared with you”. Admins can see that a private playlist exists (track count, owner) but not its name or tracks.

Multi-user authentication

DroppedNeedle is a multi-user application. Every account has one of three roles (Admin, Trusted, User) that controls request handling and admin access.

Login methods

• Username and password (case-insensitive usernames; email optional)
• Jellyfin login
• Plex login
• Any OIDC-compatible provider (Authelia, Keycloak, Authentik, and so on)

Every login method is toggled from the web UI; no environment variables needed. Users who sign in via OIDC for the first time get an account automatically, assigned the User role, and an admin can promote them.

User import

Instead of creating accounts by hand, an admin can import existing users from Jellyfin or Plex. Imported users start with the User role and sign in using their original Jellyfin or Plex credentials.

Sessions

Sessions last 30 days from login and are not extended by activity. Deleting a user ends all of that user’s sessions.

Security

HIBP password breach checking: new passwords are checked against the Have I Been Pwned database using the k-anonymity API (only the first 5 SHA-1 hash characters are transmitted). On by default. Can be disabled, or pointed at a local offline copy of the HIBP hash file for air-gapped installs.

HSTS: optional Strict-Transport-Security header for HTTPS deployments.

API keys: stored encrypted, masked on settings reads, never written to logs.

REST API

Swagger UI at /api/v1/docs. OpenAPI spec at /api/v1/openapi.json. Health check at /health. Auth via Bearer token or droppedneedle_session cookie. See API Reference for endpoint documentation.

Single Docker container

Everything above runs in one image: ghcr.io/habirabbu/droppedneedle:latest. No sidecar processes. fpcalc and AcoustID fingerprinting are bundled via libchromaprint-tools. Configuration lives in a mapped volume and is managed from the web UI.

License

AGPL-3.0. Author: Harvey Bragg.