hunterHearsPy 1.3.0__tar.gz → 1.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hunterHearsPy
-Version: 1.3.0
+Version: 1.4.0
 Summary: Audio processing.
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 Maintainer-email: Hunter Hogan <HunterHogan@pm.me>
@@ -131,13 +131,7 @@ I don't know a good way to implement user-configurable universal settings. There
 - 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`.
+- Use `sampleRate` unless I have a compelling reason not to.
 
 ### Preferred packages
 

{hunterhearspy-1.3.0 → hunterhearspy-1.4.0}/README.md

@@ -86,13 +86,7 @@ I don't know a good way to implement user-configurable universal settings. There
 - 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`.
+- Use `sampleRate` unless I have a compelling reason not to.
 
 ### Preferred packages
 

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

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

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

@@ -1,4 +1,5 @@
 # ruff: noqa: D104
+# TODO design and implement a namespace.
 from __future__ import annotations
 
 from hunterHearsPy import theTypes as theTypes
@@ -35,7 +36,8 @@ from hunterHearsPy.autoRevert import moveToAxisOfOperation as moveToAxisOfOperat
 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
+from hunterHearsPy._io import (
+	getSampleRate as getSampleRate, readAudioFile as readAudioFile, spectrogramToWAV as spectrogramToWAV, writeWAV as writeWAV)
 
 # isort: split
 from hunterHearsPy.clippingArrays import applyHardLimit as applyHardLimit, applyHardLimitComplexValued as applyHardLimitComplexValued

{hunterhearspy-1.3.0 → hunterhearspy-1.4.0}/src/hunterHearsPy/_arrays.py

