Dedicated to Maj. Brian Dix, USMC (Ret.)
Fmr. Director of "The Commandant's Own" United States Marine Drum & Bugle Corps

Dix (VibeComposing) Analyzer

Sister project: FL-Studio-MCP-Server — an MCP server that lets Claude Code drive FL Studio and generate editable .flp projects. Where this Analyzer reads a finished mix (spectrum, key, loudness), that server writes the FL project behind it. Both grew out of the As30p toolchain and are dedicated to a Marine bandmaster — this one to Maj. Brian Dix ("The Commandant's Own"), its sibling to John Philip Sousa ("The President's Own").

A native VLC audio-visualization plugin for seeing the tracks you vibecompose — a pro-style analyzer dashboard with a scrolling spectrogram, FFT spectrum, stereo waveform, vectorscope, phase correlation, and peak/RMS meters. Built for the workflow of auditioning a track in VLC and watching the mix breathe.

Module name: dixwaveform · target: VLC 3.0.x, macOS arm64 (portable to Linux .so).

What it does

• Registers as a VLC "visualization" module — an audio filter that also draws video.
• Reads the live 32-bit-float PCM buffer, computes real-time analysis, renders a 1280x720 analyzer frame, and passes the audio through untouched.
• Shows engineering views: scrolling log spectrogram, FFT magnitude/peak-hold spectrum, stereo waveform/oscilloscope, and stereo phase + peak/RMS/crest/clip meters.
• Plus a compose view that hears the music: a live chromagram (12 pitch classes), circle-of-fifths key detection, a nearest-note + cents tuning readout, and an energy/build-drop ribbon — grounded in the Dix music library (pitch math from Mathematics and Music; groove/structure from Unlocking the Groove).
• Adds a production view that turns the As30p production playbook into mix/master QA: tonal-balance bands, loudness targets, crest/headroom, low-end mono safety, per-band width, and masking risk.
• Switch views in-window — a row of clickable tabs across the top (DASH · PROD · KEYS (COMPOSE) · SPECTRO · SPECTRUM · WAVE · STEREO) lets you jump between layouts with a mouse click, no VLC menus. (KEYS (COMPOSE) = the key/compose view.)
• Selectable via Audio ▸ Visualizations ▸ Dix Analyzer, or --audio-visual=dixwaveform.

The seven views

Click a tab to switch — no VLC menus. (Screenshots: As30p feat. The Dixie Flatline — Antigua Runners Theme (OST).)

PROD — the production QA view: tonal balance, LUFS targets, crest/headroom, low-end mono safety, per-band width, and masking watch.

KEYS (COMPOSE) — the musical view: nearest note + cents, a 12-bin chromagram, the estimated key on a circle-of-fifths wheel, and an energy build/drop ribbon.

DASH — the full engineering dashboard: spectrogram, spectrum, stereo waveform, and stereo/meters (correlation, crest, clip) at a glance.

SPECTRO — a full-window scrolling log-frequency spectrogram.

SPECTRUM — a full-window FFT magnitude spectrum with peak-hold.

WAVE — a full-window stereo waveform / oscilloscope (L/R or M/S).

STEREO — a full-window vectorscope with correlation, crest, and clip meters.

Install (macOS / Linux)

./install.sh

One-shot permanent install so every VLC launch finds the plugin — including Dock / Finder / Spotlight / Start-menu launches, which do not inherit your shell environment. On macOS the installer copies the plugin straight into VLC.app's own plugin bundle, invalidates VLC's plugin cache, and re-seals the app's code signature (ad-hoc, preserving VLC's entitlements) — that last step is required because adding a file to the signed bundle otherwise makes macOS refuse to launch it. It also wires VLC_PLUGIN_PATH (shell rc + LaunchAgent) as a fallback for terminal launches. Idempotent; safe to re-run. (To just build without touching your environment, use ./build.sh below.)

Not seeing "Dix Analyzer" under Audio ▸ Visualizations after a Dock/Start-menu launch? Re-run ./install.sh (macOS installs into the app bundle), then fully quit and relaunch VLC. If VLC is installed somewhere other than /Applications/VLC.app, run VLC_APP=/path/to/VLC.app ./install.sh.

VLC won't open at all after installing? The bundle edit broke VLC's signature seal. ./install.sh now re-seals it automatically; if you hit this on an older install, run: xattr -cr /Applications/VLC.app && codesign -f -s - --preserve-metadata=entitlements /Applications/VLC.app. (VLC.app becomes ad-hoc signed; a fresh VLC reinstall restores the original signature — just re-run ./install.sh after.)

