hunterHearsPy 1.1.0__tar.gz → 1.2.0__tar.gz

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

@@ -1,12 +1,16 @@
 Metadata-Version: 2.4
 Name: hunterHearsPy
-Version: 1.1.0
+Version: 1.2.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.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hunterHearsPy"
-version = "1.1.0"
+version = "1.2.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.2.0/setup.cfg

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

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

@@ -2,14 +2,15 @@
 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,
+	ArraySpectrograms as ArraySpectrograms, ArraySpectrogramsShape as ArraySpectrogramsShape, ArrayWaveforms as ArrayWaveforms,
+	ArrayWaveformsFloating as ArrayWaveformsFloating, ArrayWaveformsShape as ArrayWaveformsShape, AxisMetadata as AxisMetadata,
+	callableReturnsNDArray as callableReturnsNDArray, E733TH4X0R as E733TH4X0R, FileDescriptorOrPath as FileDescriptorOrPath,
+	NormalizationReverter as NormalizationReverter, OptionsAlign as OptionsAlign, Parameters_loadSpectrograms as Parameters_loadSpectrograms,
+	Parameters_loadWaveforms as Parameters_loadWaveforms, Parameters_stft as Parameters_stft, ParametersShortTimeFFT as ParametersShortTimeFFT,
+	Spectrogram as Spectrogram, SpectrogramDtype as SpectrogramDtype, Waveform as Waveform, 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)
+	WaveformShape as WaveformShape, 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

hunterhearspy-1.2.0/src/hunterHearsPy/_arrays.py

@@ -0,0 +1,206 @@
+# ruff: noqa: DOC201
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from hunterHearsPy import (
+	ArraySpectrogramsShape, ArrayWaveformsShape, AxisMetadata, getAxis, readAudioFile, setting, stft, WaveformMetadata, WaveformShape)
+from hunterMakesPy.parseParameters import defineConcurrencyLimit
+from tqdm.auto import tqdm
+from typing import TYPE_CHECKING
+from typing_extensions import Unpack
+import numpy
+import sys
+
+if TYPE_CHECKING:
+	from collections.abc import Sequence
+	from hunterHearsPy 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
+	from typing import Any
+
+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]) -> ArrayWaveforms:
+	"""Load a list of audio files into a single stacked NumPy array."""
+	#============== Initialize ==========================================================
+	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)
+
+	#============== Allocate memory ==========================================================
+	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRateDesired, align)
+
+	arrayWaveforms: ArrayWaveforms = numpy.zeros(ArrayWaveformsShape(*(entry.size for entry in sorted(axis.values()))), dtype)
+
+	#============== Concurrent loading ==========================================================
+	# TODO 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)))
+
+	"""# DEVELOPMENT
+	test_loadWaveforms_align: this is an exception to the rule of 1 test function for non-error outcomes per function. The not-commented-out code in align.py is my proof of concept for this test. But I DO NOT want you to mimic the code I wrote. I want you to understand what we want to test, then I want you think about a generalized test function. I designed this ArrayWaveforms such that if all of the waveforms are align=start (which means "pad the end of the shorter waveforms"), then for the duration of the shortest waveform, that data is identical in all of the waveforms. In this case, the shortest is 20 seconds at 44100 Hz, so the first 44100*20 samples of the left channel in all 5 waveforms match each other and the first 44100*20 samples of the right channel in all 5 waveforms match each other. Said, differently, if you truncate to the shortest waveform, then all of the waveforms should be identical.
+
+	If align=stop, then if you truncate to the shortest waveform by removing the beginning of the longer waveforms, then all waveforms are identical.
+
+	If align=center, truncate by removing equal amounts from the beginning and end, and the waveforms are identical.
+
+	That is the test I want you to make. The first three parameters are the same as test_loadWaveforms because they are necessary to get the array. Then use the align parameter in the test function to truncate/trim the array to the shortest waveform. Then do a round-robin assert_array_equal for each waveform in the ArrayWaveforms.
+
+	How long is the shortest waveform? Well, fuck.
+
+	# TODO Do I need to return `dictionaryWaveformMetadata`? In addition to the padding data, it is a convenient way to get the original pathFilename.
+	I wrote a bunch of notes about this. I guess they are in old commits.
+	Instead of returning a simple tuple, I could return a named tuple, which is tuple+, of course.
+	"""
+
+	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."""
+	#============== Initialize ==========================================================
+
+	align: OptionsAlign = keywordArguments.get('align', setting.align)
+	align_pad_mode: _ModeKind = keywordArguments.get('align_pad_mode', setting.align_pad_mode)
+	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)
+
+	#============== Allocate memory ==========================================================
+
+	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRateDesired, align)
+
+	waveformShape = WaveformShape(*(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(ArraySpectrogramsShape(*arraySpectrogramsShape), dtype)
+
+	#============== 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'], sampleRateDesired, dtype_str).astype(dtypeWaveform, copy=False)
+				, pad_widthIntegralType, mode=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'], sampleRateDesired, 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 arraySpectrograms, dictionaryWaveformMetadata
+
+def BACKUPloadSpectrograms(listPathFilenames: Sequence[FileDescriptorOrPath], *, CPUlimit: bool | float | int | None = None, **keywordArguments: Any) -> tuple[ArraySpectrograms, dict[int, WaveformMetadata]]:
+	"""Load spectrograms from a list of audio files."""
+	#============== Initialize ==========================================================
+
+	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)
+
+	#============== Allocate memory ==========================================================
+
+	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRateDesired, align)
+
+	waveformShape = WaveformShape(*(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(ArraySpectrogramsShape(*arraySpectrogramsShape), dtype)
+
+	#============== Concurrent loading ==========================================================
+
+	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)
+		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.1.0 → hunterhearspy-1.2.0}/src/hunterHearsPy/_fft.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from humpy_cytoolz.dicttoolz import keyfilter, merge
-from hunterHearsPy import amplitudeIntegerToFloating, Parameters_stft, ParametersShortTimeFFT, setting, Translator
+from hunterHearsPy import amplitudeIntegerToFloating, ParametersShortTimeFFT, setting, Translator
 from scipy.signal import ShortTimeFFT
 from typing import overload, TYPE_CHECKING
 from typing_extensions import Unpack
@@ -9,7 +9,8 @@ import numpy
 
 if TYPE_CHECKING:
 	from collections.abc import Callable
-	from hunterHearsPy import ArraySpectrograms, ArrayWaveforms, ArrayWaveformsFloating, Spectrogram, Waveform, WaveformFloating
+	from hunterHearsPy import (
+		ArraySpectrograms, ArrayWaveforms, ArrayWaveformsFloating, Parameters_stft, Spectrogram, Waveform, WaveformFloating)
 	from pathlib import PurePath
 	from scipy.signal._short_time_fft import _PadType
 
@@ -45,7 +46,8 @@ def stft(arrayTarget: Waveform | ArrayWaveforms | Spectrogram | ArraySpectrogram
 			)
 			raise ValueError(message)
 
-	parametersShortTimeFFT = Translator(**ParametersShortTimeFFT(keyfilter(setting.ShortTimeFFT.keys().__contains__, merge(setting.ShortTimeFFT, keywordArguments))))  # pyright: ignore[reportArgumentType] # ty:ignore[invalid-argument-type]
+	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)
 

{hunterhearspy-1.1.0 → hunterhearspy-1.2.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,11 @@ import tempfile
 import uuid
 
 if TYPE_CHECKING:
-	from hunterHearsPy import FileDescriptorOrPath, Parameters_stft, Spectrogram, Waveform, WaveformAxes
+	from hunterHearsPy import AxisMetadata, 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 +42,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 +88,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 +132,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)