hunterHearsPy 1.0.0__tar.gz → 1.0.3__tar.gz

{hunterhearspy-1.0.0 → hunterhearspy-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hunterHearsPy
-Version: 1.0.0
+Version: 1.0.3
 Summary: Audio processing.
 Keywords: 
 Author: Hunter Hogan
@@ -16,10 +16,11 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
+Requires-Dist: huntermakespy>=0.7.0
 Requires-Dist: numpy
 Requires-Dist: resampy
 Requires-Dist: scipy
-Requires-Dist: soundfile
+Requires-Dist: soundfile>=0.14.0
 Requires-Dist: tqdm
 Requires-Dist: torch ; extra == 'torch'
 Maintainer: Hunter Hogan

{hunterhearspy-1.0.0 → hunterhearspy-1.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hunterHearsPy"
-version = "1.0.0"
+version = "1.0.3"
 description = "Audio processing."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -20,7 +20,14 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Typing :: Typed",
 ]
-dependencies = ["numpy", "resampy", "scipy", "soundfile", "tqdm"]
+dependencies = [
+  "hunterMakesPy>=0.7.0",
+  "numpy",
+  "resampy",
+  "scipy",
+  "soundfile>=0.14.0",
+  "tqdm",
+]
 optional-dependencies = { torch = ["torch"] }
 
 [project.urls]

{hunterhearspy-1.0.0 → hunterhearspy-1.0.3}/src/hunterHearsPy/__init__.py

@@ -3,17 +3,19 @@ from __future__ import annotations
 
 from hunterHearsPy.theTypes import (
 	ArraySpectrograms as ArraySpectrograms, ArrayType as ArrayType, ArrayWaveforms as ArrayWaveforms,
-	NormalizationReverter as NormalizationReverter, ParametersShortTimeFFT as ParametersShortTimeFFT, ParametersSTFT as ParametersSTFT,
-	ParametersUniversal as ParametersUniversal, Spectrogram as Spectrogram, SpectrogramDtype as SpectrogramDtype, Waveform as Waveform,
-	WaveformDtype as WaveformDtype, WaveformMetadata as WaveformMetadata, WindowingFunction as WindowingFunction,
-	WindowingFunctionDtype as WindowingFunctionDtype, 个 as 个)
+	callableReturnsNDArray as callableReturnsNDArray, NormalizationReverter as NormalizationReverter,
+	ParametersShortTimeFFT as ParametersShortTimeFFT, ParametersSTFT as ParametersSTFT, ParametersUniversal as ParametersUniversal,
+	Spectrogram as Spectrogram, SpectrogramDtype as SpectrogramDtype, Waveform as Waveform, WaveformDtype as WaveformDtype,
+	WaveformMetadata as WaveformMetadata, WindowingFunction as WindowingFunction, WindowingFunctionDtype as WindowingFunctionDtype)
 
 # isort: split
 from hunterHearsPy.amplitude import normalizeArrayWaveforms as normalizeArrayWaveforms, normalizeWaveform as normalizeWaveform
-from hunterHearsPy.autoRevert import moveToAxisOfOperation as moveToAxisOfOperation
 from hunterHearsPy.clippingArrays import applyHardLimit as applyHardLimit, applyHardLimitComplexValued as applyHardLimitComplexValued
 from hunterHearsPy.windowingFunctions import cosineWings as cosineWings, equalPower as equalPower, halfsine as halfsine, tukey as tukey
 
+# isort: split
+from hunterHearsPy.autoRevert import moveToAxisOfOperation as moveToAxisOfOperation
+
 # isort: split
 from hunterHearsPy.ioAudio import (
 	getWaveformMetadata as getWaveformMetadata, lengthWindowingFunctionDEFAULT as lengthWindowingFunctionDEFAULT,
@@ -30,5 +32,5 @@ from contextlib import suppress
 
 with suppress(ModuleNotFoundError):  # noqa: RUF067
 	from hunterHearsPy.windowingFunctionsTensor import (
-		callableReturnsNDArray as callableReturnsNDArray, cosineWingsTensor as cosineWingsTensor, equalPowerTensor as equalPowerTensor,
-		halfsineTensor as halfsineTensor, tukeyTensor as tukeyTensor)
+		cosineWingsTensor as cosineWingsTensor, equalPowerTensor as equalPowerTensor, halfsineTensor as halfsineTensor,
+		tukeyTensor as tukeyTensor)

