pyampact.dataCompilation.data_compilation

pyampact.dataCompilation.data_compilation(y, original_sr, hop_length, winms, tsr, spec, nmat, piece, audio_file_path, force_pyin=False)[source]

Compile per-note perceptual descriptors from an aligned audio-score pair and write the results to disk in the appropriate format (.krn, .mei, or .csv).

F0 estimation strategy is selected automatically based on the number of parts in the score: monophonic pieces use pyin directly; polyphonic pieces attempt pitch-separated F0 estimation via the reassigned spectrogram and fall back to pyin on failure. Set force_pyin=True to override and use pyin for all pieces regardless of polyphony.

Parameters:

  • y (ndarray) – Audio time series at the original sample rate.

  • original_sr (int) – Sample rate of y.

  • hop_length (int) – Hop size in samples at tsr used during alignment (e.g. 32).

  • winms (float) – Analysis window size in milliseconds (e.g. 100).

  • tsr (int) – Target sample rate used during alignment (e.g. 4000).

  • spec (ndarray) – Magnitude spectrogram produced by alignment, shape (freq x frames).

  • nmat (dict) – Note matrix dict returned by run_alignment, keyed by part name. Each value is a DataFrame with at minimum ONSET_SEC, OFFSET_SEC, and MIDI columns.

  • piece (Score) – Score object returned by run_alignment / load_score.

  • audio_file_path (str) – Path to the source audio file. Used to derive the output folder name (output_files/output_<stem>/) and filename stem.

  • force_pyin (bool, optional) – If True, use pyin F0 estimation for all notes regardless of whether the piece is monophonic or polyphonic. Default is False (auto-detect).

Returns:

  • nmat (dict) – The input note matrix dict with perceptual descriptor columns appended to each part DataFrame, including: f0Vals, meanf0, ppitch1, ppitch2, jitter, vibratoDepth, vibratoRate, pwrVals, meanPwr, shimmer, specCentVals, meanSpecCent, specBandwidthVals, meanSpecBandwidth, specContrastVals, meanSpecContrast, specFlatnessVals, meanSpecFlatness, specRolloffVals, meanSpecRolloff.

  • fileOutput (str) – Path to the primary output file written to disk: a .krn file for Humdrum kern scores, a .csv file for Tony CSV scores, or a .mei file (with companion .csv) for all other formats.

Notes

Spectral features (centroid, bandwidth, contrast, flatness, rolloff) are precomputed once over the full spectrogram and sliced per note to avoid redundant computation. F0 and RMS power are computed at original_sr using window and hop sizes derived from the alignment spectrogram dimensions rather than the caller-supplied hop_length, which ensures consistency with the DTW alignment grid.