chroma

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: BSD-3-Clause Imports: 4 Imported by: 0

README

chroma

Chroma audio features in pure Go, no cgo: the front end of Chromaprint, ported stage by stage against that project's own unit tests.

features, err := chroma.Features(pcm)   // mono int16 at 11025 Hz
// one []float64 of 12 bands per frame, normalised

A chroma vector says how much energy a moment of audio holds at each of the twelve notes, with octaves folded together: a C is a C whether it is played low or high. That is what makes it the right feature for "are these two files the same recording?" — it survives re-encoding, volume changes and a different master, where a waveform comparison sees none of those as the same.

⛔ Not an AcoustID fingerprint

Chromaprint turns these features into 32-bit sub-fingerprints with sixteen trained classifiers. That stage is not here, so nothing this package produces can be looked up against the AcoustID database. What it gives is the feature sequence those classifiers run on, which is what near-duplicate detection needs.

The chain

stage
window Hamming, scaled by 1/32767
transform RFFT from go-fft
spectrum energy (r² + i²), not magnitude
chroma bins folded onto 12 pitch classes, 28–3520 Hz
filter 5-tap blur over time, {0.25, 0.75, 1, 0.75, 0.25}
normalise unit length, or zero below 0.01

Geometry: 4096-sample frames at 11025 Hz, hopping by FrameSize/3 ≈ 124 ms.

Each number earns its place. The top of the band stops well short of Nyquist because that is where lossy codecs differ most, so including it would make the feature depend on the encoder. Normalisation zeroes a quiet frame instead of scaling it: dividing a nearly silent frame by its tiny norm would amplify its noise into a confident-looking chord, making the loudest thing in the fingerprint the quietest moment of the recording.

⚠ Two traps, both measured

Energy, not magnitude. The reference stores r*r + i*i and the bands are sums of that. Taking a square root first changes every value and still looks entirely reasonable.

Concert A is the worst thing to test with. The octave scale is based at A0 = 27.5 Hz, so A sits exactly on a band edge. At this geometry the nearest bin to 440 Hz is 163.46, and the energy lands in bin 163 (438.75 Hz, band 11) and bin 164 (441.44 Hz, band 0) — opposite sides of the wrap-around. Nothing is wrong: a boundary tone belongs to both neighbours. TestAToneOnTheBand BoundarySplits keeps that written down, because reaching for 440 Hz is the obvious move and it fails looking like a broken mapping.

⛔ Resampling is not done here

Features expects mono PCM already at 11025 Hz. Resampling belongs to the decoder, which knows the source rate; doing it badly here would silently change every feature. Audio at another rate produces a plausible result that matches nothing.

Verified against the reference

Chromaprint's own test values are reproduced as Go tests: six for the chroma mapping — including the interpolated cases, which are what distinguish truncating from rounding — and Blur2, Blur3 and Diff for the filter, with its exact float literals.

Beyond those: a steady tone does not wander between frames, an octave apart is the same band end to end, volume does not change the fingerprint, silence produces no pitch, and the frame count follows the hop less the frames the filter swallows while filling.

Licence

BSD-3-Clause.

Documentation

Overview

Package chroma turns a spectrum into the twelve pitch classes.

A chroma vector says how much energy a moment of audio holds at each of the twelve notes, with octaves folded together: a C is a C whether it is played low or high. That is what makes it the right feature for asking "are these two files the same recording?" — it survives re-encoding, volume changes and a different mix of the same master, while a waveform comparison sees none of those as the same.

This is the front end of Chromaprint (github.com/acoustid/chromaprint), ported stage by stage against that project's OWN unit tests, which are reproduced here as Go tests with their original values.

⛔ It is NOT an AcoustID-compatible fingerprint. Chromaprint turns these features into 32-bit sub-fingerprints with sixteen trained classifiers; that stage is not here, so nothing produced by this package can be looked up against the AcoustID database. What it gives is the feature sequence those classifiers run on, which is what near-duplicate detection needs.

Index

Constants

View Source
const (
	// SampleRate is what audio must be resampled to. Low, because pitch
	// lives well below it and a smaller rate means fewer samples to transform.
	SampleRate = 11025
	// FrameSize is the window length: 4096 samples, about 370 ms, long
	// enough to resolve a bass note.
	FrameSize = 4096
	// Overlap is how much of each frame the next one repeats, leaving a hop
	// of FrameSize/3 ≈ 124 ms. Overlapping frames are what keep a note from
	// vanishing because it fell on a frame boundary.
	Overlap = FrameSize - FrameSize/3
	// Hop is the distance between consecutive frames.
	Hop = FrameSize - Overlap
	// MinFreq and MaxFreq bound the band that carries pitch. The top stops
	// well short of Nyquist on purpose: that is where lossy codecs differ
	// most, so including it would make the feature depend on the encoder.
	MinFreq = 28
	MaxFreq = 3520
)

