DroppedNeedle

https://droppedneedle.com/docs
Admin
DroppedNeedle is a self-hosted music request and discovery application with a built-in library and...
Tokens:6,412
Snippets:108
Trust Score:4.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /api/v1/auth/setup/status

Source: https://droppedneedle.com/docs/api

Retrieves the current setup status of the authentication system.

```APIDOC
## GET /api/v1/auth/setup/status

### Description
Retrieves the current setup status of the authentication system.

### Method
GET

### Endpoint
/api/v1/auth/setup/status
```

--------------------------------

### Example slskd.yml configuration

Source: https://droppedneedle.com/docs/slskd-setup

Essential configuration sections for slskd, including credentials, shares, and API key authentication.

```yaml
soulseek:
  username: your-soulseek-username
  password: your-soulseek-password

shares:
  directories:
    - /data/share   # at least one folder of files you share (required by the network)

directories:
  downloads: /data/downloads   # the host path you also bind-mount into DroppedNeedle

web:
  authentication:
    api_keys:
      droppedneedle:
        key: choose-a-long-random-key   # give this to DroppedNeedle's Download Client settings
```

--------------------------------

### Configure DroppedNeedle download client URL

Source: https://droppedneedle.com/docs/slskd-setup

Example URL format for connecting to a slskd container on the same Docker network.

```text
# In your DroppedNeedle compose file, Settings > Download Client:
# URL: http://slskd:5030
```

--------------------------------

### Start the DroppedNeedle Container

Source: https://droppedneedle.com/docs/getting-started

Executes the container in detached mode using the defined Docker Compose configuration.

```bash
docker compose up -d
```

--------------------------------

### Configure Docker volumes for downloads

Source: https://droppedneedle.com/docs/slskd-setup

Bind-mount configuration for the downloads directory. Ensure the host paths for music and downloads reside on the same filesystem to allow atomic renames.

```yaml
environment:
  - SLSKD_DOWNLOADS_PATH=/slskd-downloads
volumes:
  - /path/to/your/music:/music:rw                # library
  - /path/to/slskd/downloads:/slskd-downloads:rw # MUST be the same filesystem as /music
```

--------------------------------

### Available Naming Template Variables

Source: https://droppedneedle.com/docs/native-engine

List of placeholders available for constructing file paths during the import process.

```text
{artist} {album} {albumartist} {year} {track:02d} {title} {ext}
{disc} {genre} {medium} {musicbrainz_id} {artist_mbid}
```

--------------------------------

### POST /api/v1/auth/login

Source: https://droppedneedle.com/docs/api

Authenticates a user and initiates a session.

```APIDOC
## POST /api/v1/auth/login

### Description
Authenticates a user and initiates a session.

### Method
POST

### Endpoint
/api/v1/auth/login
```

--------------------------------

### Configure DroppedNeedle with Docker Compose

Source: https://droppedneedle.com/docs/getting-started

Defines the service configuration for running DroppedNeedle. Ensure the volume paths for music and downloads are correctly mapped to the host filesystem.

```yaml
services:
  droppedneedle:
    image: ghcr.io/habirabbu/droppedneedle:latest
    container_name: droppedneedle
    environment:
      - PUID=1000
      - PGID=1000
      - PORT=8688
      - TZ=Etc/UTC
      - SLSKD_DOWNLOADS_PATH=/slskd-downloads
    ports:
      - "8688:8688"
    volumes:
      - ./config:/app/config
      - ./cache:/app/cache
      - /path/to/music:/music:rw
      - /path/to/slskd/downloads:/slskd-downloads:rw
    restart: unless-stopped
```

--------------------------------

### Pin slskd version

Source: https://droppedneedle.com/docs/slskd-setup

Recommended Docker image tag for compatibility.

```text
slskd/slskd:0.25.1
```

--------------------------------

### Configure SABnzbd volume mount in Docker Compose

Source: https://droppedneedle.com/docs/usenet-setup

Mount the SABnzbd completed downloads directory into the DroppedNeedle container. Ensure this path resides on the same filesystem as your music library to allow atomic moves.

```yaml
# In the droppedneedle service of your compose file:
volumes:
  - /path/to/your/music:/music:rw                    # library
  - /path/to/sabnzbd/complete:/sabnzbd-downloads:rw  # MUST be the same filesystem as /music
```

--------------------------------

### Backend Layered Architecture

Source: https://droppedneedle.com/docs/native-engine

Visual representation of the backend service layers and their dependencies.

```text
Routes (api/v1/routes/)            thin HTTP wrappers, auth-checked
  -> Services (services/native/)   scanner, orchestrator, matcher, file processor
    -> Repositories                external I/O: slskd, MusicBrainz
      -> Infrastructure            tagger (mutagen), fingerprinter (fpcalc/AcoustID),
                                   persistence (SQLite WAL), HTTP, SSE
```

--------------------------------

### Default Naming Template

Source: https://droppedneedle.com/docs/native-engine

The default structure used for organizing imported files.

```text
{albumartist}/{album} ({year})/{disc:02d}{track:02d} {title}.{ext}
```

--------------------------------

### Calculate Preflight Coherence and Final Scores

Source: https://droppedneedle.com/docs/native-engine

The scoring algorithm evaluates candidate groups based on completeness, metadata similarity, and file consistency. Final scores incorporate confidence weights, speed signals, and slot availability.

```text
coherence = 0.40 * (file_count / expected_track_count)   # completeness
          + 0.20 * dir_name_similarity                    # folder vs "artist album year"
          + 0.15 * format_consistency                     # all FLAC = 1.0
          + 0.15 * bitrate_consistency                    # low stddev
          + 0.10 * no_junk_bonus                          # not "Various/Unknown"

final = 0.50 * coherence
      + 0.30 * avg_file_confidence
      + 0.10 * upload_speed_signal
      + 0.10 * free_slot_bonus
```

--------------------------------

### DELETE /api/v1/auth/sessions/{session_id}

Source: https://droppedneedle.com/docs/api

Revokes a specific user session by its ID.

```APIDOC
## DELETE /api/v1/auth/sessions/{session_id}

### Description
Revokes a specific user session by its ID.

### Method
DELETE

### Endpoint
/api/v1/auth/sessions/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier of the session to revoke.
```
Tokens:
Raw