hunterHearsPy 1.1.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,12 +1,16 @@
 Metadata-Version: 2.4
 Name: hunterHearsPy
-Version: 1.1.0
+Version: 1.3.0
 Summary: Audio processing.
-Keywords: 
-Author: Hunter Hogan
 Author-email: Hunter Hogan <HunterHogan@pm.me>
+Maintainer-email: Hunter Hogan <HunterHogan@pm.me>
 License-Expression: CC-BY-NC-4.0
-License-File: LICENSE
+Project-URL: Context7, https://context7.com/hunterhogan/hunterhearspy
+Project-URL: Donate, https://www.patreon.com/integrated
+Project-URL: Download, https://pypi.org/project/hunterHearsPy
+Project-URL: Homepage, https://github.com/hunterhogan/hunterHearsPy
+Project-URL: Issues, https://github.com/hunterhogan/hunterHearsPy/issues
+Project-URL: Repository, https://github.com/hunterhogan/hunterHearsPy.git
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -19,26 +23,25 @@ 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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Z0Z_tools>=2.1.0
+Requires-Dist: hunterMakesPy>=0.7.0
 Requires-Dist: numpy
 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>
-Requires-Python: >=3.10
-Project-URL: Context7, https://context7.com/hunterhogan/hunterhearspy
-Project-URL: Donate, https://www.patreon.com/integrated
-Project-URL: Download, https://pypi.org/project/hunterHearsPy
-Project-URL: Homepage, https://github.com/hunterhogan/hunterHearsPy
-Project-URL: Issues, https://github.com/hunterhogan/hunterHearsPy/issues
-Project-URL: Repository, https://github.com/hunterhogan/hunterHearsPy.git
+Provides-Extra: testing
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-mock; extra == "testing"
+Requires-Dist: pytest-xdist; extra == "testing"
+Requires-Dist: torch; extra == "testing"
 Provides-Extra: torch
-Description-Content-Type: text/markdown
+Requires-Dist: torch; extra == "torch"
+Dynamic: license-file
 
 # hunterHearsPy
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "hunterHearsPy"
-version = "1.1.0"
+version = "1.3.0"
 description = "Audio processing."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
+  "Z0Z_tools>=2.1.0",
   "hunterMakesPy>=0.7.0",
   "numpy",
   "resampy",
@@ -31,9 +32,13 @@ dependencies = [
   "soundfile>=0.14.0",
   "tqdm",
   "typing-extensions>=4.0.0",
-  "Z0Z_tools>=2.1.0",
 ]
-optional-dependencies = { torch = ["torch"] }
+optional-dependencies = { testing = [
+  "pytest",
+  "pytest-mock",
+  "pytest-xdist",
+  "torch"
+], torch = ["torch"] }
 
 [project.urls]
 Context7 = "https://context7.com/hunterhogan/hunterhearspy"
@@ -44,18 +49,12 @@ Issues = "https://github.com/hunterhogan/hunterHearsPy/issues"
 Repository = "https://github.com/hunterhogan/hunterHearsPy.git"
 
 [dependency-groups]
-dev = [
-    "astToolkit",
-    "pytest-cov",
-    "scipy-stubs",
-    "types-resampy",
-]
+dev = ["astToolkit", "pytest-cov", "scipy-stubs", "types-resampy"]
 pytorch = ["torch==2.10.0"]
-testing = ["pytest", "pytest-mock", "pytest-xdist", "torch"]
 
 [build-system]
-requires = ["uv_build>=0.11.8,<0.12.0"]
-build-backend = "uv_build"
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
 
 [tool.coverage]
 report = { exclude_lines = ["if TYPE_CHECKING:", "if __name__ == \"__main__\":"], ignore_errors = false }
@@ -64,7 +63,7 @@ run = { branch = true, concurrency = ["multiprocessing"], data_file = "tests/cov
 ], parallel = true, source = ["."] }
 
 [tool.pytest]
