hunterHearsPy 1.0.3__tar.gz → 1.2.0__tar.gz

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

@@ -1,12 +1,16 @@
 Metadata-Version: 2.4
 Name: hunterHearsPy
-Version: 1.0.3
+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
@@ -14,26 +18,30 @@ 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
+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: 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
+Requires-Dist: typing-extensions>=4.0.0
+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
 
@@ -101,6 +109,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.2.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.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hunterHearsPy"
-version = "1.0.3"
+version = "1.2.0"
 description = "Audio processing."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,18 +17,28 @@ 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",
 ]
 dependencies = [
+  "Z0Z_tools>=2.1.0",
   "hunterMakesPy>=0.7.0",
   "numpy",
   "resampy",
   "scipy",
   "soundfile>=0.14.0",
   "tqdm",
+  "typing-extensions>=4.0.0",
 ]
-optional-dependencies = { torch = ["torch"] }
+optional-dependencies = { testing = [
+  "pytest",
+  "pytest-mock",
+  "pytest-xdist",
+  "torch"
+], torch = ["torch"] }
 
 [project.urls]
 Context7 = "https://context7.com/hunterhogan/hunterhearspy"
@@ -40,12 +50,11 @@ 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"]
-testing = ["pytest", "pytest-mock", "pytest-xdist", "torch"]
+pytorch = ["torch==2.10.0"]
 
 [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 }
@@ -54,7 +63,7 @@ run = { branch = true, concurrency = ["multiprocessing"], data_file = "tests/cov
 ], parallel = true, source = ["."] }
 
 [tool.pytest]
-addopts = ["--color=auto", "-n 4"]
+addopts = ["--color=auto", "--tb=line", "-n 4"]
 log_auto_indent = "On"
 pythonpath = ["src"]
 testpaths = ["tests"]
@@ -65,13 +74,22 @@ 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
+# `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.2.0/setup.cfg

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

hunterhearspy-1.2.0/src/hunterHearsPy/__init__.py

@@ -0,0 +1,52 @@
+# 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)
+
+# 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.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