analyzeAudio 0.0.11__py3-none-any.whl

analyzeAudio/__init__.py

@@ -0,0 +1,14 @@
+from .audioAspectsRegistry import registrationAudioAspect, cacheAudioAnalyzers, analyzeAudioFile, \
+    analyzeAudioListPathFilenames, getListAvailableAudioAspects, audioAspects
+
+__all__ = [
+    'analyzeAudioFile',
+    'analyzeAudioListPathFilenames',
+    'audioAspects',
+    'getListAvailableAudioAspects',
+]
+
+from . import analyzersUseFilename
+from . import analyzersUseSpectrogram
+from . import analyzersUseTensor
+from . import analyzersUseWaveform

analyzeAudio/analyzersUseFilename.py

@@ -0,0 +1,234 @@
+from .pythonator import pythonizeFFprobe
+from analyzeAudio import registrationAudioAspect, cacheAudioAnalyzers
+from statistics import mean
+from typing import Any, Dict, List, Optional, Union, cast
+import cachetools
+import numpy
+import os
+import pathlib
+import re as regex
+import subprocess
+
+@registrationAudioAspect('SI-SDR mean')
+def getSI_SDRmean(pathFilenameAlpha: Union[str, os.PathLike[Any]], pathFilenameBeta: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    """
+    Calculate the mean Scale-Invariant Signal-to-Distortion Ratio (SI-SDR) between two audio files.
+    This function uses FFmpeg to compute the SI-SDR between two audio files specified by their paths.
+    The SI-SDR values are extracted from the FFmpeg output and their mean is calculated.
+    Parameters:
+        pathFilenameAlpha: Path to the first audio file.
+        pathFilenameBeta: Path to the second audio file.
+    Returns:
+        SI_SDRmean: The mean SI-SDR value in decibels (dB).
+    Raises:
+        subprocess.CalledProcessError: If the FFmpeg command fails.
+        ValueError: If no SI-SDR values are found in the FFmpeg output.
+    """
+    commandLineFFmpeg = [
+        'ffmpeg', '-hide_banner', '-loglevel', '32',
+        '-i', f'{str(pathlib.Path(pathFilenameAlpha))}', '-i', f'{str(pathlib.Path(pathFilenameBeta))}',
+        '-filter_complex', '[0][1]asisdr', '-f', 'null', '-'
+    ]
+    systemProcessFFmpeg = subprocess.run(commandLineFFmpeg, check=True, stderr=subprocess.PIPE)
+
+    stderrFFmpeg = systemProcessFFmpeg.stderr.decode()
+
+    regexSI_SDR = regex.compile(r"^\[Parsed_asisdr_.* (.*) dB", regex.MULTILINE)
+
+    listMatchesSI_SDR = regexSI_SDR.findall(stderrFFmpeg)
+    SI_SDRmean = mean(float(match) for match in listMatchesSI_SDR)
+    return SI_SDRmean
+
+@cachetools.cached(cache=cacheAudioAnalyzers)
+def ffprobeShotgunAndCache(pathFilename: Union[str, os.PathLike[Any]]) -> Dict[str, float]:
+    # for lavfi amovie/movie, the colons after driveLetter letters need to be escaped twice.
+    pFn = pathlib.PureWindowsPath(pathFilename)
+    lavfiPathFilename = pFn.drive.replace(":", "\\\\:")+pathlib.PureWindowsPath(pFn.root,pFn.relative_to(pFn.anchor)).as_posix()
+
+    filterChain: List[str] = []
+    filterChain += ["astats=metadata=1:measure_perchannel=Crest_factor+Zero_crossings_rate+Dynamic_range:measure_overall=all"]
+    filterChain += ["aspectralstats"]
+    filterChain += ["ebur128=metadata=1:framelog=quiet"]
+
+    entriesFFprobe = ["frame_tags"]
+
+    commandLineFFprobe = [
+        "ffprobe", "-hide_banner",
+        "-f", "lavfi", f"amovie={lavfiPathFilename},{','.join(filterChain)}",
+        "-show_entries", ':'.join(entriesFFprobe),
+        "-output_format", "json=compact=1",
+    ]
+
+    systemProcessFFprobe = subprocess.Popen(commandLineFFprobe, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    stdoutFFprobe, DISCARDstderr = systemProcessFFprobe.communicate()
+    FFprobeStructured = pythonizeFFprobe(stdoutFFprobe.decode('utf-8'))[-1]
+
+    dictionaryAspectsAnalyzed = {}
+    if 'aspectralstats' in FFprobeStructured:
+        for keyName in FFprobeStructured['aspectralstats']:
+            dictionaryAspectsAnalyzed[keyName] = numpy.mean(FFprobeStructured['aspectralstats'][keyName])
+    if 'r128' in FFprobeStructured:
+        for keyName in FFprobeStructured['r128']:
+            dictionaryAspectsAnalyzed[keyName] = FFprobeStructured['r128'][keyName][-1]
+    if 'astats' in FFprobeStructured:
+        for keyName, arrayFeatureValues in cast(dict, FFprobeStructured['astats']).items():
+            dictionaryAspectsAnalyzed[keyName.split('.')[-1]] = numpy.mean(arrayFeatureValues[..., -1:])
+
+    return dictionaryAspectsAnalyzed
+
+@registrationAudioAspect('Zero-crossings rate')
+def analyzeZero_crossings_rate(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Zero_crossings_rate')
+
+@registrationAudioAspect('DC offset')
+def analyzeDCoffset(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('DC_offset')
+
+@registrationAudioAspect('Dynamic range')
+def analyzeDynamicRange(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Dynamic_range')
+
+@registrationAudioAspect('Signal entropy')
+def analyzeSignalEntropy(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Entropy')
+
+@registrationAudioAspect('Duration-samples')
+def analyzeNumber_of_samples(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Number_of_samples')
+
+@registrationAudioAspect('Peak dB')
+def analyzePeak_level(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Peak_level')
+
+@registrationAudioAspect('RMS total')
+def analyzeRMS_level(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('RMS_level')
+
+@registrationAudioAspect('Crest factor')
+def analyzeCrest_factor(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Crest_factor')
+
+@registrationAudioAspect('RMS peak')
+def analyzeRMS_peak(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('RMS_peak')
+
+@registrationAudioAspect('LUFS integrated')
+def analyzeLUFSintegrated(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('I')
+
+@registrationAudioAspect('LUFS loudness range')
+def analyzeLRA(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('LRA')
+
+@registrationAudioAspect('LUFS low')
+def analyzeLUFSlow(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('LRA.low')
+
+@registrationAudioAspect('LUFS high')
+def analyzeLUFShigh(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('LRA.high')
+
+@registrationAudioAspect('Spectral mean')
+def analyzeMean(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('mean')
+
+@registrationAudioAspect('Spectral variance')
+def analyzeVariance(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('variance')
+
+@registrationAudioAspect('Spectral centroid')
+def analyzeCentroid(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('centroid')
+
+@registrationAudioAspect('Spectral spread')
+def analyzeSpread(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('spread')
+
+@registrationAudioAspect('Spectral skewness')
+def analyzeSkewness(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('skewness')
+
+@registrationAudioAspect('Spectral kurtosis')
+def analyzeKurtosis(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('kurtosis')
+
+@registrationAudioAspect('Spectral entropy')
+def analyzeSpectralEntropy(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('entropy')
+
+@registrationAudioAspect('Spectral flatness')
+def analyzeFlatness(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('flatness')
+
+@registrationAudioAspect('Spectral crest')
+def analyzeCrest(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('crest')
+
+@registrationAudioAspect('Spectral flux')
+def analyzeFlux(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('flux')
+
+@registrationAudioAspect('Spectral slope')
+def analyzeSlope(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('slope')
+
+@registrationAudioAspect('Spectral decrease')
+def analyzeDecrease(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('decrease')
+
+@registrationAudioAspect('Spectral rolloff')
+def analyzeRolloff(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('rolloff')
+
+@registrationAudioAspect('Abs_Peak_count')
+def analyzeAbs_Peak_count(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    print('Abs_Peak_count', pathFilename)
+    return ffprobeShotgunAndCache(pathFilename).get('Abs_Peak_count')
+
+@registrationAudioAspect('Bit_depth')
+def analyzeBit_depth(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Bit_depth')
+
+@registrationAudioAspect('Flat_factor')
+def analyzeFlat_factor(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Flat_factor')
+
+@registrationAudioAspect('Max_difference')
+def analyzeMax_difference(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Max_difference')
+
+@registrationAudioAspect('Max_level')
+def analyzeMax_level(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Max_level')
+
+@registrationAudioAspect('Mean_difference')
+def analyzeMean_difference(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Mean_difference')
+
+@registrationAudioAspect('Min_difference')
+def analyzeMin_difference(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Min_difference')
+
+@registrationAudioAspect('Min_level')
+def analyzeMin_level(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Min_level')
+
+@registrationAudioAspect('Noise_floor')
+def analyzeNoise_floor(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Noise_floor')
+
+@registrationAudioAspect('Noise_floor_count')
+def analyzeNoise_floor_count(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Noise_floor_count')
+
+@registrationAudioAspect('Peak_count')
+def analyzePeak_count(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('Peak_count')
+
+@registrationAudioAspect('RMS_difference')
+def analyzeRMS_difference(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('RMS_difference')
+
+@registrationAudioAspect('RMS_trough')
+def analyzeRMS_trough(pathFilename: Union[str, os.PathLike[Any]]) -> Optional[float]:
+    return ffprobeShotgunAndCache(pathFilename).get('RMS_trough')

analyzeAudio/analyzersUseSpectrogram.py

@@ -0,0 +1,28 @@
+from analyzeAudio import registrationAudioAspect, audioAspects, cacheAudioAnalyzers
+from typing import Any
+import cachetools
+import librosa
+import numpy
+
+@registrationAudioAspect('Chromagram')
+def analyzeChromagram(spectrogramPower: numpy.ndarray, sampleRate: int, **keywordArguments: Any) -> numpy.ndarray:
+    return librosa.feature.chroma_stft(S=spectrogramPower, sr=sampleRate, **keywordArguments)
+
+@registrationAudioAspect('Spectral Contrast')
+def analyzeSpectralContrast(spectrogramMagnitude: numpy.ndarray, **keywordArguments: Any) -> numpy.ndarray:
+    return librosa.feature.spectral_contrast(S=spectrogramMagnitude, **keywordArguments)
+
+@registrationAudioAspect('Spectral Bandwidth')
+def analyzeSpectralBandwidth(spectrogramMagnitude: numpy.ndarray, **keywordArguments: Any) -> numpy.ndarray:
+    centroid = audioAspects['Spectral Centroid']['analyzer'](spectrogramMagnitude)
+    return librosa.feature.spectral_bandwidth(S=spectrogramMagnitude, centroid=centroid, **keywordArguments)
+
+@cachetools.cached(cache=cacheAudioAnalyzers)
+@registrationAudioAspect('Spectral Centroid')
+def analyzeSpectralCentroid(spectrogramMagnitude: numpy.ndarray, **keywordArguments: Any) -> numpy.ndarray:
+    return librosa.feature.spectral_centroid(S=spectrogramMagnitude, **keywordArguments)
+
+@registrationAudioAspect('Spectral Flatness')
+def analyzeSpectralFlatness(spectrogramMagnitude: numpy.ndarray, **keywordArguments: Any) -> numpy.ndarray:
+    spectralFlatness = librosa.feature.spectral_flatness(S=spectrogramMagnitude, **keywordArguments)
+    return 20 * numpy.log10(spectralFlatness, where=(spectralFlatness != 0)) # dB

analyzeAudio/analyzersUseTensor.py

@@ -0,0 +1,10 @@
+from analyzeAudio import registrationAudioAspect
+from torchmetrics.functional.audio.srmr import speech_reverberation_modulation_energy_ratio
+from typing import Any, Optional
+import numpy
+import torch
+
+@registrationAudioAspect('SRMR')
+def analyzeSRMR(tensorAudio: torch.Tensor, sampleRate: int, pytorchOnCPU: Optional[bool], **keywordArguments: Any) -> numpy.ndarray:
+    keywordArguments['fast'] = keywordArguments.get('fast') or pytorchOnCPU or None
+    return torch.Tensor.numpy(speech_reverberation_modulation_energy_ratio(tensorAudio, sampleRate, **keywordArguments))

analyzeAudio/analyzersUseWaveform.py

@@ -0,0 +1,25 @@
+from analyzeAudio import registrationAudioAspect, audioAspects, cacheAudioAnalyzers
+from typing import Any
+import librosa
+import numpy
+import cachetools
+
+@cachetools.cached(cache=cacheAudioAnalyzers)
+@registrationAudioAspect('Tempogram')
+def analyzeTempogram(waveform: numpy.ndarray, sampleRate: int, **keywordArguments: Any) -> numpy.ndarray:
+    return librosa.feature.tempogram(y=waveform, sr=sampleRate, **keywordArguments)
+
+# "RMS value from audio samples is faster ... However, ... spectrogram ... more accurate ... because ... windowed"
+@registrationAudioAspect('RMS from waveform')
+def analyzeRMS(waveform: numpy.ndarray, **keywordArguments: Any) -> numpy.ndarray:
+    arrayRMS = librosa.feature.rms(y=waveform, **keywordArguments)
+    return 20 * numpy.log10(arrayRMS, where=(arrayRMS != 0)) # dB
+
+@registrationAudioAspect('Tempo')
+def analyzeTempo(waveform: numpy.ndarray, sampleRate: int, **keywordArguments: Any) -> numpy.ndarray:
+    tempogram = audioAspects['Tempogram']['analyzer'](waveform, sampleRate)
+    return librosa.feature.tempo(y=waveform, sr=sampleRate, tg=tempogram, **keywordArguments)
+
+@registrationAudioAspect('Zero-crossing rate') # This is distinct from 'Zero-crossings rate'
+def analyzeZeroCrossingRate(waveform: numpy.ndarray, **keywordArguments: Any) -> numpy.ndarray:
+    return librosa.feature.zero_crossing_rate(y=waveform, **keywordArguments)

analyzeAudio/audioAspectsRegistry.py

@@ -0,0 +1,195 @@
+from Z0Z_tools import defineConcurrencyLimit, oopsieKwargsie
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from numpy.typing import NDArray
+from tqdm.auto import tqdm
+from typing import Any, Callable, cast, Dict, List, Optional, ParamSpec, Sequence, TypeAlias, TYPE_CHECKING, TypeVar, Union
+import cachetools
+import inspect
+import librosa
+import multiprocessing
+import numpy
+import os
+import pathlib
+import soundfile
+import torch
+import warnings
+
+if TYPE_CHECKING:
+    from typing import TypedDict
+else:
+    TypedDict = dict
+
+if __name__ == '__main__':
+    multiprocessing.set_start_method('spawn')
+
+warnings.filterwarnings('ignore', category=UserWarning, module='torchmetrics', message='.*fast=True.*')
+
+parameterSpecifications = ParamSpec('parameterSpecifications')
+typeReturned = TypeVar('typeReturned')
+
+subclassTarget: TypeAlias = numpy.ndarray
+audioAspect: TypeAlias = str
+class analyzersAudioAspects(TypedDict):
+    analyzer: Callable[..., Any]
+    analyzerParameters: List[str]
+
+audioAspects: Dict[audioAspect, analyzersAudioAspects] = {}
+"""A register of 1) measurable aspects of audio data, 2) analyzer functions to measure audio aspects, 3) and parameters of analyzer functions."""
+
+def registrationAudioAspect(aspectName: str) -> Callable[[Callable[parameterSpecifications, typeReturned]], Callable[parameterSpecifications, typeReturned]]:
+    """
+    A function to "decorate" a registrant-analyzer function and the aspect of audio data it can analyze.
+
+    Parameters:
+        aspectName: The audio aspect that the registrar will enter into the register, `audioAspects`.
+    """
+
+    def registrar(registrant: Callable[parameterSpecifications, typeReturned]) -> Callable[parameterSpecifications, typeReturned]:
+        """
+        `registrar` updates the registry, `audioAspects`, with 1) the analyzer function, `registrant`, 2) the analyzer function's parameters, and 3) the aspect of audio data that the analyzer function measures.
+
+        Parameters:
+            registrant: The function that analyzes an aspect of audio data.
+
+        Note:
+            `registrar` does not change the behavior of `registrant`, the analyzer function.
+        """
+        audioAspects[aspectName] = {
+            'analyzer': registrant,
+            'analyzerParameters': inspect.getfullargspec(registrant).args
+        }
+
+        # if registrant.__annotations__.get('return') is not None and issubclass(registrant.__annotations__['return'], subclassTarget): # maybe someday I will understand why this doesn't work
+        # if registrant.__annotations__.get('return') is not None and issubclass(registrant.__annotations__.get('return', type(None)), subclassTarget): # maybe someday I will understand why this doesn't work
+        if isinstance(registrant.__annotations__.get('return', type(None)), type) and issubclass(registrant.__annotations__.get('return', type(None)), subclassTarget): # maybe someday I will understand what all of this statement means
+            def registrationAudioAspectMean(*arguments: parameterSpecifications.args, **keywordArguments: parameterSpecifications.kwargs) -> numpy.floating[Any]:
+                """
+                `registrar` updates the registry with a new analyzer function that calculates the mean of the analyzer's numpy.ndarray result.
+
+                Returns:
+                    mean: Mean value of the analyzer's numpy.ndarray result.
+                """
+                aspectValue = registrant(*arguments, **keywordArguments)
+                return numpy.mean(cast(subclassTarget, aspectValue))
+                # return aspectValue.mean()
+            audioAspects[f"{aspectName} mean"] = {
+                'analyzer': registrationAudioAspectMean,
+                'analyzerParameters': inspect.getfullargspec(registrant).args
+            }
+        return registrant
+    return registrar
+
+def analyzeAudioFile(pathFilename: Union[str, os.PathLike[Any]], listAspectNames: List[str]) -> List[Union[str, float, NDArray[Any]]]:
+    """
+    Analyzes an audio file for specified aspects and returns the results.
+
+    Parameters:
+        pathFilename: The path to the audio file to be analyzed.
+        listAspectNames: A list of aspect names to analyze in the audio file.
+
+    Returns:
+        listAspectValues: A list of analyzed values in the same order as `listAspectNames`.
+    """
+    pathlib.Path(pathFilename).stat() # raises FileNotFoundError if the file does not exist
+    dictionaryAspectsAnalyzed: Dict[str, Union[str, float, NDArray[Any]]] = {aspectName: 'not found' for aspectName in listAspectNames}
+    """Despite returning a list, use a dictionary to preserve the order of the listAspectNames.
+    Similarly, 'not found' ensures the returned list length == len(listAspectNames)"""
+
+    # waveform, sampleRate = librosa.load(path=str(pathFilename), sr=None, mono=False)
+    with soundfile.SoundFile(pathFilename) as readSoundFile:
+        sampleRate: int = readSoundFile.samplerate
+        waveform = readSoundFile.read()
+        waveform = waveform.T
+
+    # I need "lazy" loading
+    tryAgain = True
+    while tryAgain: # `tenacity`?
+        try:
+            tensorAudio = torch.from_numpy(waveform)  # memory-sharing
+            tryAgain = False
+        except RuntimeError as ERRORmessage:
+            if 'negative stride' in str(ERRORmessage):
+                waveform = waveform.copy()  # not memory-sharing
+                tryAgain = True
+            else:
+                raise ERRORmessage
+
+    spectrogram = librosa.stft(y=waveform)
+    spectrogramMagnitude, DISCARDEDphase = librosa.magphase(D=spectrogram)
+    spectrogramPower = numpy.absolute(spectrogram) ** 2
+
+    pytorchOnCPU = not torch.cuda.is_available()  # False if GPU available, True if not
+
+    for aspectName in listAspectNames:
+        if aspectName in audioAspects:
+            analyzer = audioAspects[aspectName]['analyzer']
+            analyzerParameters = audioAspects[aspectName]['analyzerParameters']
+            dictionaryAspectsAnalyzed[aspectName] = analyzer(*map(vars().get, analyzerParameters))
+
+    return [dictionaryAspectsAnalyzed[aspectName] for aspectName in listAspectNames]
+
+def analyzeAudioListPathFilenames(listPathFilenames: Union[Sequence[str], Sequence[os.PathLike[Any]]], listAspectNames: List[str], CPUlimit: Optional[Union[int, float, bool]] = None) -> List[List[Union[str, float, NDArray[Any]]]]:
+    """
+    Analyzes a list of audio files for specified aspects of the individual files and returns the results.
+
+    Parameters:
+        listPathFilenames: A list of paths to the audio files to be analyzed.
+        listAspectNames: A list of aspect names to analyze in each audio file.
+        CPUlimit (gluttonous resource usage): whether and how to limit the CPU usage. See notes for details.
+
+    Returns:
+        rowsListFilenameAspectValues: A list of lists, where each inner list contains the filename and
+        analyzed values corresponding to the specified aspects, which are in the same order as `listAspectNames`.
+
+    Limits on CPU usage CPUlimit:
+        False, None, or 0: No limits on CPU usage; uses all available CPUs. All other values will potentially limit CPU usage.
+        True: Yes, limit the CPU usage; limits to 1 CPU.
+        Integer >= 1: Limits usage to the specified number of CPUs.
+        Decimal value (float) between 0 and 1: Fraction of total CPUs to use.
+        Decimal value (float) between -1 and 0: Fraction of CPUs to *not* use.
+        Integer <= -1: Subtract the absolute value from total CPUs.
+
+    You can save the data with `Z0Z_tools.dataTabularTOpathFilenameDelimited()`.
+    For example,
+
+    ```python
+    dataTabularTOpathFilenameDelimited(
+        pathFilename = pathFilename,
+        tableRows = rowsListFilenameAspectValues, # The return of this function
+        tableColumns = ['File'] + listAspectNames # A parameter of this function
+    )
+    ```
+
+    Nevertheless, I aspire to improve `analyzeAudioListPathFilenames` by radically improving the structure of the returned data.
+    """
+    rowsListFilenameAspectValues = []
+
+    if not (CPUlimit is None or isinstance(CPUlimit, (bool, int, float))):
+        CPUlimit = oopsieKwargsie(CPUlimit)
+    max_workers = defineConcurrencyLimit(CPUlimit)
+
+    with ProcessPoolExecutor(max_workers=max_workers) as concurrencyManager:
+        dictionaryConcurrency = {concurrencyManager.submit(analyzeAudioFile, pathFilename, listAspectNames)
+                                    : pathFilename
+                                    for pathFilename in listPathFilenames}
+
+        for claimTicket in as_completed(dictionaryConcurrency):
+            cacheAudioAnalyzers.pop(dictionaryConcurrency[claimTicket], None)
+            listAspectValues = claimTicket.result()
+            rowsListFilenameAspectValues.append(
+                [str(pathlib.PurePath(dictionaryConcurrency[claimTicket]).as_posix())]
+                + listAspectValues)
+
+    return rowsListFilenameAspectValues
+
+def getListAvailableAudioAspects() -> List[str]:
+    """
+    Returns a sorted list of audio aspect names. All valid values for the parameter `listAspectNames`, for example,
+    are returned by this function.
+
+    Returns:
+        listAvailableAudioAspects: The list of aspect names registered in `audioAspects`.
+    """
+    return sorted(audioAspects.keys())
+
+cacheAudioAnalyzers = cachetools.LRUCache(maxsize=256)

analyzeAudio/pythonator.py

@@ -0,0 +1,85 @@
+from collections import defaultdict
+from typing import Dict, Any, Tuple, Union
+import json
+import numpy
+
+def pythonizeFFprobe(FFprobeJSON_utf8: str):
+    FFroot: Dict[str, Any] = json.loads(FFprobeJSON_utf8)
+    Z0Z_dictionaries: Dict[str, Union[numpy.ndarray, Dict[str, numpy.ndarray]]] = {}
+    if 'packets_and_frames' in FFroot: # Divide into 'packets' and 'frames'
+        FFroot = defaultdict(list, FFroot)
+        for packetOrFrame in FFroot['packets_and_frames']:
+            if 'type' in packetOrFrame:
+                FFroot[section := packetOrFrame['type'] + 's'].append(packetOrFrame)
+                del FFroot[section][-1]['type']
+            else:
+                raise ValueError("'packets_and_frames' for the win!")
+        del FFroot['packets_and_frames']
+
+    Z0Z_register = [
+        'aspectralstats',
+        'astats', 
+        'r128',
+        'signalstats',
+    ]
+    if 'frames' in FFroot:
+        leftCrumbs = False
+        listTuplesBlackdetect = []
+        for indexFrame, FFframe in enumerate(FFroot['frames']):
+            if 'tags' in FFframe:
+                if 'lavfi.black_start' in FFframe['tags']:
+                    listTuplesBlackdetect.append(float(FFframe['tags']['lavfi.black_start']))
+                    del FFframe['tags']['lavfi.black_start']
+                if 'lavfi.black_end' in FFframe['tags']:
+                    listTuplesBlackdetect[-1] = (listTuplesBlackdetect[-1], float(FFframe['tags']['lavfi.black_end']))
+                    del FFframe['tags']['lavfi.black_end']
+
+                # This is not the way to do it
+                for keyName, keyValue in FFframe['tags'].items():
+                    if 'lavfi' in (keyNameDeconstructed := keyName.split('.'))[0]:
+                        channel = None
+                        if (registrant := keyNameDeconstructed[1]) in Z0Z_register:
+                            keyNameDeconstructed = keyNameDeconstructed[2:]
+                            if keyNameDeconstructed[0].isdigit(): 
+                                channel = int(keyNameDeconstructed[0])
+                                keyNameDeconstructed = keyNameDeconstructed[1:]
+                            statistic = '.'.join(keyNameDeconstructed)
+                            if channel is None:
+                                while True:
+                                    try:
+                                        Z0Z_dictionaries[registrant][statistic][indexFrame] = float(keyValue)
+                                        break  # If successful, exit the loop
+                                    except KeyError:                                    
+                                        if registrant not in Z0Z_dictionaries:
+                                            Z0Z_dictionaries[registrant] = {}
+                                        elif statistic not in Z0Z_dictionaries[registrant]:
+                                            Z0Z_dictionaries[registrant][statistic] = numpy.zeros((len(FFroot['frames'])))
+                                        else:
+                                            raise  # Re-raise the exception
+                            else:
+                                while True:
+                                    try:
+                                        Z0Z_dictionaries[registrant][statistic][channel - 1, indexFrame] = float(keyValue)
+                                        break  # If successful, exit the loop
+                                    except KeyError:
+                                        if registrant not in Z0Z_dictionaries:
+                                            Z0Z_dictionaries[registrant] = {}
+                                        elif statistic not in Z0Z_dictionaries[registrant]:
+                                                Z0Z_dictionaries[registrant][statistic] = numpy.zeros((channel, len(FFroot['frames'])))
+                                        else:
+                                            raise  # Re-raise the exception
+                                    except IndexError:
+                                        if channel > Z0Z_dictionaries[registrant][statistic].shape[0]:
+                                            Z0Z_dictionaries[registrant][statistic].resize((channel, len(FFroot['frames'])))
+                                        else:
+                                            raise  # Re-raise the exception
+
+                if not FFframe['tags']: # empty = False
+                    del FFframe['tags']
+            if FFframe:
+                leftCrumbs = True
+        if listTuplesBlackdetect:
+            Z0Z_dictionaries['blackdetect'] = numpy.array(listTuplesBlackdetect, dtype=[('black_start', numpy.float32), ('black_end', numpy.float32)], copy=False)
+    if not leftCrumbs:
+        del FFroot['frames']
+    return FFroot, Z0Z_dictionaries

analyzeAudio-0.0.11.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.2
+Name: analyzeAudio
+Version: 0.0.11
+Summary: Measure one or more aspects of one or more audio files.
+Author-email: Hunter Hogan <HunterHogan@pm.me>
+License: CC-BY-NC-4.0
+Project-URL: Homepage, https://github.com/hunterhogan/analyzeAudio
+Project-URL: Donate, https://www.patreon.com/integrated
+Keywords: audio,analysis,measurement,metrics,torch
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Other Audience
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cachetools
+Requires-Dist: librosa
+Requires-Dist: numpy
+Requires-Dist: torch
+Requires-Dist: torchmetrics[audio]
+Requires-Dist: tqdm
+Requires-Dist: Z0Z-tools
+Provides-Extra: testing
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: pytest-env; extra == "testing"
+
+# 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](https://www.ffmpeg.org/download.html) at ffmpeg.org.
+
+## Some ways to use this package
+
+### Use `analyzeAudioFile` to measure one or more aspects of a single audio file
+
+```python
+from analyzeAudio import analyzeAudioFile
+listAspectNames = ['LUFS integrated', 
+                   'RMS peak', 
+                   'SRMR mean', 
+                   'Spectral Flatness mean']
+listMeasurements = analyzeAudioFile(pathFilename, listAspectNames)
+```
+
+### Use `getListAvailableAudioAspects` to get a crude list of aspects this package can measure
+
+The aspect names are accurate, but the lack of additional documentation can make things challenging. 'Zero-crossing rate', 'Zero-crossing rate mean', and 'Zero-crossings rate', for example, are different from each other. ("... lack of additional documentation ...")
+
+```python
+import analyzeAudio
+analyzeAudio.getListAvailableAudioAspects()
+```
+
+### Use `analyzeAudioListPathFilenames` to measure one or more aspects of individual file in a list of audio files
+
+### Use `audioAspects` to call an analyzer function by using the name of the aspect you wish to measure
+
+```python
+from analyzeAudio import audioAspects
+SI_SDR_channelsMean = audioAspects['SI-SDR mean']['analyzer'](pathFilenameAudioFile, pathFilenameDifferentAudioFile)
+```
+
+Retrieve the names of the parameters for an analyzer function with the `['analyzerParameters']` key-name.
+
+```python
+from analyzeAudio import audioAspects
+print(audioAspects['Chromagram']['analyzerParameters'])
+```
+
+## Install this package
+
+### From Github
+
+```sh
+pip install analyzeAudio@git+https://github.com/hunterhogan/analyzeAudio.git
+```
+
+### From a local directory
+
+#### Windows
+
+```powershell
+git clone https://github.com/hunterhogan/analyzeAudio.git \path\to\analyzeAudio
+pip install analyzeAudio@file:\path\to\analyzeAudio
+```
+
+#### POSIX
+
+```bash
+git clone https://github.com/hunterhogan/analyzeAudio.git /path/to/analyzeAudio
+pip install analyzeAudio@file:/path/to/analyzeAudio
+```
+
+## Install updates
+
+```sh
+pip install --upgrade analyzeAudio@git+https://github.com/hunterhogan/analyzeAudio.git
+```

analyzeAudio-0.0.11.dist-info/RECORD

@@ -0,0 +1,14 @@
+analyzeAudio/__init__.py,sha256=WT2LnWdO-7r8ARjS9fVqjedu-TwUDj-gStQMJouplc4,452
+analyzeAudio/analyzersUseFilename.py,sha256=RMoIKlLzHZW-ks-J-CxgrpD8IgifTl2B514VeW0J2W4,11316
+analyzeAudio/analyzersUseSpectrogram.py,sha256=bY06q3iacB0ciyjAlfde6rxLRXCvrg7CY3Yp-elv9b4,1623
+analyzeAudio/analyzersUseTensor.py,sha256=n5jOwtam5pDErYp_Ja_VGVR_Q4c0MS3KPLIQnaRfDgs,572
+analyzeAudio/analyzersUseWaveform.py,sha256=4HCWb8LCqZAeXGxkBOpfViXDv3ffFQiTtTyIpLoVZ24,1381
+analyzeAudio/audioAspectsRegistry.py,sha256=abIbrXRqDfx8DRE9HKSv7qQPfUzxU8IhLbB6n5JJAuU,9365
+analyzeAudio/pythonator.py,sha256=jTsQapE537hP_Wav16EsvETdwsw7FzDhQnbX6tISC8g,4835
+tests/conftest.py,sha256=BhZswOjkl_u-qiS4Zy38d2fETdWAtZiigeuXYBK8l0k,397
+tests/test_audioAspectsRegistry.py,sha256=bZb6TQQwRedaCKzH5hqPpJkn7cHl_cHpj4OHtPonawo,28
+tests/test_other.py,sha256=mJxNqTjs5U_qdmNIVN599h3XzoDtRMvM8koE9-wI664,549
+analyzeAudio-0.0.11.dist-info/METADATA,sha256=VEDc6M2hh2eNHAJJVJWME3dYpuDaGZ9GoaRiIrttrdY,3462
+analyzeAudio-0.0.11.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+analyzeAudio-0.0.11.dist-info/top_level.txt,sha256=QV8LQ0r_1LIQuewxDcEzODpykv5qRYG3I70piOUSVRg,19
+analyzeAudio-0.0.11.dist-info/RECORD,,

analyzeAudio-0.0.11.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

analyzeAudio-0.0.11.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+analyzeAudio
+tests

tests/conftest.py

@@ -0,0 +1,16 @@
+import pathlib
+import pytest
+
+pathDataSamples = pathlib.Path(__file__).parent / "dataSamples"
+
+listOfFiles = ["pink-20RMS60sec.wav",
+"pink-40RMS60sec.wav",
+"pink-60RMS60sec.wav",
+"testParkMono96kHz32float12.1sec.wav",
+"testPink2ch7.1sec.wav",
+"testSine2ch5sec.wav",
+"testSine2ch5secCopy1.wav",
+"testTrain2ch48kHz6.3sec.wav",
+"testVideo11sec.mkv",
+"testWooWooMono16kHz32integerClipping9sec.wav",
+]

tests/test_audioAspectsRegistry.py

@@ -0,0 +1,3 @@
+
+import numpy
+import pytest

tests/test_other.py

@@ -0,0 +1,13 @@
+import pytest
+from Z0Z_tools.pytest_parseParameters import makeTestSuiteConcurrencyLimit, makeTestSuiteOopsieKwargsie
+from Z0Z_tools import defineConcurrencyLimit, oopsieKwargsie
+
+def test_oopsieKwargsie():
+    dictionaryTests = makeTestSuiteOopsieKwargsie(oopsieKwargsie)
+    for testName, testFunction in dictionaryTests.items():
+        testFunction()
+
+def test_defineConcurrencyLimit():
+    dictionaryTests = makeTestSuiteConcurrencyLimit(defineConcurrencyLimit)
+    for testName, testFunction in dictionaryTests.items():
+        testFunction()