analyzeAudio 0.1.1

Measure one or more aspects of one or more audio files.

analyzeAudio

Measure one or more aspects of one or more audio files.

Note well: FFmpeg & FFprobe binaries must be in PATH

Some options to download FFmpeg and FFprobe at ffmpeg.org.

Some ways to use this package

The top-level package re-exports a small high-level API:

API	Purpose
analyzeAudioFile(pathFilename, listAspectNames)	Analyze one file and return one result per requested registered aspect name.
analyzeAudioListPathFilenames(listPathFilenames, listAspectNames, CPUlimit=None)	Analyze many files in parallel and return one row per completed file.
getListAvailableAudioAspects()	Return the sorted list of registered aspect names.
audioAspects	Registry of aspect name -> analyzer callable + required parameter names.
dataTabularTOpathFilenameDelimited(...)	Write batch results to a delimited text file.

Use analyzeAudioFile to measure one or more registered aspects of a single audio file

from analyzeAudio import analyzeAudioFile

listAspectNames = [
    'LUFS integrated',
    'RMS peak',
    'SRMR mean',
    'Spectral Flatness mean',
]

listMeasurements = analyzeAudioFile(pathFilename, listAspectNames)
dictionaryMeasurements = dict(zip(listAspectNames, listMeasurements, strict=True))

analyzeAudioFile preserves the order of listAspectNames. If a requested aspect name is not registered, the matching return entry is 'not found'.

The registered names are case-sensitive and sometimes very similar names refer to different measurements. For example, Spectral Flatness mean and Spectral flatness mean are different entries, and so are Zero-crossing rate mean and Zero-crossings rate.

Use analyzeAudioListPathFilenames to measure one or more aspects for many audio files

from analyzeAudio import analyzeAudioListPathFilenames, dataTabularTOpathFilenameDelimited

listAspectNames = ['LUFS integrated', 'Spectral Flatness mean']
rowsListFilenameAspectValues = analyzeAudioListPathFilenames(listPathFilenames, listAspectNames)

dataTabularTOpathFilenameDelimited(
    pathFilenameOutput,
    rowsListFilenameAspectValues,
    ['pathFilename', *listAspectNames],
)

Each returned row starts with the file path converted to POSIX text, followed by the requested values. The rows are returned in worker-completion order rather than the original input order.

Use getListAvailableAudioAspects and audioAspects to inspect the registry or call an analyzer directly

from analyzeAudio import audioAspects, getListAvailableAudioAspects

print(getListAvailableAudioAspects())
print(audioAspects['Chromagram mean']['analyzerParameters'])

SI_SDR_channelsMean = audioAspects['SI-SDR mean']['analyzer'](
    pathFilenameAudioFile,
    pathFilenameDifferentAudioFile,
)

Use audioAspects[name]['analyzerParameters'] to see what inputs a registered analyzer expects. This is especially useful when a registered analyzer needs more than the single pathFilename accepted by analyzeAudioFile, such as a comparison between two files or a metric that expects tensors.

Use the lower-level analyzer modules when you want data arrays or tensors instead of one float

Most registered names ending in mean are scalar summaries. If you want the full feature array or tensor instead, import the lower-level analyzer function directly:

• analyzeAudio.analyzersUseFilename
  • filename-based scalar analyzers, including comparisons such as SI-SDR mean
• analyzeAudio.analyzersUseWaveform
  • analyzeTempogram -> full tempogram array
  • analyzeRMS -> framewise RMS-in-dB array
  • analyzeTempo -> tempo array
  • analyzeZeroCrossingRate -> framewise zero-crossing-rate array
• analyzeAudio.analyzersUseSpectrogram
  • analyzeChromagram -> chromagram matrix
  • analyzeSpectralContrast -> spectral-contrast array
  • analyzeSpectralBandwidth -> spectral-bandwidth array
  • analyzeSpectralCentroid -> spectral-centroid array
  • analyzeSpectralFlatness -> spectral-flatness-in-dB array
• analyzeAudio.analyzersUseTensor
  • analyzeSRMR -> torch.Tensor of SRMR values

The matching ...Mean functions return one float summary instead. getListAvailableAudioAspects() lists the registered public aspect names, not every lower-level helper function.

import numpy
import soundfile

from analyzeAudio.analyzersUseWaveform import analyzeTempogram

with soundfile.SoundFile(pathFilename) as readSoundFile:
    sampleRate = readSoundFile.samplerate
    waveform = readSoundFile.read(dtype='float32').astype(numpy.float32).T

tempogram = analyzeTempogram(waveform, sampleRate)

Use whatMeasurements to list registered measurements from the command line

whatMeasurements

This prints the same sorted registry names returned by getListAvailableAudioAspects().

Reference materials

A Spectral-Flatness Measure for Studying the Autocorrelation Method of Linear Prediction of Speech Analysis

• Common name: spectral flatness
• BibTeX citation.
• DOI: 10.1109/TASSP.1974.1162572
• Implementation:
  • librosa/librosa.feature.spectral_flatness

Perceptual Effects of Spectral Modifications on Musical Timbres

