Connecting to Navidrome

Nokkvi is a client for the Navidrome music server. To use it, you’ll need a running Navidrome instance.

If your server hosts more than one library (music folder), see Multi-library filter for how Nokkvi scopes the browse views.

Server Connection

When you first launch Nokkvi, you’ll be greeted with a login screen.

1. Server URL: Enter the full URL of your server, including the protocol (e.g., https://music.yourdomain.com). If your server isn’t behind a reverse proxy on 443/80, include the port — Navidrome’s default is 4533, e.g. http://navidrome.local:4533. You can also type just the host (e.g. navidrome.local:4533) — Nokkvi tries HTTPS first and falls back to HTTP only for local/LAN addresses; an explicit http:// to a remote server shows a cleartext-credentials warning.
2. Username: Your Navidrome username.
3. Password: Your Navidrome password.

Persistent Sessions

Nokkvi uses Navidrome’s native API (JWT tokens) for most operations. The session token is stored locally in the app’s state database (app.redb) after first login and resumes automatically on subsequent launches. Your password is never written to disk — only the rotating JWT and Subsonic credential are saved, so an expired session simply prompts a fresh login. Navidrome rotates the JWT on every authenticated response (via the X-ND-Authorization header), so an active session keeps refreshing itself for as long as you’re using the app. To switch servers or users, go to Settings and select Logout.

If the username field in config.toml is blank when a stored session resumes, Nokkvi backfills it from the saved credential automatically — so the value populates on the first auto-login after upgrading from a build that left it empty.

By default, Navidrome sessions expire after 48 hours, which may drop you back to the login screen with a “Session expired. Please log in again.” prompt when the token becomes invalid. The SessionTimeout setting in the recommended config below extends this.

Recommended navidrome.toml for Nokkvi

Below is a reference configuration tuned for use with Nokkvi. Artwork-specific settings (ImageCacheSize, CoverArtQuality) are covered in Artwork & Performance.

Session Timeout

SessionTimeout is documented in Navidrome’s configuration options reference (under Advanced configuration).

SessionTimeout = "8760h"

Security Tradeoff

A long session timeout means a compromised device stays authenticated longer. Use a duration that fits your security needs.

Scrobbling

Nokkvi submits scrobbles through Navidrome’s Subsonic API — Navidrome handles forwarding them to Last.fm and ListenBrainz. Both services need to be configured on the server side for scrobbling to work end-to-end. Client-side toggles live under scrobbling_enabled and scrobble_threshold.

Nokkvi — not the server — decides when a play counts. It submits a scrobble once your actual listening time reaches scrobble_threshold of the track length, or 4 minutes, whichever comes first. Listening time is real playback: seeking ahead or pausing doesn’t count toward it.

When that point is reached, Nokkvi tells Navidrome once, and Navidrome trusts it — it increments the track’s play count (and the album’s and artist’s) and forwards the scrobble to Last.fm/ListenBrainz in the same step. There’s no second threshold on the server. If a track never reaches that point (you skip it early, or play less than the threshold of a track shorter than 4 minutes), Nokkvi sends nothing: no play count is recorded and nothing reaches Last.fm. The “now playing” updates sent during playback never count as plays.

A high threshold won't hold back long tracks

The 4-minute arm is fixed and independent of scrobble_threshold. Set the threshold to 0.90 and a 20-minute mix still scrobbles after 4 minutes of listening — not 18. The threshold only governs tracks short enough that its percentage is reached before the 4-minute mark.

To get Last.fm API credentials, create an API account at last.fm/api. For ListenBrainz, generate a token from your profile settings.

EnableExternalServices = true

[LastFM]
Enabled = true
ApiKey = "your_lastfm_api_key"
Secret = "your_lastfm_secret"

[ListenBrainz]
Enabled = true
Token = "your_listenbrainz_token"

---

Next: Library Basics for the navigation and search conventions shared across every library view.