Spectral Sample Finder — User Guide

What this does

Spectral Sample Finder searches an audio sample library for files whose detected sounding pitch matches a requested target. The target may be entered as a note name such as C2, F#3 or Bb1, as a frequency in Hz, or as a MIDI note number.

The script is designed for orchestration and sample-library work. A typical use is to ask for a contrabass around C2, scan a folder containing many contrabass recordings, and return only the files that are actually close enough to C2 to be useful.

Key Features:

• Recursive corpus scan — searches WAV, AIFF, AIF and FLAC files, optionally including subfolders.
• Spectral-root analysis — uses harmonic summation plus direct-fundamental support rather than relying only on a conventional monophonic pitch track.
• Multichannel-safe analysis — channel power spectra are summed; stereo channels are never phase-cancellingly folded to mono.
• Sub-bin pitch refinement — H1–H6 are refined by parabolic interpolation and combined by a power/harmonic-weighted log mean.
• Weak-fundamental rescue — low-string samples may still match when H2 is stronger than H1, while true octave-up samples remain rejected.
• Ranked retrieval — accepted files are ranked by pitch error, root confidence and direct fundamental support.
• Memory-safe corpus workflow — files are loaded only temporarily during scanning; only the requested top matches remain in the Praat Objects window.
• Persistent results Table — pitch, confidence, ranking and spectral descriptors remain available for inspection or export.
• Corpus-level visualization — accepted and rejected files are shown together so threshold choices and octave errors can be evaluated visually.

Corpus → matches

Quick start

1. Run Spectral_Sample_Finder.praat from the Praat Objects window. No Sound selection is required.
2. Leave Folder blank to choose a folder after clicking Apply, or type/paste a folder path directly.
3. Leave Include_subfolders enabled when the library is organized into nested articulation, dynamic or instrument folders.
4. Choose the target input type: Note name, Frequency in Hz, or MIDI number.
5. Enter the target, for example C2.
6. Set Pitch_tolerance_cents. The default ±35 cents is deliberately selective without requiring laboratory tuning.
7. Set Minimum_root_confidence. The default is 0.20.
8. Set Maximum_results to limit how many matching Sounds are finally loaded.
9. Leave Create_results_table and Draw_visualization enabled for a complete diagnostic run.

Pitch-detection method

1. Power-summed multichannel spectrum

Every channel is transformed separately. Spectral power is summed across channels before root estimation, avoiding the cancellations that can occur when opposite-phase stereo channels are mixed to mono.

2. Target-centred root search

The search is centred on the requested pitch but deliberately extends around it so octave competitors can win when the file is actually an octave away. With the default advanced setting, the root search spans ±1200 cents around the target.

For every candidate root, the engine measures energy near its harmonics and weights higher harmonics progressively less. A direct-support term reduces phantom subharmonic solutions that are supported only because a strong higher harmonic happens to fit.

3. Root confidence

Confidence describes how clearly the best root candidate wins over a distinct alternative. Acceptance therefore depends not only on closeness to the requested note, but also on whether the spectrum supports a stable root interpretation.

4. Sub-bin refinement in v0.2

Version 0.2 replaces the earlier 2.5-cent band search with parabolic interpolation around the measured H1–H6 spectral peaks. The interpolated harmonic estimates are combined using power and harmonic-number weighting in the logarithmic frequency domain.

Controls

Main form

Advanced settings

Acceptance & ranking

Acceptance and ranking are deliberately separate. A file first has to pass both hard tests:

Only accepted files receive a retrieval rank. Their score is:

Lower scores are better. This means a sample that is exactly on pitch normally outranks a less accurate sample, while confidence and direct support resolve cases in which pitch error alone is not enough.

Weak-fundamental rescue

Low orchestral strings and some other instrumental samples can have a fundamental that is much weaker than H2. A naive harmonic-sum detector can therefore label a true C2 sample as C3.

When the rescue option is enabled, Spectral Sample Finder checks whether the requested lower pitch has real direct spectral support and a sufficiently coherent harmonic pattern. If the guard conditions are met, the file may be accepted at the requested lower root.

Rescued files are explicitly marked in the Results Table and use the secondary colour in the visualization.

Visualization

Version 0.2 uses the AudioTools 8 × 9.6 inch report format and draws even when no file is accepted.

A · Corpus map

Every successfully analysed file appears in the map, not only accepted files. The horizontal axis is detected pitch in cents relative to the target; the vertical axis is root confidence.

• the pitch-tolerance region is shaded;
• the confidence threshold is shown;
• octave and fifth guides reveal common root-selection errors;
• accepted, rejected and weak-fundamental-rescued samples can be distinguished visually.

This panel is intended as threshold QC: it shows whether a corpus naturally clusters around the requested pitch, whether the tolerance is too strict, and whether octave errors are common.

B · Ranked matches

The accepted files are shown in retrieval order. The panel combines file-name labels, pitch-error lollipops and root-confidence bars. The confidence threshold is drawn directly on the plot.

C · Spectrum

The best match is shown as a spectrum against the target's harmonic grid, with the detected F0 marked. If nothing matches, the closest rejected file is shown instead, making no-match runs diagnostically useful rather than blank.

Summary strip

The bottom strip reports corpus size, readable and analysed counts, accepted and loaded files, rejection categories, skipped-file counts, the ranking formula and the pitch-analysis method.

Outputs

Results Table fields

Reliability & practical notes

The matcher combines spectral-root analysis, sub-bin pitch refinement, multichannel power-spectrum analysis and guarded weak-fundamental recovery. These choices are intended to make retrieval useful with real sample libraries rather than only with clean sustained tones.

• Short samples: final pitch is refined between FFT bins, reducing coarse tuning errors when a file is brief.
• Vibrato: moderate pitch modulation can still return a stable central estimate when the sample remains clearly pitched.
• Stereo material: channel power spectra are summed, so antiphase stereo content is not cancelled by waveform fold-down.
• Weak fundamentals: a guarded rescue can recover low-string samples whose second harmonic is stronger than the fundamental, while checking for real energy around the requested lower pitch.
• Recursive folders: subfolders are scanned as part of the corpus when Include_subfolders is enabled.
• Clean Objects window: files used during scanning are temporary; only the requested final matches and optional Results Table remain.

Notes & limitations

• Pitch retrieval, not instrument recognition. The script does not determine whether a file is a contrabass, bassoon or synthesizer. Folder organization supplies that semantic context.
• Designed primarily for pitched samples. Strongly noisy or unstable material may still produce a root candidate. Confidence is therefore part of acceptance.
• Confidence threshold is corpus-dependent. No single value is ideal for every library. Increase the threshold when noisy or unstable files are being admitted; lower it cautiously when quiet or weak-fundamental samples are being missed.
• Whole-file analysis. The current version estimates one root per file. A recording that changes pitch substantially over time is represented by one global result.
• Weak-fundamental rescue is guarded but heuristic. It is designed for low-string and related spectra, not as a general missing-fundamental theorem.
• Centroid and spread are descriptive only. They do not yet implement timbral matching against a selected orchestral context.
• Maximum recursion depth: the internal limit is 64 folder levels.
• Native Praat implementation. No Python, subprocess or external DSP engine is required.

Citation

Praat AudioTools: Cohen, S. (2026). Praat AudioTools: An Offline Analysis–Resynthesis Toolkit for Experimental Composition.

• Praat AudioTools repository