-addopts = ["--color=auto", "-n 4", "--tb=line"]
+addopts = ["--color=auto", "--tb=line", "-n 4"]
 log_auto_indent = "On"
 pythonpath = ["src"]
 testpaths = ["tests"]
@@ -75,7 +74,7 @@ pathFilenameCitationSSOT = "citations/CITATION.cff"
 
 [tool.uv]
 build-backend = { module-name = "hunterHearsPy", module-root = "src" }
-default-groups = ["dev", "testing"]
+default-groups = ["dev"]
 
 [[tool.uv.index]]
 # NOTE I use this to install torch+cuda on my computer that doesn't have cuda. 2026-06-13

hunterhearspy-1.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

{hunterhearspy-1.1.0 → hunterhearspy-1.3.0}/src/hunterHearsPy/__init__.py

@@ -1,15 +1,7 @@
 # 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)
+from hunterHearsPy import theTypes as theTypes
 
 # isort: split
 from hunterHearsPy.windowingFunctions import cosineWings as cosineWings, equalPower as equalPower, halfsine as halfsine, tukey as tukey
@@ -23,10 +15,12 @@ with suppress(ModuleNotFoundError):  # noqa: RUF067
 		tukeyTensor as tukeyTensor)
 
 # isort: split
-from hunterHearsPy.theSSOT import getAxis as getAxis, setting as setting
+from hunterHearsPy.dataBaskets import (
+	AxisMetadata as AxisMetadata, SpectrogramsAndMetadata as SpectrogramsAndMetadata, WaveformMetadata as WaveformMetadata,
+	WaveformsAndMetadata as WaveformsAndMetadata)
 
 # isort: split
-from hunterHearsPy.dataBaskets import Translator as Translator
+from hunterHearsPy.theSSOT import getAxis as getAxis, setting as setting
 
 # isort: split
 from hunterHearsPy._resample import resampleWaveform as resampleWaveform
@@ -34,6 +28,9 @@ from hunterHearsPy.amplitude import (
 	amplitudeIntegerToFloating as amplitudeIntegerToFloating, amplitudeToSoundfile as amplitudeToSoundfile,
 	normalizeArrayWaveforms as normalizeArrayWaveforms, normalizeWaveform as normalizeWaveform)
 
+# isort: split
+from hunterHearsPy.autoRevert import moveToAxisOfOperation as moveToAxisOfOperation
+
 # isort: split
 from hunterHearsPy._fft import stft as stft, waveformSpectrogramWaveform as waveformSpectrogramWaveform
 
@@ -43,9 +40,6 @@ from hunterHearsPy._io import readAudioFile as readAudioFile, spectrogramToWAV a
 # 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.3.0/src/hunterHearsPy/_arrays.py

