Visualizer Reference

Nokkvi features a custom-built, GPU-accelerated visualizer that runs an internal FFT over Nokkvi’s own audio output and renders it with WGSL shaders. This reference explains the modes, effects, and color-mapping strategies available in config.toml.

The colors come from the active theme’s [dark.visualizer] / [light.visualizer] tables, or, with Visualizer From Album Art on (Settings → Theme), from the playing cover. See Colors from the album art.

Frequency data rendered as vertical columns with optional peak indicators.

Animated demo of Nokkvi's bars visualizer — vertical frequency columns reacting over the now-playing cover art

Bars Mode

The bars mode renders frequency data as vertical columns. It is highly configurable with various gradient and peak behaviors.

Gradient Modes

Controls how colors from your theme’s palette are mapped onto the bars.

Mode	Description
`static`	Static Height. The gradient is pinned to the visualizer; bars reveal higher colors as they rise.
`wave` (default)	Stretched Gradient. Each bar’s gradient is stretched by its amplitude, redistributing the palette as the bar rises and falls.
`drift`	Drift. The palette slowly scrolls up through the bars.
`swell`	Swell. The gradient slowly breathes in and out: the light colors spread down the bars, then pull back, with a gentle brightness swell in step.
`pulse`	Pulse. Like `wave`, plus overall loudness pushes the light colors down every bar and brightens them.
`ripple`	Ripple. A slow color wave travels sideways across the bars.

drift, swell and ripple move on their own, even when the music holds steady, while pulse follows the loudness. drift and ripple run through the palette and back again, so the colors never jump from the last one to the first.

Orientation

Determines the axis along which gradient colors are applied.

vertical: Colors map from the bottom of the visualizer to the top.
horizontal: Colors map from the low frequencies (left) to high frequencies (right).

Peak Behavior

Peaks are small indicators that mark the highest point reached by a bar.

Mode	Description
`none`	Peaks are disabled.
`fade`	Peaks hold for a duration, then fade out in their current position.
`fall`	Peaks hold, then drop at a constant velocity.
`fall_accel`	Peaks hold, then fall with simulated gravity (acceleration).
`fall_fade`	Peaks fall at a constant velocity while simultaneously fading out.

Peak Gradient Modes

Controls the coloring of the peak indicators.

static: Uses only the first color defined in peak_gradient_colors.
cycle: Smoothly cycles through all peak colors over time (breathing effect).
height: Color is determined by the peak’s vertical position.
match: The peak always matches the color of the bar at that specific height.

Peak Flash

visualizer.bars.flash_intensity (default 0.6, range 0.0–1.0; 0 disables). When a bar spikes on a transient or beat, its body blooms toward the first peak color. The flash spreads to a few neighbouring bars and decays. This is separate from the peak indicator and from the global Bloom Glow.

LED Mode

visualizer.bars.led_bars (default false) renders each bar as a stack of LED/VU-meter segments. led_segment_height sets the segment height. The gap between segments follows bar_spacing (plus border_width when borders are on), so the LEDs are spaced vertically the same way the bars are spaced horizontally. Each LED gets its own border_width outline, like a bar; when bar_spacing is larger than border_width the background shows between neighbouring outlines, otherwise they merge. In LED mode the peak indicator is exactly one segment tall, so peak_height_ratio is ignored.

Nokkvi bars visualizer in LED mode — each bar rendered as a vertical stack of discrete VU-meter segments

Isometric Depth

visualizer.bars.bar_depth_3d (default 0, off) extrudes each bar with shaded top and side faces for an isometric 3D look. Higher values deepen the extrusion (up to 20 px).

Nokkvi bars visualizer with isometric 3D depth — bars extruded with shaded top and side faces

Lines Mode

The lines mode renders frequency data as a continuous path (oscilloscope style).

Style

smooth: Uses Catmull-Rom spline interpolation for a liquid, organic look.
angular: Uses direct point-to-point lines for a sharper, technical look.

Gradient Modes

Mode	Description
`breathing`	The entire line cycles through the palette over time.
`static` (default)	The line stays a single solid color (the first in the palette).
`position`	Colors are mapped from left (bass) to right (treble).
`height`	Colors are mapped based on amplitude (quiet = bottom colors, loud = top colors).
`gradient`	A blend of horizontal position and amplitude — peaks shift the palette further along, mixing the position and height mappings 50/50.

