ReferenceExtractor

Offline pre-extraction of the reference side of a lesson.

Turns raw reference audio + phrase segments + tonic into a fully-populated LessonMaterial — pitch contour and HPCP frames pre-computed — so a client app hands the result straight to CalibraLiveEval / CalibraMelodyEval without doing pitch/chroma DSP at runtime.

This is an authoring helper (run ahead of time, e.g. in a content pipeline). It only produces a LessonMaterial; evaluation consumes one. The on-disk bundle format that ships these features lives outside the SDK; this facade is the SDK-internal compute it builds on (it needs the module-internal HPCP extractor, which is why it lives in calibra rather than a separate module).

What it computes

• pitchContour — via the injected PitchContourExtractor (caller owns its lifecycle; release it when done). Looked up by time at evaluation.

• hpcpFrames — a whole-file flat array of 12-bin chroma at the ReferenceExtractorConfig geometry, the form the live evaluator indexes by absolute frame number. The geometry must match the consuming session; see ReferenceExtractorConfig.

Audio is resampled to 16 kHz internally (ADR-017); the returned LessonMaterial holds the 16 kHz mono samples used for the features.

Quick Start

val extractor = PitchDetection.createContourExtractor(ContourExtractorConfig.SCORING)
val reference = ReferenceExtractor.extract(
    samples = wavSamples, sampleRate = 44100,
    segments = phrases, keyHz = 196f,
    contourExtractor = extractor
)
extractor.release()
// reference.pitchContour and reference.hpcpFrames are now populated

See also