@@ -0,0 +1,239 @@
+# ruff: noqa: DOC201
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from hunterHearsPy import (
+	AxisMetadata, getAxis, readAudioFile, setting, SpectrogramsAndMetadata, stft, WaveformMetadata, WaveformsAndMetadata)
+from hunterMakesPy.parseParameters import defineConcurrencyLimit
+from tqdm.auto import tqdm
+from typing import NamedTuple, TYPE_CHECKING
+from typing_extensions import Unpack
+import numpy
+import sys
+
+if TYPE_CHECKING:
+	from collections.abc import Sequence
+	from hunterHearsPy.theTypes import (
+		ArraySpectrograms, ArrayWaveforms, FileDescriptorOrPath, OptionsAlign, Parameters_loadSpectrograms, Parameters_loadWaveforms, Waveform)
+	from numpy.lib._arraypad_impl import _ModeKind
+	from numpy.typing import DTypeLike
+	from soundfile import dtype_str as Options_dtype_str
+
+#======== Idiosyncratic classes tell type checkers about the shape of arrays ======================
+
+class Axes2(NamedTuple):
+	a0: int
+	a1: int
+
+class Axes3(NamedTuple):
+	a0: int
+	a1: int
+	a2: int
+
+class Axes4(NamedTuple):
+	a0: int
+	a1: int
+	a2: int
+	a3: int
+
+def getWaveformMetadata(
+	listPathFilenames: Sequence[FileDescriptorOrPath], sampleRate: float, align: OptionsAlign
+) -> tuple[dict[int, WaveformMetadata], dict[str, AxisMetadata]]:
+	"""Retrieve metadata for a collection of audio waveform files."""
+	#============== Initialize ==========================================================
+
+	axis: dict[str, AxisMetadata] = 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'] = AxisMetadata(number=axis['channel'].number, size=channelMaximum)
+	axis['indexing'] = AxisMetadata(number=axis['indexing'].number, size=len(listPathFilenames))
+	axis['time'] = AxisMetadata(number=axis['time'].number, size=lengthMaximum)
+
+	#============== Calculate ===========================================================
+
+	multiplicandSamplesStart: float = max((align == 'center') / 2, align == 'stop')
+
+	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: Unpack[Parameters_loadWaveforms]
+) -> WaveformsAndMetadata:
+	"""Load a list of audio files into a single stacked NumPy array."""
+	#============== Initialize ==========================================================
+
+	align: OptionsAlign = keywordArguments.get('align', setting.align)
+	dtypeWaveform: DTypeLike = keywordArguments.get('dtypeWaveform', setting.dtypeWaveform)
+	dtype_str: Options_dtype_str = keywordArguments.get('dtype_str', setting.dtype_str)
+	sampleRate: float = keywordArguments.get('sampleRate', setting.sampleRate)
+
+	max_workers: int = defineConcurrencyLimit(limit=CPUlimit)
+
+	#============== Allocate memory ==========================================================
+
+	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRate, align)
+	arrayWaveforms: ArrayWaveforms = numpy.zeros(Axes3(*(entry.size for entry in sorted(axis.values()))), dtypeWaveform)
+
+	#============== Concurrent loading ==========================================================
+
+	# TODO the axis order is hardcoded.
+	def workhorse(index: int, metadata: WaveformMetadata) -> None:
+		arrayWaveforms[:, metadata['samplesStart'] : metadata['samplesStop'], index] = readAudioFile(
+			metadata['pathFilename'], sampleRate, dtype_str
+		).astype(dtypeWaveform, copy=False)
+
+	with ThreadPoolExecutor(max_workers=max_workers) as threadManager:
+		tuple(tqdm(threadManager.map(workhorse, dictionaryWaveformMetadata, dictionaryWaveformMetadata.values())
+				, desc='Loading waveforms.'
+				, total=len(dictionaryWaveformMetadata)
+		))
+
+	return WaveformsAndMetadata(array=arrayWaveforms, metadata=dictionaryWaveformMetadata)
+
+def loadSpectrograms(
+	listPathFilenames: Sequence[FileDescriptorOrPath], *, CPUlimit: bool | float | int | None = None, **keywordArguments: Unpack[Parameters_loadSpectrograms]
+) -> SpectrogramsAndMetadata:
+	"""Load spectrograms from a list of audio files."""
+	#============== Initialize ==========================================================
+
+	align: OptionsAlign = keywordArguments.get('align', setting.align)
+	align_pad_mode: _ModeKind = keywordArguments.get('align_pad_mode', setting.align_pad_mode)
+	dtypeSpectrogram: DTypeLike = keywordArguments.get('dtypeSpectrogram', setting.dtypeSpectrogram)
+	dtype_str: Options_dtype_str = keywordArguments.get('dtype_str', setting.dtype_str)
+	dtypeWaveform: DTypeLike = keywordArguments.get('dtypeWaveform', setting.dtypeWaveform)
+	sampleRate: float = keywordArguments.get('sampleRate', setting.sampleRate)
+
+	max_workers: int = defineConcurrencyLimit(limit=CPUlimit)
+
+	#============== Allocate memory ==========================================================
+
+	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRate, align)
+
+	waveformShape = Axes2(*(entry.size for entry in sorted((axis['channel'], axis['time']))))
+	axisSpectrogram = AxisMetadata(setting.axisSpectrogramIndexing, len(dictionaryWaveformMetadata))
+	arraySpectrogramsShape: list[int] = list(stft(numpy.zeros(waveformShape, dtypeWaveform), **keywordArguments).shape)
+	arraySpectrogramsShape.insert(axisSpectrogram.number, axisSpectrogram.size)
+
+	arraySpectrograms: ArraySpectrograms = numpy.zeros(Axes4(*arraySpectrogramsShape), dtypeSpectrogram)
+
+	#============== Concurrent loading ==========================================================
+
+	def workhorse(index: int, metadata: WaveformMetadata) -> None:
+		# TODO make tests that can check if this works.
+
+		pad_width: dict[int, tuple[int, int]] = {
+			axis['channel'].number: (0, 0)
+			, axis['time'].number: (metadata['samplesStart'], axis['time'].size - metadata['samplesStop'])
+		}
+
+		# python3.10: TypeError: `pad_width` must be of integral type.
+		# f.m.l.
+		# TODO in 2026 October: drop Py3.10 and this crap. I just want semantic, dynamic access to the data! It's the year 2026, ffs!
+
+		pad_widthIntegralType: tuple[tuple[int, int], ...] = tuple(dict(sorted(pad_width.items())).values())
+
+		# TODO axisSpectrogram.number is hardcoded here. grr!
+		arraySpectrograms[..., index] = stft(
+			numpy.pad(
+				readAudioFile(metadata['pathFilename'], sampleRate, dtype_str).astype(dtypeWaveform, copy=False)
+				, pad_widthIntegralType
+				, align_pad_mode
+			)
+			, **keywordArguments
+		)
+
+		if False:  # This fails the current tests.
+			arraySpectrogramsShape[axisSpectrogram.number] = index
+			indices = numpy.indices(tuple(arraySpectrogramsShape))
+			numpy.put_along_axis(
+				arraySpectrograms,
+				indices=indices,
+				values=stft(
+					numpy.pad(
+						readAudioFile(metadata['pathFilename'], sampleRate, dtype_str).astype(dtypeWaveform, copy=False),
+						pad_widthIntegralType,
+						mode=align_pad_mode,
+					),
+					**keywordArguments,
+				),
+				axis=axisSpectrogram.number,
+			)
+
+	with ThreadPoolExecutor(max_workers=max_workers) as threadManager:
+		tuple(tqdm(threadManager.map(workhorse, dictionaryWaveformMetadata.keys(), dictionaryWaveformMetadata.values())
+				, desc='Loading spectrograms.'
+				, total=axisSpectrogram.size
+		))
+
+	return SpectrogramsAndMetadata(arraySpectrograms, dictionaryWaveformMetadata)
+
+def BACKUPloadSpectrograms(
+	listPathFilenames: Sequence[FileDescriptorOrPath], *, CPUlimit: bool | float | int | None = None, **keywordArguments: Unpack[Parameters_loadSpectrograms]
+) -> tuple[ArraySpectrograms, dict[int, WaveformMetadata]]:
+	"""Load spectrograms from a list of audio files."""
+	#============== Initialize ==========================================================
+
+	align: OptionsAlign = keywordArguments.get('align', setting.align)
+	dtypeSpectrogram: DTypeLike = keywordArguments.get('dtypeSpectrogram', setting.dtypeSpectrogram)
+	dtype_str: Options_dtype_str = keywordArguments.get('dtype_str', setting.dtype_str)
+	dtypeWaveform: DTypeLike = keywordArguments.get('dtypeWaveform', setting.dtypeWaveform)
+	sampleRate: float = keywordArguments.get('sampleRate', setting.sampleRate)
+
+	max_workers: int = defineConcurrencyLimit(limit=CPUlimit)
+
+	#============== Allocate memory ==========================================================
+
+	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRate, align)
+
+	waveformShape = Axes2(*(entry.size for entry in sorted((axis['channel'], axis['time']))))
+	waveformZeros: Waveform = numpy.zeros(waveformShape, dtypeWaveform)
+
+	axisSpectrogram = AxisMetadata(setting.axisSpectrogramIndexing, len(dictionaryWaveformMetadata))
+
+	arraySpectrogramsShape: list[int] = list(stft(waveformZeros, **keywordArguments).shape)
+	arraySpectrogramsShape.insert(axisSpectrogram.number, axisSpectrogram.size)
+	arraySpectrograms: ArraySpectrograms = numpy.zeros(Axes4(*arraySpectrogramsShape), dtypeSpectrogram)
+
+	#============== Concurrent loading ==========================================================
+
+	def workhorse(index: int, metadata: WaveformMetadata) -> None:
+		waveform: Waveform = waveformZeros.copy()
+		waveform[:, metadata['samplesStart'] : metadata['samplesStop']] = readAudioFile(
+			metadata['pathFilename'], sampleRate, dtype_str
+		).astype(dtypeWaveform, copy=False)
+		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=axisSpectrogram.size,
+			)
+		)
+
+	return arraySpectrograms, dictionaryWaveformMetadata