• BibTeX citation.
• DOI: 10.1121/1.381843

Robust Entropy-Based Endpoint Detection for Speech Recognition in Noisy Environments

• Common name: spectral entropy
• BibTeX citation.
• DOI: 10.21437/ICSLP.1998-527
• Proceedings: ISCA Archive

Realtime Chord Recognition of Musical Sound: A System Using Common Lisp Music

• Common name: chroma features
• BibTeX citation.
• Proceedings: University of Michigan ICMC archive
• Implementation:
  • librosa/librosa.feature.chroma_stft

A Robust Audio Classification and Segmentation Method

• BibTeX citation.
• Technical report: Microsoft Research
• Implementations:
  • FFprobe astats filter
    • C file with implementation details for AI agents.
  • FFprobe aspectralstats filter
    • C file reference with implementation functions for AI agents.
  • librosa/librosa

Music Type Classification by Spectral Contrast Feature

• Common name: spectral contrast
• BibTeX citation.
• DOI: 10.1109/ICME.2002.1035731
• Free PDF: Tsinghua University
• Implementation:
  • librosa/librosa.feature.spectral_contrast

A Speech/Music Discriminator Based on RMS and Zero-Crossings

• Common names: RMS, zero-crossing rate
• BibTeX citation.
• DOI: 10.1109/TMM.2004.840604
• Free author proof: University of Crete
• Implementation:
  • librosa/librosa.feature.rms
  • librosa/librosa.feature.zero_crossing_rate

Performance Measurement in Blind Audio Source Separation

• Common name: BSS Eval SDR
• BibTeX citation.
• DOI: 10.1109/TSA.2005.858005
• Free author PDF: IRISA
• Implementations:
  • sigsep/sigsep-mus-eval
  • mir-evaluation/mir_eval
  • FFprobe asdr filter
    • C source with implementation formulas for AI agents.

Automatic Chord Recognition from Audio Using a HMM with Supervised Learning

• BibTeX citation.
• Proceedings: ISMIR 2006
• Free PDF: Stanford CCRMA
• Implementation:
  • librosa/librosa.feature.chroma_stft

Cyclic Tempogram: A Mid-Level Tempo Representation for Music Signals

• Common name: tempogram
• BibTeX citation.
• DOI: 10.1109/ICASSP.2010.5495219
• Free author PDF: AudioLabs Erlangen
• Implementations:
  • librosa/librosa.feature.tempogram
  • Vamp Tempogram Plugin

A Non-Intrusive Quality and Intelligibility Measure of Reverberant and Dereverberated Speech

• Common name: SRMR
• BibTeX citation.
• DOI: 10.1109/TASL.2010.2052247
• Free author PDF: MUSEA Lab
• Implementation:
  • Lightning-AI/torchmetrics

Signal Processing for Music Analysis

• BibTeX citation.
• DOI: 10.1109/JSTSP.2011.2112333
• Free author PDF: Columbia University
• Implementation:
  • librosa/librosa

The Timbre Toolbox: Extracting Audio Descriptors from Musical Signals

• BibTeX citation.
• DOI: 10.1121/1.3642604
• Free PDF: McGill University
• Implementations:
  • MPCL-McGill/TimbreToolbox-R2021a
  • librosa/librosa

Blind Audio Watermarking Technique Based on Two Dimensional Cellular Automata

• Common name: APSNR reference
• BibTeX citation.
• DOI: 10.14257/ijsia.2016.10.9.18
• Free repository copy: Universidad Autonoma de Madrid
• Implementation:
  • FFprobe apsnr filter
    • C source with implementation formulas for AI agents.

SDR - Half-Baked or Well Done?

• Common name: SI-SDR
• BibTeX citation. TeX Source with precise formulas for AI agents.
• DOI: 10.1109/ICASSP.2019.8683855
• Free author PDF: Jonathan Le Roux
• Implementations:
  • Lightning-AI/torchmetrics
  • FFprobe asisdr filter

Loudness Range: A Measure to Supplement EBU R 128 Loudness Normalisation

• Common name: LUFS
• BibTeX citation.
• Standard: EBU Tech 3342
• Free PDF: EBU
• Implementation:
  • FFprobe ebur128 filter
    • C source with implementation details for AI agents.
    • C source with loudness calculations for AI agents.

Algorithms to Measure Audio Programme Loudness and True-Peak Audio Level

• Common name: True peak
• BibTeX citation.
• Standard: ITU-R BS.1770-5
• Free PDF: ITU
• Implementation:
  • FFprobe ebur128 filter
    • C source with implementation details for AI agents.
    • C source with loudness calculations for AI agents.

An Overview on Sound Features in Time and Frequency Domain

• BibTeX citation.
• DOI: 10.2478/ijasitels-2023-0006
• Open access article: Reference Global

Packages and documentation

• FFmpeg documentation
  • FFprobe filter documentation
• librosa/librosa
  • official documentation
• Lightning-AI/torchmetrics
  • official documentation
• sigsep/sigsep-mus-eval
• mir-evaluation/mir_eval

My recovery