Glow

visualizer.lines.glow_intensity (default 0.5, range 0.0–1.0). A neon emissive halo drawn beyond the main stroke — over the dark backdrop it reads as a tube of light. The halo widens (≈3–10 px) with intensity, brightens with overall loudness, and flares on each beat. The dark outline never glows, so it stays crisp. 0 disables it.

Nokkvi lines visualizer with a bright neon glow halo around the waveform

Fill & Mirror

Fill. visualizer.lines.fill_opacity (default 0.5) shades the area under the curve with the gradient.
Mirror. visualizer.lines.mirror (default false) draws the waveform symmetrically from the centre, oscilloscope-style.

Nokkvi lines visualizer in mirror mode — the waveform drawn symmetrically from the centre

Surfing Boat

On by default for lines mode: a small boat rides the waveform. Set visualizer.lines.boat = false in config.toml, or toggle it under Settings → Visualizer → Lines, to turn it off.

Cruise speed is driven by tagged BPM, onset energy, a slow energy envelope, and spectral presence. Top speed scales with the full energy stack, so denser tracks read faster; silence brings the boat to rest.
Rowing. A beat-locked half-sine envelope adds gentle thrust pulses when BPM is tagged.
Tacks ramp sail thrust from zero back to full over 4 seconds.
Slope tilts the boat to match the local wave (spring-damped, capped near 17°). Slope force only resists motion, never assists.
Heading. The sprite mirrors horizontally so the sail catches wind from behind.
Edge wrap preserves momentum; the boat sails fully off one edge (through an off-screen margin) before reappearing on the opposite side — it is drawn as a single sprite, never split across the seam.
Anchor. Every 45–120 s the boat anchors for 10–15 s, dropping a lucide-anchor icon to the visualizer floor with a curved rope back to the boat. The rope sways with the local wave; tacks pause for the duration.
Sizing. Boat sprite clamps to 48–160 px; rope stroke 1.5–3.5 px; the anchor scales with the boat.
Outline. The boat hull, anchor, and rope all use the theme’s dark-variant border_color / border_opacity, so they stay solid in light mode even when the wave’s own outline fades. The boat outline is independent of the wave’s outline_thickness / outline_opacity; only a border_opacity of 0 hides it.
Pause vs silence. Freezes when audio is paused; sinks to the floor during silence while playing.

The same boat also sails the Harbour Trawl panel, where it behaves differently: it drags its anchor continuously (that’s the trawling) and cruises on a fixed gentle breeze rather than the audio — so none of the periodic anchoring, rowing, or tacking above applies, and it keeps moving with nothing playing.

Scope Mode

The scope mode draws a circular oscilloscope — a time-domain waveform ring — over the now-playing cover art. It is cycled after Lines with the V hotkey, or set visualization_mode = "scope". The ring reuses the Lines gradient modes and style options, and adds geometry, tunnel and particle controls of its own.

Nokkvi's scope visualizer — a glowing circular oscilloscope ring with a drifting particle field, drawn over the now-playing cover art

Ring Geometry

Radius. visualizer.scope.radius (default 0.7) sets the ring’s mean radius as a fraction of the space inside the cover — 0.1 is a tiny inner ring, 0.95 nearly fills the panel.
Sensitivity. visualizer.scope.sensitivity (default 1.5) is the waveform swing: how far loud audio pushes the ring in and out (0.5 subtle, 5.0 wild).
Point count. visualizer.scope.point_count (default 16) sets how many points trace the ring — low values give a chunky, blobby ring; high values resolve fine waveform detail.
Thickness. visualizer.scope.line_thickness (default 0.01) is the ring stroke as a fraction of the panel.

Ring Look

Fill. visualizer.scope.fill_opacity (default 0.5) shades a radial gradient from the ring toward the centre. It has no effect while the Tunnel is on, which fills the ring instead.
Glow. visualizer.scope.glow_intensity (default 0.35) wraps the ring in a neon halo, like the Lines glow.
Beam. visualizer.scope.beam (default true) renders the ring with additive blending so overlapping glow accumulates into a bright neon beam (woscope-style).
Outline. visualizer.scope.outline_thickness / outline_opacity (default off) draw a darker border behind the ring for contrast on busy covers.