hunterhearspy-1.3.0/src/hunterHearsPy/_fft.py

@@ -0,0 +1,145 @@
+# pyright: reportArgumentType=false
+# pyright: reportAssignmentType=false
+# ty:ignore[invalid-argument-type]
+# ty:ignore[invalid-assignment]
+from __future__ import annotations
+
+from humpy_cytoolz.dicttoolz import keyfilter, merge
+from hunterHearsPy import amplitudeIntegerToFloating, getAxis, setting
+from hunterHearsPy.dataBaskets import ParametersShortTimeFFT
+from numpy import complexfloating, floating, integer
+from scipy.signal import ShortTimeFFT
+from typing import overload, TYPE_CHECKING
+from typing_extensions import Unpack
+import dataclasses
+import numpy
+
+if TYPE_CHECKING:
+	from collections.abc import Callable
+	from hunterHearsPy.theTypes import (
+		ArraySpectrograms, ArrayWaveforms, ArrayWaveformsFloating, Parameters_stft, 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:
+	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)
+
+	#============== Initialize ==========================================================
+
+	parametersShortTimeFFT = ParametersShortTimeFFT(**keyfilter(dataclasses.asdict(setting.ShortTimeFFT).keys().__contains__, merge(dataclasses.asdict(setting.ShortTimeFFT), keywordArguments)))
+	padding: _PadType = keywordArguments.get('padding', setting.padding)
+
+	workhorseSTFT: ShortTimeFFT = ShortTimeFFT(**parametersShortTimeFFT.e733T)
+
+	# DEVELOPMENT This assumes I will only run stft on floating-point valued waveform data. But is
+	# that true? Is that necessary? Is that desirable?
+	arrayFloating = arrayTarget
+	arrayWaveforms = arrayTarget
+	if numpy.issubdtype(arrayTarget.dtype, integer):
+		if arrayTarget.ndim == 3:
+			arrayWaveforms: ArrayWaveformsFloating = amplitudeIntegerToFloating(arrayTarget)
+		if arrayTarget.ndim == 2:
+			arrayFloating: WaveformFloating = amplitudeIntegerToFloating(arrayTarget)
+	elif numpy.issubdtype(arrayTarget.dtype, 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 the temporary directory of this computer so you might recover the data. '
+			f'{arrayTarget.shape = }, {arrayTarget.dtype = }\n'
+			f'{pathFilename = }'
+		)
+		raise ValueError(message)
+
+	# DEVELOPMENT There are eleventy different systems below because I have been trying to find 1)
+	# efficient logic that 2) the type checkers understand.
+	if arrayFloating.ndim == 2:
+		arrayWaveforms: ArrayWaveformsFloating = numpy.expand_dims(arrayFloating, indexingAxis)
+	elif (arrayTarget.ndim == 3) and (numpy.issubdtype(arrayTarget.dtype, complexfloating)):
+		spectrogram: Spectrogram = arrayTarget
+		return turtleShell(spectrogram, lengthWaveform)
+
+	if (arrayWaveforms.ndim == 3) and (numpy.issubdtype(arrayWaveforms.dtype, floating)):
+		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, 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.
+	"""
+	def stft_istft(waveform: Waveform) -> Waveform:
+		axisWaveformTime: int = getAxis()['time'].number
+
+		return stft(callableNeedsSpectrogram(stft(waveform)), lengthWaveform=waveform.shape[axisWaveformTime])
+
+	return stft_istft

{hunterhearspy-1.1.0 → hunterhearspy-1.3.0}/src/hunterHearsPy/_io.py

@@ -1,10 +1,9 @@
-# pyright: reportArgumentType=false
-# ty:ignore[invalid-assignment]
 from __future__ import annotations
 
 from hunterHearsPy import amplitudeToSoundfile, getAxis, resampleWaveform, setting, stft
 from hunterMakesPy.filesystemToolkit import makeDirectorySafely
 from pathlib import Path, PurePath
+from soundfile import AudioData
 from typing import TYPE_CHECKING
 from typing_extensions import Unpack
 import numpy
@@ -13,22 +12,12 @@ import tempfile
 import uuid
 
 if TYPE_CHECKING:
-	from hunterHearsPy import FileDescriptorOrPath, Parameters_stft, Spectrogram, Waveform, WaveformAxes
+	from hunterHearsPy import AxisMetadata
+	from hunterHearsPy.theTypes import FileDescriptorOrPath, Parameters_stft, Spectrogram, Waveform
 	from numpy import dtype, ndarray
-	from soundfile import dtype_str as Options_dtype_str
+	from soundfile import AudioData_2d, dtype_str as Options_dtype_str
 	from typing import Any
 
-# TODO. The typing has too many moving parts.
-# 1. This function: that should be the easiest--if I get the other parts right.
-# 2. `SoundFile.read(dtype=setting.dtype_str` is dynamic, and the static checker is using the type of
-#    the field, `dtype_str: soundfile_dtype_str`, `Literal["float64", "float32", "int32", "int16"]`
-# 3. `Soundfile.read` has decent typing, but I have total control because I have a custom stub file in
-#    `stubFileNotFound`.
-# 4. `resampy` accepts integer or floating input and returns float32 or the same floating type.
-
-# AND NOW, `writeWAV` is pulled into the problem.
-
-# This is a general purpose function: it is not a subroutine of _arrays.
 def readAudioFile(pathFilename: FileDescriptorOrPath, sampleRateDesired: float | None = None, dtype_str: Options_dtype_str | None = None) -> Waveform:
 	"""Read an audio file and return waveform data as a NumPy array.
 
