hunterHearsPy 1.0.3__py3-none-any.whl

hunterHearsPy/__init__.py

@@ -0,0 +1,36 @@
+# ruff: noqa: D104
+from __future__ import annotations
+
+from hunterHearsPy.theTypes import (
+	ArraySpectrograms as ArraySpectrograms, ArrayType as ArrayType, ArrayWaveforms as ArrayWaveforms,
+	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.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,
+	loadSpectrograms as loadSpectrograms, loadWaveforms as loadWaveforms, parametersDEFAULT as parametersDEFAULT,
+	parametersShortTimeFFTUniversal as parametersShortTimeFFTUniversal, parametersSTFTUniversal as parametersSTFTUniversal,
+	readAudioFile as readAudioFile, resampleWaveform as resampleWaveform, setParametersUniversal as setParametersUniversal,
+	spectrogramToWAV as spectrogramToWAV, stft as stft, universalDtypeSpectrogram as universalDtypeSpectrogram,
+	universalDtypeWaveform as universalDtypeWaveform, waveformSpectrogramWaveform as waveformSpectrogramWaveform,
+	windowingFunctionCallableDEFAULT as windowingFunctionCallableDEFAULT,
+	windowingFunctionCallableUniversal as windowingFunctionCallableUniversal, writeWAV as writeWAV)
+
+# isort: split
+from contextlib import suppress
+
+with suppress(ModuleNotFoundError):  # noqa: RUF067
+	from hunterHearsPy.windowingFunctionsTensor import (
+		cosineWingsTensor as cosineWingsTensor, equalPowerTensor as equalPowerTensor, halfsineTensor as halfsineTensor,
+		tukeyTensor as tukeyTensor)

hunterHearsPy/amplitude.py

