foo_wavebar is a foobar2000 component that renders the waveform of the playing or selected track as an interactive seek bar. It provides a single Waveform Seek Bar panel — available in both the Default UI and Columns UI — backed by a shared analysis cache and swappable rendering engines.
%wavebar_channels% Title Format field.proton-11.0-2e (Wine 11.0):
foo_wavebar.fb2k-component) from the component
page.foo_wavebar.fb2k-component into foobar2000 using
the File > Preferences > Components >
Install... menu item.wavecache.db), saved presets and
screenshots live in the
<foobar2000 profile folder>\wavebar directory.The panel begins analyzing the current track automatically and shows an incremental waveform (if enabled) until the scan completes.
The panel is driven by the mouse directly on its surface and by a right-click context menu. Global behavior is set on the preferences page and each panel has its own configuration dialog.
All panel instances share the same mouse-driven playback controls.
| Action | Stopped | Paused | Playing |
|---|---|---|---|
| Left-click | Start playback at the clicked position. | Move playback to the clicked position and remain paused. | Continue playback from the clicked position. |
| Left double-click | No separate playback command; the first click seeks/starts playback as above. | Same as stopped. | Same as stopped. |
| Left drag | Preview, then start playback at the release position. | Seek to the release position and remain paused. | Continue playback from the release position. |
| Middle-click | Start playback of the current track. | Resume playback. | Pause playback. |
| Mouse wheel | No playback action; the event is passed to the parent window. | Seek backward or forward and remain paused. | Seek backward or forward and continue playing. |
| Right-click | Open the context menu (downmix, scale mode, waveform track, configuration and preferences). | Same as stopped. | Same as stopped. |
| Back / Forward (thumb) button | Toggle borderless fullscreen for this panel. | Same as stopped. | Same as stopped. |
Wheel direction, step size, and units are configurable in the global
preferences. In Default UI layout-editing mode, right-click is passed to
the host layout editor. Either mouse thumb button (XBUTTON1
/ XBUTTON2) toggles fullscreen, matching the
Fullscreen context-menu item and
Alt+Enter.
A panel showing a track other than the one playing (for example, a panel set to Selected track) treats left-click seeking as stopped: clicking or dragging starts playback of the shown track at the chosen position, and the plain mouse wheel is passed to the parent window instead of seeking the playing track. Middle-click still controls the current playback, not the previewed track.
| Modified action | Behavior |
|---|---|
Ctrl + left drag |
Copy the selected waveform audio range to the clipboard. |
Ctrl + Shift + left-click |
Save a waveform screenshot in
<foobar2000 profile folder>\wavebar. |
Ctrl + mouse wheel |
Zoom around the pointer using newly decoded range data. |
Alt + left drag |
Pan the visible time interval without seeking. |
Alt + left double-click |
Toggle borderless fullscreen. |
Right-click a panel to open the context menu. When the host layout is in editing mode (Default UI) or a Preferences/Configure dialog is open, some items are grayed out.
Open the separate modeless Analysis dialog from the panel's Analysis... context-menu item or the Open Analysis button in Configure.... Analysis display features and global next-track prefetch are opt-in; Fade cursor and spectrogram frequency labels are enabled by default but become relevant only when their corresponding curves or view are used. Configure retains waveform settings while disabling controls that do not apply to spectrogram view. Hover over controls, captions and group headings in Analysis and Preferences for help.
Prefetch is shared by all panels. It examines one candidate, preferring the playback queue, and predicts playlist transitions only for the "Default" and "Repeat (playlist)" playback orders. Unsupported sources, stop-after-current and unpredictable playback-follow-cursor transitions are skipped. Unknown/localized order names are conservatively skipped. Cached data is reused; foreground demand can promote a pending prefetch.
Use Ctrl+wheel or the zoom buttons to magnify the time interval, and Alt+drag or the pan buttons to move it. Whole track restores the overview. Follow playback advances the viewport with playback and is saved with the panel; it stays enabled across track changes. Zooming or panning so that the playback cursor leaves the view pauses following until the cursor is back in view (by playback or panning back), or until you seek or the track changes. Track changes reset the viewport. Plain-wheel seeking and Ctrl-drag clipboard selection keep their previous behavior. Zoom initially crops the overview, then requests higher-resolution original samples for reusable range tiles. The minimum viewport is 100 ms (or the track length, if shorter).
Three-band coloring blends bass (below 250 Hz, red), mids (250 Hz to 4 kHz, green) and highs (4 kHz and above, blue). A 2,048-sample Hann FFT with a 1,024-sample hop stores three linear band energies rather than rendered colors. Spectrogram view separately requests frequency-bin powers. Spectral context outside a requested range avoids artificial edge discontinuities without entering the raw envelope or loudness measurements.
The Spectral coloring selector offers Off (default), Three-band, Tint (subtle) and Tint (strong). Tint preserves the waveform palette while shifting lightness and hue with spectral balance: darker for bass-heavy passages and lighter for brighter ones. Tint applies to 7-color waveform styling, not 4-color or spectrogram view, and uses the same three-band analysis.
Spectrogram is selected under View in the Analysis dialog. It replaces the waveform with a cached time/frequency heatmap, not a live analyzer. It reuses the same background analysis, cache, seeking, zoom, pan and follow-playback behavior. The image appears when analysis completes; zoom first crops the available image, then uses higher-resolution range analysis. The frequency axis is linear; the upper-frequency limit selects the visible range, capped at half the decoded PCM sample rate (Nyquist). Frequency labels have their own checkbox; enable Time under Labels for the time axis.
Downmix and the channel selection in Configure... choose the spectrogram bands: None shows one band per selected channel in the configured order, Mono one band and Stereo left and right bands (one band for a mono source). Changing them analyzes the track again. Mirror channels flips every second band and Mirror frequency flips the frequency axis. Channel labels name the bands. Mono and stereo bands sum original-channel power, so opposite-phase stereo does not cancel. The spectrogram uses the existing 2,048-point Hann FFT and 1,024-sample hop, retaining at most 1,024 time columns and 1,025 frequency bins per band (about 4 MiB per band). Spectrograms with more than one band are kept in memory only; see Detailed Analysis Storage. Levels are window-gain-corrected tone amplitudes in dBFS, averaged in the power domain over time; they are not power spectral density. Frequency reduction preserves narrow peaks, but zoom does not improve the FFT's sample-rate-dependent frequency resolution. Floor sets the lower display limit from -120 to -40 dBFS (default -100); zero dBFS is the upper limit. SoX (default), Grayscale, Spectrum and Custom palettes, the floor and the upper-frequency limit can change without decoding again. These settings are saved with the panel and presets.
Choose Custom, then Edit... to open the spectrogram color editor. The palette runs from the floor at 0% to the peak at 100%, with RGB interpolation between stops. Click a stop marker to select it, drag it or enter its position, and click its color swatch to change the color. Add inserts a stop in the widest gap without changing the color at that position; Remove deletes the selected stop. A palette can contain 1 to 16 stops. The color picker's first seven custom colors are the panel's resolved waveform colors. Changes preview live; OK keeps them, Cancel restores the original palette, and Defaults restores the built-in custom stops.
Spectrogram colors are independent of waveform gain, ReplayGain display scaling, played shading, waveform opacity and waveform palettes. Album-art colors are ignored in this view without changing the saved waveform preference. Pseudo-transparency remains available on supported hosts. Up to four selected metric curves can overlay the heatmap using their existing fixed metric scales, not the frequency scale. Marker rails and the phase-correlation strip are waveform-only; measurement tooltips, summary and cursor text, time/frequency/channel labels and seek/playback cursors remain available. All three renderers support the view. Direct3D 11 uses its built-in shader in this view and resumes any selected custom waveform shader when switching back.
Measurement tooltips report original-channel sample peak, bucket crest factor, stereo correlation, momentary/short-term loudness and true peak/integrated loudness/LRA summaries. Enable Show tooltips while seeking, Show tooltips while hovering, or both. Hover tooltips appear as the pointer moves over the panel without clicking and disappear when it leaves. Check the desired measurements in the list and use Up / Down to set their display order; the selection and order are shared by seek and hover tooltips. Turning off seek measurements leaves the normal time tooltip available. Translucent tooltips makes measurement and hover tooltip backgrounds 80% opaque while leaving text and borders opaque; it is off by default.
Whole-track summaries are preferred when available; interval-only summaries are labeled. Momentary/short-term values use bucket endpoints after 400 ms/3 seconds. Each range is measured as an independent excerpt, with restarted loudness history and true-peak edge padding. Silence and unsupported/insufficient data are not presented as zero-valued valid measurements. Seek and drag redraws follow the configured FPS cadence.
Near-full-scale markers mean a sample peak at or above -0.1 dBFS, not proven clipping. Separate rails mark full-scale samples (>= 0 dBFS) and true-peak overs (> 0 dBTP). An optional phase-correlation strip uses red/amber/green for -1/0/+1 with unavailable gaps.
Select up to four curves, up to four whole-track summary values, and optional values near the playback cursor. The selectors show the fixed scales, independent of display gain. Available metrics include peaks, RMS, crest, momentary/short-term loudness, PSR/PLR, stereo correlation/width/balance, spectral centroid/spread, integrated loudness/LRA, loudness maxima, DR and ReplayGain tags. Unsupported or insufficient data stays unavailable; crowded labels are shortened or omitted.
Each curve has a color swatch; the defaults are yellow, cyan, pink and green. Click a swatch to choose a color or middle-click it to restore that slot's default. Selecting a metric for an unused slot also restores its default color. Fade cursor emphasizes waveform curves near the playback cursor, fading farther behind it and dimming the portion ahead. It is enabled by default; turn it off for uniform curve opacity and thin strokes. Spectrogram curves remain static overlays. Curve values near playback cursor places each selected value near its curve level rather than collecting all values at the panel's center; labels can switch sides or move to avoid collisions.
Summary Position selects any of nine screen-relative placements: the four corners, top/bottom center, middle-left/right, or center. The default is top-right. Layout arranges the values Vertical (default) or Horizontal. Text remains upright in vertical or reversed-time panels, and crowded summary/cursor text takes priority over axis labels.
Enable Time and Channel labels as needed. The S / E button beside Channel places channel labels at the start or end of the time axis (default E); placement follows Reverse time. Font... chooses the typeface, style and size (default Segoe UI Bold, 12 DIPs), plus an optional custom text color and opacity for time, channel and summary labels. Otherwise those labels use black or white against the effective background. Cursor labels retain their curve hue with a contrast adjustment. Outline adds a contrasting outline behind text and ticks. Frequency / dB toggles the spectrogram frequency scale and dB legend together, independently of time and channel labels.
DR follows the TT DR meter algorithm (as reproduced by foo_dr_meter), so values are comparable with those tools; the track value is a rounded integer and tooltips list per-channel values. DR left and DR right are also available as separate summary values when the corresponding original channels exist. Other definitions are independent: local DR is a trailing 3-second crest, not TT DR. Width is side-energy percentage; bandwidth is power-weighted spectral spread. No new ReplayGain tags are computed or written.
All built-in renderers support the new visual features. Accurate mono
display retains original-channel measurements; approximate
multichannel-to-stereo display cannot supply valid waveform overlays.
Custom Direct3D 11 waveform shaders need explicit support for optional
t3 through t8 analysis textures and
t9 styled colors; t1 is the spectrogram and
t2 is the parent background. Shaders that hard-code an
older register or constant-buffer layout need updating; see Authoring a shader for the current
layout.
Detailed analysis is source-specific (path/subsong, size/timestamp, version, interval and capabilities), unlike the cross-encode overview cache. Known source size and timestamp are required for reuse/persistence. See Detailed Analysis Storage for what is stored and its limits. Existing storage, global age/size limits, processing halt and abort-when-slow policies apply. Removed/rescanned sources invalidate detailed results; disk pages are reusable but do not shrink until compaction. Retry resubmits the current requests; failures are reported in the dialog and foobar2000 console.
The global preferences page lives under File > Preferences > Tools > Waveform Seek Bar. Its settings apply to every panel except where a panel overrides them in its own configuration dialog.
VACUUM.Each panel has its own configuration dialog, opened from the context menu's Configure... item. Changes apply to that panel only and are reflected in real time. Only one configuration dialog can be open at a time.
Front end:
Color overrides:
Style:
Presets:
<name>.json in the
wavebar directory.default is reserved. Saved presets
contain only settings that differ from the defaults unless Save
all settings in preset files is enabled under Advanced Preferences.Waveform track:
Tuning:
Channels:
Effects:
BPM,
TBPM or TEMPO metadata. Tracks without a
usable tempo keep the default speed. Enabled only when an effect is
selected.Open Preferences: opens the global Waveform Seek Bar preferences page.
Open Analysis: opens or brings forward this panel's Analysis dialog without closing Configure.
Reset to defaults: resets every setting in the dialog to the built-in defaults.
The component adds a Waveform Seek Bar submenu under foobar2000's Library main menu with cache-maintenance commands:
The active command's status, progress and Pause/Resume/Cancel controls are shown on the Waveform Seek Bar preferences page. Only one cache-maintenance command runs at a time.
Under Preferences > Advanced > Display > Visualisations, find the Waveform Seek Bar branch:
DISCARD) swap effect instead of the DXGI flip model
for the Direct3D 11 and Direct2D renderers. Disabled by default. Enable
it to keep the panel DWM-composited and avoid windowed
independent-flip/overlay promotion (for example NVIDIA "G-Sync
fullscreen only" engaging system-wide variable refresh), at the cost of
the flip model's efficiency.The DirectComposition option adapts transparent-surface presentation to Wavebar's child render window; it does not alter foobar2000's top-level window. It is not a guarantee that a driver will avoid variable refresh or overlay promotion. To evaluate it, uncheck Disable flip-model presentation, check the DirectComposition option, restart, and test with only one Wavebar GPU panel active. Debug output logs successful DirectComposition initialization. Compare the monitor's VRR indicator and PresentMon results with the option off, then check resizing, tab hide/show, fullscreen transitions, waveform opacity, and transparent backgrounds in both GPU renderers. Other GPU visualizations can independently trigger VRR. Wine compatibility and affected-monitor behavior require separate verification; compositor presentation may add latency.
Direct3D 11.1 is the standard renderer for new panels. Enable Enable alternate renderers under Advanced Preferences to expose Direct2D and GDI in the global and per-panel renderer selectors. Existing panels configured for an alternate renderer remain available when the option is off.
If the selected engine cannot be created, the component automatically falls back to GDI.
Hold Ctrl + Shift and left-click a panel to
save a screenshot of the current waveform. The image is written as a PNG
to the <foobar2000 profile folder>\wavebar directory,
named wave_YYYYMMDD_HHMMSS_mmm.png.
Hold Ctrl and left-drag across a panel to select an
audio range. On release, that range of the current track is rendered to
the Windows clipboard as WAV audio, preserving the source channel count
and sample rate. Dragging outside the panel cancels the selection.
The component exposes a %wavebar_channels% Title Format
field that resolves to the channel count of the track's cached waveform,
for use in playlists and other Title Format contexts.
Each stored signal contains minimum, maximum, and RMS arrays of
32-bit floats. The original 2048-bucket format therefore requires
2048 * 3 * 4 = 24,576 bytes (24 KiB) per signal before
compression. The 4096-bucket format requires 48 KiB per signal.
| Stored layout | 4096 buckets per track | 4096 buckets for 100k tracks |
|---|---|---|
| Mono source or Store analyzed tracks in mono | 48 KiB | 4.92 GB |
| Stereo plus accurate mono envelope | 144 KiB | 14.75 GB |
| 5.1 plus accurate mono envelope | 336 KiB | 34.41 GB |
These are uncompressed payload sizes. Track duration does not affect the stored size; channel count does. Short tracks that use the special resampling path are not persisted.
In actual use the compressed BLOB payload was 72.35% of the raw size. The complete SQLite database averaging 54.2 KiB per track for a 2048 bucket format.
| Cache format | Projected 100k tracks |
|---|---|
| 4096 buckets, measured | 10.8 GB |
Waveform cache writes use zlib's default level 6.
The cache database uses SQLite's write-ahead log (WAL), which makes
saving waveforms cheaper. While foobar2000 runs,
wavecache.db-wal and wavecache.db-shm appear
next to wavecache.db; they are merged back and removed when
foobar2000 exits cleanly. When the profile folder is on a network share,
the database uses SQLite's classic rollback journal instead, because WAL
requires shared memory that network file systems do not reliably
provide.
The Cache size limit and Cache age limit preferences are enforced in the background at startup, after every 64 newly stored waveforms, and when the preferences are applied. Enforcement waits while a cache-maintenance command is running or waveform processing is halted. Each entry records when it was last stored or displayed (to the day); the oldest entries are removed first. Removing entries frees space inside the database for reuse but does not shrink the file; run Compact waveform database to shrink it.
Detailed analysis (zoomed intervals, three-band coloring,
measurements and the spectrogram) is stored apart from the overview
waveforms, in the analysis table of the same
wavecache.db. Each entry belongs to one source file (path,
subsong, size and timestamp) and one request (interval, bands,
measurements and spectrogram bands). It holds per-channel and mono
bucket envelopes, band energies, true peaks, loudness, correlation,
local DR and PSR series, the whole-track summaries, and the spectrogram
as 32-bit floats. Entries are not compressed.
If wavecache.db cannot be read at startup, it is renamed
to wavecache.db.corrupt (with any -wal,
-shm or -journal files renamed alongside) and
a new, empty cache is created. If corruption is detected while
foobar2000 is running, a console message is printed and the same
replacement happens when foobar2000 exits. Only the most recent corrupt
copy is kept. Waveforms are re-analyzed as tracks are displayed or the
library is synchronized.
When foobar2000 is installed as a non-Steam title, it can be launched
against its Proton prefix directly from the command line. Replace
<id> with the app's compatdata
identifier and adjust the Proton build path if you use a different
Proton version.
STEAM_COMPAT_DATA_PATH="/home/deck/.steam/steam/steamapps/compatdata/<id>" \
STEAM_COMPAT_CLIENT_INSTALL_PATH="/home/deck/.steam/steam" \
"/home/deck/.steam/steam/steamapps/common/Proton - Experimental/proton" run \
"/home/deck/.steam/steam/steamapps/compatdata/<id>/pfx/drive_c/users/steamuser/foobar2000/foobar2000.exe"STEAM_COMPAT_DATA_PATH points at the app's
compatdata/<id> directory; its pfx
subfolder is the Wine prefix used for the fonts and scaling tweaks
below.STEAM_COMPAT_CLIENT_INSTALL_PATH points at the Steam
installation root.foobar2000.exe inside
the prefix.The configuration and preferences dialogs request the "Segoe UI" font. Windows ships this font, but Wine and Proton do not, so they substitute a default sans-serif face (often Liberation Sans or the host desktop font). To restore a Segoe UI-like appearance, use one of the following approaches. In each case, restart foobar2000 afterward.
~/.steam/steam/steamapps/compatdata/<AppID>/pfx; for
plain Wine it is $WINEPREFIX (default
~/.wine). Copy the Segoe UI family
(segoeui.ttf, segoeuib.ttf,
segoeuii.ttf, segoeuiz.ttf,
segoeuil.ttf, seguisb.ttf,
segoeuisl.ttf, seguibl.ttf and their italics)
from a licensed C:\Windows\Fonts into
<prefix>/drive_c/windows/Fonts/.selawik*.ttf into the prefix Fonts
folder, then map the name: under the
HKEY_CURRENT_USER\Software\Wine\Fonts\Replacements registry
key, add a string value named Segoe UI with data
Selawik.Wine\Fonts\Replacements key, map Segoe UI
to a similar installed face such as Open Sans,
Noto Sans or Liberation Sans.Note 1: The
Wine\Fonts\Replacementskey is also where to look for (and delete) an existingSegoe UI(andSegoe UI Semibold) mapping if a copied font is not being picked up. A stray mapping to a serif face such asTimes New Romanis a common reason the dialogs render in a serif font even when Segoe UI is installed.
Note 2: Copying Segoe UI from a licensed Windows installation for personal use is permitted; it may not be redistributed, which is why Selawik exists for bundling a prefix.
If the dialogs render too small or too large under Wine or Proton, adjust the prefix's DPI. Scaling is controlled through winecfg.
WINEPREFIX=<prefix> winecfg.winetricks, select the prefix, then
choose Run winecfg.protontricks, select the prefix,
then choose Run winecfg.Note: The DPI value is stored in the registry at
HKEY_CURRENT_USER\Control Panel\Desktop\LogPixels(a decimalREG_DWORD, e.g. 120), which you can also set directly withwine regeditinstead of winecfg.
Caution
⚠️ SUBJECT TO CHANGE WITHOUT NOTICE ⚠️
This is an experimental, unstable, developer-oriented
feature. The shader interface described below — the entry
points, texture and sampler registers, the Parameters
constant-buffer layout and field meanings, the vertex feed, and the
waveform texture format — may change, break, or be removed
entirely in any build, with no notice, no warning, no migration path,
and no attempt to preserve compatibility. A shader that works
today may fail to compile or render incorrectly after any update.
Do not rely on it. There is no guarantee of stability,
support, or persistence.
The Direct3D 11 engine can load an external HLSL pixel/vertex shader at runtime, replacing the built-in waveform shader for that panel.
.hlsl
extension onto the panel.bars_reflection.hlsl
ports the Effects11 bars/reflection effect to the plugin's shader
interface. It uses two-pixel bars with shaded one-pixel gaps, a baseline
three-quarters down each unflipped horizontal channel band, a compressed
reflection, and partial-bar played/seek coloring. The signed upper peak
is converted to the legacy biased range before applying the original
height arithmetic.
The effect uses Background, Highlight (played) and Foreground (unplayed) colors. Like the original, it supplies its own shape and played/seek treatment rather than using the built-in seven-color palette, half-wave shape, cursor lines or Shade played option. Seeking tints only the main waveform, not the background or reflection. Orientation, time/amplitude flips, channel spacing (including darkened channel gaps) and pseudo-transparency are supported. Bar gaps are shaded independently of the channel-gap darkening option.
The Bars Reflection preset sets the recommended opaque colors: white background and foreground (RGB 255, 255, 255), and orange-red highlight (RGB 255, 51, 0). It selects Direct3D 11 with mono downmix and disables album-art colors and pseudo-transparency. To install:
<foobar2000 profile>\wavebar\.<foobar2000 profile>\wavebar\shaders\bars_reflection.hlsl
(create the shaders folder if needed).The JSON references the shader; it does not embed it. Save your current settings as a named preset first: loading replaces panel settings, with omitted fields using component defaults.
Whether a dropped shader persists depends on where the file lives:
<foobar2000 profile>\wavebar\, e.g.
wavebar\shaders\my.hlsl) — the panel stores a
relative path to it. This persists with the panel, is
written into presets, and is reloaded on restart.
Because presets carry the path, choosing a preset also switches
the shader. If the referenced file is missing when it loads, an
error is logged and the built-in shader is used.To clear a custom shader (whether persisted or session-only) and restore the built-in one, use Reset custom shader in the panel's right-click menu (shown only while a Direct3D 11 panel has a shader active), or choose a preset whose shader path is empty.
Presets store the shader as a relative shader_path
string in their JSON, for example:
"shader_path": "shaders/bars_reflection.hlsl"A shader only needs to define a vertex entry point VS
(compiled as vs_4_0) and a pixel entry point
PS (compiled as ps_4_0). The component
automatically prepends the shared declarations below
before compiling, so your shader must not declare or
#include the textures, sampler, constant buffer,
or the VS_IN/PS_IN structs — just use
them:
Texture2D<float4> waveformTex : register(t0); // encoded waveform envelope
Texture2D<float4> spectrogramTex : register(t1); // colorized spectrogram
Texture2D<float4> bgTex : register(t2); // parent background
Texture2D<float4> bandTex : register(t3); // three-band color and validity
Texture2D<float4> measurementTex : register(t4); // first curve and near-full-scale marker
Texture2D<float4> curveTex : register(t5); // four normalized curves
Texture2D<float4> curveValidTex : register(t6); // four curve validity flags
Texture2D<float4> markerTex : register(t7); // peak markers and correlation
Texture2D<float4> labelTextTex : register(t8); // premultiplied labels and ticks
Texture2D<float4> styleTex : register(t9); // six rows: RMS/deep/hot, each unplayed then played
SamplerState sTex : register(s0);
// Constant buffer — the field order and packing are load-bearing.
cbuffer Parameters : register(b0)
{
float4 backgroundColor;
float4 textColor; // unplayed wave color (foreground)
float4 highlightColor; // played wave color
float4 selectionColor;
float4 fillPlayedColor;
float4 fillUnplayedColor;
float4 rmsPlayedColor;
float4 rmsColor;
float4 bgPlayedColor;
float4 bgUnplayedColor;
float4 windowSize; // .xy window px, .z channel gap px, .w reveal-played
float4 cursorParams; // .x width px, .y alpha, .z edge-fade, .w zero-line
float4 cursorExtras; // .x soft, .y live seeking, .z sampled line, .w original seek color
float4 cursorGlow; // .x reach ahead px, .y opacity amplitude, .z ripple phase, .w wavelength px
float4 glowColor; // .rgb tint, .w reach behind in multiples of cursorGlow.x (0=whole played area)
float4 curveColors[4];
float4 curveEmphasis; // .x full-opacity reach (<0 disables), .y fade length, .zw thin/thick width
float2 viewportSize; // current channel band size, in pixels
float cursorPos; // playback position relative to visible range, unclamped
float seekPos; // seek target relative to visible range, unclamped
float scanProgress; // waveform analysis progress, 0..1
bool playbackActive; // playback is active; drives played coloring
bool cursorVisible; // draw the cursor line marker
bool seeking;
bool horizontal; // panel orientation
bool flipped_h; // horizontal (time-axis) mirror
bool flipped_v; // vertical (amplitude) mirror
bool half_wave;
bool useCustomColors; // 7-slot palette vs 4-color style
bool shade_played;
bool transparent;
bool gap_dark;
float4 styleParams; // .x fill (0 flat, 1 glow, 2 heat), .y peak outline, .z styleTex enabled, .w outline width px
float4 styleDeep[2]; // dark gradient end: [0] unplayed, [1] played
float4 styleHot[2]; // bright gradient end: [0] unplayed, [1] played
float4 effectParams; // .x kind (0 none, 1 scanline, 2 pulse, 3 shimmer), .y played color weight, .zw line/band width px
float4 effectLines; // scanline offsets from cursor in pixels; positive = later in time
float4 effectLineAlphas; // scanline opacities
float4 effectBands; // shimmer opacities for bands 1-4, oldest first
float4 effectColor; // .rgb tint, .w shimmer band 5 opacity (next to cursor)
};
struct VS_IN { float2 pos : POSITION; float2 tc : TEXCOORD0; };
struct PS_IN { float4 pos : SV_POSITION; float2 tc : TEXCOORD0; };
So a minimal shader file is just your VS and
PS (plus any helpers). Reported compile errors count from
line 1 of your file. Because the block is prepended, these declarations
may change between builds (see the warning above).
Pipeline conventions:
POSITION and TEXCOORD0 are both
float2. Multi-channel tracks are drawn as stacked bands,
once per enabled channel, each in its own viewport.tc.x is time in [0, 1] (with the horizontal
flip already applied) and tc.y is the amplitude axis in
[-1, 1], with 0 at the band centre line.sample.rgb = (sample.rgb - 0.5 * sample.a) * (1 + sample.a)
before interpreting .r as the lower peak, .g
as the upper peak and .b as RMS. Mip levels are
envelope-preserving (peaks are not averaged away) so narrow panels keep
their detail.transparent is
set, sample bgTex at
input.pos.xy / windowSize.xy to composite over the parent
window; otherwise fall back to backgroundColor.labelTextTex is a full-panel
premultiplied-alpha bitmap. Composite it as
label + background * (1 - label.a), not straight-alpha
interpolation.styleParams, styleDeep, styleHot
and the effect fields to implement the corresponding controls. When
styleParams.z is enabled, styleTex provides
per-time-column tinted colors in six rows: RMS unplayed/played, deep
unplayed/played, then hot unplayed/played. Disabled or unavailable
optional textures can be null.The component only provides these inputs — it is
entirely up to the shader writer to honor them. The constant-buffer
fields largely correspond to Configuration dialog
settings; if a shader ignores a field or uses it differently, the
matching tuning control will have no effect, a different effect,
or an unintended effect. For example, a shader that never reads
shade_played, half_wave,
cursorParams, the color fields, and so on will not respond
to those settings, and the built-in behavior for them does not apply.
Matching the tuning dialog is the shader's responsibility, not the
component's.
| Item | GUID | Purpose |
|---|---|---|
| Default UI element | 7AFF636B-616F-4EBB-990C-9CDC09FE1527 |
The "Waveform Seek Bar" Default UI panel. |
| Columns UI panel | 1758AA44-F83A-432F-88AA-A0E98497CCD3 |
The "Waveform Seek Bar" Columns UI panel. |
| Columns UI toolbar | 398D31E4-6C1F-4545-9FE8-B546D1AFFC75 |
The "Waveform Seek Bar" Columns UI toolbar (rebar) variant. |
| Preferences page | 6F2A9D31-8C44-4E2B-9F51-7A3E0B6C1D02 |
Page under Preferences > Tools. |
| Advanced Preferences branch | CB775F9B-E3E7-40C5-A1DF-9FFA10BD3765 |
"Waveform Seek Bar" branch under Preferences > Advanced > Display > Visualisations. |
| Main menu group | 25053399-FCE4-4ED3-8571-7E5E877C2D28 |
"Waveform Seek Bar" submenu under Library. |
| Cache service | FAB05A5F-6018-4AB5-A27F-3A4753E7C9DC |
Waveform analysis/cache service. |
| Player service | 39912A07-E84D-4DF9-8A27-6A3F75D7E363 |
Playback interface service. |
| Waveform query | C0B698B5-D347-46B2-B64F-820A7470000B |
Asynchronous waveform request object. |
| Main menu: Sync waveforms with Library | 3F6C1A82-9D4E-4B7A-B1C2-5E8F0A6D3C74 |
Command. |
| Main menu: Rescan all waveforms | 287AEEC4-F88A-4520-9E3B-D4B6FD9C242F |
Command. |
| Main menu: Remove stale waveforms | A8BD96C9-C4B6-4DEE-B29E-0695574F8C9C |
Command. |
| Main menu: Compact waveform database | 506880BC-E8C9-4256-8F56-55C37315C705 |
Command. |
| Context menu: Extract/analyze | DFEA3DE8-45B7-485B-8FDA-96187986AED5 |
Playlist context-menu command (analyze selection). |
| Context menu: Force re-extract | E97BB75F-98DF-45D6-96D8-FC78FB2B07E8 |
Playlist context-menu command (re-analyze selection). |
| Context menu: Remove waveform | B84348AD-40F2-4F22-8CAF-DDE9354C0855 |
Playlist context-menu command (remove selection's waveform). |
Global settings on the Preferences > Tools > Waveform
Seek Bar page, persisted as foobar2000 cfg_var
entries.
| Option | GUID | Type | Default |
|---|---|---|---|
| Match pattern | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E01 |
cfg_string |
Built-in match pattern |
| Use custom colors | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E02 |
cfg_bool |
false |
| Color palette | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E03 |
cfg_struct |
Built-in 7-slot palette |
| FPS | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E04 |
cfg_int |
30 |
| Seek per wheel notch (amount) | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E07 |
cfg_int |
10 |
| Wheel seek unit | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E08 |
cfg_int |
seconds |
| Invert wheel direction | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E09 |
cfg_bool |
false |
| Waveform track | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E0A |
cfg_int |
Playing track |
| Waveform storage | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E0D |
cfg_int |
Streams and tracks in library |
| Abort when below real time | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E0F |
cfg_bool |
true |
| Use saved defaults | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E16 |
cfg_bool |
false |
| Default renderer | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E17 |
cfg_int |
0 (Direct3D 11.1) |
| Analyze tracks outside library | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E19 |
cfg_bool |
true |
| Incremental updates | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E1A |
cfg_bool |
true |
| Store analyzed tracks in mono | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E1B |
cfg_bool |
false |
| Concurrent scanning threads | A2C1E6F0-3B14-4E90-9C21-0F1A1E93B511 |
cfg_int |
3 (clamped 1–16) |
| Halt waveform processing | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E1C |
cfg_bool |
false (toggled from context menu) |
| Filtered waveform resampling | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E1E |
cfg_bool |
false |
| Cache size limit (MB) | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E1F |
cfg_int |
0 (no limit) |
| Cache age limit (days) | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E20 |
cfg_int |
0 (keep forever) |
| Prefetch next track | A2C1E6F0-3B14-4E90-9C21-0F1A6D9B7E21 |
cfg_bool |
false (set in Analysis dialog) |
Per-panel settings from the Configure... and Analysis dialogs. Each panel instance stores these together as a JSON blob in its Default UI element / Columns UI panel configuration (keyed by the panel GUID above). Presets and saved panel defaults include Analysis settings; global prefetch and the current zoom/pan interval are not per-panel preset settings. The JSON keys, types, defaults and ranges are:
| JSON key | Type | Default | Range / values |
|---|---|---|---|
frontend |
enum | 0 (Direct3D 11.1) |
0 = Direct3D 11.1, 2 = Direct2D 1.1,
3 = GDI |
legacy_rendering |
bool | false |
4-color styling instead of the 7-slot palette |
custom_colors[7] |
color | palette colors | Per-slot RGBA override values |
custom_override[7] |
bool | all false |
Per-slot: use the custom color instead of the global one |
has_border |
bool | false |
Draw window border |
always_show_cursor |
bool | false |
Show the play cursor over the waveform while playing; when off, it appears only if no waveform is available (never while stopped) |
cursor_width |
float | 2 |
Logical pixels, DPI-scaled at draw; fractional so any device-pixel
width is selectable (~0.1–64) |
cursor_translucency |
int | 100 |
10–100 percent opaque |
soft_cursor |
bool | false |
Draw the cursor with a soft feathered glow instead of a hard edge |
cursor_glow |
bool | false |
Animated glow trailing the playback cursor |
glow_trail |
int | 3 |
0–24; dialog offers 3,
6, 12, 24, or 0
(100% of played area in Direct3D 11; 24x in other renderers) |
cursor_effect |
int | 0 (None) |
0 = None, 1 = Scanline, 2 =
Pulse, 3 = Shimmer |
bpm_sync |
bool | false |
Sync cursor effects to the displayed track's BPM/TBPM/TEMPO tag; default speed when unavailable |
no_seek_color |
bool | false |
Draw the live-seek/scrub marker in the cursor color instead of a derived contrast color |
album_art_colors |
bool | false |
Derive a contrast-checked waveform palette from the displayed track's front cover (falls back to normal colors when unavailable) |
accent_colors |
bool | false |
Derive waveform colors from RMS (played); backgrounds retained, album art and per-slot overrides take priority (7-color waveform only) |
fill_style |
int | 0 (Flat) |
0 = Flat, 1 = Glow, 2 = Heat
(7-color waveform only) |
shade_played |
bool | true |
Shade the played portion |
reveal_played |
bool | false |
Draw only the played portion |
flip_display |
bool | false |
Flip horizontally (reverse time) |
flip_vertical |
bool | false |
Flip vertically (mirror amplitude) |
flip_alternate |
bool | false |
Flip every other channel or spectrogram band (half-wave or spectrogram; not with Mono downmix) |
half_wave |
bool | false |
Draw only the upper half |
zero_line |
bool | false |
Draw the silence/zero line |
edge_fade |
bool | false |
Feather the waveform silhouette with anti-aliasing (Direct3D 11 and GDI) |
peak_outline |
bool | false |
Thin peak-envelope contour in 7-color waveform view |
rms_smoothing |
int | 0 (Off) |
0–3000 ms; dialog offers Off, 400 ms or 3
s; affects display RMS only (7-color waveform view) |
scale |
int | 0 (Original) |
0 = Original, 1 = Normalize,
2 = RG track, 3 = RG album |
db_scale |
bool | false |
Amplitude on a decibel (dB) scale |
db_floor |
float | -60 |
-120–-20 dB |
scale_multiplier |
float | 1.0 |
0.1–5.0 |
replaygain_boost_db |
int | 0 |
0–30 dB |
transparent_background |
bool | false |
Pseudo-transparent background compositing |
channel_gap |
float | 2 |
Logical pixels between channel bands, DPI-scaled at draw; fractional
so any device-pixel gap is selectable (0–32,
Direct3D 11 only) |
gap_dark |
bool | false |
Darken the channel gap with translucent black (Direct3D 11 only) |
shader_path |
string | "" |
Relative path (under wavebar\) to a custom HLSL shader;
empty = built-in (Direct3D 11 only, experimental) |
waveform_track |
int | -1 (global) |
-1 = Use global setting, 0 = Playing,
1 = Selected, 2 = Playing/selected when
stopped, 3 = Blank at startup, 4 = Blank when
stopped |
downmix_display |
enum | 0 (None) |
0 = None, 1 = Mono, 2 =
Stereo; also selects the spectrogram bands |
channel_order |
list | default order | Channel enable/disable flags and top-to-bottom order |
display_mode |
enum | 0 (Normal) |
0–5 (Normal, Only + half, Only - half,
Average, Minimum, Maximum) |
Analysis and navigation settings use the same JSON object:
| JSON key | Type | Default | Range / values |
|---|---|---|---|
follow_playback |
bool | false |
Keep playback in view while zoomed; retained across tracks |
spectral_colors |
bool | false |
Three-band waveform coloring |
spectral_tint |
int | 0 |
0 = Off, 1 = Subtle, 2 =
Strong; 7-color waveform tint (selector excludes Three-band) |
spectrogram |
bool | false |
Show the spectrogram instead of the waveform |
spectrogram_floor |
int | -100 |
-120 to -40 dBFS |
spectrogram_palette |
int | 0 |
0 = SoX, 1 = Grayscale, 2 =
Spectrum, 3 = Custom |
spectrogram_max_frequency |
int | 22000 |
0 to 384000 Hz; display is capped at
Nyquist |
spectrogram_labels |
bool | true |
Frequency labels in spectrogram view |
spectrogram_stops |
list | four built-in stops | Custom palette positions and #RRGGBB colors; 1 to 16
stops |
measurement_curve{1,2,3,4} |
int | all 0 |
0 = None; 1 to 19 select
metrics with fixed display scales |
curve_colors |
list | yellow/cyan/pink/green | Four #RRGGBB curve colors |
curve_fade |
bool | true |
Cursor emphasis and fading of waveform curves |
cursor_metrics |
bool | false |
Values near the playback cursor at their curve levels |
full_scale_markers |
bool | false |
Near-full-scale sample markers (>= -0.1 dBFS) |
clipping_markers |
bool | false |
Full-scale sample markers (>= 0 dBFS) |
true_peak_markers |
bool | false |
True-peak overs (> 0 dBTP) |
correlation_strip |
bool | false |
Stereo phase-correlation strip |
summary{1,2,3,4} |
int | all 0 |
0 = None; remaining values select summary metrics,
including DR left/right |
summary_placement |
int | 2 |
0 to 8: top-left/center/right,
middle-left/center/right, bottom-left/center/right |
summary_layout |
int | 0 |
0 = Vertical, 1 = Horizontal |
time_labels, channel_labels |
bool | both false |
Time-axis and waveform channel labels |
channel_location |
bool | false |
false = End (E), true = Start (S) of time
axis; follows Reverse time |
label_outline |
bool | false |
Contrasting outline behind overlay labels and ticks |
label_font |
object | Segoe UI Bold, 12 DIPs | Font family, size (6 to 72), weight,
style, stretch and optional custom color |
measurement_tooltips |
bool | false |
Measurements in seek tooltips |
hover_tooltips |
bool | false |
Tooltips while moving the pointer without seeking |
tooltip_translucent |
bool | false |
80%-opaque measurement/hover tooltip background |
tooltip_measurements |
list | built-in selection/order | Enabled measurements and their tooltip display order |
Checkboxes under the Preferences > Advanced > Display
> Visualisations > Waveform Seek Bar branch (branch GUID
CB775F9B-E3E7-40C5-A1DF-9FFA10BD3765).
| Option | GUID | Default | Effect |
|---|---|---|---|
| Optimize memory | 2A4F1C8E-71B3-4D62-9A0E-5C2D88146F93 |
Checked (true) |
Releases GPU resources for hidden panels and rebuilds on show. |
| Disable flip-model presentation | A2755B1A-7073-4F8D-974E-C4343B4CB39A |
Unchecked (false) |
Uses the legacy blt (DISCARD) swap effect instead of
the DXGI flip model (Direct3D 11 and Direct2D); keeps the panel
DWM-composited. |
| Use DirectComposition presentation | B8BA47A3-7F30-42AF-ACB5-ED6012C98BE7 |
Unchecked (false) |
Alpha-capable composition flip swap chain for both GPU renderers; ignored when Disable flip-model presentation is checked, with HWND fallback on setup failure. |
| Enable alternate renderers | 7E9C89D8-64D4-4F64-A706-3D5B2DBACF21 |
Unchecked (false) |
Exposes Direct2D and GDI in renderer selectors; existing alternate-renderer panels remain unchanged. |
| Debug output | 1830F07C-5983-4F1D-8B3F-AD0151D8DD22 |
Unchecked (false) |
Logs scanning, screenshot and clipboard activity to the console. |
| Save all settings in preset files | 16E26B6E-5760-4213-80FA-C8B2498F4414 |
Unchecked (false) |
Writes every setting into saved presets; otherwise presets contain only values that differ from the defaults. |