@@ -54,11 +43,11 @@ def readAudioFile(pathFilename: FileDescriptorOrPath, sampleRateDesired: float |
 	sampleRateDesired = sampleRateDesired or setting.sampleRate
 	with soundfile.SoundFile(pathFilename) as readSoundFile:
 		sampleRateSource: int = readSoundFile.samplerate
-		waveform: Waveform = readSoundFile.read(dtype=dtype_str or setting.dtype_str, always_2d=True)
-	axis: dict[str, WaveformAxes] = getAxis()
-	waveform = waveform.transpose((axis['time'].number, axis['channel'].number))
+		audioData: AudioData_2d = readSoundFile.read(dtype=dtype_str or setting.dtype_str, always_2d=True)  # ty:ignore[invalid-assignment] https://github.com/astral-sh/ty/issues/2799
+	axis: dict[str, AxisMetadata] = getAxis()
+	waveform: Waveform = audioData.transpose((axis['time'].number, axis['channel'].number))
 
-	return resampleWaveform(waveform, sampleRateDesired, sampleRateSource, axis['time'].number)
+	return resampleWaveform(waveform, sampleRateDesired, sampleRateSource, axis['time'].number)  # ty:ignore[no-matching-overload] https://github.com/astral-sh/ty/issues/2799
 
 def writeWAV(pathFilename: FileDescriptorOrPath, waveform: Waveform, sampleRate: float | None = None, subtype: str | None = None) -> FileDescriptorOrPath:
 	"""Write a waveform array to a WAV file.
@@ -100,11 +89,11 @@ def writeWAV(pathFilename: FileDescriptorOrPath, waveform: Waveform, sampleRate:
 	subtype = subtype or setting.subtype
 	makeDirectorySafely(pathFilename)
 
-	waveform = amplitudeToSoundfile(waveform)
+	audioData: AudioData = amplitudeToSoundfile(waveform)
 
-	waveform = waveform.transpose()
+	audioData = audioData.transpose()
 
-	soundfile.write(file=pathFilename, data=waveform, samplerate=sampleRate, subtype=subtype, format='WAV')
+	soundfile.write(file=pathFilename, data=audioData, samplerate=sampleRate, subtype=subtype, format='WAV')
 	return pathFilename
 
 def spectrogramToWAV(spectrogram: Spectrogram, pathFilename: FileDescriptorOrPath, lengthWaveform: int, **parametersSTFT: Unpack[Parameters_stft]) -> None:
@@ -144,7 +133,7 @@ def spectrogramToWAV(spectrogram: Spectrogram, pathFilename: FileDescriptorOrPat
 	sampleRate: float = parametersSTFT.get('sampleRate', setting.sampleRate)
 	writeWAV(pathFilename, waveform, sampleRate)
 
-def saveOnError(arrayTarget: ndarray[tuple[int, ...], dtype[Any]], *, identifierTarget: str = 'arrayTarget') -> PurePath:
+def saveOnError(arrayTarget: ndarray[tuple[Any, ...], dtype[Any]], *, identifierTarget: str = 'arrayTarget') -> PurePath:
 	pathFilename: Path = Path(tempfile.mkdtemp(prefix='hunterHearsPy'), f"{identifierTarget}_{uuid.uuid4().hex}.npy").resolve()
 	numpy.save(pathFilename, arrayTarget)
 

{hunterhearspy-1.1.0 → hunterhearspy-1.3.0}/src/hunterHearsPy/_resample.py

@@ -7,7 +7,7 @@ from typing import overload, TYPE_CHECKING
 import resampy
 
 if TYPE_CHECKING:
-	from hunterHearsPy import 形floating, 形Shape
+	from hunterHearsPy.theTypes import 形floating, 形Shape
 	from numpy import dtype, float32, integer, ndarray
 	from typing import Any
 
@@ -18,10 +18,6 @@ def resampleWaveform(waveform: ndarray[形Shape, dtype[形floating]], sampleRate
 def resampleWaveform(waveform: ndarray[形Shape, dtype[形floating]] | ndarray[形Shape, dtype[integer[Any]]], sampleRateDesired: float, sampleRateSource: float, axisTime: int = -1) -> ndarray[形Shape, dtype[形floating]] | ndarray[形Shape, dtype[float32]]:
 	"""Resample `waveform` array to `sampleRateDesired` along the `axisTime` axis.
 
-	Warning
-	-------
-	The returned `ndarray` always has a floating-point `dtype`, even if the sample rate is unchanged.
-
 	This function is _not_ regulated by the universal settings.
 
 	Parameters