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: Off (default) keeps the file sparse with helpful # description comments, On writes every default value for easier manual editing, and Clean stays sparse with no comments at all.

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
[hotkeys]	Key rebindings — see Keyboard Shortcuts
[views]	Per-view sort preferences — see View Sort Preferences below
[visualizer], [visualizer.bars], [visualizer.lines], [visualizer.scope]	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	"Queue"	The view to show on startup. Options: Queue, Albums, Artists, Songs, Genres, Playlists. 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.
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.
verbose_config	"off"	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.

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	"mini_player"	Placement of the metadata strip. Options: off, player_bar (24 px strip below the player bar), 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.
slot_text_links	true	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).
horizontal_volume	false	Stack volume sliders horizontally instead of vertically in the player bar.
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). 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) and their kebab (⋮) overflow in the mini-player bar. Only applies when track_info_display = "mini_player".

Views

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

Artwork Column

Key	Default	Description
artwork_auto_max_pct	0.40	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 (size derived from window width; 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_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.

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.

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).
crossfade_enabled	true	Enable smooth transitions between tracks. Mutually exclusive with bit_perfect (Strict/Relaxed).
crossfade_duration_secs	7	Duration of the crossfade in seconds (1 to 12).
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.
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. Cycle live with the V hotkey — see Visualizer Reference.

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.

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.
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 (Left / 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.25	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.
visualizer.bars.border_width	2.0	Border thickness in pixels. Also controls LED segment gaps when led_bars is on (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.placement	"over_cover"	Where the Bars visualizer is drawn. Options: over_cover (over the now-playing cover art on the Queue view, while playing), bottom_band (a band across the bottom of the window, above the player bar, on every view).

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.placement	"over_cover"	Where the Lines visualizer is drawn. Options: over_cover (over the now-playing cover art on the Queue view, while playing), bottom_band (a band across the bottom of the window, above the player bar, on every view).

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 and an optional glowing particle field. 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).
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	1.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 display when on.

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.