@@ -0,0 +1,170 @@
+"""Normalize audio waveform amplitudes.
+
+(AI generated docstring)
+
+You can use this module to scale audio waveforms to a target peak amplitude. Each normalization
+function returns both the scaled waveform and a reversion callable that restores the original
+amplitude scale when applied to any waveform derived from the normalized result.
+
+Contents
+--------
+Functions
+    normalizeArrayWaveforms
+        Normalize multiple waveforms in an array to a specified peak amplitude.
+    normalizeWaveform
+        Normalize a waveform to a specified peak amplitude.
+
+"""
+from __future__ import annotations
+
+from numpy import divide, finfo as numpy_finfo, max as numpy_max, multiply
+from typing import cast, overload, TYPE_CHECKING
+
+if TYPE_CHECKING:
+	from hunterHearsPy import ArrayWaveforms, NormalizationReverter, Waveform
+
+def normalizeWaveform(waveform: Waveform, amplitudeNorm: float = 1.0) -> tuple[Waveform, NormalizationReverter]:
+	"""Normalize a waveform to a specified peak amplitude.
+
+	(AI generated docstring)
+
+	You can use this function to scale a `Waveform` [1] so that its absolute peak value equals
+	`amplitudeNorm`. This function also returns `revertNormalization`, a `NormalizationReverter` [2]
+	callable that reverses the scaling when applied to any waveform derived from `waveformNormalized`.
+
+	Parameters
+	----------
+	waveform : Waveform
+		The input audio waveform to normalize.
+	amplitudeNorm : float = 1.0
+		Target peak amplitude. The absolute maximum value of `waveformNormalized` equals `amplitudeNorm`.
+
+	Returns
+	-------
+	waveformNormalized : Waveform
+		The scaled waveform with absolute peak value equal to `amplitudeNorm`.
+	revertNormalization : NormalizationReverter
+		A callable that reverses the normalization scaling. Apply `revertNormalization` to any
+		waveform derived from `waveformNormalized` to restore the original amplitude scale.
+
+	Warns
+	-----
+	UserWarning
+		If `amplitudeNorm` is 0, `normalizeWaveform` replaces it with the smallest positive finite
+		value representable in the dtype of `waveform` using `numpy.finfo` [3] and continues.
+	UserWarning
+		If `waveform` contains only zeros, `waveformNormalized` will also be all zeros.
+		`revertNormalization` will divide by `amplitudeNorm` rather than by the waveform peak.
+
+	See Also
+	--------
+	`normalizeArrayWaveforms`
+		Normalize multiple waveforms in an array to a specified peak amplitude.
+
+	Amplitude Scaling
+	-----------------
+	`normalizeWaveform` computes the absolute peak of `waveform` as the maximum of `waveform.max()`
+	and `-waveform.min()`, then multiplies every sample by `amplitudeNorm / peakAbsolute`.
+	`revertNormalization` reverses this by dividing every sample by the same factor.
+
+	Examples
+	--------
+	Normalize a waveform and revert the normalization:
+
+		```python
+		from hunterHearsPy import normalizeWaveform
+
+		waveformNormalized, revertNormalization = normalizeWaveform(waveform.copy())
+		waveformReverted = revertNormalization(waveformNormalized)
+		```
+
+	References
+	----------
+	[1] `hunterHearsPy.theTypes.Waveform`
+
+	[2] `hunterHearsPy.theTypes.NormalizationReverter`
+
+	[3] numpy.finfo - NumPy reference
+		https://numpy.org/doc/stable/reference/generated/numpy.finfo.html
+
+	"""
+	amplitudeNorm = amplitudeNorm or float(numpy_finfo(waveform.dtype).tiny.astype(waveform.dtype))
+
+	peakAbsolute: float = abs(float(numpy_max([waveform.max(), -waveform.min()]))) or 1.0
+	amplitudeAdjustment: float = amplitudeNorm / peakAbsolute
+
+	multiply(waveform, amplitudeAdjustment, out=waveform)
+
+	@overload
+	def revertNormalization(waveformDescendant: Waveform) -> Waveform: ...
+	@overload
+	def revertNormalization(waveformDescendant: ArrayWaveforms) -> ArrayWaveforms: ...
+	def revertNormalization(waveformDescendant: ArrayWaveforms | Waveform) -> ArrayWaveforms | Waveform:
+		return divide(waveformDescendant, amplitudeAdjustment, out=waveformDescendant)
+	return waveform, revertNormalization
+
+def normalizeArrayWaveforms(arrayWaveforms: ArrayWaveforms, amplitudeNorm: float = 1.0) -> tuple[ArrayWaveforms, list[NormalizationReverter]]:
+	"""Normalize multiple waveforms in an array to a specified peak amplitude.
+
+	(AI generated docstring)
+
+	You can use this function to scale each `Waveform` [1] in an `ArrayWaveforms` [2] so that
+	each waveform's absolute peak value equals `amplitudeNorm`. This function also returns
+	`listRevertNormalization`, a list of `NormalizationReverter` [3] callables, one per waveform,
+	that each reverse the scaling for the corresponding waveform at the matching last-axis index.
+
+	`normalizeArrayWaveforms` delegates each individual waveform normalization to
+	`normalizeWaveform` [4] and modifies `arrayWaveforms` in place before returning it.
+
+	Parameters
+	----------
+	arrayWaveforms : ArrayWaveforms
+		Array containing multiple waveforms indexed on the last axis. Shape is
+		(channels, samples, waveforms).
+	amplitudeNorm : float = 1.0
+		Target peak amplitude. The absolute maximum value of each normalized waveform equals
+		`amplitudeNorm`.
+
+	Returns
+	-------
+	arrayWaveformsNormalized : ArrayWaveforms
+		The array of normalized waveforms, identical to `arrayWaveforms` modified in place.
+		Each waveform is scaled to peak amplitude `amplitudeNorm`.
+	listRevertNormalization : list[NormalizationReverter]
+		A list of callables indexed in the same order as the last axis of `arrayWaveforms`.
+		Each callable reverses the normalization scaling for the corresponding waveform.
+
+	See Also
+	--------
+	`normalizeWaveform`
+		Normalize a single waveform to a specified peak amplitude.
+
+	Examples
+	--------
+	Normalize all waveforms in an array and revert each one:
+
+		```python
+		from hunterHearsPy import normalizeArrayWaveforms
+
+		arrayNormalized, listRevertNormalization = normalizeArrayWaveforms(arrayWaveforms.copy())
+		for indexWaveform in range(arrayNormalized.shape[-1]):
+			arrayReverted[..., indexWaveform] = listRevertNormalization[indexWaveform](
+				arrayReverted[..., indexWaveform]
+			)
+		```
+
+	References
+	----------
+	[1] `hunterHearsPy.theTypes.Waveform`
+
+	[2] `hunterHearsPy.theTypes.ArrayWaveforms`
+
+	[3] `hunterHearsPy.theTypes.NormalizationReverter`
+
+	[4] `normalizeWaveform`
+
+	"""
+	listRevertNormalization: list[NormalizationReverter] = [lambda makeTypeCheckerHappy: makeTypeCheckerHappy] * arrayWaveforms.shape[-1]
+	for index in range(arrayWaveforms.shape[-1]):
+		arrayWaveforms[..., index], listRevertNormalization[index] = normalizeWaveform(cast("Waveform", arrayWaveforms[..., index]), amplitudeNorm)
+	return arrayWaveforms, listRevertNormalization

