Module matching 

In-memory fingerprint matching and identification.

This module provides a Matcher trait and one algorithm per fingerprinter. All matching is purely in memory — there is no persistence, no serialisation format, no database adapter, and no on-disk index. Everything operates on in-memory fingerprints and returns an in-memory MatchResult.

Architecture

Matcher	Fingerprint	Strategy
WangMatcher	WangFingerprint	Offset-histogram voter (Shazam-style)
PanakoMatcher	PanakoFingerprint	2-D Hough + optional RANSAC (tempo-invariant)
HaitsmaMatcher	HaitsmaFingerprint	BER sliding + sub-fingerprint LUT
NeuralMatcher	NeuralFingerprint	Cosine similarity (requires the neural feature)

Quick example

extern crate alloc;
use audiofp::classical::{Wang, WangFingerprint};
use audiofp::matching::{WangMatcher, WangMatchConfig, Matcher, MatchResult};
use audiofp::{Fingerprinter, SampleRate};

let samples: alloc::vec::Vec<f32> = alloc::vec![0.0_f32; 8_000 * 4];
let mut wang = Wang::default();
let q = wang.extract(&samples, SampleRate::HZ_8000).unwrap();
let r = q.clone();

let matcher = WangMatcher::new(WangMatchConfig::default());
let m = matcher.match_one(&q, &r);
if m.is_match {
    println!("same recording (score {:.2}, offset {} ms)", m.score, m.offset.ms);
}

Structs

HaitsmaIndex

An in-memory inverted index over several Haitsma fingerprints.

HaitsmaMatchConfig

Configuration for HaitsmaMatcher.

HaitsmaMatcher

Offline 1:1 Haitsma matcher (BER minimisation).

MatchResult

Outcome of matching a query fingerprint against one reference.

NeuralMatchConfig

Configuration for NeuralMatcher.

NeuralMatcher

Offline 1:1 neural matcher (cosine similarity).

PanakoIndex

An in-memory inverted index over several Panako fingerprints.

PanakoMatchConfig

Configuration for PanakoMatcher.

PanakoMatcher

Offline 1:1 Panako matcher (2-D Hough + optional RANSAC).

PanakoRefIndex

Prebuilt reference index for PanakoMatcher::match_one_prebuilt.

TimeOffset

Signed time offset of the query relative to the reference.

WangIndex

An in-memory inverted index over several Wang fingerprints.

WangMatchConfig

Configuration for WangMatcher.

WangMatcher

Offline 1:1 Wang matcher (Shazam-style offset-histogram voter).

WangRefIndex

Prebuilt single-reference index for WangMatcher.

Enums

Aggregation

Aggregation strategy for comparing two embedding sequences.

Constants

HAITSMA_V1_MID

Haitsma v1 calibration: score (1 − BER) gap (0.573, 0.888) → mid 0.73, slope 29 maps the edges to ≈0.010/0.990.

HAITSMA_V1_SLOPE

See HAITSMA_V1_MID.

NEURAL_SLOPE

Neural calibration slope: deliberately conservative (k=20) — there is no corpus coverage for embeddings, and cosine scales vary by model. The midpoint is NOT fixed here: it anchors at the matcher’s own min_cosine, so the decision boundary always maps to exactly 0.5. Refit per deployment; see the recalibration recipe in ROBUSTNESS.md.

PANAKO_V1_MID

Panako v1 calibration: score gap (0.003, 0.480) at fit time → mid 0.24, slope 19 maps the edges to ≈0.011/0.989. The corpus expansion added a weaker positive (acidjazz ogg, 0.394 → ≈0.949); the map is unchanged — see ROBUSTNESS.md “Calibrated confidence”.

PANAKO_V1_SLOPE

See PANAKO_V1_MID.

WANG_V1_MID

Wang v1 calibration: score gap (0.001, 0.405) on the corpus → mid 0.20, slope 22 maps the edges to ≈0.011/0.989.

WANG_V1_SLOPE

See WANG_V1_MID.

Traits

Matcher

One matcher per fingerprinting algorithm.

Functions

calibrated_haitsma

Estimated P(same recording | Haitsma evidence): logistic map of the 1 − BER score. Versioned haitsma-v1; see module docs.

calibrated_neural

Estimated P(same recording | neural evidence): logistic map of the cosine score anchored at min_cosine (the matcher’s own decision boundary → exactly 0.5). Provisional slope (NEURAL_SLOPE): no corpus coverage, model-dependent — refit per deployment.

calibrated_panako

Estimated P(same recording | Panako evidence): logistic map of the RANSAC-inlier-ratio score. Versioned panako-v1; see module docs.

calibrated_wang

Estimated P(same recording | Wang evidence): logistic map of the contrib-ratio score. Versioned wang-v1; see module docs.

clamp_score

Clamp a score into [0.0, 1.0].

compute_prominence

Compute prominence: peak / (mean_of_rest + 1.0).

match_best

Find the single best-matching reference.

match_ranked

Score every reference and return all results sorted by descending score (ties broken by descending prominence).

match_result_compare_desc

Compare two MatchResults in descending order of quality.

par_match_best

Rayon-parallel match_best (requires the rayon feature, audit C5).

par_match_ranked

Rayon-parallel match_ranked (requires the rayon feature, audit C5).

score_compare

Compare two f32 scores safely (NaN-proof).