{hunterhearspy-1.0.0 → hunterhearspy-1.0.3}/src/hunterHearsPy/ioAudio.py

@@ -9,24 +9,24 @@ arrays shaped `(channels, samples)`. All spectrograms are complex 64-bit float
 Contents
 --------
 Functions
-    getWaveformMetadata
-        Retrieve metadata for a collection of audio waveform files.
-    loadSpectrograms
-        Load spectrograms from a list of audio files.
-    loadWaveforms
-        Load a list of audio files into a single stacked NumPy array.
-    readAudioFile
-        Read an audio file and return stereo waveform data as a NumPy array.
-    resampleWaveform
-        Resample a waveform array to a target sample rate.
-    spectrogramToWAV
-        Write a complex spectrogram to a WAV file.
-    stft
-        Perform Short-Time Fourier Transform or its inverse on waveform or spectrogram data.
-    waveformSpectrogramWaveform
-        Decorate a spectrogram-processing callable to accept and return waveforms.
-    writeWAV
-        Write a waveform array to a WAV file.
+	getWaveformMetadata
+		Retrieve metadata for a collection of audio waveform files.
+	loadSpectrograms
+		Load spectrograms from a list of audio files.
+	loadWaveforms
+		Load a list of audio files into a single stacked NumPy array.
+	readAudioFile
+		Read an audio file and return stereo waveform data as a NumPy array.
+	resampleWaveform
+		Resample a waveform array to a target sample rate.
+	spectrogramToWAV
+		Write a complex spectrogram to a WAV file.
+	stft
+		Perform Short-Time Fourier Transform or its inverse on waveform or spectrogram data.
+	waveformSpectrogramWaveform
+		Decorate a spectrogram-processing callable to accept and return waveforms.
+	writeWAV
+		Write a waveform array to a WAV file.
 
 """
 from __future__ import annotations
@@ -34,6 +34,7 @@ from __future__ import annotations
 from hunterHearsPy import (
 	ArraySpectrograms, ArrayWaveforms, halfsine, ParametersShortTimeFFT, ParametersSTFT, ParametersUniversal, Spectrogram, Waveform,
 	WaveformMetadata, WindowingFunction)
+from hunterMakesPy.filesystemToolkit import makeDirectorySafely
 from math import ceil as ceiling, log2 as log_base2
 from multiprocessing import set_start_method as multiprocessing_set_start_method
 from numpy import complex64, dtype, float32, floating, ndarray
@@ -48,7 +49,6 @@ if TYPE_CHECKING:
 	from collections.abc import Callable, Sequence
 	from os import PathLike
 
-# When to use multiprocessing.set_start_method https://github.com/hunterhogan/mapFolding/issues/6
 if __name__ == '__main__':
 	multiprocessing_set_start_method('spawn')
 
@@ -138,19 +138,18 @@ def getWaveformMetadata(listPathFilenames: Sequence[str | PathLike[str]], sample
 def readAudioFile(pathFilename: str | PathLike[Any] | BinaryIO, sampleRate: float | None = None) -> Waveform:
 	"""Read an audio file and return stereo waveform data as a NumPy array.
 
