Configuration Reference

Nokkvi stores your preferences in ~/.config/nokkvi/config.toml. While most of these can be toggled in the in-app Settings menu (Default: ` backtick), this guide provides a complete technical reference for each key.

Verbose Config

By default, Nokkvi only writes settings you have changed to the file. The Verbose Config setting controls this: Clean (default) keeps the file sparse with no comments at all, Off stays sparse but adds a # description comment above each [visualizer] key it writes, and On writes every default value for easier manual editing.

What lives elsewhere

A few values you might expect here are stored separately. Volume and session tokens live in Nokkvi’s internal state database at ~/.local/state/nokkvi/app.redb so they can update at high frequency without rewriting the config file. Theme color overrides live in ~/.config/nokkvi/themes/*.toml — see the Theming guide.

TOML layout

config.toml is divided into a few sections. Keys must be written at the correct nesting level — keys placed in the wrong section deserialize as defaults and the change silently no-ops.

Section	Contents
Root (no header)	server_url, username
[settings]	Everything in General Settings, Interface Settings, Behavior Settings, Playback Settings, and Audio Engine below
[radio_scrobble]	ListenBrainz token and Last.fm API credentials for Radio Scrobbling — stored in plaintext; usually set in-app. See Radio → Scrobbling
[hotkeys]	Key rebindings — see Keyboard Shortcuts
[views]	Per-view sort preferences — see View Sort Preferences below
[visualizer], [visualizer.bars], [visualizer.lines], [visualizer.scope], [visualizer.milkdrop]	Visualizer settings — the dotted keys in the tables below (e.g. visualizer.bars.led_bars) reflect this nesting

A minimal file looks like:

server_url = "https://music.example.com"
username   = "alice"

[settings]
start_view = "Albums"
crossfade_enabled = true

[hotkeys]
slot_list_down = "J"

[views]
albums_sort = "name"

[visualizer]
auto_sensitivity = true

[visualizer.bars]
led_bars = true

Top-level keys

These live at the root of config.toml, not under [settings].

Key	Default	Description
server_url	""	The full URL of your Navidrome server (e.g., https://music.example.com).
username	""	Your Navidrome username.

General Settings

All keys in this section live under [settings].

Key	Default	Description
start_view	"Harbour"	The view to show on startup. Options: Queue, Albums, Artists, Songs, Genres, Playlists, Harbour. Any unrecognized value (e.g. Radios, Settings) falls back to Queue.
local_music_path	""	Absolute path to your local music library. If set, Nokkvi will try to open files directly (for things like “Show in File Manager”).
library_page_size	"default"	How many items to fetch per request. Options: small (100), default (500), large (1000), massive (5000).
artwork_resolution	"default"	Quality for large panel artwork. Options: default (1000px), high (1500px), ultra (2000px), original. See note below.
track_artwork	"album_cover"	Which cover songs show in the queue, song lists and on the now-playing panels. Options: album_cover (the album’s cover), own_cover (the art embedded in each song’s file, or the album’s when a file has none; fetched once per track). See Track artwork.
show_album_artists_only	true	If true, the Artists view shows only album artists and excludes track-level featured artists.
suppress_library_refresh_toasts	true	Hide the toast notification that appears when Navidrome reports a library refresh.
harbour_expandable_shelves	false	Harbour shelves open to browse their picks instead of playing in one press. See Harbour.
similar_artists_online	true	List similar artists from ListenBrainz under the centered artist’s biography in Artists, and in the Similar Artists popup. Sends the artist’s MusicBrainz ID to ListenBrainz; false sends nothing there. With this and similar_artists_deezer both off, no list shows. See Similar artists.
similar_artists_deezer	true	Add Deezer’s related artists to the similar artists list under the centered artist’s biography in Artists, and in the Similar Artists popup, blended with ListenBrainz’s. Deezer covers more small, new and non-English artists. Sends the artist’s name to Deezer, with no account or key; false sends nothing there. See Similar artists.
verbose_config	"clean"	How config.toml is rewritten when you change settings. Options: off (sparse — only non-default keys, with # description comments above each [visualizer] key), on (writes every setting, including unchanged defaults — a full template for manual editing), clean (sparse like off, but no comments). Legacy true/false values still load (true → on, false → off).
queue_show_stars	true	Show the star rating column in the queue.
queue_show_album	true	Show the album column in the queue.
queue_show_duration	true	Show the duration column in the queue.
queue_show_love	true	Show the loved/heart column in the queue.
queue_show_plays	false	Show the play count column in the queue.
queue_show_index	true	Show the row index column in the queue.
queue_show_thumbnail	true	Show the thumbnail column in the queue.
queue_show_genre	false	Show the genre column in the queue.
queue_show_select	false	Show the multi-select checkbox column in the queue.
albums_show_stars	false	Show the star rating column in the albums view.
albums_show_songcount	true	Show the song count column in the albums view.
albums_show_plays	false	Show the play count column in the albums view.
albums_show_love	true	Show the loved/heart column in the albums view.
albums_show_index	true	Show the row index column in the albums view.
albums_show_thumbnail	true	Show the thumbnail column in the albums view.
albums_show_select	false	Show the multi-select checkbox column in the albums view.
songs_show_stars	false	Show the star rating column in the songs view.
songs_show_album	true	Show the album column in the songs view.
songs_show_duration	true	Show the duration column in the songs view.
songs_show_plays	false	Show the play count column in the songs view.
songs_show_love	true	Show the loved/heart column in the songs view.
songs_show_index	true	Show the row index column in the songs view.
songs_show_thumbnail	true	Show the thumbnail column in the songs view.
songs_show_genre	false	Show the genre column in the songs view.
songs_show_select	false	Show the multi-select checkbox column in the songs view.
artists_show_stars	true	Show the star rating column in the artists view.
artists_show_albumcount	true	Show the album count column in the artists view.
artists_show_songcount	true	Show the song count column in the artists view.
artists_show_plays	true	Show the play count column in the artists view.
artists_show_love	true	Show the loved/heart column in the artists view.
artists_show_index	true	Show the row index column in the artists view.
artists_show_thumbnail	true	Show the thumbnail column in the artists view.
artists_show_select	false	Show the multi-select checkbox column in the artists view.
genres_show_index	true	Show the row index column in the genres view.
genres_show_thumbnail	true	Show the thumbnail column in the genres view.
genres_show_albumcount	true	Show the album count column in the genres view.
genres_show_songcount	true	Show the song count column in the genres view.
genres_show_select	false	Show the multi-select checkbox column in the genres view.
playlists_show_index	true	Show the row index column in the playlists view.
playlists_show_thumbnail	true	Show the thumbnail column in the playlists view.
playlists_show_songcount	false	Show the song count column in the playlists view.
playlists_show_duration	false	Show the total duration column in the playlists view.
playlists_show_updatedat	false	Show the last updated column in the playlists view.
playlists_show_select	false	Show the multi-select checkbox column in the playlists view.
similar_show_index	true	Show the row index column in the similar songs view (Find Similar / Top Songs results).
similar_show_thumbnail	true	Show the thumbnail column in the similar songs view.
similar_show_album	true	Show the album column in the similar songs view.
similar_show_duration	true	Show the duration column in the similar songs view.
similar_show_love	true	Show the loved/heart column in the similar songs view.
similar_show_select	false	Show the multi-select checkbox column in the similar songs view.
preview_show_stars	true	Show the star rating column in the smart playlist preview (the rules editor’s results pane).
preview_show_love	true	Show the loved/heart column in the smart playlist preview.
preview_show_plays	true	Show the play count column in the smart playlist preview.
preview_show_genre	true	Show the genre column in the smart playlist preview.
preview_show_duration	true	Show the duration column in the smart playlist preview.

library_page_size: massive

Setting library_page_size to "massive" fetches up to 5,000 items per request. On large libraries this can cause slow initial loads and put significant load on the Navidrome server. Start with "large" and only go higher if you need it.

artwork_resolution: original

"original" disables server-side resizing and streams the raw embedded artwork from each file. On a large library or a slow connection this can cause noticeable delays when browsing albums. "ultra" (2000px) is the practical maximum for most displays.

System Tray

Key	Default	Description
show_tray_icon	false	Register a StatusNotifierItem tray icon on the session bus. When off, no tray icon is shown.
close_to_tray	false	When show_tray_icon is on, the window’s close button hides Nokkvi into the tray instead of quitting. Ignored when the tray icon is disabled.

Interface Settings

Key	Default	Description
light_mode	false	Use the light variant of the active theme.
nav_layout	"top"	Placement of view tabs. Options: top (horizontal bar), side (vertical sidebar), none (hidden — only the active view and player bar render).
nav_display_mode	"text_only"	Content of tabs. Options: text_only, text_and_icons, icons_only.
track_info_display	"player_bar_above"	Placement of the metadata strip. Options: off, player_bar (24 px strip in the player bar, below the transport row), player_bar_above (the same strip in the player bar, above the transport row), top_bar (merged into the right side of the nav row in top-nav layout; sits as its own row above the slot list in side-nav / no-nav), top_bar_under (its own row directly below the top nav bar; falls back to top_bar in side-nav / no-nav layouts), mini_player (artwork + title/artist/album column inside the player bar; auto-hides when the artwork/metadata column can no longer fit beside the transport controls — the exact width depends on which mini-player controls are enabled, the nav layout, and rounded_mode).
slot_row_height	"compact"	Row density in lists. Options: compact (50px), default (70px), comfortable (90px), spacious (110px).
font_family	""	Font family override. Leave empty to use system default sans-serif.
rounded_mode	"on"	Rounded corners on UI elements. Options: off (flat throughout), on (rounded everywhere), player_only (rounded player bar/progress/volume/transport and bottom metadata strip; rest of the UI stays flat).
opacity_gradient	false	Apply a subtle opacity fade to items that are not in the center of the list.
dynamic_accent	false	Take the accent color from the playing cover (or the radio station’s logo) instead of the theme. Covers highlights, active buttons, the progress bar, the now-playing row, and rating stars and love hearts; the rest of the theme stays. The color is adjusted to stay readable, and black-and-white covers give a grey accent. Only while something is playing or paused. See Colors from the album art.
dynamic_visualizer	false	Build the visualizer gradient from the playing cover’s colors (up to four of its hues) instead of the theme’s bar_gradient_colors / peak_gradient_colors. Applies to bars, lines, scope, and Nokkvi’s own MilkDrop presets. Independent of dynamic_accent. See Colors from the album art.
slot_text_links	false	Make artist and album names inside list rows clickable links to their respective views.
scrollbar_visibility	"always"	How the slot-list scrollbar is shown. Options: on_hover (transient fade handle, reserves no width), always (permanent track, reserves a right-side gutter), hidden (no scrollbar; mouse-wheel still scrolls).
icon_set	"phosphor"	Which icon family the UI renders its glyphs from. Options: phosphor (default — Phosphor glyphs at Regular weight, with the transport and rating glyphs forced to Fill so the play button and stars stay solid), lucide (the original thin stroked outlines the app first shipped).
horizontal_volume	false	Stack volume sliders horizontally instead of vertically in the player bar.
seekbar_style	"classic"	How the player bar draws its seek bar, in every metadata strip mode except mini_player. Options: classic (a track with a drag handle), line (a thin track that thickens and shows its handle under the cursor), capsule (a solid block with the times inside), cells (a row of blocks), waveform (the song’s shape, worked out once per song in the background and saved; draws line until it is ready, and always for radio). Every style but classic shows the time under the cursor. See Seek bar styles.
autohide_toolbar	true	Auto-hide the view-header toolbar (sort and search controls) to a thin line until you hover it or use a sort/search shortcut.
autohide_toolbar_height	4	Height in pixels of the collapsed auto-hide toolbar. Only applies when autohide_toolbar is on.
autohide_toolbar_grip	true	Show a centered accent grip bar on the collapsed hairline sliver. Only applies when autohide_toolbar is on and autohide_collapsed_appearance = "hairline".
autohide_collapsed_appearance	"count_strip"	What the auto-hide toolbar shows while collapsed. Options: hairline (a thin sliver with an optional accent grip — hover to reveal), hidden (nothing; the list reclaims the space, but flicking the mouse to the top edge or using a sort/search hotkey still reveals it), count_strip (a slim strip echoing the current sort and item count, without controls; in the Queue it also leads with the playing playlist’s cover and name). Only applies when autohide_toolbar is on.
mini_player_show_volume	true	Show the volume control in the mini-player bar. Only applies when track_info_display = "mini_player".
mini_player_show_modes	true	Show the playback-mode toggles (repeat, shuffle, consume, EQ, sound effects, crossfade, bit-perfect, visualizer, lyrics) and their kebab (⋮) overflow in the mini-player bar. Only applies when track_info_display = "mini_player".
mini_player_seekbar_style	"capsule"	How the mini player’s seek bar is drawn, kept separate from seekbar_style. Same options; the default capsule puts the times, format and bitrate inside the bar, and every other style puts them beside it. Only applies when track_info_display = "mini_player".
mini_player_show_artwork	true	Show the album cover at the left of the mini-player bar. Off starts the title, artist and album at the left edge, lined up with the elapsed time above them. Only applies when track_info_display = "mini_player".

Views

Key	Default	Description
albums_artwork_overlay	true	Show a text overlay on the large artwork panel in the Albums view.
artists_artwork_overlay	true	Show a text overlay on the large artwork panel in the Artists view.
songs_artwork_overlay	true	Show a text overlay on the large artwork panel in the Songs view.
playlists_artwork_overlay	true	Show a text overlay on the large artwork panel in the Playlists view.

Artwork Column

Key	Default	Description
artwork_auto_max_pct	0.70	Max artwork size in auto mode, as a fraction of the window’s short axis (0.30–0.70).
artwork_column_mode	"auto"	Visibility and sizing of the large artwork panel shown alongside list views. Options: auto (beside the list, a square as tall as the window; auto-hides when the slot list would have less than 800px), always_native (user-defined width; image stays square and letterboxed vertically), always_stretched (user-defined width; image fills the column non-square per artwork_column_stretch_fit), always_vertical_native (user-defined height; artwork stacked above the slot list, stays square), always_vertical_stretched (user-defined height; artwork stacked above the slot list, fills the rect via artwork_column_stretch_fit), never (column hidden everywhere).
artwork_column_stretch_fit	"cover"	Fit mode used when artwork_column_mode = "always_stretched". Options: cover (preserve aspect ratio, crop to fill), fill (true stretch — distorts album art). Ignored in other modes.
artwork_column_width_pct	0.40	Artwork column width as a fraction of the window width (0.05 to 0.80). Only consulted in always_native and always_stretched modes.
artwork_cover	"show"	Cover picture or a plain backdrop on the now-playing panels (the Queue cover, the Radios panel, Theater Mode). Options: show, hide_in_theater (backdrop in Theater Mode only), hide_everywhere. The backdrop is black in dark mode and the theme’s hard background in light mode; the visualizer and lyrics stay.
artwork_vertical_height_pct	0.40	Artwork height as a fraction of window height (0.10–0.80). Only consulted in always_vertical_native and always_vertical_stretched modes.

Theater

Theater Mode (F11) is covered in the Theater Mode guide.

Key	Default	Description
theater_controls	"auto_hide"	How Theater Mode shows the player bar. Options: auto_hide (slides away 2.5 seconds after the last mouse or key activity, back on any movement), always_shown, always_hidden (hotkeys still work).
theater_window_fullscreen	false	When true, entering Theater Mode also makes the window fullscreen and leaving restores the previous window mode. When false, only the layout changes.

Metadata Strip Customization

Key	Default	Description
strip_show_title	true	Show the song title in the metadata strip.
strip_show_artist	true	Show the artist name in the metadata strip.
strip_show_album	true	Show the album name in the metadata strip.
strip_show_format_info	true	Show technical info (codec/sample rate) in the strip.
strip_click_action	"go_to_queue"	Action on click. Options: go_to_queue, go_to_album, go_to_artist, copy_track_info, do_nothing.
strip_merged_mode	true	Apply strip patterns to the merged artist/album display string rather than individual fields.
strip_show_labels	true	Show the field labels (title: / artist: / album:) before each value in the metadata strip.
strip_separator	"slash"	Character used to join visible fields in the metadata strip. Options: dot (·), bullet (•), pipe (|), em_dash (—), slash (/), bar (│).

Behavior Settings

Key	Default	Description
stable_viewport	true	Clicking an item highlights it in place; the list does not auto-scroll on playback changes.
auto_follow_playing	true	The Queue view auto-scrolls to keep the currently playing track visible as it changes.
seek_step_secs	5	Seconds the Seek Backward / Seek Forward keys jump (1 to 60). 1s is a fine nudge; 60s leaps through a long mix.

Playback Settings

Key	Default	Description
enter_behavior	"play_all"	Action when pressing Enter on a song. Options: play_all (replace queue with the current view), play_single (replace queue with just this track), append_and_play (add to queue and play).
enter_shuffle	false	When enabled, pressing Enter (or clicking) to play a collection starts it in a fresh random order instead of list order. Ctrl + Enter forces a one-shot shuffle regardless of this setting.
crossfade_enabled	true	Overlap and blend the end of each track into the next. Off plays tracks gapless with no overlap. Mutually exclusive with bit_perfect (Strict/Relaxed).
crossfade_duration_secs	7	Duration of the crossfade in seconds (1 to 12). Applies as tracks change on their own, not when you skip.
crossfade_curve	"equal_power"	Gain curve for the blend. Options: equal_power (default — holds perceived loudness steady through the blend, best for different songs), constant_gain (dips ~3 dB in the middle, softer for same-album material), linear (plain straight-line fade). See the Audio guide.
crossfade_min_track_secs	10	Tracks shorter than this (in seconds) play gapless instead of crossfading. Range 0 to 60. 0 blends everything including short interludes; higher values keep segues sharp and only blend full-length songs.
crossfade_album_gapless	false	When enabled, consecutive tracks from the same album play gapless so authored segues stay tight. Crossfade still applies between different albums, on shuffle, and on compilations.
bit_perfect	"off"	Bit-perfect output mode for the Linux/PipeWire backend. Options: off (standard 48 kHz DSP path — EQ, software volume, and crossfade all apply), strict (untouched samples to the DAC at each track’s native rate, hard-cut between every track), relaxed (untouched bodies, but crossfades adjacent tracks that share a sample rate and channel count using crossfade_duration_secs — only that few-second blend isn’t bit-perfect). Strict and Relaxed bypass the EQ, software volume, limiter, and ReplayGain/AGC (volume moves to the PipeWire node) and switch off crossfade_enabled. Needs PipeWire rate-switching (allowed-rates) configured. See the Audio guide.
rewind_on_previous	false	When enabled, pressing Previous restarts the current track instead of stepping to the previous one, once it has played past 5 seconds.
smooth_track_starts	true	Ramp up the first ~20 ms of each track to remove the click when a skip or seek lands mid-waveform. Off restores an instant onset. Bit-perfect streams always start instantly.
fade_on_pause	false	Ramp the volume out when pausing and back in on resume, instead of cutting mid-waveform. Bit-perfect streams always cut instantly.
fade_pause_ms	100	Pause/resume ramp length in milliseconds. Range 20 to 500. Applies when fade_on_pause is true.
fade_on_stop	false	Ease the sound out when playback stops instead of a hard cut. Track changes are unaffected.
fade_stop_ms	100	Stop ramp length in milliseconds. Range 20 to 500. Applies when fade_on_stop is true.
fade_on_skip	"off"	What a manual Next/Previous does to the sound. Options: off (instant cut), boundary_fade (ease the old track out, then start the next fresh), crossfade (overlap and blend into the skipped-to track, falling back to a boundary fade or plain cut when a blend is blocked). Bit-perfect streams always cut instantly. See the Audio guide.
fade_skip_secs	2	“Fade on Skip” length in seconds — also the Boundary Fade ease-out length. Range 1 to 4. Applies when fade_on_skip is not off.
fade_radio_transitions	false	Fade out and back in (about a quarter-second each way) when starting a radio station or returning to the queue, instead of a hard cut. The fade-in waits for the station’s first audio.
skip_silence	false	Trim near-silent lead-ins from tracks prepared in advance and start the blend early over a silent outro. Bit-perfect streams never trim.
crossfade_offset_secs	0	Gap/overlap trim in seconds. Range −2 to +2. Negative starts blends early, folding in the outgoing track’s tail; positive holds that many seconds of silence between tracks on gapless joins. A live crossfade overrides the gap.
crossfade_bar_snap	false	Round the crossfade length to whole bars of the outgoing track’s BPM tag so beats line up through the blend. Ignored when a track has no BPM tag.
volume_normalization_mode	"off"	Volume-normalization mode. Options: off, replay_gain_track, replay_gain_album, agc. See the Audio guide.
normalization_level	"normal"	AGC target level (linear amplitude, not LUFS). Options: quiet (0.6), normal (1.0), loud (1.4). Applies only when volume_normalization_mode = "agc".
replay_gain_preamp_db	0.0	Pre-amp dB applied on top of the resolved ReplayGain value. Range −15 to +15. Typical values: 0 (reference), +6 (modern-loudness target).
replay_gain_fallback_db	0.0	dB applied to tracks with no ReplayGain tags. Range −15 to +15. Ignored when replay_gain_fallback_to_agc is true.
replay_gain_fallback_to_agc	false	Untagged tracks fall through to real-time AGC instead of using replay_gain_fallback_db.
replay_gain_prevent_clipping	true	Clamp the resolved gain so track_peak × gain ≤ 1.0 using the per-track peak tag.
visualization_mode	"bars"	Active visualizer mode. Options: off, bars, lines, scope, milkdrop. Cycle live with the V hotkey — see Visualizer Reference.
lyrics_enabled	false	Lyrics over the Queue cover art and in Theater Mode. false (Off): no lyrics, nothing looked up. true (On): lyrics for every song, or a “No lyrics for this track” note; synced lyrics follow the track line by line, plain lyrics drift with playback and scroll with the mouse wheel. "auto": lyrics only for songs that have them; every song played while the Queue or Theater Mode is open is looked up, and the L hotkey or the player-bar button hides or shows them for the playing song only. See the Lyrics guide.
lyrics_fetch_online	true	Fetch missing lyrics from lrclib.net. Timed ones are cached into the local store for next time. Off resolves lyrics only from your own files, your server, and downloads already cached on disk — no third-party requests. See Where lyrics come from.
lyrics_backdrop_blur	"off"	Frost the cover art while lyrics display. Options: off (the cover stays sharp under the lyrics), light (a gentle soften — detail stays readable), medium (a true frosted-glass read — shapes survive, detail goes), heavy (melts the cover to a color wash). Blurred once per track and cached, never per frame.
lyrics_word_highlight	"sweep"	How the active line lights up when the lyrics carry word timing (TTML or enhanced LRC). Options: sweep (the accent floods each word left to right as it is sung, karaoke-style), word (each word lights up whole as its moment comes), off (the whole line in accent). Line-synced and plain lyrics look the same whichever you pick.
lyrics_alignment	"center"	Where lyric lines sit on the Queue cover and in Theater Mode. Options: left (every line starts at the left edge), center (each line centered), right (every line ends at the right edge). Each row of a wrapped line follows the setting, and so does the “No lyrics for this track” note.

Crossfade and normalization

In AGC mode, tracks that differ much in loudness may show a brief level mismatch at the crossfade boundary because each stream’s AGC has not converged yet — see Combining crossfade and normalization. The two ReplayGain modes use static, pre-computed gains instead, so both sides of a crossfade are already at target level — no convergence delay, no mismatch.

Scrobbling

Key	Default	Description
scrobbling_enabled	true	Report listening activity back to the server.
scrobble_threshold	0.50	Portion of the track you must actually listen to before a scrobble fires (0.25 to 0.90). A scrobble also fires after 4 minutes of listening regardless of this value — whichever comes first.

Radio Scrobbling

Internet-radio streams scrobble directly to ListenBrainz and/or Last.fm from Nokkvi, bypassing Navidrome — radio tracks have no library id for the server to relay. These keys live under [settings]; the service credentials live in a separate [radio_scrobble] table set up in-app. See Radio → Scrobbling for the full setup.

Key	Default	Description
radio_scrobbling_enabled	false	Scrobble internet-radio streams directly to ListenBrainz and/or Last.fm, bypassing Navidrome (radio tracks carry no library id to relay through the server). Reads the Artist - Title from the stream’s ICY metadata and submits it once it passes radio_scrobble_threshold_secs. Needs at least one service connected — see Radio → Scrobbling.
radio_scrobble_threshold_secs	60	Seconds of actual playback a radio track must accrue before it scrobbles. Radio streams report no duration, so this is an absolute-seconds gate rather than the percentage used by scrobble_threshold. Range 20–240.
radio_now_playing_enabled	true	Send a live now-playing update to ListenBrainz and Last.fm each time the radio track changes, refreshed every 30 seconds. No effect unless radio_scrobbling_enabled is on.

Rating Reminder

Key	Default	Description
rating_reminder_enabled	false	Show a “rate this track” desktop notification after you finish listening to a song. When off, no reminder is shown.
rating_change_notification_enabled	false	Show a desktop notification confirming the new rating whenever you rate via the rating hotkey or the nokkvi rate command — handy when the window is minimized or on another workspace. Only fires on a real change, so a no-op like +1 at 5 stars stays silent.
love_change_notification_enabled	false	Whether to fire a desktop notification when a track is loved/unloved via the love hotkey or the nokkvi love IPC verb (default false).
rating_reminder_trigger	"on_scrobble"	When the reminder fires. Options: on_scrobble (when the server confirms the play — requires scrobbling to be active), percentage_played (once rating_reminder_percent of the track has elapsed).
rating_reminder_percent	75	Percentage of the track that must play before the reminder fires when rating_reminder_trigger = "percentage_played". Range 60–90. Ignored by the on_scrobble trigger.

Playlists

Key	Default	Description
queue_show_default_playlist	false	Show a chip in the Queue view’s header for the remembered default playlist (the one used by quick_add_to_playlist).
quick_add_to_playlist	false	Skip the “Add to Playlist” dialog and add directly to a remembered default playlist.

View Sort Preferences

Per-view sort mode and direction live under [views] and persist across restarts. Each view has two keys: <view>_sort (string) and <view>_ascending (bool). The in-app sort cycle (Shift + Left / Shift + Right / Page Up) writes these for you; manual TOML edits work too.

Key	Default	Description
albums_sort	"recently_added"	Sort mode for the Albums view.
albums_ascending	false	Ascending order in the Albums view.
artists_sort	"name"	Sort mode for the Artists view.
artists_ascending	true	Ascending order in the Artists view.
songs_sort	"recently_added"	Sort mode for the Songs view.
songs_ascending	false	Ascending order in the Songs view.
genres_sort	"name"	Sort mode for the Genres view.
genres_ascending	true	Ascending order in the Genres view.
playlists_sort	"updated_at"	Sort mode for the Playlists view.
playlists_ascending	false	Ascending order in the Playlists view.
queue_sort	"album"	Sort mode for the Queue view (last applied; manual reorder works from any mode).
queue_ascending	true	Ascending order in the Queue view.

Valid sort modes per view

Unknown values fall back to name (or title for queue_sort). The displayed list and cycle order in-app match these tables.

View	Valid <view>_sort values
Albums	recently_added, recently_played, most_played, favorited, random, name, album_artist, artist, release_year, song_count, duration, rating, genre
Artists	name, favorited, most_played, album_count, song_count, rating, random
Songs	recently_added, recently_played, most_played, favorited, random, title, album, artist, album_artist, release_year, duration, bpm, channels, genre, rating, comment
Genres	name, album_count, song_count, random
Playlists	name, song_count, duration, updated_at, random
Queue	album, artist, title, duration, genre, rating, most_played, random

Random in the Queue view

Picking random for the queue re-shuffles on each apply (or order-toggle) and is not persisted to config.toml — the saved queue_sort only updates when you pick a deterministic mode again.

Visualizer Settings

Nokkvi features a high-performance GPU visualizer with three modes: bars, lines, and scope (a circular oscilloscope). For a detailed breakdown of color mapping, peak behaviors, and animations, see the Visualizer Reference.

General Visualizer

Key	Default	Description
visualizer.auto_sensitivity	true	Automatically scale gain to fill the available height.
visualizer.noise_reduction	0.77	Smoothing of the raw FFT data (0.0 to 1.0).
visualizer.waves	false	Enable spline smoothing between bars.
visualizer.waves_smoothing	5	Spline control-point density when waves is on (2 to 16; higher = smoother curves).
visualizer.monstercat	1	Monstercat-style energy spread to neighbouring bars. Values below 0.7 snap to 0.0 (disabled); effective range is 0.7 to 10.0.
visualizer.lower_cutoff_freq	20	Bass floor in Hz. Frequencies below this are excluded from the spectrum (minimum 20).
visualizer.higher_cutoff_freq	10000	Treble ceiling in Hz. Capped at the Nyquist limit (22050).
visualizer.height_percent	0.4	Percentage of window height occupied by the visualizer (0.1 to 0.6).
visualizer.opacity	1.0	Transparency of the visualizer (0.0 to 1.0).
visualizer.bloom	true	Bloom glow post-processing — bright bars, peak flashes, and the neon line core bleed a soft additive halo. Applies to all modes.
visualizer.bloom_intensity	0.6	Bloom glow strength (0.0 disables; up to 1.0 for maximum additive glow).
visualizer.beat_reactivity	1.0	How strongly effects pump on the beat and bass drops (0.0 = static/loudness-only, 1.0 = full punch). Scales the bloom surge, neon glow flare, and bar brightness lift together.
visualizer.crt	0.0	CRT/film composite post-process — chromatic aberration, scanlines, vignette, grain, and a beat zoom-punch under one master amount (0.0 disables; up to 1.0).

Bars Mode

Key	Default	Description
visualizer.bars.max_bars	512	Maximum number of bars the dynamic layout will try to fit (16 to 2048).
visualizer.bars.bar_width_min	10	Minimum bar width in pixels for small windows (1.0 to 10.0).
visualizer.bars.bar_width_max	20	Maximum bar width in pixels for large windows. Must be ≥ bar_width_min (up to 20.0). Equal min/max gives uniform bar widths regardless of window size.
visualizer.bars.bar_spacing	2	Gap between bars in pixels. Also sets the gap between LED segments when led_bars is on.
visualizer.bars.border_width	2.0	Border thickness in pixels. Outlines each bar and, when led_bars is on, each LED segment (0.0 to 5.0).
visualizer.bars.led_bars	false	Render bars as discrete LED segments (VU meter style).
visualizer.bars.led_segment_height	5	Height of each LED segment in pixels (LED mode only; 2.0 to 20.0).
visualizer.bars.gradient_mode	"wave"	Color mapping mode. Learn more →
visualizer.bars.gradient_orientation	"vertical"	Axis for color mapping (vertical or horizontal).
visualizer.bars.peak_mode	"fall_fade"	Behavior of peak indicators. Learn more →
visualizer.bars.peak_gradient_mode	"static"	Color mode for peaks (static, cycle, height, match).
visualizer.bars.peak_hold_time	1950	Duration in milliseconds peaks stay at maximum before falling/fading.
visualizer.bars.peak_fade_time	750	Fade-out duration in milliseconds (fade and fall_fade modes only).
visualizer.bars.peak_height_ratio	35	Peak indicator height as a percentage of bar width (10 to 100; ignored in LED mode).
visualizer.bars.peak_fall_speed	5	Peak fall velocity scale (1 = slow, 5 = default, 20 = fast; does not affect fade mode).
visualizer.bars.bar_depth_3d	0	3D isometric depth in pixels (0.0 disables; up to 20.0).
visualizer.bars.flash_intensity	0.6	Peak-flash bloom strength for Bars mode (0.0 disables; up to 1.0). Bars bloom toward the peak color on transients/beats.
visualizer.bars.trails	0.0	Motion trails — bars leave a fading after-image (0.0 disables; 1.0 = long comet trails).
visualizer.bars.echo	0.0	Milkdrop-style zoom/rotate feedback — the bars spiral and tunnel into themselves, swirling with the bass/beat (0.0 disables; 1.0 = strong persistence). Takes over the display when on.
visualizer.bars.reflection	false	Stand the bars on a waterline and mirror them in dark, rippling water below it; beats send ripples across. Learn more →
visualizer.bars.reflection_below_cover	true	Over the cover, hang the Reflection’s water below the cover, over the UI there, with the bars standing on the cover’s bottom edge; false keeps the water on the cover. Learn more →
visualizer.bars.horizon	false	About the last second and a half of bars recede behind the live ones in rows toward a misty horizon. Learn more →
visualizer.bars.placement	"over_cover"	Where the Bars visualizer is drawn. Options: over_cover (over the cover art on the Queue and Radios panels and in Theater Mode; holds still while paused), bottom_band (a band above the player bar on every view, as wide as the bar: beside the artwork column, over the list only).

Lines Mode

Key	Default	Description
visualizer.lines.point_count	8	Number of points used to draw the line (8 to 512).
visualizer.lines.line_thickness	0.01	Thickness of the line as a fraction of visualizer height (0.01 to 0.10).
visualizer.lines.outline_thickness	1	Outline border thickness in pixels (0.0 disables; up to 5.0).
visualizer.lines.outline_opacity	1.0	Outline opacity (0.0 to 1.0).
visualizer.lines.animation_speed	0.1	Color cycle speed for the breathing gradient mode (0.05 = very slow, 1.0 = very fast).
visualizer.lines.fill_opacity	0.5	Transparency of the area under the line (0.0 to 1.0).
visualizer.lines.mirror	false	Symmetric oscilloscope mode (extends from center).
visualizer.lines.style	"smooth"	Interpolation style (smooth or angular).
visualizer.lines.gradient_mode	"static"	Color mapping mode. Learn more →
visualizer.lines.boat	true	Render a small boat sprite that rides the waveform.
visualizer.lines.glow_intensity	0.5	Neon glow halo around the main line (0.0 disables; up to 1.0). An exponential emissive falloff beyond the stroke that brightens with loudness.
visualizer.lines.trails	0.0	Motion trails — the line leaves a fading after-image (0.0 disables; 1.0 = long comet trails).
visualizer.lines.echo	0.0	Milkdrop-style zoom/rotate feedback — the line spirals and tunnels into itself, swirling with the bass/beat (0.0 disables; 1.0 = strong persistence). Takes over the display when on.
visualizer.lines.reflection	false	Stand the line above a waterline and mirror it in dark, rippling water below it; beats send ripples across. Learn more →
visualizer.lines.reflection_below_cover	true	Over the cover, hang the Reflection’s water below the cover, over the UI there, with the line riding down to the cover’s bottom edge; false keeps the water on the cover. Learn more →
visualizer.lines.horizon	false	About the last second and a half of the line recedes behind it as misty waves toward a horizon. Learn more →
visualizer.lines.placement	"over_cover"	Where the Lines visualizer is drawn. Options: over_cover (over the cover art on the Queue and Radios panels and in Theater Mode; holds still while paused), bottom_band (a band above the player bar on every view, as wide as the bar: beside the artwork column, over the list only).

Scope Mode

The scope mode draws a circular oscilloscope — a time-domain waveform ring — over the now-playing cover art. It reuses the Lines appearance knobs (gradient, style, glow, outline) plus ring-specific geometry, an optional glowing particle field, and a tunnel of the recent spectrum spiralling down behind the ring. Unlike Bars and Lines, Scope has no placement of its own — it is always drawn over the cover. See the Visualizer Reference.

Key	Default	Description
visualizer.scope.point_count	16	Points around the ring; more = finer waveform detail (16 to 512).
visualizer.scope.radius	0.7	Mean ring radius as a fraction of the space inside the cover (0.1 = tiny inner ring, 0.95 = nearly fills the panel).
visualizer.scope.sensitivity	1.5	Waveform swing/gain — how far loud audio pushes the ring in and out (0.5 = subtle, 5.0 = wild).
visualizer.scope.line_thickness	0.01	Ring thickness as a fraction of the panel size (0.005 to 0.1).
visualizer.scope.fill_opacity	0.5	Radial gradient fill from the ring toward the center (0.0 = no fill, 1.0 = opaque rim). No effect while the Tunnel is on.
visualizer.scope.glow_intensity	0.35	Neon glow halo around the ring (0.0 disables; up to 1.0).
visualizer.scope.outline_thickness	0.0	Outline thickness in pixels behind the ring (0.0 disables; up to 5.0).
visualizer.scope.outline_opacity	0.0	Outline opacity (0.0 to 1.0).
visualizer.scope.gradient_mode	"height"	Color mapping mode. Options: breathing, static, position, height, gradient.
visualizer.scope.animation_speed	0.1	Color cycle speed for the breathing gradient mode (0.05 = very slow, 1.0 = very fast).
visualizer.scope.style	"smooth"	Interpolation style around the ring (smooth or angular).
visualizer.scope.particles	true	Glowing particle field drifting out from the ring (the NCS/Wav2Bar look).
visualizer.scope.particle_count	192	Number of particles in the field (0 disables; up to 2048).
visualizer.scope.particle_speed	0.5	Particle launch-speed multiplier — how fast they fly out from the ring (0.1 = lazy drift, 4.0 = energetic).
visualizer.scope.beam	true	Luminous-beam look: additive blending so the glow accumulates into a bright neon beam over the cover (woscope-style).
visualizer.scope.trails	0.0	Motion trails — the ring leaves a fading after-image (0.0 disables; 1.0 = long comet trails).
visualizer.scope.echo	0.0	Milkdrop-style zoom/rotate feedback — the ring spirals and tunnels inward, swirling with the bass/beat (0.0 disables; 1.0 = strong persistence). Takes over the ring when on; the Tunnel stays sharp beneath it.
visualizer.scope.tunnel	true	About the last second of the spectrum spirals down into the cover behind the ring, lighting a ring on each kick as it falls away. The ring’s Fill has no effect while it is on. Learn more →

MilkDrop Mode

The milkdrop mode plays MilkDrop presets in place of the now-playing cover (and fills Theater Mode). These keys control how presets change and how sharply they render. See the MilkDrop guide.

Key	Default	Description
visualizer.milkdrop.preset_interval_secs	30	Seconds before MilkDrop picks another preset (0 to 600). 0 keeps the current preset until you press Next Preset.
visualizer.milkdrop.preset_crossfade_secs	2.0	Seconds one preset takes to dissolve into the next (0 to 10, in half seconds). 0 cuts straight to the new preset. A fade never runs longer than half the preset interval, and two presets are drawn at once while it lasts.
visualizer.milkdrop.switch_on_track_change	true	Each new track brings a new preset. Off: presets change only on the timer and the keys.
visualizer.milkdrop.preset_source	"all"	Which presets are drawn: all (every preset you haven’t hidden), favorites_only (your favorites) or nokkvi (Nokkvi’s own presets, drawn in your theme’s colours with the playing cover); all of them while the choice has none left.
visualizer.milkdrop.render_quality	"medium"	Pixels rendered on the shorter side of the panel before scaling: low (480), medium (720), high (1080) or native (the panel’s own size, the most expensive on a big window).
visualizer.milkdrop.show_preset_names	true	Show each preset’s name in a toast when it appears.

Audio Engine (Internal)

These settings drive the internal audio engine and the UI sound effects layer. They are also exposed in the Settings menu.

Key	Default	Description
eq_enabled	false	Global bypass for the 10-band equalizer.
eq_gains	[0.0, ...]	List of 10 gain values in dB (one per band: 31, 62, 125, 250, 500, 1k, 2k, 4k, 8k, 16k Hz). Range −12.0 to +12.0 per band.
custom_eq_presets	[]	User-saved EQ presets. Each preset is a { name, gains } object; managed through the in-app EQ panel.
sound_effects_enabled	false	Global toggle for UI sound effects.
sfx_volume	0.68	Volume for UI sound effects (0.0 to 1.0).

eq_gains must have exactly 10 values

eq_gains is typed [f32; 10]. Providing fewer or more values is a deserialize hard error — the whole [settings] section fails to load and Nokkvi falls back to defaults for every field in it. Use the in-app EQ panel to manage presets safely; it will write the correct array for you.