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.
TOML layout
Section titled “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 = trueTop-level keys
Section titled “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
Section titled “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. |
System Tray
Section titled “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
Section titled “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). |
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. |
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". |
| 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
Section titled “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
Section titled “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
Section titled “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
Section titled “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. |
Scrobbling
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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 |
Visualizer Settings
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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)
Section titled “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). |