foo_wavebar

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.

Highlights

Rendering and Graphics

Waveform Analysis and Caching

Display and Styling

Configuration and Control

Platform and Interface

Verification

Run Requirements and Installation

Adding a Panel

The panel begins analyzing the current track automatically and shows an incremental waveform (if enabled) until the scan completes.

Usage

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.

Mouse Behavior

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.

Context Menu

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.

Analysis

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).

Spectral Coloring and Spectrogram

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.

Tooltips and Measurements

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.

Curves, Summaries and Labels

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.

Analysis Data and Compatibility

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.

Preferences

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.

Configuration Dialog

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:

Waveform track:

Tuning:

Channels:

Effects:

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.

Advanced Preferences

Under Preferences > Advanced > Display > Visualisations, find the Waveform Seek Bar branch:

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.

Rendering Engines

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.

Screenshot

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.

Clipboard

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.

Title Formatting

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.

Waveform Cache Storage

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.

Journal Mode

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.

Cache Limits

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 Storage

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.

Corrupt Database Recovery

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.

Running foobar2000 under Proton

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"

Fonts under Wine and Proton

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.

  1. Copy Segoe UI into the prefix (most faithful; requires a Windows license). Locate the Wine/Proton prefix foobar2000 runs in. For a Steam/Proton shortcut this is ~/.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/.
  2. Use Selawik (open, metric-compatible). Microsoft's MIT-licensed Selawik font is a drop-in, metric-compatible substitute for Segoe UI. Install 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.
  3. Substitute a font already on the system. Using the same 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\Replacements key is also where to look for (and delete) an existing Segoe UI (and Segoe UI Semibold) mapping if a copied font is not being picked up. A stray mapping to a serif face such as Times New Roman is 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.

Window Scaling under Wine and Proton

If the dialogs render too small or too large under Wine or Proton, adjust the prefix's DPI. Scaling is controlled through winecfg.

  1. Open winecfg for the prefix foobar2000 uses:
  1. In winecfg, open the Graphics tab and change the Screen resolution DPI value. 96 dpi is 100%; common steps are 120 (125%), 144 (150%) and 192 (200%). Higher values enlarge the entire UI; lower values shrink it.
  2. Click Apply / OK.

Note: The DPI value is stored in the registry at HKEY_CURRENT_USER\Control Panel\Desktop\LogPixels (a decimal REG_DWORD, e.g. 120), which you can also set directly with wine regedit instead of winecfg.

Custom Shaders (Experimental)

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.

Loading a shader

Bars and reflection example

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:

  1. Copy the preset JSON into <foobar2000 profile>\wavebar\.
  2. Copy the shader into <foobar2000 profile>\wavebar\shaders\bars_reflection.hlsl (create the shaders folder if needed).
  3. Reopen the panel's Configure... dialog, select Bars Reflection under Preset name, and click Load.

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.

Persistence

Whether a dropped shader persists depends on where the file lives:

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"

Authoring a shader

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:

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.

Reference

Component Identifiers (GUIDs)

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).

Preferences Options

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)

Configuration Options

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

Advanced Options

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.