hunterHearsPy 1.0.3__tar.gz → 1.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hunterHearsPy
-Version: 1.0.3
+Version: 1.1.0
 Summary: Audio processing.
 Keywords: 
 Author: Hunter Hogan
@@ -14,6 +14,9 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Dist: huntermakespy>=0.7.0
@@ -22,6 +25,8 @@ Requires-Dist: resampy
 Requires-Dist: scipy
 Requires-Dist: soundfile>=0.14.0
 Requires-Dist: tqdm
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: z0z-tools>=2.1.0
 Requires-Dist: torch ; extra == 'torch'
 Maintainer: Hunter Hogan
 Maintainer-email: Hunter Hogan <HunterHogan@pm.me>
@@ -101,6 +106,78 @@ processor = waveformSpectrogramWaveform(boost_low_frequencies)
 processed_waveform = processor(original_waveform)
 ```
 
+## Development
+
+I want:
+
+- consistent waveforms,
+- consistent spectrograms, and
+- efficient, reliable transformations.
+
+Therefore, I want one package, this package, to manage those objectives with a single source of truth for configurable universal settings.
+
+- I need good default universal settings.
+- I need an easy way to change a universal setting.
+- I want _ad hoc_ overrides for some or all universal settings.
+
+I don't know a good way to implement user-configurable universal settings. Therefore, as I normally do, I will use my HARDCODED system as a placeholder.
+
+### Semiotics
+
+- channel, rarely channels.
+- time is more generic than samples and often preferred.
+- array is generic.
+- when talking about a NumPy `ndarray`, write `ndarray` not array.
+- `sampleRate` is giving me problems in the "ingest" functions.
+  - Regularly review these semiotics until the system is clear.
+  - Most of the time, `sampleRate` is descriptive: this is the sample rate. See `writeWAV`.
+  - In `readAudioFile`, the parameter is prescriptive: make this the sample rate. Even worse, the
+    attribute of the current sample rate is `readSoundFile.samplerate`, which is descriptive, of course.
+  - However, `def resampleWaveform(waveform, sampleRateDesired: float, sampleRateSource: float):` has
+    excellent semiotics because it does not use `sampleRate`.
+
+### Preferred packages
+
+- NumPy
+- scipy
+- hunterMakesPy
+- tqdm (for status messages)
+- cytoolz via the [Z0Z_tools](https://github.com/hunterhogan/Z0Z_tools) package (until it finds a forever home)
+- more_itertools
+- `astToolKit`
+- `pytest`
+
+### Probably won't need
+
+- `analyzeAudio`
+- `gmpy2`
+- `numba`
+- `platformdirs`
+- `sympy`
+- `torch-einops-kit`
+
+### Not using `PyTorch` for "business" logic
+
+- But, I must have `torch` compatibility.
+- At a minimum, a transformation to and from `torch` that the user must call.
+- `astToolkit` easily creates real `torch` APIs and identifiers, however, for the `windowingFunctions` module in `windowingFunctionsTensor`.
+
+### Not using librosa
+
+- Dependency bloated.
+- Slow.
+- Less precise than I want.
+- I generally dislike the API and identifiers.
+
+### Disfavored packages
+
+- `pandas`
+
+### More vectorization
+
+- Few or no `for` loops.
+- Few or no `for` object comprehensions.
+
 ## Installation
 
 ```bash

hunterhearspy-1.1.0/README.md