@@ -54,6 +54,7 @@ def getWaveformMetadata(
 		sys.stderr.write(message + '\n')
 
 	for index, pathFilename in enumerate(tqdm(listPathFilenames, desc='Preparing combined array', leave=False)):
+		# NOTE Use readAudioFile with the prescribed sampleRate to get the exact length.
 		channels, lengthWaveform = readAudioFile(pathFilename, sampleRate).shape
 		dictionaryWaveformMetadata[index] = WaveformMetadata(
 			channels=channels, lengthWaveform=lengthWaveform, pathFilename=pathFilename, samplesStart=0, samplesStop=0
@@ -71,7 +72,7 @@ def getWaveformMetadata(
 
 	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.
+		# 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']
 

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

@@ -18,18 +18,21 @@ if TYPE_CHECKING:
 	from soundfile import AudioData_2d, dtype_str as Options_dtype_str
 	from typing import Any
 
-def readAudioFile(pathFilename: FileDescriptorOrPath, sampleRateDesired: float | None = None, dtype_str: Options_dtype_str | None = None) -> Waveform:
+def getSampleRate(pathFilename: FileDescriptorOrPath) -> int:
+	return soundfile.info(pathFilename).samplerate
+
+def readAudioFile(pathFilename: FileDescriptorOrPath, sampleRate: float | None = None, dtype_str: Options_dtype_str | None = None) -> Waveform:
 	"""Read an audio file and return waveform data as a NumPy array.
 
 	You can use this function to load any audio file that `soundfile` [1] supports. The returned
-	`Waveform` [2] is always shaped `(channels, samples)`. When `sampleRateDesired` differs from the file's
+	`Waveform` [2] is always shaped `(channels, samples)`. When `sampleRate` differs from the file's
 	native sample rate, `readAudioFile` resamples using `resampleWaveform`.
 
 	Parameters
 	----------
 	pathFilename : FileDescriptorOrPath
 		Path to the audio file or a binary stream.
-	sampleRateDesired : float | None = 44100
+	sampleRate : float | None = 44100
 		Target sample rate of the returned `Waveform` [2] in Hz. Defaults to `setting.sampleRate`,
 		which is probably 44100, when `None`.
 	dtype_str : Literal["float64", "float32", "int32", "int16"] | None = 'float32'
@@ -40,7 +43,7 @@ def readAudioFile(pathFilename: FileDescriptorOrPath, sampleRateDesired: float |
 	waveform : Waveform
 		Audio data shaped `(channels, samples)` as `setting.dtypeWaveform`.
 	"""
-	sampleRateDesired = sampleRateDesired or setting.sampleRate
+	sampleRateDesired: float = sampleRate or setting.sampleRate
 	with soundfile.SoundFile(pathFilename) as readSoundFile:
 		sampleRateSource: int = readSoundFile.samplerate
 		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
@@ -49,6 +52,42 @@ def readAudioFile(pathFilename: FileDescriptorOrPath, sampleRateDesired: float |
 
 	return resampleWaveform(waveform, sampleRateDesired, sampleRateSource, axis['time'].number)  # ty:ignore[no-matching-overload] https://github.com/astral-sh/ty/issues/2799
 
+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)
+
+	return PurePath(pathFilename)
+
+def spectrogramToWAV(spectrogram: Spectrogram, pathFilename: FileDescriptorOrPath, lengthWaveform: int, **parametersSTFT: Unpack[Parameters_stft]) -> None:
+	"""Write a complex spectrogram to a WAV file by computing the inverse STFT.
+
+	You can use this function to reconstruct a waveform from a `Spectrogram` [1] and save
+	it directly to a WAV file. `spectrogramToWAV` calls `stft` with `inverse=True` to
+	obtain the reconstructed `Waveform` [2], then passes it to `writeWAV`.
+
+	Parameters
+	----------
+	spectrogram : Spectrogram
+		Complex spectrogram to convert back to a waveform.
+	pathFilename : FileDescriptorOrPath
+		Destination path for the WAV file, or a binary stream.
+	lengthWaveform : int
+		Number of samples in the output waveform. The inverse STFT cannot recover the
+		original length from the spectrogram alone, so `lengthWaveform` is required.
+	sampleRate : float | None = None
+		Sample rate for the output WAV file in Hz. Defaults to `44100` when `None`.
+	**parametersSTFT : Any
+		Keyword parameters forwarded to `stft`, such as `lengthWindowingFunction` and
+		`lengthHop`.
+
+	File Overwrite and Format
+	-------------------------
+	See `writeWAV` for file overwrite behavior and output format details.
+	"""
+	waveform: Waveform = stft(spectrogram, lengthWaveform=lengthWaveform, **parametersSTFT)
+	sampleRate: float = parametersSTFT.get('sampleRate', setting.sampleRate)
+	writeWAV(pathFilename, waveform, sampleRate)
+
 def writeWAV(pathFilename: FileDescriptorOrPath, waveform: Waveform, sampleRate: float | None = None, subtype: str | None = None) -> FileDescriptorOrPath:
 	"""Write a waveform array to a WAV file.
 
@@ -95,46 +134,3 @@ def writeWAV(pathFilename: FileDescriptorOrPath, waveform: Waveform, sampleRate:
 
 	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:
-	"""Write a complex spectrogram to a WAV file by computing the inverse STFT.
-
-	You can use this function to reconstruct a waveform from a `Spectrogram` [1] and save
-	it directly to a WAV file. `spectrogramToWAV` calls `stft` with `inverse=True` to
-	obtain the reconstructed `Waveform` [2], then passes it to `writeWAV`.
-
-	Parameters
-	----------
-	spectrogram : Spectrogram
-		Complex spectrogram to convert back to a waveform.
-	pathFilename : FileDescriptorOrPath
-		Destination path for the WAV file, or a binary stream.
-	lengthWaveform : int
-		Number of samples in the output waveform. The inverse STFT cannot recover the
-		original length from the spectrogram alone, so `lengthWaveform` is required.
-	sampleRate : float | None = None
-		Sample rate for the output WAV file in Hz. Defaults to `44100` when `None`.
-	**parametersSTFT : Any
-		Keyword parameters forwarded to `stft`, such as `lengthWindowingFunction` and
-		`lengthHop`.
-
-	File Overwrite and Format
-	-------------------------
-	See `writeWAV` for file overwrite behavior and output format details.
-
-	References
-	----------
-	[1] `Spectrogram`
-
-	[2] `Waveform`
-
-	"""
-	waveform: Waveform = stft(spectrogram, lengthWaveform=lengthWaveform, **parametersSTFT)
-	sampleRate: float = parametersSTFT.get('sampleRate', setting.sampleRate)
-	writeWAV(pathFilename, waveform, sampleRate)
-
-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)
-
-	return PurePath(pathFilename)

{hunterhearspy-1.3.0 → hunterhearspy-1.4.0}/src/hunterHearsPy/dataBaskets.py

@@ -58,7 +58,7 @@ class WaveformMetadata(TypedDict):
 	channels: int
 	lengthWaveform: int
 	pathFilename: FileDescriptorOrPath
-	# NOTE If the following values were assigned directly to a `slice` object, the slice object would
+	# DOCUMENT If the following values were assigned directly to a `slice` object, the slice object would
 	# work as desired. https://docs.python.org/3/library/functions.html#slice Therefore, maintain this
 	# functionality, and keep the semiotics aligned: `slice(start, stop)`.
 	samplesStart: int

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hunterHearsPy
-Version: 1.3.0
+Version: 1.4.0
 Summary: Audio processing.
 Author-email: Hunter Hogan <HunterHogan@pm.me>
 Maintainer-email: Hunter Hogan <HunterHogan@pm.me>
@@ -131,13 +131,7 @@ I don't know a good way to implement user-configurable universal settings. There
 - 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`.
+- Use `sampleRate` unless I have a compelling reason not to.
 
 ### Preferred packages
 

{hunterhearspy-1.3.0 → hunterhearspy-1.4.0}/tests/test_io.py

@@ -10,8 +10,8 @@ if TYPE_CHECKING:
 	from pathlib import Path
 	from soundfile import dtype_str as Options_dtype_str
 
-# TODO add `None` to `sampleRateDesired`.
-@pytest.mark.parametrize('sampleRateDesired', (44100, 48000))
+# TODO add `None` to `sampleRate`.
+@pytest.mark.parametrize('sampleRate', (44100, 48000))
 @pytest.mark.parametrize('pathFilename'
 	, indirect=['pathFilename']
 	, argvalues=(
@@ -24,7 +24,7 @@ if TYPE_CHECKING:
 		, ('Music_ch2_Hz44100_float32_sec20_RMS-20.wav')
 	)
 )
-def test_readAudioFile(pathFilename: Path, sampleRateDesired: float, dtype_str: Options_dtype_str | None, expected: Waveform) -> None:
-	actual: Waveform = readAudioFile(pathFilename, sampleRateDesired, dtype_str)
+def test_readAudioFile(pathFilename: Path, sampleRate: float, dtype_str: Options_dtype_str | None, expected: Waveform) -> None:
+	actual: Waveform = readAudioFile(pathFilename, sampleRate, dtype_str)
 
-	assert_array_equal(actual, expected, 'readAudioFile', pathFilename.name, sampleRateDesired=sampleRateDesired, dtype_str=dtype_str)
+	assert_array_equal(actual, expected, 'readAudioFile', pathFilename.name, sampleRate=sampleRate, dtype_str=dtype_str)