hunterHearsPy/autoRevert.py

@@ -0,0 +1,75 @@
+"""Temporarily reposition array axes and restore the original axis order on context exit.
+
+Contents
+--------
+Functions
+	moveToAxisOfOperation
+		Move an array axis to an operation position, then automatically restore the original axis order on exit.
+
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from hunterHearsPy import normalizeWaveform
+from numpy import moveaxis
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+	from collections.abc import Generator
+	from hunterHearsPy import ArrayType, Waveform
+
+@contextmanager
+def moveToAxisOfOperation(arrayTarget: ArrayType, axisSource: int, axisOfOperation: int = -1) -> Generator[ArrayType]:
+	"""Move an array axis to an operation position, then automatically restore the original axis order on exit.
+
+	You can use `moveToAxisOfOperation` as a context manager to temporarily rearrange the axes of
+	`arrayTarget`. The context yields `arrayStandardized`, a `numpy.moveaxis` [1] view of `arrayTarget`
+	with `axisSource` moved to `axisOfOperation`. Because `arrayStandardized` shares memory with
+	`arrayTarget`, modifications to `arrayStandardized` inside the context are reflected in `arrayTarget`.
+	When the context exits, `arrayTarget` retains its original axis order.
+
+	Parameters
+	----------
+	arrayTarget : ArrayType
+		The array whose axis to move.
+	axisSource : int
+		The source axis position to move. Negative values count from the last axis.
+	axisOfOperation : int = -1
+		The destination axis position for `axisSource`. Negative values count from the last axis.
+
+	Yields
+	------
+	arrayStandardized : ArrayType
+		A view of `arrayTarget` with `axisSource` at position `axisOfOperation`.
+
+	Examples
+	--------
+	Move axis 0 to the last position and modify values inside the context:
+
+		```python
+		import numpy
+		from hunterHearsPy import moveToAxisOfOperation
+
+		arrayAxisOperation = numpy.arange(24).reshape(2, 3, 4)
+		with moveToAxisOfOperation(arrayAxisOperation, axisSource=0, axisOfOperation=-1) as arrayStandardized:
+			arrayStandardized += 10
+		```
+
+	References
+	----------
+	[1] numpy.moveaxis
+		https://numpy.org/doc/stable/reference/generated/numpy.moveaxis.html
+
+	"""
+	arrayStandardized: ArrayType = moveaxis(arrayTarget, axisSource, axisOfOperation)
+	try:
+		yield arrayStandardized
+	finally:
+		moveaxis(arrayStandardized, axisOfOperation, axisSource)
+
+"""
+@contextmanager
+def normalizeUnnormalize(waveform: Waveform, amplitudeNorm: float = 1.0):
+	pass
+"""
+# C:\apps\loudnessWeightedSpectrogram\loudnessWeightedSpectrogram\spectrogram.py

hunterHearsPy/clippingArrays.py

@@ -0,0 +1,143 @@
+"""Clip and limit array values using magnitude-based hard limits.
+
+(AI generated docstring)
+
+You can use this module to apply hard clipping [1] to NumPy [2] arrays, constraining element
+magnitudes within bounds defined by a comparand array. The module is not yet fully implemented
+and may not correctly handle all cases.
+
+Contents
+--------
+Functions
+	applyHardLimit
+		Clip the elements of a real-valued array to stay within the magnitude of a comparand.
+	applyHardLimitComplexValued
+		Clip the elements of a complex-valued array using magnitude-based scaling.
+
+References
+----------
+[1] Clipping (signal processing) - Wikipedia
+	https://en.wikipedia.org/wiki/Clipping_(signal_processing)
+
+[2] NumPy
+	https://numpy.org/doc/stable/
+"""
+from __future__ import annotations
+
+from numpy import absolute, complexfloating, float64, floating, multiply, ones_like
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+	from hunterHearsPy import ArrayType
+	from numpy.typing import ArrayLike, NDArray
+
+def applyHardLimit(arrayTarget: ArrayType, comparand: ArrayLike = 1.0) -> ArrayType:
+	"""Clip the elements of `arrayTarget` to the magnitude bounds defined by `comparand`.
+
+	This function applies a hard amplitude limit element-wise to `arrayTarget`. Elements whose
+	magnitude exceeds the corresponding magnitude of `comparand` are reduced toward zero until
+	the element magnitude equals the comparand magnitude. The operation modifies `arrayTarget`
+	in place and returns a reference to it.
+
+	Parameters
+	----------
+	arrayTarget : ArrayType
+		The array to clip. Modified in place.
+	comparand : ArrayLike = 1.0
+		The magnitude threshold. Elements of `arrayTarget` whose magnitude strictly exceeds the
+		corresponding magnitude in `comparand` are clipped to that comparand magnitude.
+
+	Returns
+	-------
+	arrayClipped : ArrayType
+		A reference to the modified `arrayTarget`.
+
+	See Also
+	--------
+	`applyHardLimitComplexValued`
+		Clip complex-valued array elements using magnitude-based scaling.
+
+	References
+	----------
+	[1] Clipping (signal processing) - Wikipedia
+		https://en.wikipedia.org/wiki/Clipping_(signal_processing)
+
+	[2] numpy.typing.NDArray
+		https://numpy.org/doc/stable/reference/typing.html#numpy.typing.NDArray
+
+	[3] numpy.typing.ArrayLike
+		https://numpy.org/doc/stable/reference/typing.html#numpy.typing.ArrayLike
+
+	"""
+	maskTrueAboveThreshold = absolute(comparand) - absolute(arrayTarget) < 0.0
+	reduction = arrayTarget - (absolute(arrayTarget) - absolute(comparand))
+	arrayTarget[maskTrueAboveThreshold] = reduction[maskTrueAboveThreshold]
+	return arrayTarget
+
+def applyHardLimitComplexValued(
+	arrayTarget: ArrayType,
+	comparand: NDArray[floating[Any] | complexfloating[Any, Any]],
+	penalty: float = 1.0
+	) -> ArrayType:
+	"""Clip the elements of complex-valued `arrayTarget` by scaling magnitudes to stay within `comparand`.
+
+	This function applies a magnitude-based hard limit to each element of `arrayTarget`. When the
+	magnitude of an element strictly exceeds the corresponding value in `comparand`, the element is
+	scaled down by a power of the ratio of comparand magnitude to target magnitude. Elements whose
+	magnitudes are within the limit are left unchanged. This function returns a new array and does
+	not modify `arrayTarget` in place.
+
+	Parameters
+	----------
+	arrayTarget : NDArray[complexfloating[Any, Any]]
+		The complex-valued array to clip.
+	comparand : NDArray[floating[Any] | complexfloating[Any, Any]]
+		The magnitude threshold array. Only the magnitudes of `comparand` values are used.
+	penalty : float = 1.0
+		Exponent applied to the scaling factor when limiting is needed. Values greater than 1.0
+		produce more aggressive clipping; values between 0.0 and 1.0 produce less aggressive clipping.
+
+	Returns
+	-------
+	arrayResult : NDArray[complexfloating[Any, Any]]
+		A new array with the same shape and dtype as `arrayTarget`, with element magnitudes
+		clipped according to `comparand`.
+
+	See Also
+	--------
+	`applyHardLimit`
+		Clip real-valued array elements to stay within the magnitude of a comparand.
+
+	Mathematics
+	-----------
+	magnitude scaling : equation
+	```
+		Let a ≜ `arrayTarget`,  c ≜ `comparand`,  p ≜ `penalty`,
+			s ≜ (|cᵢ| / |aᵢ|)
+
+		For each element i where |aᵢ| > |cᵢ|:
+			resultᵢ = aᵢ × sᵖ
+
+		For each element i where |aᵢ| ≤ |cᵢ|:
+			resultᵢ = aᵢ
+	```
+
+	References
+	----------
+	[1] Clipping (signal processing) - Wikipedia
+		https://en.wikipedia.org/wiki/Clipping_(signal_processing)
+
+	[2] numpy.typing.NDArray
+		https://numpy.org/doc/stable/reference/typing.html#numpy.typing.NDArray
+
+	"""
+	magnitudeArrayTarget: NDArray[float64] = absolute(arrayTarget, dtype=float64)
+	magnitudeComparand: NDArray[float64] = absolute(comparand, dtype=float64)
+
+	maskTrueAboveThreshold = magnitudeComparand - magnitudeArrayTarget < 0.0
+
+	arrayCoefficients_Float64: NDArray[float64] = magnitudeComparand[maskTrueAboveThreshold] / magnitudeArrayTarget[maskTrueAboveThreshold]
+	arrayCoefficients_ComplexValued: ArrayType = ones_like(arrayTarget, dtype=arrayTarget.dtype)
+	arrayCoefficients_ComplexValued[maskTrueAboveThreshold] = arrayCoefficients_Float64**penalty
+
+	return multiply(arrayTarget, arrayCoefficients_ComplexValued)