Tunnel

visualizer.scope.tunnel (default true). About the last second of the spectrum spirals down into the cover behind the ring, so the ring becomes the mouth of a tunnel.

Rings. A new ring joins the mouth every twentieth of a second and falls away, shrinking in perspective and turning a little as it goes, so the walls twist into a vortex.
Spectrum. Each ring is the spectrum wrapped around the circle: bass at the bottom, treble at the top, mirrored left and right. Loud frequencies push the wall out.
Walls. The walls are dark, lit by the ring behind each one, so the tunnel reads over a bright cover as well as a dark one. They thin with depth, and the cover shows at the far end.
Kicks. A ring kept on a beat glows hot as it falls away down the tunnel.
The live ring is still the raw waveform; only the tunnel behind it is drawn from the spectrum.
With Echo on, the ring’s echo swirls over the tunnel while the tunnel stays sharp.

Particles

visualizer.scope.particles (default true) launches a glowing particle field that drifts outward from the ring on the beat — the NCS / Wav2Bar look. particle_count (default 192, up to 2048) sets how many, and particle_speed (default 0.5) how fast they fly out (0.1 lazy drift, 4.0 energetic).

Placement

Bars and Lines can be drawn in one of two places, set per mode via visualizer.bars.placement and visualizer.lines.placement:

over_cover (default) — over the cover art panel on the Queue and Radios views, and in Theater Mode. It draws whether or not audio is playing and holds still while paused.
bottom_band — the classic placement: a band across the bottom of the window, above the player bar, visible on every view. Beside the artwork column, where the player bar spans only the list, the band does too and leaves the cover clear.

Scope has no placement setting of its own — it is always drawn over the cover.

Over-cover drawing shares its surface with the lyrics overlay: with both on, the visualizer keeps playing beneath the words rather than yielding to them.

Reflection & Horizon

Two scenery toggles for Bars and Lines, each set per mode under Settings → Visualizer → Bars / Lines and off by default. On together, they turn the visualizer into a fjord: the past few moments of the spectrum recede toward a horizon behind the live bars or line, and the whole scene is mirrored in dark water below. Neither applies to Scope or MilkDrop.

Nokkvi bars visualizer with Reflection and Horizon on — rows of past bars recede toward a misty horizon behind the live bars, all mirrored in dark rippling water below

Both carry their own dark body (the water, the rows), so they read over a bright cover as well as a dark one. They work in either placement.

Reflection

visualizer.bars.reflection / visualizer.lines.reflection (default false). The visualizer stands on a waterline and dark water below mirrors it, squashed so most of the skyline fits. In the bottom band, and over a cover with no room below it, the waterline sits about two-thirds of the way down the visualizer’s area.

Below the cover. Over the cover, the bars or line stand on the cover’s bottom edge and fill the whole Visualizer Height, and the water hangs below the cover, over whatever is there (the Queue’s header and first rows when the cover sits above the list), fading out toward its end. It never covers the player bar, and with only a little room below the cover the waterline settles partway. Reflection Below Cover (visualizer.bars.reflection_below_cover / visualizer.lines.reflection_below_cover, default true) turns this off and keeps the water on the cover.
Water. The body takes the visualizer’s border colour, deepening toward the bottom, so the cover shows through only faintly.
Ripples. The reflection wobbles in ripples that are fine near the waterline and widen further down, and swell with the bass.
Light on water. Reflections smear downward and break into slivers; the waterline shimmers and the water glints under bright bars.
Kicks. Each beat drops a ripple under the bar that jumped hardest, and it runs sideways across the water in both directions.
Boat. In Lines mode the surfing boat rides the line above the water.
The water mirrors what is on screen, so Motion Trails and Echo show in it too; Bloom glows across the surface.

Nokkvi bars visualizer with Reflection on — the bars stand on a waterline and are mirrored in dark, rippling water below

Horizon

