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 ¶
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.
const Bands = 12
Bands is the number of pitch classes: twelve semitones in an octave.
const MinOverlap = 0.5
MinOverlap is the smallest share of the shorter recording that must line up before an alignment counts.
⛔ Without it the score is meaningless. Sliding two sequences past each other eventually leaves a single frame facing a single frame, and one frame matching one frame is a cosine of 1.0 — a perfect score built on a quarter of a second. The floor is what makes a high score mean "these recordings agree over most of their length".
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 ¶
var DefaultCoefficients = []float64{0.25, 0.75, 1.0, 0.75, 0.25}
DefaultCoefficients is Chromaprint's five-tap blur.
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.
var ErrTooShort = errors.New("chroma: audio shorter than one frame")
ErrTooShort is returned when the audio does not fill one window.
Functions ¶
func Compare ¶ added in v0.2.0
Compare scores two feature sequences in [0,1]: 1.0 when they agree everywhere, 0.0 when they share nothing.
One sequence is slid against the other and the best alignment wins, so a recording that starts a few seconds later — a different rip, a leading silence, a trimmed intro — still matches. Only alignments overlapping at least MinOverlap of the shorter sequence are considered.
The score is the mean cosine of the aligned frames. Each frame is already unit length or zero, so the cosine is a dot product; a frame zeroed for being too quiet contributes nothing and is not counted, which keeps a long silence from either inflating or deflating the result.
⚠ It returns 0 when neither sequence has a usable frame, which is also what two recordings of silence give. Silence matches nothing, including itself, because there is nothing in it to match on.
func CompareAt ¶ added in v0.2.0
CompareAt is Compare plus the offset that produced the best score: the number of frames b must be shifted by to line up with a, negative when b starts first.
The offset is worth having for more than diagnosis: a caller that knows two files are the same recording can use it to say WHERE they differ.
func Features ¶
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 ¶
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.
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.