-	You can use this function to load any audio file that `soundfile` [1] supports. The
-	returned `Waveform` [2] is always shaped `(channels, samples)` where `channels` is `2`.
-	When the source file is mono, `readAudioFile` duplicates the single channel to produce
-	a stereo array. When `sampleRate` differs from the file's native sample rate,
-	`readAudioFile` resamples using `resampleWaveform`.
+	You can use this function to load any audio file that `soundfile` [1] supports. The returned
+	`Waveform` [2] is always shaped `(channels, samples)` where `channels` is `2`. When the source
+	file is mono, `readAudioFile` duplicates the single channel to produce a stereo array. When
+	`sampleRate` differs from the file's native sample rate, `readAudioFile` resamples using
+	`resampleWaveform`.
 
 	Parameters
 	----------
 	pathFilename : str | PathLike[Any] | BinaryIO
 		Path to the audio file or a binary stream compatible with `soundfile` [1].
-	sampleRate : float | None = None
-		Target sample rate of the returned `Waveform` [2] in Hz. Defaults to `44100`
-		when `None`.
+	sampleRate : float | None = 44100
+		Target sample rate of the returned `Waveform` [2] in Hz. Defaults to `44100` when `None`.
 
 	Returns
 	-------
@@ -188,6 +187,7 @@ def readAudioFile(pathFilename: str | PathLike[Any] | BinaryIO, sampleRate: floa
 	axisTime = 0
 	axisChannels = 1
 	waveform = cast('Waveform', resampleWaveform(waveform, sampleRateDesired=sampleRate, sampleRateSource=sampleRateSource, axisTime=axisTime))
+	# TODO In my audio ecosystem, must I force a minimum of 2 channels, or can I merely force an axis for time, even if the axis is length=1?
 	if waveform.shape[axisChannels] == 1:
 		waveform = cast('Waveform', numpy.repeat(waveform, 2, axis=axisChannels))
 	return cast('Waveform', numpy.transpose(waveform, axes=(axisChannels, axisTime)))
@@ -342,7 +342,7 @@ def writeWAV(pathFilename: str | PathLike[Any] | BinaryIO, waveform: Waveform, s
 	"""
 	if sampleRate is None:
 		sampleRate = parametersUniversal['sampleRate']
-	# makeDirsSafely(pathFilename)
+	makeDirectorySafely(pathFilename)
 	soundfile.write(file=pathFilename, data=waveform.T, samplerate=int(sampleRate), subtype='FLOAT', format='WAV')
 
 @overload  # stft 1 ndarray
@@ -352,10 +352,10 @@ def stft(arrayTarget: Waveform, *, sampleRate: float | None = None, lengthHop: i
 def stft(arrayTarget: ArrayWaveforms, *, sampleRate: float | None = None, lengthHop: int | None = None, windowingFunction: WindowingFunction | None = None, lengthWindowingFunction: int | None = None, lengthFFT: int | None = None, inverse: Literal[False] = False, lengthWaveform: None = None, indexingAxis: int = -1) -> ArraySpectrograms: ...
 
 @overload  # istft 1 ndarray
-def stft(arrayTarget: Spectrogram, *, sampleRate: float | None = None, lengthHop: int | None = None, windowingFunction: WindowingFunction | None = None, lengthWindowingFunction: int | None = None, lengthFFT: int | None = None, inverse: Literal[True] = True, lengthWaveform: int, indexingAxis: None = None) -> Waveform: ...
+def stft(arrayTarget: Spectrogram, *, sampleRate: float | None = None, lengthHop: int | None = None, windowingFunction: WindowingFunction | None = None, lengthWindowingFunction: int | None = None, lengthFFT: int | None = None, inverse: Literal[True], lengthWaveform: int, indexingAxis: None = None) -> Waveform: ...
 
 @overload  # istft many ndarray
-def stft(arrayTarget: ArraySpectrograms, *, sampleRate: float | None = None, lengthHop: int | None = None, windowingFunction: WindowingFunction | None = None, lengthWindowingFunction: int | None = None, lengthFFT: int | None = None, inverse: Literal[True] = True, lengthWaveform: int, indexingAxis: int = -1) -> ArrayWaveforms: ...
+def stft(arrayTarget: ArraySpectrograms, *, sampleRate: float | None = None, lengthHop: int | None = None, windowingFunction: WindowingFunction | None = None, lengthWindowingFunction: int | None = None, lengthFFT: int | None = None, inverse: Literal[True], lengthWaveform: int, indexingAxis: int = -1) -> ArrayWaveforms: ...
 
 def stft(arrayTarget: Waveform | ArrayWaveforms | Spectrogram | ArraySpectrograms
 		, *

{hunterhearspy-1.0.0 → hunterhearspy-1.0.3}/src/hunterHearsPy/theTypes.py

@@ -16,10 +16,10 @@ from typing import Any, TYPE_CHECKING, TypeAlias, TypedDict, TypeVar
 if TYPE_CHECKING:
 	from scipy.signal._short_time_fft import _FFTMode, _PadType, _ScaleTo
 
-个 = TypeVar('个', covariant=True)
 ArrayType = TypeVar('ArrayType', bound=ndarray[tuple[Any, ...], dtype[Any]], covariant=True)
 WindowingFunctionDtype: TypeAlias = floating[Any]
 WindowingFunction: TypeAlias = ndarray[tuple[int], dtype[WindowingFunctionDtype]]
+callableReturnsNDArray = TypeVar('callableReturnsNDArray', bound=Callable[..., WindowingFunction])
 WaveformDtype: TypeAlias = floating[Any]
 Waveform: TypeAlias = ndarray[tuple[int, int], dtype[WaveformDtype]]
 """Two-axes NumPy `ndarray` representing audio waveforms.

{hunterhearspy-1.0.0 → hunterhearspy-1.0.3}/src/hunterHearsPy/windowingFunctionsTensor.py

@@ -1,13 +1,12 @@
 """Create PyTorch tensor windowing functions."""
 from __future__ import annotations
 
-from collections.abc import Callable
-from hunterHearsPy import cosineWings, equalPower, halfsine, tukey, WindowingFunction
-from torch.types import Device
-from typing import Any, TypeVar
+from hunterHearsPy import callableReturnsNDArray, cosineWings, equalPower, halfsine, tukey
+from typing import Any, TYPE_CHECKING
 import torch
 
-callableReturnsNDArray = TypeVar('callableReturnsNDArray', bound=Callable[..., WindowingFunction])
+if TYPE_CHECKING:
+    from torch.types import Device
 
 def _convertToTensor(*arguments: Any, callableTarget: callableReturnsNDArray, device: Device, **keywordArguments: Any) -> torch.Tensor:
     arrayTarget = callableTarget(*arguments, **keywordArguments)
@@ -29,7 +28,7 @@ def cosineWingsTensor(lengthWindow: int, ratioTaper: float | None=None, device:
         Ratio of taper length to windowing-function length. The value must be between 0 and 1,
         inclusive.
     device : Device = torch.device(device='cpu')
-        PyTorch device for tensor allocation.
+        PyTorch device for `Tensor`.
 
     Returns
     -------
@@ -70,7 +69,7 @@ def equalPowerTensor(lengthWindow: int, ratioTaper: float | None=None, device: D
         Ratio of taper length to windowing-function length. The value must be between 0 and 1,
         inclusive.
     device : Device = torch.device(device='cpu')
-        PyTorch device for tensor allocation.
+        PyTorch device for `Tensor`.
 
     Returns
     -------
@@ -107,7 +106,7 @@ def halfsineTensor(lengthWindow: int, device: Device | None=None) -> torch.Tenso
     lengthWindow : int
         Total length of the windowing function.
     device : Device = torch.device(device='cpu')
-        PyTorch device for tensor allocation.
+        PyTorch device for `Tensor`.
 
     Returns
     -------
@@ -150,7 +149,7 @@ def tukeyTensor(lengthWindow: int, ratioTaper: float | None=None, device: Device
         Additional keyword arguments. `alpha` overrides `ratioTaper` when provided, matching SciPy's
         API.
     device : Device = torch.device(device='cpu')
-        PyTorch device for tensor allocation.
+        PyTorch device for `Tensor`.
 
     Returns
     -------