Kudio 3.0.0__tar.gz

kudio-3.0.0/Kudio.egg-info/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: Kudio
+Version: 3.0.0
+Summary: Audio toolkit for industrial acoustic inspection: I/O, streaming, feature extraction, noisy-data synthesis, enhancement and evaluation.
+Author-email: RL <recognizer.light@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/recklight/kudio
+Project-URL: Repository, https://github.com/recklight/kudio
+Project-URL: Issues, https://github.com/recklight/kudio/issues
+Project-URL: Changelog, https://github.com/recklight/kudio/blob/main/CHANGELOG.md
+Keywords: audio,acoustic,signal-processing,speech-enhancement
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy<2.5,>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: librosa>=0.10
+Requires-Dist: soundfile>=0.12
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.60
+Requires-Dist: PyWavelets>=1.4
+Provides-Extra: audio
+Requires-Dist: PyAudio>=0.2.13; extra == "audio"
+Requires-Dist: sounddevice>=0.4.5; extra == "audio"
+Provides-Extra: eval
+Requires-Dist: mir_eval>=0.7; extra == "eval"
+Requires-Dist: pystoi>=0.3.3; extra == "eval"
+Requires-Dist: pysepm>=0.1; extra == "eval"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == "viz"
+Provides-Extra: data
+Requires-Dist: pandas>=2.0; extra == "data"
+Requires-Dist: openpyxl>=3.1; extra == "data"
+Provides-Extra: all
+Requires-Dist: kudio[audio,data,eval,viz]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: kudio[data]; extra == "dev"
+Dynamic: license-file
+
+# Kudio
+
+[![PyPI](https://img.shields.io/pypi/v/kudio.svg)](https://pypi.org/project/kudio/)
+[![Python](https://img.shields.io/pypi/pyversions/kudio.svg)](https://pypi.org/project/kudio/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
+
+**Lightweight, composable audio toolkit for acoustic inspection.**
+
+Kudio gives you audio I/O, streaming/recording, feature extraction, noisy-data
+synthesis, effects & augmentation, enhancement, and quality metrics — as small
+composable functions with a clean, typed API.
+
+The core stays light (numpy + soundfile + librosa); heavy or niche features
+(plotting, dataframes, PESQ/STOI, live audio) are opt-in extras.
+
+## Install
+
+```bash
+pip install kudio            # core: I/O, features, effects, synthesis, metrics
+pip install kudio[audio]     # + live capture / playback (PyAudio, sounddevice)
+pip install kudio[eval]      # + PESQ / STOI / SDR back-ends
+pip install kudio[viz]       # + plotting helpers (matplotlib)
+pip install kudio[data]      # + Excel / dataframe export (pandas, openpyxl)
+pip install kudio[all]       # everything
+```
+
+Requires **Python 3.9+** (tested on CPython 3.9–3.13).
+
+> The Python badge above reflects the version currently published on PyPI; it
+> updates automatically once v3.0 is released.
+
+## Quick start
+
+```python
+import kudio
+
+# --- I/O (soundfile-backed; float32) --------------------------------------
+y, sr = kudio.file_load("clip.wav")             # native rate, no resample
+kudio.save_wave("out.wav", y, sr, subtype="PCM_24")   # 16/24-bit or FLOAT
+
+# --- features -------------------------------------------------------------
+spec = kudio.waveform_to_spectrogram(y, norm=True)    # log-power spectrogram
+feat = kudio.mfcc(y, sr, n_mfcc=40)                    # (1, frames, 40)
+mel  = kudio.melspectrogram("clip.wav", n_mels=64)
+
+# --- effects & augmentation ----------------------------------------------
+clip, (a, b) = kudio.trim_silence(y, top_db=30)       # isolate the event
+segments      = kudio.split_on_silence(y)
+aug = kudio.pitch_shift(y, sr, n_steps=2)
+aug = kudio.add_noise_snr(y, noise, snr_db=5, seed=0) # reproducible
+spec = kudio.spec_augment(spec, freq_mask_width=8, time_mask_width=16, seed=0)
+
+# --- noisy-data synthesis -------------------------------------------------
+syx = kudio.Synthesizer("data/clean", "data/noise",
+                        out_path="data/mixed", snr_ratio=(-5, 0, 5))
+syx.syn(mode="inc", seed=17)                          # reproducible
+
+# --- metrics (pure numpy, no extra deps) ----------------------------------
+print(kudio.si_sdr(ref, est), kudio.snr(ref, est), kudio.segmental_snr(ref, est))
+
+# --- recording (needs kudio[audio]) --------------------------------------
+wave = kudio.record(seconds=3, sr=16000)
+```
+
+## Command line
+
+```bash
+kudio devices                                  # list audio devices
+kudio info clip.wav                            # sr / channels / duration / peak
+kudio convert in.wav out.wav --rate 16000 --subtype PCM_16
+kudio synth --clean C --noise N --out O --snr -5 0 5 --seed 17
+kudio trim in.wav out.wav --top-db 30
+```
+
+## Modules
+
+| Module | What's inside |
+|---|---|
+| `kudio.core.io` | `file_load`, `save_wave`, `check_input`, `load_waves`, `copy_waves` |
+| `kudio.core.feature` | `waveform_to_spectrogram`, `spectrogram_to_waveform`, `mfcc`, `melspectrogram`, ... |
+| `kudio.effects` | `trim_silence`, `split_on_silence`, `time_stretch`, `pitch_shift`, `add_noise_snr`, `reverb`, `spec_augment` |
+| `kudio.core.synth` | `Synthesizer` (SNR mixing, seedable) |
+| `kudio.core.evaluator` | `si_sdr`, `snr`, `segmental_snr` (dep-free); `AudioEvaluate` (PESQ/STOI/SDR) |
+| `kudio.core.stream` | `record`, `play_audio`, `Recorder`, `LocalStreamReader`, `RemoteStreamReader` |
+| `kudio.util` | `CheckDevice`, `map_waves`, colored console helpers, timers |
+
+Everything commonly used is importable straight from the top level (`kudio.…`).
+
+## Errors
+
+All library errors derive from `kudio.KudioError` (`AudioIOError`,
+`FeatureError`, `DeviceError`, `SynthesisError`, `DependencyError`), so you can
+catch them in one place. Missing an optional extra raises a `DependencyError`
+that tells you exactly what to install.
+
+## Logging
+
+kudio uses the standard `logging` module (loggers named `kudio.*`) and prints
+nothing by default:
+
+```python
+import logging; logging.basicConfig(level=logging.INFO)
+```
+
+## Migrating from v2
+
+v3 is a cleanup release. The short cryptic names still work but now emit a
+`DeprecationWarning` — switch to the canonical names:
+
+| v2 (deprecated) | v3 canonical |
+|---|---|
+| `w2s`, `wavform2spec` | `waveform_to_spectrogram` |
+| `spec2wavform` | `spectrogram_to_waveform` |
+| `f2s`, `wav2spec` | `file_to_spectrogram` |
+| `s2w`, `spec2wav` | `save_spectrogram_as_wave` |
+| `w2mfcc`, `wav2mfcc` | `mfcc` |
+| `concat_mfcc_` | `mfcc_from_files` |
+| `concat_logspec_`, `contextual_LogSpectrogram` | `logspec_from_files` |
+| `wav2mel` | `melspectrogram` |
+
+Also: `matplotlib` / `pandas` / `openpyxl` are no longer installed by default
+(use the `[viz]` / `[data]` extras), and the deprecated `_config` / `_enh` /
+`version` compatibility shims were removed.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

kudio-3.0.0/Kudio.egg-info/SOURCES.txt

@@ -0,0 +1,49 @@
+LICENSE.txt
+README.md
+pyproject.toml
+Kudio.egg-info/PKG-INFO
+Kudio.egg-info/SOURCES.txt
+Kudio.egg-info/dependency_links.txt
+Kudio.egg-info/entry_points.txt
+Kudio.egg-info/requires.txt
+Kudio.egg-info/top_level.txt
+kudio/__init__.py
+kudio/_deprecation.py
+kudio/_version.py
+kudio/cli.py
+kudio/config.py
+kudio/exceptions.py
+kudio/py.typed
+kudio/core/__init__.py
+kudio/core/buffer.py
+kudio/core/evaluator.py
+kudio/core/feature.py
+kudio/core/io.py
+kudio/core/manager.py
+kudio/core/stream.py
+kudio/core/synth.py
+kudio/effects/__init__.py
+kudio/effects/augment.py
+kudio/effects/silence.py
+kudio/enhance/__init__.py
+kudio/enhance/traditional.py
+kudio/util/__init__.py
+kudio/util/check.py
+kudio/util/colors.py
+kudio/util/conv.py
+kudio/util/parallel.py
+kudio/util/tools.py
+kudio/util/visual.py
+tests/test_buffer.py
+tests/test_cli.py
+tests/test_config.py
+tests/test_effects.py
+tests/test_enhance.py
+tests/test_evaluator.py
+tests/test_feature.py
+tests/test_io.py
+tests/test_manager.py
+tests/test_metrics.py
+tests/test_package.py
+tests/test_synth.py
+tests/test_utils.py

kudio-3.0.0/Kudio.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kudio-3.0.0/Kudio.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kudio = kudio.cli:main

kudio-3.0.0/Kudio.egg-info/requires.txt

@@ -0,0 +1,30 @@
+numpy<2.5,>=1.24
+scipy>=1.10
+librosa>=0.10
+soundfile>=0.12
+PyYAML>=6.0
+tqdm>=4.60
+PyWavelets>=1.4
+
+[all]
+kudio[audio,data,eval,viz]
+
+[audio]
+PyAudio>=0.2.13
+sounddevice>=0.4.5
+
+[data]
+pandas>=2.0
+openpyxl>=3.1
+
+[dev]
+pytest>=7.0
+kudio[data]
+
+[eval]
+mir_eval>=0.7
+pystoi>=0.3.3
+pysepm>=0.1
+
+[viz]
+matplotlib>=3.7

kudio-3.0.0/Kudio.egg-info/top_level.txt

@@ -0,0 +1 @@
+kudio

kudio-3.0.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kudio-3.0.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: Kudio
+Version: 3.0.0
+Summary: Audio toolkit for industrial acoustic inspection: I/O, streaming, feature extraction, noisy-data synthesis, enhancement and evaluation.
+Author-email: RL <recognizer.light@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/recklight/kudio
+Project-URL: Repository, https://github.com/recklight/kudio
+Project-URL: Issues, https://github.com/recklight/kudio/issues
+Project-URL: Changelog, https://github.com/recklight/kudio/blob/main/CHANGELOG.md
+Keywords: audio,acoustic,signal-processing,speech-enhancement
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy<2.5,>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: librosa>=0.10
+Requires-Dist: soundfile>=0.12
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.60
+Requires-Dist: PyWavelets>=1.4
+Provides-Extra: audio
+Requires-Dist: PyAudio>=0.2.13; extra == "audio"
+Requires-Dist: sounddevice>=0.4.5; extra == "audio"
+Provides-Extra: eval
+Requires-Dist: mir_eval>=0.7; extra == "eval"
+Requires-Dist: pystoi>=0.3.3; extra == "eval"
+Requires-Dist: pysepm>=0.1; extra == "eval"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == "viz"
+Provides-Extra: data
+Requires-Dist: pandas>=2.0; extra == "data"
+Requires-Dist: openpyxl>=3.1; extra == "data"
+Provides-Extra: all
+Requires-Dist: kudio[audio,data,eval,viz]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: kudio[data]; extra == "dev"
+Dynamic: license-file
+
+# Kudio
+
+[![PyPI](https://img.shields.io/pypi/v/kudio.svg)](https://pypi.org/project/kudio/)
+[![Python](https://img.shields.io/pypi/pyversions/kudio.svg)](https://pypi.org/project/kudio/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
+
+**Lightweight, composable audio toolkit for acoustic inspection.**
+
+Kudio gives you audio I/O, streaming/recording, feature extraction, noisy-data
+synthesis, effects & augmentation, enhancement, and quality metrics — as small
+composable functions with a clean, typed API.
+
+The core stays light (numpy + soundfile + librosa); heavy or niche features
+(plotting, dataframes, PESQ/STOI, live audio) are opt-in extras.
+
+## Install
+
+```bash
+pip install kudio            # core: I/O, features, effects, synthesis, metrics
+pip install kudio[audio]     # + live capture / playback (PyAudio, sounddevice)
+pip install kudio[eval]      # + PESQ / STOI / SDR back-ends
+pip install kudio[viz]       # + plotting helpers (matplotlib)
+pip install kudio[data]      # + Excel / dataframe export (pandas, openpyxl)
+pip install kudio[all]       # everything
+```
+
+Requires **Python 3.9+** (tested on CPython 3.9–3.13).
+
+> The Python badge above reflects the version currently published on PyPI; it
+> updates automatically once v3.0 is released.
+
+## Quick start
+
+```python
+import kudio
+
+# --- I/O (soundfile-backed; float32) --------------------------------------
+y, sr = kudio.file_load("clip.wav")             # native rate, no resample
+kudio.save_wave("out.wav", y, sr, subtype="PCM_24")   # 16/24-bit or FLOAT
+
+# --- features -------------------------------------------------------------
+spec = kudio.waveform_to_spectrogram(y, norm=True)    # log-power spectrogram
+feat = kudio.mfcc(y, sr, n_mfcc=40)                    # (1, frames, 40)
+mel  = kudio.melspectrogram("clip.wav", n_mels=64)
+
+# --- effects & augmentation ----------------------------------------------
+clip, (a, b) = kudio.trim_silence(y, top_db=30)       # isolate the event
+segments      = kudio.split_on_silence(y)
+aug = kudio.pitch_shift(y, sr, n_steps=2)
+aug = kudio.add_noise_snr(y, noise, snr_db=5, seed=0) # reproducible
+spec = kudio.spec_augment(spec, freq_mask_width=8, time_mask_width=16, seed=0)
+
+# --- noisy-data synthesis -------------------------------------------------
+syx = kudio.Synthesizer("data/clean", "data/noise",
+                        out_path="data/mixed", snr_ratio=(-5, 0, 5))
+syx.syn(mode="inc", seed=17)                          # reproducible
+
+# --- metrics (pure numpy, no extra deps) ----------------------------------
+print(kudio.si_sdr(ref, est), kudio.snr(ref, est), kudio.segmental_snr(ref, est))
+
+# --- recording (needs kudio[audio]) --------------------------------------
+wave = kudio.record(seconds=3, sr=16000)
+```
+
+## Command line
+
+```bash
+kudio devices                                  # list audio devices
+kudio info clip.wav                            # sr / channels / duration / peak
+kudio convert in.wav out.wav --rate 16000 --subtype PCM_16
+kudio synth --clean C --noise N --out O --snr -5 0 5 --seed 17
+kudio trim in.wav out.wav --top-db 30
+```
+
+## Modules
+
+| Module | What's inside |
+|---|---|
+| `kudio.core.io` | `file_load`, `save_wave`, `check_input`, `load_waves`, `copy_waves` |
+| `kudio.core.feature` | `waveform_to_spectrogram`, `spectrogram_to_waveform`, `mfcc`, `melspectrogram`, ... |
+| `kudio.effects` | `trim_silence`, `split_on_silence`, `time_stretch`, `pitch_shift`, `add_noise_snr`, `reverb`, `spec_augment` |
+| `kudio.core.synth` | `Synthesizer` (SNR mixing, seedable) |
+| `kudio.core.evaluator` | `si_sdr`, `snr`, `segmental_snr` (dep-free); `AudioEvaluate` (PESQ/STOI/SDR) |
+| `kudio.core.stream` | `record`, `play_audio`, `Recorder`, `LocalStreamReader`, `RemoteStreamReader` |
+| `kudio.util` | `CheckDevice`, `map_waves`, colored console helpers, timers |
+
+Everything commonly used is importable straight from the top level (`kudio.…`).
+
+## Errors
+
+All library errors derive from `kudio.KudioError` (`AudioIOError`,
+`FeatureError`, `DeviceError`, `SynthesisError`, `DependencyError`), so you can
+catch them in one place. Missing an optional extra raises a `DependencyError`
+that tells you exactly what to install.
+
+## Logging
+
+kudio uses the standard `logging` module (loggers named `kudio.*`) and prints
+nothing by default:
+
+```python
+import logging; logging.basicConfig(level=logging.INFO)
+```
+
+## Migrating from v2
+
+v3 is a cleanup release. The short cryptic names still work but now emit a
+`DeprecationWarning` — switch to the canonical names:
+
+| v2 (deprecated) | v3 canonical |
+|---|---|
+| `w2s`, `wavform2spec` | `waveform_to_spectrogram` |
+| `spec2wavform` | `spectrogram_to_waveform` |
+| `f2s`, `wav2spec` | `file_to_spectrogram` |
+| `s2w`, `spec2wav` | `save_spectrogram_as_wave` |
+| `w2mfcc`, `wav2mfcc` | `mfcc` |
+| `concat_mfcc_` | `mfcc_from_files` |
+| `concat_logspec_`, `contextual_LogSpectrogram` | `logspec_from_files` |
+| `wav2mel` | `melspectrogram` |
+
+Also: `matplotlib` / `pandas` / `openpyxl` are no longer installed by default
+(use the `[viz]` / `[data]` extras), and the deprecated `_config` / `_enh` /
+`version` compatibility shims were removed.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

kudio-3.0.0/README.md

@@ -0,0 +1,127 @@
+# Kudio
+
+[![PyPI](https://img.shields.io/pypi/v/kudio.svg)](https://pypi.org/project/kudio/)
+[![Python](https://img.shields.io/pypi/pyversions/kudio.svg)](https://pypi.org/project/kudio/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
+
+**Lightweight, composable audio toolkit for acoustic inspection.**
+
+Kudio gives you audio I/O, streaming/recording, feature extraction, noisy-data
+synthesis, effects & augmentation, enhancement, and quality metrics — as small
+composable functions with a clean, typed API.
+
+The core stays light (numpy + soundfile + librosa); heavy or niche features
+(plotting, dataframes, PESQ/STOI, live audio) are opt-in extras.
+
+## Install
+
+```bash
+pip install kudio            # core: I/O, features, effects, synthesis, metrics
+pip install kudio[audio]     # + live capture / playback (PyAudio, sounddevice)
+pip install kudio[eval]      # + PESQ / STOI / SDR back-ends
+pip install kudio[viz]       # + plotting helpers (matplotlib)
+pip install kudio[data]      # + Excel / dataframe export (pandas, openpyxl)
+pip install kudio[all]       # everything
+```
+
+Requires **Python 3.9+** (tested on CPython 3.9–3.13).
+
+> The Python badge above reflects the version currently published on PyPI; it
+> updates automatically once v3.0 is released.
+
+## Quick start
+
+```python
+import kudio
+
+# --- I/O (soundfile-backed; float32) --------------------------------------
+y, sr = kudio.file_load("clip.wav")             # native rate, no resample
+kudio.save_wave("out.wav", y, sr, subtype="PCM_24")   # 16/24-bit or FLOAT
+
+# --- features -------------------------------------------------------------
+spec = kudio.waveform_to_spectrogram(y, norm=True)    # log-power spectrogram
+feat = kudio.mfcc(y, sr, n_mfcc=40)                    # (1, frames, 40)
+mel  = kudio.melspectrogram("clip.wav", n_mels=64)
+
+# --- effects & augmentation ----------------------------------------------
+clip, (a, b) = kudio.trim_silence(y, top_db=30)       # isolate the event
+segments      = kudio.split_on_silence(y)
+aug = kudio.pitch_shift(y, sr, n_steps=2)
+aug = kudio.add_noise_snr(y, noise, snr_db=5, seed=0) # reproducible
+spec = kudio.spec_augment(spec, freq_mask_width=8, time_mask_width=16, seed=0)
+
+# --- noisy-data synthesis -------------------------------------------------
+syx = kudio.Synthesizer("data/clean", "data/noise",
+                        out_path="data/mixed", snr_ratio=(-5, 0, 5))
+syx.syn(mode="inc", seed=17)                          # reproducible
+
+# --- metrics (pure numpy, no extra deps) ----------------------------------
+print(kudio.si_sdr(ref, est), kudio.snr(ref, est), kudio.segmental_snr(ref, est))
+
+# --- recording (needs kudio[audio]) --------------------------------------
+wave = kudio.record(seconds=3, sr=16000)
+```
+
+## Command line
+
+```bash
+kudio devices                                  # list audio devices
+kudio info clip.wav                            # sr / channels / duration / peak
+kudio convert in.wav out.wav --rate 16000 --subtype PCM_16
+kudio synth --clean C --noise N --out O --snr -5 0 5 --seed 17
+kudio trim in.wav out.wav --top-db 30
+```
+
+## Modules
+
+| Module | What's inside |
+|---|---|
+| `kudio.core.io` | `file_load`, `save_wave`, `check_input`, `load_waves`, `copy_waves` |
+| `kudio.core.feature` | `waveform_to_spectrogram`, `spectrogram_to_waveform`, `mfcc`, `melspectrogram`, ... |
+| `kudio.effects` | `trim_silence`, `split_on_silence`, `time_stretch`, `pitch_shift`, `add_noise_snr`, `reverb`, `spec_augment` |
+| `kudio.core.synth` | `Synthesizer` (SNR mixing, seedable) |
+| `kudio.core.evaluator` | `si_sdr`, `snr`, `segmental_snr` (dep-free); `AudioEvaluate` (PESQ/STOI/SDR) |
+| `kudio.core.stream` | `record`, `play_audio`, `Recorder`, `LocalStreamReader`, `RemoteStreamReader` |
+| `kudio.util` | `CheckDevice`, `map_waves`, colored console helpers, timers |
+
+Everything commonly used is importable straight from the top level (`kudio.…`).
+
+## Errors
+
+All library errors derive from `kudio.KudioError` (`AudioIOError`,
+`FeatureError`, `DeviceError`, `SynthesisError`, `DependencyError`), so you can
+catch them in one place. Missing an optional extra raises a `DependencyError`
+that tells you exactly what to install.
+
+## Logging
+
+kudio uses the standard `logging` module (loggers named `kudio.*`) and prints
+nothing by default:
+
+```python
+import logging; logging.basicConfig(level=logging.INFO)
+```
+
+## Migrating from v2
+
+v3 is a cleanup release. The short cryptic names still work but now emit a
+`DeprecationWarning` — switch to the canonical names:
+
+| v2 (deprecated) | v3 canonical |
+|---|---|
+| `w2s`, `wavform2spec` | `waveform_to_spectrogram` |
+| `spec2wavform` | `spectrogram_to_waveform` |
+| `f2s`, `wav2spec` | `file_to_spectrogram` |
+| `s2w`, `spec2wav` | `save_spectrogram_as_wave` |
+| `w2mfcc`, `wav2mfcc` | `mfcc` |
+| `concat_mfcc_` | `mfcc_from_files` |
+| `concat_logspec_`, `contextual_LogSpectrogram` | `logspec_from_files` |
+| `wav2mel` | `melspectrogram` |
+
+Also: `matplotlib` / `pandas` / `openpyxl` are no longer installed by default
+(use the `[viz]` / `[data]` extras), and the deprecated `_config` / `_enh` /
+`version` compatibility shims were removed.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

kudio-3.0.0/kudio/__init__.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""kudio — a lightweight, composable audio toolkit for acoustic inspection.
+
+Audio I/O, streaming/recording, feature extraction, noisy-data synthesis,
+effects/augmentation, enhancement, and evaluation metrics.
+
+>>> import kudio
+>>> y, sr = kudio.file_load('some.wav')
+>>> spec = kudio.waveform_to_spectrogram(y)
+>>> clean = kudio.trim_silence(y)[0]
+
+Heavy/niche features are optional extras and are *not* imported here:
+plotting (`kudio.util.visual`, needs ``kudio[viz]``), Excel export
+(`kudio.util.conv`, needs ``kudio[data]``), and live audio
+(`kudio[audio]`).
+"""
+import logging as _logging
+
+from kudio._version import __author__, __version__
+from kudio.config import KC, KudioConfig
+from kudio.exceptions import (
+    AudioIOError,
+    DependencyError,
+    DeviceError,
+    FeatureError,
+    KudioError,
+    SynthesisError,
+    UnsupportedFormatError,
+)
+
+from kudio import core, effects, enhance, util  # noqa: E402
+from kudio.core import *  # noqa: F401,F403  (curated __all__)
+from kudio.effects import *  # noqa: F401,F403
+from kudio.enhance import trad_enhance, wavelet_low_pass_filter
+from kudio.util import *  # noqa: F401,F403  (curated __all__)
+
+_logging.getLogger(__name__).addHandler(_logging.NullHandler())
+
+__all__ = [
+    '__version__', '__author__', 'KudioConfig', 'KC',
+    'trad_enhance', 'wavelet_low_pass_filter',
+    # exceptions
+    'KudioError', 'AudioIOError', 'UnsupportedFormatError', 'DeviceError',
+    'FeatureError', 'SynthesisError', 'DependencyError',
+]
+__all__ += core.__all__
+__all__ += effects.__all__
+__all__ += util.__all__

kudio-3.0.0/kudio/_deprecation.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""Helpers for keeping backwards-compatible aliases while nudging callers
+towards the v3 canonical names."""
+from __future__ import annotations
+
+import functools
+import warnings
+from typing import Callable, Optional
+
+
+def alias(new: Callable, name: Optional[str] = None) -> Callable:
+    """Return a wrapper around *new* that emits a ``DeprecationWarning``.
+
+    >>> w2s = alias(waveform_to_spectrogram, 'w2s')
+    """
+    old_name = name or new.__name__
+
+    @functools.wraps(new)
+    def wrapper(*args, **kwargs):
+        warnings.warn(
+            f"kudio.{old_name}() is deprecated and will be removed in a future "
+            f"release; use kudio.{new.__name__}() instead.",
+            DeprecationWarning, stacklevel=2)
+        return new(*args, **kwargs)
+
+    wrapper.__name__ = old_name
+    wrapper.__qualname__ = old_name
+    wrapper.__doc__ = f"Deprecated alias for :func:`{new.__name__}`."
+    return wrapper

kudio-3.0.0/kudio/_version.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""Single source of truth for the package version."""
+__version__ = "3.0.0"
+__author__ = "RL"