Skip to content

API Reference

Jabberjay

Jabberjay.jabberjay.Jabberjay

Unified entry point for every synthetic voice detection model.

Construct once and call detect() with an audio file path or a pre-loaded (samples, sample_rate) tuple. Model weights are downloaded from Hugging Face Hub on first use and cached in memory for the lifetime of the process, so repeated calls for the same model skip both the download and the reload.

Example::

jj = Jabberjay()
result = jj.detect("audio.wav")            # default VIT model
result = jj.detect("audio.wav", model="HuBERT")

detect(audio, model=Model.VIT, visualisation=Visualisation.ConstantQ, dataset=Dataset.VoxCelebSpoof)

Detect whether audio is bonafide or spoofed.

Parameters:

Name Type Description Default
audio str | Path | Audio

Path to an audio file, or a pre-loaded (samples, sample_rate) tuple.

 required
model Model | str

Model to use. Accepts a Model enum value or its string name (e.g. "VIT").

 VIT
visualisation Visualisation | str | None

Visualisation for VIT models. Accepts Visualisation enum or string.

 ConstantQ
dataset Dataset | str | None

Dataset the model was trained on. Accepts Dataset enum or string.

 VoxCelebSpoof

Returns:

Type Description
DetectionResult

DetectionResult with label, confidence, and full scores where available.

Raises:

Type Description
ValueError

If required arguments are missing, or audio is empty.
KeyError

If an unrecognised string is passed for model, dataset, or visualisation.
Note

VIT requires both visualisation and dataset; both default to ConstantQ and VoxCelebSpoof respectively so a bare jj.detect("audio.flac") works out of the box. AST requires dataset; defaults to VoxCelebSpoof. All other models (Classical, RawNet2, Spectra0, SpectraAASIST, SpectraAASIST3, HuBERT, Wav2Vec2, WavLM) ignore both.

enable_logging(level='DEBUG') classmethod

Enable Jabberjay's built-in logging output to stderr.

Safe to call multiple times — the handler is only registered once. Subsequent calls with a different level are silently ignored.

Parameters:

Name Type Description Default
level str

Minimum log level to emit. One of "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL". Defaults to "DEBUG".

 'DEBUG'

Example::

Jabberjay.enable_logging()          # all messages
Jabberjay.enable_logging("INFO")    # skip debug messages

list_datasets() staticmethod

Return all available datasets.

list_models() staticmethod

Return all available models.

list_visualisations() staticmethod

Return all available visualisations.

load(path) staticmethod

Load an audio file and return (samples, sample_rate).

DetectionResult

Jabberjay.jabberjay.DetectionResult(label, is_bonafide, confidence, model, scores=None) dataclass

Structured result returned by every call to Jabberjay.detect().

confidence instance-attribute

Confidence score for the top prediction (0.0-1.0).

is_bonafide instance-attribute

True if the audio was classified as genuine.

label instance-attribute

'Bonafide' or 'Spoof'.

model instance-attribute

The model used to produce this result.

scores = field(default=None) class-attribute instance-attribute

Full label/score breakdown from transformer models; None for Classical and RawNet2.

Enums

Model

Jabberjay.Utilities.enum_handler.Model

Bases: Enum

Dataset

Jabberjay.Utilities.enum_handler.Dataset

Bases: Enum

Visualisation

Jabberjay.Utilities.enum_handler.Visualisation

Bases: Enum