Crate audiofp 

audiofp — audio fingerprinting SDK for Rust.

audiofp extracts compact, codec-tolerant perceptual hashes from audio so you can identify the same recording across re-encoding, modest noise, and (for some algorithms) tempo or pitch changes — the fundamental primitive behind systems like Shazam or AcoustID.

The crate is no_std + alloc in API shape when the std feature is disabled, but the current FFT dependency chain still keeps the no_std path host-only today. The file decoder (io, behind std-* codec features) and watermark detector (watermark, feature watermark) live behind feature flags and require std.

Quick tour

• Errors — AfpError (#[non_exhaustive]) plus the Result alias.
• Value types — SampleRate (newtype around NonZeroU32 with HZ_* constants) and TimestampMs (ordered millisecond timestamp). Extraction takes &[f32] samples plus a SampleRate directly (the old AudioBuffer wrapper was removed in 0.4.0; see the migration guide in CHANGELOG.md).
• Traits — Fingerprinter for whole-buffer extraction, StreamingFingerprinter for incremental extraction. Every algorithm in the crate implements both.
• Classical fingerprinters — classical::Wang (Shazam-style landmark pairs), classical::Panako (tempo-invariant triplets), classical::Haitsma (Philips robust hash bands), each with a streaming sibling.
• Matching — matching identifies recordings from fingerprints in memory (WangMatcher, HaitsmaMatcher, PanakoMatcher with tempo-invariant 2-D Hough + RANSAC, optional neural cosine), plus WangIndex / HaitsmaIndex / PanakoIndex 1:N accelerators.
• DSP primitives — dsp exposes STFT, mel filterbank, peak picker, resampler, and tapered windows for users building their own pipelines on top of audiofp.

Panics in streaming APIs

All StreamingFingerprinter::push / flush implementations are fallible and return Result — including neural::StreamingNeuralEmbedder::push, which propagates ONNX inference errors instead of panicking (use neural::StreamingNeuralEmbedder::try_push / try_push_with for the callback-style equivalents). Classical streaming fingerprinters (Wang / Panako / Haitsma) never error on valid input. Constructors named new (e.g. ShortTimeFFT::new) panic on invalid configs; each has a try_new counterpart returning Result.

Example

Match two Wang fingerprints with the offset-histogram voter:

extern crate alloc;
use audiofp::classical::{WangFingerprint, WangHash};
use audiofp::matching::{Matcher, WangMatchConfig, WangMatcher};

let fp = WangFingerprint {
    hashes: (0..8u32)
        .map(|i| WangHash {
            hash: i,
            // 10 STFT frames apart (frame index in t_anchor).
            t_anchor: i * 10,
        })
        .collect(),
    frames_per_sec: 62.5,
};

let matcher = WangMatcher::new(WangMatchConfig::default());
let m = matcher.match_one(&fp, &fp);
assert!(m.is_match);
assert_eq!(m.offset.frames, 0);

Cargo features

The default build is no_std + alloc with no codecs. File decoding (audiofp::io) is opt-in per codec; each std-* feature pulls the matching symphonia decoder:

Feature	Default	Description
std		Symphonia itself (no codecs). Also enables the codec-free cache module (.afp fingerprint files) and IoError. Combine with a std-* feature for io.
std-wav		WAV + raw PCM decoding → io.
std-mp3		MP3 decoding → io.
std-flac		FLAC decoding → io.
std-ogg		Ogg-Vorbis decoding → io.
std-aac		AAC decoding → io.
std-mp4		AAC-in-MP4 / ISO-BMFF decoding → io.
std-aiff / std-mkv / std-adpcm / std-alac		Extended codecs → io.
all-codecs		Every format/codec above at once → io (the pre-0.4.0 std).
rayon		Parallel batch fingerprinting via fingerprint_batch_parallel (implies std).
watermark		Pulls in tract-onnx → watermark (implies std).
neural		Generic ONNX log-mel embedder (neural); pulls in tract-onnx (implies std).
mimalloc		Installs mimalloc::MiMalloc as the process-wide allocator (implies std).

See USAGE.md for the complete API guide.

Re-exports

pub use serial::FingerprintEnvelope;

pub use classical::Haitsma;

pub use classical::HaitsmaConfig;

pub use classical::HaitsmaFingerprint;

pub use classical::Panako;

pub use classical::PanakoConfig;

pub use classical::PanakoFingerprint;

pub use classical::PanakoHash;

pub use classical::StreamingHaitsma;

pub use classical::StreamingPanako;

pub use classical::StreamingWang;

pub use classical::Wang;

pub use classical::WangConfig;

pub use classical::WangFingerprint;

pub use classical::WangHash;

Modules

cache

File caching for fingerprints (.afp files).

classical

Classical (DSP-only) fingerprinters.

dsp

Digital signal processing primitives.

io

Audio file I/O helpers.

matching

In-memory fingerprint matching and identification.

neural

Generic ONNX log-mel audio embedder.

prelude

Convenience re-exports of the most commonly used types. See prelude for details. Convenience re-exports of the most commonly used types.

serial

Lightweight binary serialization for fingerprint types.

watermark

Audio watermark detection (AudioSeal-compatible).

Structs

IoError

Structured I/O error with path and source.

SampleRate

A sample rate in hertz, guaranteed non-zero.

TimestampMs

A timestamp in milliseconds since the start of a stream.

Enums

AfpError

All errors surfaced by audiofp.

Constants

VERSION

Crate version string, sourced from Cargo.toml.

Traits

Fingerprinter

Offline (whole-buffer) fingerprinter.

StreamingFingerprinter

Streaming fingerprinter that emits zero-or-more frames per push.

ZeroAllocStreaming

Marker contract for streaming fingerprinters whose push_with / flush_with perform no allocation after warmup.

Functions

fingerprint_batch_parallel

Multi-threaded batch fingerprinting (requires the rayon feature). Fingerprint a batch of audio buffers in parallel using rayon.

Type Aliases

Result

Shorthand for core::result::Result<T, AfpError>.