Build (macOS, arm64)

./build.sh

Fetches the VLC 3.0.23 public headers, compiles against your VLC.app's own bundled libvlccore (ABI-matched), ad-hoc signs, and stages the plugin to ~/vlc-plugins/. No full VLC source build required — the one trick that makes an out-of-tree macOS plugin feasible.

After replacing the plugin, refresh VLC's plugin cache once with --reset-plugins-cache; otherwise VLC may report a stale user-plugin cache.

Run

VLC_PLUGIN_PATH=~/vlc-plugins /Applications/VLC.app/Contents/MacOS/VLC \
  --reset-plugins-cache --audio-visual=dixwaveform yourtrack.mp3

Add VLC_PLUGIN_PATH=~/vlc-plugins to your login environment to have it always available.

Linux:

./build-linux.sh
VLC_PLUGIN_PATH=~/vlc-plugins vlc --reset-plugins-cache \
  --audio-visual=dixwaveform yourtrack.mp3

Windows:

# Run from an MSYS2 shell with MinGW on PATH.
pacman -Sy --needed --noconfirm mingw-w64-x86_64-gcc p7zip curl file
export PATH=/mingw64/bin:/usr/bin:$PATH
./build-win.sh

The Windows build produces libdixwaveform_plugin.dll. Stage it into VLC's visualization plugin directory, then regenerate the VLC plugin cache:

Copy-Item .\libdixwaveform_plugin.dll "$env:ProgramFiles\VideoLAN\VLC\plugins\visualization\"
& "$env:ProgramFiles\VideoLAN\VLC\vlc-cache-gen.exe" "$env:ProgramFiles\VideoLAN\VLC\plugins"

Options

vlc --audio-visual=dixwaveform \
  --dix-layout=dashboard \
  --dix-fft=4096 \
  --dix-scale=log \
  --dix-channels=lr \
  --dix-speed=normal \
  --dix-palette=warm \
  --dix-title="The Star-Spangled Banner - United States Marine Band" \
  yourtrack.mp3

• --dix-layout=dashboard|spectrogram|waveform|spectrum|stereo|compose|production
  • compose — chromagram, circle-of-fifths key, note/cents readout, and energy/build-drop ribbon.
  • production — playbook-derived mix QA: tonal balance, LUFS targets, low-end mono, per-band width, crest/headroom, and masking watch.
• --dix-fft=1024|2048|4096|8192
• --dix-scale=log|linear
• --dix-channels=lr|ms|left|right
• --dix-speed=slow|normal|fast
• --dix-palette=warm|classic|mono
• --dix-reference=off|avg|tilt|both — overlay a reference on the spectrum: avg = the track's long-term-average curve, tilt = a −3 dB/oct "pink" target slope, both. A quick tonal-balance check.
• --dix-dash="a,b,c,…" — custom dashboard: a comma list of panels auto-arranged into a grid, mixing engineering, composition, and production panels freely. Panels: spectrogram, spectrum, waveform, stereo, chroma, key, note, energy, lufs, tonal, lowmono, width, crest, mask (up to 6). Empty = the default dashboard. Example: --dix-dash="spectrum,lufs,tonal,width".

The lufs panel is a real ITU-R BS.1770-4 / EBU R128 loudness meter: momentary (400 ms), short-term (3 s), and gated integrated LUFS, with −14 (streaming), −10..−9 (club/SoundCloud), and −23 (broadcast) target ticks. K-weighting coefficients are derived for the actual sample rate; the engine (dix_lufs.h) is unit-tested.

• --dix-title="Track Name" draws title text after DIX ANALYZER in the header.

The compose view

--dix-layout=compose turns the analyzer from an engineering scope into a musical one — it reads the live FFT and shows what note/key/energy the track is, not just its signal. Four panels:

Panel	What it shows	How to read it
NOTE	The nearest note of the strongest pitch, e.g. A4, with a cents readout and a tuning needle.	Needle green = in tune (±8¢), amber = off. Also prints the raw Hz.
CHROMA	A 12-bar chromagram — how much energy is in each pitch class (C, C#, … B) right now, octave-collapsed.	Tall bars = the pitches sounding. In-key classes are bright; out-of-key are dimmed.
KEY	The estimated musical key on a circle-of-fifths wheel (e.g. D MINOR), tonic lit.	Uses Krumhansl–Schmuckler profile matching, time-smoothed so it doesn't flicker.
ENERGY	A scrolling low/mid/high spectral-balance ribbon with an onset (spectral-flux) overlay.	The build/drop map — energy rises into drops, shifts upward on brighter sections.

The music theory is grounded in the Dix library: pitch math (A440, midi = 69 + 12·log2(f/440), cents) from Mathematics and Music; key/groove framing from Unlocking the Groove and the Complete Idiot's Guide to Music Composition. The DSP lives in dix_pitch.h and is unit-tested (see Tests).

Access it: click the KEYS (COMPOSE) tab at the top of the Dix window, launch with --dix-layout=compose, or set the layout in the plugin's advanced preferences.

The production view

--dix-layout=production turns the analyzer into a real-time production QA surface grounded in the As30p production playbook:

Panel	What it shows	Playbook check
TONAL BALANCE	Sub, low, mud, body, presence, harsh, air, and top bands relative to full-band average.	Pink-ish contour, cut mud, watch harshness, keep air controlled.
LOUDNESS	Momentary, short-term, and gated integrated LUFS.	Streaming -14 LUFS; club/SoundCloud -10..-9 LUFS; broadcast -23 LUFS.
CREST HEADROOM	Crest factor, sample peak, and integrated LUFS readout.	Preserve 8-12 dB crest and avoid hot sample peaks.
LOW MONO	Low-band correlation and side-width.	Kick, bass, and sub stay mono-centered.
WIDTH BY BAND	Low/mid/high correlation plus side share.	Low end narrow, highs may widen, correlation stays above zero.
MASK WATCH	Mud, vocal presence, harshness, and air risk bands.	Pan first, mirror EQ, protect vocal presence, cut narrow and boost wide.

Tests & CI

• Unit tests cover the pitch/chroma/key DSP (dix_pitch.h), the BS.1770 loudness engine (dix_lufs.h), and the production QA helpers (dix_prod.h) — Hz→note, cents, key detection, diatonic membership, K-weighting coefficients, level scaling, gated integrated loudness, band power, stereo correlation, width, and crest math. Run locally:

  cc -O2 -std=c99 -o test_pitch tests/test_pitch.c -lm && ./test_pitch
  cc -O2 -std=c99 -o test_lufs  tests/test_lufs.c  -lm && ./test_lufs
  cc -O2 -std=c99 -o test_prod  tests/test_prod.c  -lm && ./test_prod

• CI (.github/workflows/ci.yml) runs those unit tests and a plugin build-smoke on Linux, macOS, and Windows for every push/PR to main. Release binaries for all three are published on v* tags (release.yml).
• UI is verified interactively on macOS (arm64). The Linux/Windows builds are exercised in CI, but interactive UI on those platforms is not yet part of automated testing.

Layout

• waveform.c — the plugin: descriptor + Open/DoWork/Close, FFT analysis, meters, composition analysis, RGB dashboard renderer, and I420 conversion.
• dix_pitch.h — pure, VLC-independent pitch/chroma/key DSP (unit-tested standalone).
• dix_lufs.h — ITU-R BS.1770 loudness engine (unit-tested standalone).
• dix_prod.h — pure production QA helpers for band power, correlation, width, and crest math.
• tests/test_pitch.c, tests/test_lufs.c, tests/test_prod.c — unit tests for the DSP.
• build.sh — fetch headers, compile, sign, stage (macOS).
• build-linux.sh — compile and stage the Linux .so.
• build-win.sh — build the Windows .dll with MSYS2/MinGW.
• vlc-3.0.23-include/ — VLC public headers (fetched by build.sh; git-ignored).

Scope & honesty

A real-time "watch it scroll" visualizer, not a scrub-the-whole-file analyzer (that's Audacity's job). Loudness is a real ITU-R BS.1770-4 / EBU R128 meter (lufs panel: momentary/short-term/gated-integrated), and PROD adds playbook-derived production guidance from live analyzer metrics. It still does not do offline source separation, DAW/project inspection, true-peak oversampling, or ML chord/tempo transcription.

Roadmap

See BACKLOG.md. Future ideas: onset/tempo/beat-grid detection, chord identification, and sound-design diagnostics.

License

Links VLC's libvlccore (LGPL-2.1+/GPL-2.0+), so this ships GPL-2.0-or-later to stay compatible. See LICENSE.

Built live with Dix. As30p / Ronin 48.

Proudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/