Skip to main content

Generate waveforms

ClaudeAuthored by Claude · Last updated AI generated documentation written by reading the source code
self-hosted

The generate_waveforms job analyzes your music files and creates the waveform that Cardinal Music shows for the currently playing track, replacing the plain scrubber bar with a smooth, colored wave.

What it creates​

For each track, the job decodes the audio once and stores a compact summary:

  • The waveform: The shape of the track over time, including how the energy is spread across bass, mids, and treble. Cardinal Music uses the frequency data to color the wave.
  • Loudness: The overall loudness of the track, measured with the EBU R128 standard.
  • Silence: The length of any silence at the start and end of the track.

The waveform is a small summary (a few kilobytes per track), and the original audio files are never modified.

How the shape is calculated​

The track is decoded to mono 44.1 kHz PCM, then split into a fixed number of time bins (roughly 5 per second, clamped between 600 and 2,400 so short tracks stay detailed and long ones stay compact). For each bin:

  • RMS (root-mean-square energy) drives the body of the wave. RMS is used instead of peak level because it survives heavily compressed ("brickwalled") masters, where the peak level alone would just render a flat rectangle.
  • Peak (maximum absolute sample) is rendered separately as a thin, low-opacity line floating just outside the body, carrying the transient detail RMS smooths away.
  • Low / mid / high energy is the same RMS calculation run through three frequency filters (crossovers at 250 Hz and 4 kHz). Cardinal Music blends these three values into the color wash across the wave, so bass-heavy sections read as a different color than bright, treble-heavy ones.

The body shape is a single continuous, mirrored envelope, not discrete bars.

Normalization​

Raw bin values are quantized to a single byte (0–255) before being stored:

  • Peak and RMS are each normalized to their own 98th-percentile value, independently. This keeps one loud transient from flattening the rest of the wave relative to it.
  • The three frequency bands share one normalization scale (the largest of their individual 98th percentiles), so their relative balance — the thing that actually drives the color — isn't distorted by normalizing them separately.

On top of that, Cardinal Music applies a perceptual gamma curve when rendering, and enforces a minimum visible height so quiet passages still show a faint line rather than disappearing completely.

When it runs​

The job runs automatically after each indexing run, and only processes tracks that don't have a waveform yet. If you play a track before the job has reached it, the waveform is generated on the spot and appears in the player — crossfading in — as soon as it's ready.

File types​

Any audio file that your Media Server can play will work, including .mp3 and .flac — the same ffmpeg decoder used for playback and transcoding generates the waveform, so there's no separate compatibility list to maintain.

Was this article helpful?