visualizer.bars.horizon / visualizer.lines.horizon (default false). About the last second and a half of the spectrum recedes behind the live visualizer: a new row every tenth of a second, each one further back sitting higher, shorter and narrower as it heads for a horizon near the top, fading into mist on the way. The newest row sits on the live bars or line.

Bars recede as rows of bars in the bar gradient, with gaps you see the rows behind through. In LED mode they are cut into LED segments too.
Lines recede as smooth, misty waves with lit crests. A quiet stretch of a wave stays low ground, so the cover shows through there instead of a solid slab.
Edges. The front rows run off both sides of the visualizer (the spectrum continues past the edges, mirrored); the far rows narrow toward the middle and show their ends.
With Reflection on as well, the rows stand above the waterline and appear in the water.

Bars

Nokkvi bars visualizer with Horizon on — rows of past bars recede in perspective toward a misty horizon behind the live bars

Lines

Nokkvi lines visualizer with Horizon and Reflection on — misty waves of the past spectrum recede behind the line, mirrored in the water below

Effects

These effects apply on top of whichever mode (bars, lines, or scope) is active, and live under Settings → Visualizer → Frame. Bloom, Beat Reactivity, and CRT are global; Motion Trails and Echo are configured per mode.

Bloom Glow

visualizer.bloom (default true) makes bright bars, peak flashes, and the neon line core bleed a soft additive halo. A brightness threshold means only the bright parts glow. visualizer.bloom_intensity (default 0.6, range 0.0–1.0) sets the strength — at 0 nothing glows even with bloom enabled.

Beat Reactivity

visualizer.beat_reactivity (default 1.0, range 0.0–1.0) controls how hard the effects pump on the beat and bass drops. It scales the bloom surge, the lines-mode glow flare, the bar brightness lift, and the echo swirl together. At 0.0 everything is steady and tracks loudness only; at 1.0 it punches on every kick. (The CRT beat zoom-punch is driven by the raw beat and is not affected by this setting.)

Motion Trails

Motion trails leave a fading after-image behind the waveform — a short ghost at low values, a long comet trail near 1.0. It is a flat per-frame fade; for the swirling variant use Echo. Configured per mode — visualizer.bars.trails, visualizer.lines.trails, visualizer.scope.trails — and off (0.0) by default everywhere because it noticeably changes the look.

Echo

Echo is Milkdrop-style zoom/rotate feedback: the visualizer spirals and tunnels into itself, swirling harder with the bass and beat. Near 1.0 the feedback persists strongly and effectively takes over the display. Unlike Motion Trails (a flat fade), Echo warps and rotates each fading copy. Configured per mode — visualizer.bars.echo, visualizer.lines.echo, visualizer.scope.echo. All three default to 0.0 (off). In Scope it takes over the ring, and the Tunnel stays sharp beneath it.

CRT / Film

visualizer.crt (default 0.0, off) is a retro composite under one master amount: chromatic aberration, scanlines, vignette, film grain, and a beat zoom-punch. It is masked to the visualizer content, so it never tints the rest of the UI.

Nokkvi visualizer with the CRT / film effect — scanlines, grain, and vignette over the bars

MilkDrop Mode

The milkdrop mode is different from the others: instead of Nokkvi’s own shaders it runs MilkDrop presets through a separate engine, over the cover art on the Queue and Radios panels and full-window in Theater Mode. None of the effects above apply to it. It is cycled after Scope with the V hotkey, or set visualization_mode = "milkdrop"; its own settings are under [visualizer.milkdrop]. The MilkDrop guide covers the presets, the keys and the panel menu.

Advanced Smoothing

Nokkvi provides two mutually exclusive smoothing algorithms to tailor the visualizer’s response. Both apply to bars mode only — lines mode does its own Catmull-Rom smoothing on the GPU.

Monstercat Smoothing

An exponential falloff effect that spreads energy to neighboring bars, creating a “bouncy” and connected look.

Key: visualizer.monstercat
Value: 0.7 to 10.0 (higher = more spread). Values below 0.7 snap to 0.0 (disabled).

Waves Smoothing

Applies spline interpolation between bars to create a smooth, wave-like silhouette.

Key: visualizer.waves
Value: true / false.
Intensity: visualizer.waves_smoothing (2 to 16).