The geometry Chromaprint uses, and the reason for each number.

View Source
const Bands = 12

Bands is the number of pitch classes: twelve semitones in an octave.

View Source
const NormalizeThreshold = 0.01

NormalizeThreshold is the norm below which a vector is considered to carry no pitch at all.

⛔ Below it the vector is zeroed rather than scaled up. Dividing a nearly silent frame by its tiny norm would amplify whatever noise it holds into a confident-looking chord — the loudest thing in the fingerprint would be the quietest moment of the recording.

Variables

View Source
var DefaultCoefficients = []float64{0.25, 0.75, 1.0, 0.75, 0.25}

DefaultCoefficients is Chromaprint's five-tap blur.

View Source
var ErrTooManyTaps = errors.New("chroma: filter has more taps than the frame history can hold")

ErrTooManyTaps is returned for a filter longer than the ring can hold.

View Source
var ErrTooShort = errors.New("chroma: audio shorter than one frame")

ErrTooShort is returned when the audio does not fill one window.

Functions

func Features

func Features(samples []int16) ([][]float64, error)

Features turns mono PCM into a sequence of normalised chroma vectors.

⛔ samples must already be mono at SampleRate. Resampling is not done here: it belongs to the decoder, which knows the source rate, and doing it badly here would silently change every feature. Feeding audio at another rate produces a plausible result that matches nothing.

Each returned vector is a moment of music described only by the proportions of the twelve pitch classes — indifferent to volume, and to any re-encoding that preserves what a listener hears.

func Normalize

func Normalize(features []float64)

Normalize scales a chroma vector to unit length in place, or zeroes it when it is too quiet to mean anything.

After this a vector says only the PROPORTIONS of the twelve pitches, which is what makes the feature indifferent to volume: the same music mastered louder normalises to the same thing.

Types

type Chroma

type Chroma struct {

	// Interpolate spreads each bin's energy between its own note and the
	// neighbour it leans toward, instead of giving all of it to the nearest.
	// Off by default, as in the reference.
	Interpolate bool
	// contains filtered or unexported fields
}

Chroma maps the bins of one spectrum onto the twelve pitch classes.

It is built once for a given frame geometry and reused for every frame: the bin-to-note table depends only on the frame size and the sample rate, not on the audio.

func New

func New(minFreq, maxFreq, frameSize, sampleRate int) *Chroma

New builds the mapping for a frame of frameSize samples taken at sampleRate, considering only frequencies between minFreq and maxFreq.

Chromaprint's own values are 28 Hz and 3520 Hz at 11025 Hz: low enough for a bass line, high enough for the notes that carry melody, and deliberately short of the top of the spectrum, where lossy codecs differ most.

func (*Chroma) Consume

func (c *Chroma) Consume(spectrum []float64, out []float64) []float64

Consume folds one spectrum into twelve pitch classes.

spectrum holds the magnitudes of a frame's bins; only those inside the frequency range given to New are read. The result is written into out, which must have room for Bands values, and returned.

type Filter

type Filter struct {
	// contains filtered or unexported fields
}

Filter smooths a stream of chroma vectors over TIME, one tap per past frame.

Smoothing in time is what makes the feature survive re-encoding: a lossy codec moves energy between neighbouring frames, and a filter that spans several frames sees the same shape either way. Chromaprint's own coefficients, DefaultCoefficients below, are a five-tap blur.

⛔ A Filter is STATEFUL and emits nothing until it has seen as many frames as it has taps: a 5-tap filter over 4 frames produces no output at all. That is correct and is the first thing to check when a short clip yields an empty fingerprint.

func NewFilter

func NewFilter(coefficients []float64) (*Filter, error)

NewFilter returns a filter with the given taps.

func (*Filter) Consume

func (f *Filter) Consume(features []float64) []float64

Consume takes one chroma vector and returns the filtered vector, or nil while the filter is still filling.

The returned slice is reused on the next call: a caller that keeps it must copy it.

func (*Filter) Reset

func (f *Filter) Reset()

Reset forgets the history, as if no frame had been seen.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL