hunterHearsPy 1.2.0__tar.gz → 1.3.0__tar.gz

{hunterhearspy-1.2.0/src/hunterHearsPy.egg-info → hunterhearspy-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hunterHearsPy
-Version: 1.2.0
+Version: 1.3.0
 Summary: Audio processing.
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 Maintainer-email: Hunter Hogan <HunterHogan@pm.me>

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

@@ -1,6 +1,6 @@
 [project]
 name = "hunterHearsPy"
-version = "1.2.0"
+version = "1.3.0"
 description = "Audio processing."
 readme = "README.md"
 requires-python = ">=3.10"

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

@@ -1,16 +1,7 @@
 # ruff: noqa: D104
 from __future__ import annotations
 
-from hunterHearsPy.theTypes import (
-	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,
-	WaveformShape as WaveformShape, 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
@@ -24,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
@@ -35,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
 
@@ -44,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.2.0 → hunterhearspy-1.3.0}/src/hunterHearsPy/_arrays.py

@@ -3,22 +3,38 @@ from __future__ import annotations
 
 from concurrent.futures import ThreadPoolExecutor
 from hunterHearsPy import (
-	ArraySpectrogramsShape, ArrayWaveformsShape, AxisMetadata, getAxis, readAudioFile, setting, stft, WaveformMetadata, WaveformShape)
+	AxisMetadata, getAxis, readAudioFile, setting, SpectrogramsAndMetadata, stft, WaveformMetadata, WaveformsAndMetadata)
 from hunterMakesPy.parseParameters import defineConcurrencyLimit
 from tqdm.auto import tqdm
-from typing import TYPE_CHECKING
+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 import (
+	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
-	from typing import Any
+
+#======== 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
@@ -61,72 +77,68 @@ def getWaveformMetadata(
 
 	return dictionaryWaveformMetadata, axis
 
-def loadWaveforms(listPathFilenames: Sequence[FileDescriptorOrPath], *, CPUlimit: bool | float | int | None = None, **keywordArguments: Unpack[Parameters_loadWaveforms]) -> ArrayWaveforms:
+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)
-	dtype: DTypeLike = keywordArguments.get('dtype', setting.dtypeWaveform)
+	dtypeWaveform: DTypeLike = keywordArguments.get('dtypeWaveform', setting.dtypeWaveform)
 	dtype_str: Options_dtype_str = keywordArguments.get('dtype_str', setting.dtype_str)
-	sampleRateDesired: float = keywordArguments.get('sampleRateDesired', setting.sampleRate)
+	sampleRate: float = keywordArguments.get('sampleRate', 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)
+	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'], sampleRateDesired, dtype_str
-		).astype(dtype, copy=False)
+			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()), 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.
+		tuple(tqdm(threadManager.map(workhorse, dictionaryWaveformMetadata, dictionaryWaveformMetadata.values())
+				, desc='Loading waveforms.'
+				, total=len(dictionaryWaveformMetadata)
+		))
 
-	If align=stop, then if you truncate to the shortest waveform by removing the beginning of the longer waveforms, then all waveforms are identical.
+	return WaveformsAndMetadata(array=arrayWaveforms, metadata=dictionaryWaveformMetadata)
 
-	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]]:
+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)
-	dtype: DTypeLike = keywordArguments.get('dtype', setting.dtypeSpectrogram)
+	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)
-	sampleRateDesired: float = keywordArguments.get('sampleRateDesired', setting.sampleRate)
+	sampleRate: float = keywordArguments.get('sampleRate', setting.sampleRate)
 
 	max_workers: int = defineConcurrencyLimit(limit=CPUlimit)
 
 	#============== Allocate memory ==========================================================
 
-	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRateDesired, align)
+	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRate, align)
 
-	waveformShape = WaveformShape(*(entry.size for entry in sorted((axis['channel'], axis['time']))))
+	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(ArraySpectrogramsShape(*arraySpectrogramsShape), dtype)
+	arraySpectrograms: ArraySpectrograms = numpy.zeros(Axes4(*arraySpectrogramsShape), dtypeSpectrogram)
 
 	#============== Concurrent loading ==========================================================
 
@@ -147,60 +159,81 @@ def loadSpectrograms(listPathFilenames: Sequence[FileDescriptorOrPath], *, CPUli
 		# 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)
+				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'], sampleRateDesired, dtype_str).astype(dtypeWaveform, copy=False)
-					, pad_widthIntegralType, mode=align_pad_mode)
-				, **keywordArguments
-			), axis=axisSpectrogram.number
-		)
+			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))
+		tuple(tqdm(threadManager.map(workhorse, dictionaryWaveformMetadata.keys(), dictionaryWaveformMetadata.values())
+				, desc='Loading spectrograms.'
+				, total=axisSpectrogram.size
+		))
 
-	return arraySpectrograms, dictionaryWaveformMetadata
+	return SpectrogramsAndMetadata(arraySpectrograms, dictionaryWaveformMetadata)
 
-def BACKUPloadSpectrograms(listPathFilenames: Sequence[FileDescriptorOrPath], *, CPUlimit: bool | float | int | None = None, **keywordArguments: Any) -> tuple[ArraySpectrograms, dict[int, WaveformMetadata]]:
+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)
-	dtype: DTypeLike = keywordArguments.get('dtype', setting.dtypeSpectrogram)
+	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)
-	sampleRateDesired: float = keywordArguments.get('sampleRateDesired', setting.sampleRate)
+	sampleRate: float = keywordArguments.get('sampleRate', setting.sampleRate)
 
 	max_workers: int = defineConcurrencyLimit(limit=CPUlimit)
 
 	#============== Allocate memory ==========================================================
 
-	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRateDesired, align)
+	dictionaryWaveformMetadata, axis = getWaveformMetadata(listPathFilenames, sampleRate, align)
 
-	waveformShape = WaveformShape(*(entry.size for entry in sorted((axis['channel'], axis['time']))))
+	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(ArraySpectrogramsShape(*arraySpectrogramsShape), dtype)
+	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'], sampleRateDesired, dtype_str).astype(dtypeWaveform, copy=False)
+		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))
+		tuple(
+			tqdm(
+				threadManager.map(workhorse, dictionaryWaveformMetadata.keys(), dictionaryWaveformMetadata.values()),
+				desc='Loading spectrograms',
+				total=axisSpectrogram.size,
+			)
+		)
 
 	return arraySpectrograms, dictionaryWaveformMetadata

{hunterhearspy-1.2.0 → hunterhearspy-1.3.0}/src/hunterHearsPy/_fft.py

@@ -1,75 +1,101 @@
+# 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, ParametersShortTimeFFT, setting, Translator
+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 import (
+	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: ...
+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: ...
+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: ...
+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 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:
-		arrayFloating: ArrayWaveformsFloating = numpy.expand_dims(arrayFloating, indexingAxis)
-	elif (arrayTarget.ndim == 3) and (numpy.issubdtype(arrayTarget.dtype, numpy.complexfloating)):
+		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 (arrayFloating.ndim == 3) and (numpy.issubdtype(arrayFloating.dtype, numpy.floating)):
-		arrayWaveforms: ArrayWaveformsFloating = arrayFloating
+	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])
+		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)
@@ -77,11 +103,13 @@ def stft(arrayTarget: Waveform | ArrayWaveforms | Spectrogram | ArraySpectrogram
 			arraySpectrograms = numpy.squeeze(arraySpectrograms, indexingAxis)
 		return arraySpectrograms
 
-	elif (arrayTarget.ndim == 4) and (numpy.issubdtype(arrayTarget.dtype, numpy.complexfloating)):
+	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])
+		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)
@@ -108,22 +136,10 @@ def waveformSpectrogramWaveform(callableNeedsSpectrogram: Callable[[Spectrogram]
 		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])
+		axisWaveformTime: int = getAxis()['time'].number
+
+		return stft(callableNeedsSpectrogram(stft(waveform)), lengthWaveform=waveform.shape[axisWaveformTime])
+
 	return stft_istft

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

@@ -12,7 +12,8 @@ import tempfile
 import uuid
 
 if TYPE_CHECKING:
-	from hunterHearsPy import AxisMetadata, FileDescriptorOrPath, Parameters_stft, Spectrogram, Waveform
+	from hunterHearsPy import AxisMetadata
+	from hunterHearsPy.theTypes import FileDescriptorOrPath, Parameters_stft, Spectrogram, Waveform
 	from numpy import dtype, ndarray
 	from soundfile import AudioData_2d, dtype_str as Options_dtype_str
 	from typing import Any

{hunterhearspy-1.2.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