@@ -0,0 +1,150 @@
+# hunterHearsPy
+
+A comprehensive collection of Python utilities for audio processing.
+
+## Audio Processing Made Simple
+
+### Load and Save Audio Files
+
+Read audio files with automatic stereo conversion and sample rate control:
+
+```python
+from hunterHearsPy import readAudioFile, writeWAV
+
+# Load audio with sample rate conversion
+waveform = readAudioFile('input.wav', sampleRate=44100)
+
+# Save in WAV format (always 32-bit float)
+writeWAV('output.wav', waveform)
+```
+
+### Process Multiple Audio Files at Once
+
+Load and process batches of audio files:
+
+```python
+from hunterHearsPy import loadWaveforms
+
+# Load multiple files with consistent formatting
+array_waveforms = loadWaveforms(['file1.wav', 'file2.wav', 'file3.wav'])
+
+# The result is a unified array with shape (channels, samples, file_count)
+```
+
+### Work with Spectrograms
+
+Convert between waveforms and spectrograms:
+
+```python
+from hunterHearsPy import stft, halfsine
+
+# Create a spectrogram with a half-sine window
+spectrogram = stft(waveform, windowingFunction=halfsine(1024))
+
+# Convert back to a waveform
+reconstructed = stft(spectrogram, inverse=True, lengthWaveform=original_length)
+```
+
+### Process Audio in the Frequency Domain
+
+Create functions that operate on spectrograms:
+
+```python
+from hunterHearsPy import waveformSpectrogramWaveform
+
+def boost_low_frequencies(spectrogram):
+    # Boost frequencies below 500 Hz
+    spectrogram[:, :10, :] *= 2.0
+    return spectrogram
+
+# Create a processor that handles the STFT/ISTFT automatically
+processor = waveformSpectrogramWaveform(boost_low_frequencies)
+
+# Apply the processor to a waveform
+processed_waveform = processor(original_waveform)
+```
+
+## Development
+
+I want:
+
+- consistent waveforms,
+- consistent spectrograms, and
+- efficient, reliable transformations.
+
+Therefore, I want one package, this package, to manage those objectives with a single source of truth for configurable universal settings.
+
+- I need good default universal settings.
+- I need an easy way to change a universal setting.
+- I want _ad hoc_ overrides for some or all universal settings.
+
+I don't know a good way to implement user-configurable universal settings. Therefore, as I normally do, I will use my HARDCODED system as a placeholder.
+
+### Semiotics
+
+- channel, rarely channels.
+- time is more generic than samples and often preferred.
+- array is generic.
+- when talking about a NumPy `ndarray`, write `ndarray` not array.
+- `sampleRate` is giving me problems in the "ingest" functions.
+  - Regularly review these semiotics until the system is clear.
+  - Most of the time, `sampleRate` is descriptive: this is the sample rate. See `writeWAV`.
+  - In `readAudioFile`, the parameter is prescriptive: make this the sample rate. Even worse, the
+    attribute of the current sample rate is `readSoundFile.samplerate`, which is descriptive, of course.
+  - However, `def resampleWaveform(waveform, sampleRateDesired: float, sampleRateSource: float):` has
+    excellent semiotics because it does not use `sampleRate`.
+
+### Preferred packages
+
+- NumPy
+- scipy
+- hunterMakesPy
+- tqdm (for status messages)
+- cytoolz via the [Z0Z_tools](https://github.com/hunterhogan/Z0Z_tools) package (until it finds a forever home)
+- more_itertools
+- `astToolKit`
+- `pytest`
+
+### Probably won't need
+
+- `analyzeAudio`
+- `gmpy2`
+- `numba`
+- `platformdirs`
+- `sympy`
+- `torch-einops-kit`
+
+### Not using `PyTorch` for "business" logic
+
+- But, I must have `torch` compatibility.
+- At a minimum, a transformation to and from `torch` that the user must call.
+- `astToolkit` easily creates real `torch` APIs and identifiers, however, for the `windowingFunctions` module in `windowingFunctionsTensor`.
+
+### Not using librosa
+
+- Dependency bloated.
+- Slow.
+- Less precise than I want.
+- I generally dislike the API and identifiers.
+
+### Disfavored packages
+
+- `pandas`
+
+### More vectorization
+
+- Few or no `for` loops.
+- Few or no `for` object comprehensions.
+
+## Installation
+
+```bash
+pip install hunterHearsPy
+```
+
+## My recovery
+
+[![Static Badge](https://img.shields.io/badge/2011_August-Homeless_since-blue?style=flat)](https://HunterThinks.com/support)
+[![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UC3Gx7kz61009NbhpRtPP7tw)](https://www.youtube.com/@HunterHogan)
+
+[![CC-BY-NC-4.0](https://raw.githubusercontent.com/hunterhogan/hunterHearsPy/refs/heads/main/.github/CC-BY-NC-4.0.png)](https://creativecommons.org/licenses/by-nc/4.0/)

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

@@ -1,6 +1,6 @@
 [project]
 name = "hunterHearsPy"
-version = "1.0.3"
+version = "1.1.0"
 description = "Audio processing."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,6 +17,9 @@ classifiers = [
   "Natural Language :: English",
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
   "Typing :: Typed",
 ]
@@ -27,6 +30,8 @@ dependencies = [
   "scipy",
   "soundfile>=0.14.0",
   "tqdm",
+  "typing-extensions>=4.0.0",
+  "Z0Z_tools>=2.1.0",
 ]
 optional-dependencies = { torch = ["torch"] }
 
@@ -39,8 +44,13 @@ Issues = "https://github.com/hunterhogan/hunterHearsPy/issues"
 Repository = "https://github.com/hunterhogan/hunterHearsPy.git"
 
 [dependency-groups]
-dev = ["astToolkit", "pytest-cov", "scipy-stubs", "types-resampy"]
-pytorch = ["torch==2.10.0", "torchaudio==2.10.0"]
+dev = [
+    "astToolkit",
+    "pytest-cov",
+    "scipy-stubs",
+    "types-resampy",
+]
+pytorch = ["torch==2.10.0"]
 testing = ["pytest", "pytest-mock", "pytest-xdist", "torch"]
 
 [build-system]
@@ -54,7 +64,7 @@ run = { branch = true, concurrency = ["multiprocessing"], data_file = "tests/cov
 ], parallel = true, source = ["."] }
 
 [tool.pytest]
-addopts = ["--color=auto", "-n 4"]
+addopts = ["--color=auto", "-n 4", "--tb=line"]
 log_auto_indent = "On"
 pythonpath = ["src"]
 testpaths = ["tests"]
@@ -68,10 +78,19 @@ build-backend = { module-name = "hunterHearsPy", module-root = "src" }
 default-groups = ["dev", "testing"]
 
 [[tool.uv.index]]
+# NOTE I use this to install torch+cuda on my computer that doesn't have cuda. 2026-06-13
+# `uv sync --group pytorch` OR `uv sync --all-groups` will trigger the following.
+# dependency-groups.pytorch amends the dependencies: `torch`, limitation `==2.10.0`, group = "pytorch".
+# At this point, the default source, pypi, is the highest priority on the `torch` sources list. (LIFO)
+# tool.uv.sources sees '`torch`, group = "pytorch"' so pushes "indexPytorch" on top the `torch` sources list.
+# tool.uv.index translates "indexPytorch" to the url of a package index.
+# uv queries the package index for all `torch` that match all limitations.
+# If the package index returns any matches, uv will install the "best" match.
+# Because the package index only has cuda 12.8 versions, uv installs torch+cu128.
+# I picked torch==2.10.0 + cuda 12.8 because that is the pre-installed package on Google Colab T4.
 explicit = true
 name = "indexPytorch"
 url = "https://download.pytorch.org/whl/cu128"
 
 [tool.uv.sources]
-torch = { index = "indexPytorch", group = "pytorch" }
-torchaudio = { index = "indexPytorch", group = "pytorch" }
+torch = { group = "pytorch", index = "indexPytorch" }

hunterhearspy-1.1.0/src/hunterHearsPy/__init__.py

@@ -0,0 +1,51 @@
+# ruff: noqa: D104
+from __future__ import annotations
+
+from hunterHearsPy.theTypes import (
+	ArraySpectrograms as ArraySpectrograms, ArrayWaveforms as ArrayWaveforms, ArrayWaveformsFloating as ArrayWaveformsFloating,
+	ArrayWaveformsShape as ArrayWaveformsShape, callableReturnsNDArray as callableReturnsNDArray, E733TH4X0R as E733TH4X0R,
+	FileDescriptorOrPath as FileDescriptorOrPath, NormalizationReverter as NormalizationReverter, OptionsAlign as OptionsAlign,
+	Parameters_stft as Parameters_stft, ParametersShortTimeFFT as ParametersShortTimeFFT, Spectrogram as Spectrogram,
+	SpectrogramDtype as SpectrogramDtype, Waveform as Waveform, WaveformAxes as WaveformAxes, WaveformDtype as WaveformDtype,
+	WaveformFloating as WaveformFloating, WaveformFloatingDtype as WaveformFloatingDtype, WaveformMetadata as WaveformMetadata,
+	WindowingFunction as WindowingFunction, WindowingFunctionDtype as WindowingFunctionDtype, 个 as 个, 形floating as 形floating,
+	形ndarray as 形ndarray, 形Shape as 形Shape)
+
+# isort: split
+from hunterHearsPy.windowingFunctions import cosineWings as cosineWings, equalPower as equalPower, halfsine as halfsine, tukey as tukey
+
+# 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)
+
+# isort: split
+from hunterHearsPy.theSSOT import getAxis as getAxis, setting as setting
+
+# isort: split
+from hunterHearsPy.dataBaskets import Translator as Translator
+
+# isort: split
+from hunterHearsPy._resample import resampleWaveform as resampleWaveform
+from hunterHearsPy.amplitude import (
+	amplitudeIntegerToFloating as amplitudeIntegerToFloating, amplitudeToSoundfile as amplitudeToSoundfile,
+	normalizeArrayWaveforms as normalizeArrayWaveforms, normalizeWaveform as normalizeWaveform)
+
+# isort: split
+from hunterHearsPy._fft import stft as stft, waveformSpectrogramWaveform as waveformSpectrogramWaveform
+
+# isort: split
+from hunterHearsPy._io import readAudioFile as readAudioFile, spectrogramToWAV as spectrogramToWAV, writeWAV as writeWAV
+
+# isort: split
+from hunterHearsPy.clippingArrays import applyHardLimit as applyHardLimit, applyHardLimitComplexValued as applyHardLimitComplexValued
+
+# isort: split
+from hunterHearsPy.autoRevert import moveToAxisOfOperation as moveToAxisOfOperation
+
+# isort: split
+from hunterHearsPy._arrays import (
+	getWaveformMetadata as getWaveformMetadata, loadSpectrograms as loadSpectrograms, loadWaveforms as loadWaveforms)

hunterhearspy-1.1.0/src/hunterHearsPy/_arrays.py

@@ -0,0 +1,109 @@
+# ruff: noqa: DOC201
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from hunterHearsPy import ArrayWaveformsShape, getAxis, readAudioFile, setting, stft, WaveformAxes, WaveformMetadata
+from hunterMakesPy.parseParameters import defineConcurrencyLimit
+from tqdm.auto import tqdm
+from typing import TYPE_CHECKING
+import numpy
+import sys
+
+if TYPE_CHECKING:
+	from collections.abc import Sequence
+	from hunterHearsPy import ArraySpectrograms, ArrayWaveforms, FileDescriptorOrPath, OptionsAlign, Waveform
+	from numpy.typing import DTypeLike
+	from soundfile import dtype_str as Options_dtype_str
+	from typing import Any
+
+def getWaveformMetadata(
+	listPathFilenames: Sequence[FileDescriptorOrPath], sampleRate: float, align: OptionsAlign
+) -> tuple[dict[int, WaveformMetadata], dict[str, WaveformAxes]]:
+	"""Retrieve metadata for a collection of audio waveform files."""
+	# ======== Initialize ==========================================================
+
+	axis: dict[str, WaveformAxes] = getAxis()
+	channelMaximum: int = 0
+	dictionaryWaveformMetadata: dict[int, WaveformMetadata] = {}
+	lengthMaximum: int = 0
+
+	# ======== Populate ===========================================================
+
+	if len(listPathFilenames) == 0:
+		message: str = f'I received `{len(listPathFilenames) = }`, so `arrayWaveforms` will have zero-sized axes.'
+		sys.stderr.write(message + '\n')
+
+	for index, pathFilename in enumerate(tqdm(listPathFilenames, desc='Preparing combined array', leave=False)):
+		channels, lengthWaveform = readAudioFile(pathFilename, sampleRate).shape
+		dictionaryWaveformMetadata[index] = WaveformMetadata(
+			channels=channels, lengthWaveform=lengthWaveform, pathFilename=pathFilename, samplesStart=0, samplesStop=0
+		)
+		channelMaximum = max(channelMaximum, channels)
+		lengthMaximum = max(lengthMaximum, lengthWaveform)
+
+	axis['channel'] = WaveformAxes(number=axis['channel'].number, size=channelMaximum)
+	axis['indexing'] = WaveformAxes(number=axis['indexing'].number, size=len(listPathFilenames))
+	axis['time'] = WaveformAxes(number=axis['time'].number, size=lengthMaximum)
+
+	# ======== Calculate ===========================================================
+
+	multiplicandSamplesStart: float = max((align == 'center') / 2, align == 'start')
+
+	for metadata in dictionaryWaveformMetadata.values():
+		samplesPadding: int = axis['time'].size - metadata['lengthWaveform']
+		# TODO document that if `samplesPadding` is odd, the extra pad-sample is added to samplesStop.
+		metadata['samplesStart'] = int(samplesPadding * multiplicandSamplesStart)
+		metadata['samplesStop'] = metadata['samplesStart'] + metadata['lengthWaveform']
+
+	return dictionaryWaveformMetadata, axis
+
+def loadWaveforms(listPathFilenames: Sequence[FileDescriptorOrPath], *, CPUlimit: bool | float | int | None = None, **keywordArguments: Any) -> ArrayWaveforms:
+	"""Load a list of audio files into a single stacked NumPy array."""
+	align: OptionsAlign = keywordArguments.get('align', setting.align)
+	dtype: DTypeLike = keywordArguments.get('dtype', setting.dtypeWaveform)
+	dtype_str: Options_dtype_str = keywordArguments.get('dtype_str', setting.dtype_str)
+	sampleRateDesired: float = keywordArguments.get('sampleRateDesired', setting.sampleRate)
+
+	max_workers: int = defineConcurrencyLimit(limit=CPUlimit)
+
+	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRateDesired, align)
+
+	arrayWaveforms: ArrayWaveforms = numpy.zeros(ArrayWaveformsShape(*(entry.size for entry in sorted(axis.values()))), dtype)
+	# TODO frustrating! ^^^ in the line above, the axis order is entirely based on the SSOT, `axis`,
+	# but IMMEDIATELY below, the axis order is hardcoded!
+
+	def workhorse(index: int, metadata: WaveformMetadata) -> None:
+		arrayWaveforms[:, metadata['samplesStart'] : metadata['samplesStop'], index] = readAudioFile(
+			metadata['pathFilename'], sampleRateDesired, dtype_str
+		).astype(dtype, copy=False)
+
+	with ThreadPoolExecutor(max_workers=max_workers) as threadManager:
+		tuple(tqdm(threadManager.map(workhorse, dictionaryWaveformMetadata, dictionaryWaveformMetadata.values()), total=len(dictionaryWaveformMetadata)))
+
+	return arrayWaveforms
+
+def loadSpectrograms(listPathFilenames: Sequence[FileDescriptorOrPath], *, CPUlimit: bool | float | int | None = None, **keywordArguments: Any) -> tuple[ArraySpectrograms, dict[int, WaveformMetadata]]:
+	"""Load spectrograms from a list of audio files."""
+	align: OptionsAlign = keywordArguments.get('align', setting.align)
+	dtype: DTypeLike = keywordArguments.get('dtype', setting.dtypeSpectrogram)
+	dtype_str: Options_dtype_str = keywordArguments.get('dtype_str', setting.dtype_str)
+	dtypeWaveform: DTypeLike = keywordArguments.get('dtypeWaveform', setting.dtypeWaveform)
+	sampleRateDesired: float = keywordArguments.get('sampleRateDesired', setting.sampleRate)
+
+	max_workers: int = defineConcurrencyLimit(limit=CPUlimit)
+
+	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRateDesired, align)
+
+	waveformZeros: Waveform = numpy.zeros((axis['channel'].size, axis['time'].size), dtypeWaveform)
+	arraySpectrograms: ArraySpectrograms = numpy.zeros(shape=(*stft(waveformZeros, **keywordArguments).shape, len(dictionaryWaveformMetadata)), dtype=dtype)
+
+	def workhorse(index: int, metadata: WaveformMetadata) -> None:
+		waveform: Waveform = waveformZeros.copy()
+		waveform[:, metadata['samplesStart'] : metadata['samplesStop']] = readAudioFile(metadata['pathFilename'], sampleRateDesired, dtype_str).astype(dtypeWaveform, copy=False)
+		# TODO Think about numpy.pad.mode waveform = numpy.pad(waveform, ((0, 0), (metadata['samplesStart'], waveform.shape[1] - metadata['samplesStop'])), mode=mode)
+		arraySpectrograms[..., index] = stft(waveform, **keywordArguments)
+
+	with ThreadPoolExecutor(max_workers=max_workers) as threadManager:
+		tuple(tqdm(threadManager.map(workhorse, dictionaryWaveformMetadata.keys(), dictionaryWaveformMetadata.values()), desc='Loading spectrograms', total=len(dictionaryWaveformMetadata)))
+
+	return arraySpectrograms, dictionaryWaveformMetadata

hunterhearspy-1.1.0/src/hunterHearsPy/_fft.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from humpy_cytoolz.dicttoolz import keyfilter, merge
+from hunterHearsPy import amplitudeIntegerToFloating, Parameters_stft, ParametersShortTimeFFT, setting, Translator
+from scipy.signal import ShortTimeFFT
+from typing import overload, TYPE_CHECKING
+from typing_extensions import Unpack
+import numpy
+
+if TYPE_CHECKING:
+	from collections.abc import Callable
+	from hunterHearsPy import ArraySpectrograms, ArrayWaveforms, ArrayWaveformsFloating, Spectrogram, Waveform, WaveformFloating
+	from pathlib import PurePath
+	from scipy.signal._short_time_fft import _PadType
+
+@overload  # stft 1 ndarray
+def stft(arrayTarget: Waveform, *, lengthWaveform: int = 0, indexingAxis: int = -1, **keywordArguments: Unpack[Parameters_stft]) -> Spectrogram: ...
+@overload  # stft many ndarray
+def stft(arrayTarget: ArrayWaveforms, *, lengthWaveform: int = 0, indexingAxis: int = -1, **keywordArguments: Unpack[Parameters_stft]) -> ArraySpectrograms: ...
+@overload  # istft 1 ndarray
+def stft(arrayTarget: Spectrogram, *, lengthWaveform: int, indexingAxis: int = -1, **keywordArguments: Unpack[Parameters_stft]) -> Waveform: ...
+@overload  # istft many ndarray
+def stft(arrayTarget: ArraySpectrograms, *, lengthWaveform: int, indexingAxis: int = -1, **keywordArguments: Unpack[Parameters_stft]) -> ArrayWaveforms: ...
+def stft(arrayTarget: Waveform | ArrayWaveforms | Spectrogram | ArraySpectrograms
+		, *
+		, lengthWaveform: int = 0
+		, indexingAxis: int = -1
+		, **keywordArguments: Unpack[Parameters_stft]
+	) -> Waveform | ArrayWaveforms | Spectrogram | ArraySpectrograms:
+	if numpy.issubdtype(arrayTarget.dtype, numpy.integer):
+		if arrayTarget.ndim == 3:
+			arrayFloating: ArrayWaveformsFloating = amplitudeIntegerToFloating(arrayTarget)
+		if arrayTarget.ndim == 2:
+			arrayFloating: WaveformFloating = amplitudeIntegerToFloating(arrayTarget)
+	else:
+		arrayFloating = arrayTarget
+		if numpy.issubdtype(arrayTarget.dtype, numpy.complexfloating) and (lengthWaveform < 1):
+			from hunterHearsPy._io import saveOnError  # noqa: PLC0415
+			pathFilename: PurePath = saveOnError(arrayTarget)
+			message: str = (
+				"I did not receive `lengthWaveform`, so I could not perform the inverse STFT. "
+				"I saved `arrayTarget` to a file in this computer's temporary directory so you might recover the data. "
+				f"{arrayTarget.shape = }, {arrayTarget.dtype = }\n"
+				f"{pathFilename = }"
+			)
+			raise ValueError(message)
+
+	parametersShortTimeFFT = Translator(**ParametersShortTimeFFT(keyfilter(setting.ShortTimeFFT.keys().__contains__, merge(setting.ShortTimeFFT, keywordArguments))))  # pyright: ignore[reportArgumentType] # ty:ignore[invalid-argument-type]
+
+	padding: _PadType = keywordArguments.get('padding', setting.padding)
+
+	workhorseSTFT: ShortTimeFFT = ShortTimeFFT(**parametersShortTimeFFT.e733T)
+
+	def mushroom(waveform: WaveformFloating) -> Spectrogram:
+		return workhorseSTFT.stft(x=waveform, padding=padding)
+
+	def turtleShell(spectrogram: Spectrogram, lengthWaveform: int) -> WaveformFloating:
+		return workhorseSTFT.istft(S=spectrogram, k1=lengthWaveform)
+
+	if arrayFloating.ndim == 2:
+		arrayFloating: ArrayWaveformsFloating = numpy.expand_dims(arrayFloating, indexingAxis)
+	elif (arrayTarget.ndim == 3) and (numpy.issubdtype(arrayTarget.dtype, numpy.complexfloating)):
+		spectrogram: Spectrogram = arrayTarget
+		return turtleShell(spectrogram, lengthWaveform)
+
+	if (arrayFloating.ndim == 3) and (numpy.issubdtype(arrayFloating.dtype, numpy.floating)):
+		arrayWaveforms: ArrayWaveformsFloating = arrayFloating
+		arrayWaveforms = numpy.moveaxis(arrayWaveforms, indexingAxis, -1)
+		index = 0
+		arraySpectrograms: ArraySpectrograms = numpy.tile(mushroom(arrayWaveforms[..., index])[..., numpy.newaxis], arrayWaveforms.shape[-1])
+		for index in range(1, arrayWaveforms.shape[-1]):
+			arraySpectrograms[..., index] = mushroom(arrayWaveforms[..., index])
+		arraySpectrograms = numpy.moveaxis(arraySpectrograms, -1, indexingAxis)
+		if arraySpectrograms.shape[indexingAxis] == 1:
+			arraySpectrograms = numpy.squeeze(arraySpectrograms, indexingAxis)
+		return arraySpectrograms
+
+	elif (arrayTarget.ndim == 4) and (numpy.issubdtype(arrayTarget.dtype, numpy.complexfloating)):
+		arrayTARGET: ArraySpectrograms = arrayTarget
+		arrayTARGET = numpy.moveaxis(arrayTARGET, indexingAxis, -1)
+		index = 0
+		arrayTransformed: ArrayWaveforms = numpy.tile(turtleShell(arrayTARGET[..., index], lengthWaveform)[..., numpy.newaxis], arrayTARGET.shape[-1])
+		for index in range(1, arrayTARGET.shape[-1]):
+			arrayTransformed[..., index] = turtleShell(arrayTARGET[..., index], lengthWaveform)
+		return numpy.moveaxis(arrayTransformed, -1, indexingAxis)
+	else:
+		return arrayTarget
+
+def waveformSpectrogramWaveform(callableNeedsSpectrogram: Callable[[Spectrogram], Spectrogram]) -> Callable[[Waveform], Waveform]:
+	"""Decorate a spectrogram-processing callable to accept and return waveforms.
+
+	You can use this function as a decorator when you have a function that transforms `Spectrogram`
+	[1] data and you want a version that operates directly on `Waveform` [2] data. The returned
+	function applies `stft` to convert the input `Waveform` [2] to a `Spectrogram` [1], calls
+	`callableNeedsSpectrogram`, then applies inverse `stft` to convert the result back to a `Waveform`
+	[2] of the original length.
+
+	Parameters
+	----------
+	callableNeedsSpectrogram : Callable[[Spectrogram], Spectrogram]
+		A function that accepts and returns a `Spectrogram` [1].
+
+	Returns
+	-------
+	stft_istft : Callable[[Waveform], Waveform]
+		A function that accepts a `Waveform` [2], converts it to a `Spectrogram` [1], applies
+		`callableNeedsSpectrogram`, and returns the reconstructed `Waveform` [2] at the original
+		length.
+
+	Time Axis Assumption
+	--------------------
+	The inner function `stft_istft` assumes the time axis of the input `Waveform` [2] is the last axis
+	(`-1`). This matches the `(channels, samples)` shape convention.
+
+	References
+	----------
+	[1] `Spectrogram`
+
+	[2] `Waveform`
+
+	"""
+	def stft_istft(waveform: Waveform) -> Waveform:
+		axisTime = -1
+		arrayTarget = stft(waveform)
+		spectrogram = callableNeedsSpectrogram(arrayTarget)
+		return stft(spectrogram, lengthWaveform=waveform.shape[axisTime])
+	return stft_istft