Skip to content

Navidrome Module API Explanation

The Navidrome module monitors media streaming activity and library statistics from a Navidrome music server via the Subsonic API protocol.

API Execution Logic

The module locates the service definition matching the identifier navidrome. Authentication credentials are loaded from environment variables:

  • NAVIDROME_USER (or NAVIDROME_USERNAME fallback)
  • NAVIDROME_PASSWORD

Subsonic API Authentication

To secure communication, the module utilizes the Subsonic salted-token authentication standard (v1.16.1):

  1. Salt Generation: A cryptographically pseudo-random string of alphanumeric characters is generated: salt = randomString().
  2. MD5 Challenge Hashing: The module generates an MD5 token challenge by hashing the concatenated password and salt using the built-in node:crypto module: token = MD5(password + salt).
  3. Query Parameters: The authenticated query parameters (u=username&t=token&s=salt&v=1.16.1&c=swisshd&f=json) are attached to all REST endpoint URLs. Specifying f=json ensures response payloads return formatted as JSON objects.

Request Execution

The module issues concurrent requests using Promise.all with a 5-second timeout constraint:

  • Playback Telemetry: A GET request to /rest/getNowPlaying.view checks for active music playback sessions.
  • Library Telemetry: A GET request to /rest/getScanStatus.view checks the current media library and scanner metrics.

Dynamic Display States

The module dynamically adjusts what is rendered on the dashboard card depending on server activity:

  • Active Playback State:

    • If active playing tracks are found in the nowPlaying.entry payload list, the module extracts the primary track name, artist, and album.
    • Primary Metric: Song title (formatted as Artist - Title, truncated to 22 characters if it exceeds 25 characters).
    • Primary Label: now playing
    • Secondary Metric: Album name (truncated if it exceeds 25 characters).
    • Secondary Label: album

  • Default Idle State:

    • If no active playback streams are detected, the module displays the overall status of the library database scan:
    • Primary Metric: Total track count (count from scan status).
    • Primary Label: tracks
    • Secondary Metric: Total album count (folderCount from scan status).
    • Secondary Label: albums

Caching Strategy

To prevent overloading the Navidrome server with redundant token hashing and HTTP API requests, the results are cached with a Time-To-Live (TTL) of 15 seconds, and a maximum stale window of 60 seconds.