Kudio 3.0.0__py3-none-any.whl

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/_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/_version.py

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

kudio/cli.py

@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+"""``kudio`` command line: quick audio utilities.
+
+    kudio devices                       # list input/output audio devices
+    kudio info  file.wav                # duration / sr / channels / peak
+    kudio convert in.wav out.wav --rate 16000 --subtype PCM_16
+    kudio synth  --clean C --noise N --out O --snr -5 0 5
+    kudio trim  in.wav out.wav --top-db 30
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+from typing import Optional, Sequence
+
+log = logging.getLogger("kudio.cli")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="kudio", description="kudio audio utilities")
+    p.add_argument("-v", "--verbose", action="store_true")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("devices", help="list audio devices (needs kudio[audio])")
+
+    s_info = sub.add_parser("info", help="show audio file properties")
+    s_info.add_argument("file")
+
+    s_conv = sub.add_parser("convert", help="resample / re-encode a wave file")
+    s_conv.add_argument("src")
+    s_conv.add_argument("dst")
+    s_conv.add_argument("--rate", type=int, default=None)
+    s_conv.add_argument("--subtype", default="PCM_16")
+
+    s_syn = sub.add_parser("synth", help="mix clean + noise at given SNRs")
+    s_syn.add_argument("--clean", required=True)
+    s_syn.add_argument("--noise", required=True)
+    s_syn.add_argument("--out", required=True)
+    s_syn.add_argument("--snr", type=int, nargs="+", default=[-5, 0, 5])
+    s_syn.add_argument("--mode", default="inc", choices=["inc", "reg"])
+    s_syn.add_argument("--seed", type=int, default=None)
+
+    s_trim = sub.add_parser("trim", help="trim leading/trailing silence")
+    s_trim.add_argument("src")
+    s_trim.add_argument("dst")
+    s_trim.add_argument("--top-db", type=float, default=30.0)
+    return p
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.INFO,
+                        format="%(levelname)s %(name)s: %(message)s")
+    import kudio
+
+    if args.command == "devices":
+        with kudio.CheckDevice() as cd:
+            for d in cd.system_devices():
+                print(f"[{d['index']:>2}] in={d['in']} out={d['out']} "
+                      f"fs={int(d['fs'])}  {d['Device']}")
+    elif args.command == "info":
+        y, sr = kudio.file_load(args.file, sr=None, mono=False)
+        ch = 1 if y.ndim == 1 else y.shape[1]
+        n = y.shape[0]
+        import numpy as np
+        print(f"file      : {args.file}")
+        print(f"samplerate: {sr} Hz")
+        print(f"channels  : {ch}")
+        print(f"duration  : {n / sr:.3f} s ({n} samples)")
+        print(f"peak      : {float(np.max(np.abs(y))):.4f}")
+    elif args.command == "convert":
+        y, sr = kudio.file_load(args.src, sr=args.rate, mono=True)
+        kudio.save_wave(args.dst, y, sr, subtype=args.subtype)
+        print(f"wrote {args.dst} ({sr} Hz, {args.subtype})")
+    elif args.command == "synth":
+        syx = kudio.Synthesizer(args.clean, args.noise, out_path=args.out,
+                                snr_ratio=args.snr)
+        result = syx.syn(mode=args.mode, seed=args.seed)
+        print(f"synthesized {len(result or [])} files -> {args.out}")
+    elif args.command == "trim":
+        y, sr = kudio.file_load(args.src, sr=None, mono=True)
+        trimmed, (a, b) = kudio.trim_silence(y, top_db=args.top_db)
+        kudio.save_wave(args.dst, trimmed, sr)
+        print(f"trimmed [{a}:{b}] -> {args.dst} ({len(trimmed)} samples)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kudio/config.py

@@ -0,0 +1,244 @@
+# -*- coding: utf-8 -*-
+"""YAML-backed configuration with attribute access.
+
+>>> from kudio import KudioConfig
+>>> cfg = KudioConfig.load_config('TrainConfig.yaml')
+>>> cfg.train.clean
+'data/train/clean'
+"""
+from __future__ import annotations
+
+import copy
+import logging
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+__all__ = ['KudioConfig', 'KC']
+
+log = logging.getLogger(__name__)
+
+
+class Dict(dict):
+    """dict subclass with attribute access and recursive conversion.
+
+    Vendored from the `addict <https://github.com/mewwts/addict>`_ project
+    (MIT license), trimmed to what kudio needs.
+    """
+
+    def __init__(__self, *args, **kwargs):
+        object.__setattr__(__self, '__parent', kwargs.pop('__parent', None))
+        object.__setattr__(__self, '__key', kwargs.pop('__key', None))
+        object.__setattr__(__self, '__frozen', False)
+        for arg in args:
+            if not arg:
+                continue
+            if isinstance(arg, dict):
+                for key, val in arg.items():
+                    __self[key] = __self._hook(val)
+            elif isinstance(arg, tuple) and (not isinstance(arg[0], tuple)):
+                __self[arg[0]] = __self._hook(arg[1])
+            else:
+                for key, val in iter(arg):
+                    __self[key] = __self._hook(val)
+
+        for key, val in kwargs.items():
+            __self[key] = __self._hook(val)
+
+    def __setattr__(self, name, value):
+        if hasattr(self.__class__, name):
+            raise AttributeError(
+                f"'Dict' object attribute {name!r} is read-only")
+        self[name] = value
+
+    def __setitem__(self, name, value):
+        is_frozen = (hasattr(self, '__frozen') and
+                     object.__getattribute__(self, '__frozen'))
+        if is_frozen and name not in super().keys():
+            raise KeyError(name)
+        super().__setitem__(name, value)
+        try:
+            p = object.__getattribute__(self, '__parent')
+            key = object.__getattribute__(self, '__key')
+        except AttributeError:
+            p = None
+            key = None
+        if p is not None:
+            p[key] = self
+            object.__delattr__(self, '__parent')
+            object.__delattr__(self, '__key')
+
+    @classmethod
+    def _hook(cls, item):
+        if isinstance(item, dict):
+            return cls(item)
+        if isinstance(item, (list, tuple)):
+            return type(item)(cls._hook(elem) for elem in item)
+        return item
+
+    def __getattr__(self, item):
+        return self.__getitem__(item)
+
+    def __missing__(self, name):
+        if object.__getattribute__(self, '__frozen'):
+            raise KeyError(name)
+        return self.__class__(__parent=self, __key=name)
+
+    def __delattr__(self, name):
+        del self[name]
+
+    def to_dict(self) -> dict:
+        base = {}
+        for key, value in self.items():
+            if isinstance(value, type(self)):
+                base[key] = value.to_dict()
+            elif isinstance(value, (list, tuple)):
+                base[key] = type(value)(
+                    item.to_dict() if isinstance(item, type(self)) else item
+                    for item in value)
+            else:
+                base[key] = value
+        return base
+
+    def copy(self):
+        return copy.copy(self)
+
+    def deepcopy(self):
+        return copy.deepcopy(self)
+
+    def __deepcopy__(self, memo):
+        other = self.__class__()
+        memo[id(self)] = other
+        for key, value in self.items():
+            other[copy.deepcopy(key, memo)] = copy.deepcopy(value, memo)
+        return other
+
+    def update(self, *args, **kwargs):
+        other = {}
+        if args:
+            if len(args) > 1:
+                raise TypeError("update expected at most 1 argument")
+            other.update(args[0])
+        other.update(kwargs)
+        for k, v in other.items():
+            if ((k not in self) or
+                    (not isinstance(self[k], dict)) or
+                    (not isinstance(v, dict))):
+                self[k] = v
+            else:
+                self[k].update(v)
+
+    def __getnewargs__(self):
+        return tuple(self.items())
+
+    def __getstate__(self):
+        return self
+
+    def __setstate__(self, state):
+        self.update(state)
+
+    def __or__(self, other):
+        if not isinstance(other, (Dict, dict)):
+            return NotImplemented
+        new = Dict(self)
+        new.update(other)
+        return new
+
+    def __ror__(self, other):
+        if not isinstance(other, (Dict, dict)):
+            return NotImplemented
+        new = Dict(other)
+        new.update(self)
+        return new
+
+    def __ior__(self, other):
+        self.update(other)
+        return self
+
+    def setdefault(self, key, default=None):
+        if key in self:
+            return self[key]
+        self[key] = default
+        return default
+
+    def freeze(self, should_freeze: bool = True):
+        object.__setattr__(self, '__frozen', should_freeze)
+        for val in self.values():
+            if isinstance(val, Dict):
+                val.freeze(should_freeze)
+
+    def unfreeze(self):
+        self.freeze(False)
+
+
+class KudioConfig(Dict):
+    """Attribute-style config with YAML load/save and audio-centric defaults."""
+
+    def write_config(self, file: str = 'cfg.yaml', exist_ok: bool = False) -> bool:
+        """Dump the config to *file*; refuses to overwrite unless ``exist_ok``."""
+        if Path(file).exists() and not exist_ok:
+            log.warning("Config exists, not overwritten: %s", file)
+            return False
+        with open(str(file), 'w', encoding='utf-8') as f:
+            yaml.safe_dump(self.to_dict(), f, allow_unicode=True)
+        log.info("Config written to %s", file)
+        return True
+
+    @classmethod
+    def load_config(cls, cfg_dir: str = '') -> Optional['KudioConfig']:
+        """Load a YAML config file.
+
+        *cfg_dir* may be a file, or a directory containing exactly one
+        ``cfg.yaml``. Anything else falls back to :meth:`default_config`.
+        """
+
+        def _load(f_: Path):
+            log.info("Load config -> %s", f_.absolute())
+            with open(str(f_.absolute()), encoding="utf-8") as f:
+                return yaml.safe_load(f)
+
+        _file = Path(cfg_dir)
+        if _file.is_file():
+            return cls(_load(_file))
+        if _file.is_dir():
+            candidates = list(_file.rglob("cfg.yaml"))
+            if len(candidates) == 1:
+                return cls(_load(candidates[0]))
+        log.info("No config file found, using defaults")
+        return cls(**cls.default_config())
+
+    @staticmethod
+    def default_config() -> dict:
+        """Audio-only defaults. Training/model settings live in the
+        application layer (e.g. chptrain), not in the audio library."""
+        return {
+            'waveform': {
+                'type': '.wav',
+                'default_rate': 16000,
+                'common_rate': [192000, 96000, 88200, 64000, 48000, 44100,
+                                32000, 22050, 16000, 11025, 8000, 6000],
+                'resample_rate': 16000,
+                'channels': 'mono',
+                'format': '16bit'},
+            'device': {
+                'pool_max': 200, 'cpu_cores': 8},
+            'f_mfe': {
+                'n_mels': 40,
+                'bank': 1,
+                'f0': 0,
+                'f1': 48000},
+        }
+
+    def show(self, key: Optional[str] = None) -> None:
+        """Print one key (or the whole config) to the log."""
+        if key is None:
+            for k, value in self.items():
+                log.info("%s: %s", k, value)
+        elif key in self:
+            log.info("%s: %s", key, self.get(key))
+        else:
+            log.warning("Unknown config key: %s", key)
+
+
+KC = KudioConfig

kudio/core/__init__.py

@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+"""Core audio functionality: I/O, buffering, streaming, features, synthesis,
+and evaluation."""
+from kudio.core.buffer import AudioBuffer, FetchBuffer
+from kudio.core.evaluator import (
+    AudioEvaluate,
+    eval_metrics,
+    segmental_snr,
+    si_sdr,
+    snr,
+)
+from kudio.core.feature import (
+    # canonical (v3)
+    denoise_spec2wav,
+    denoise_wav2spec,
+    features2matrix,
+    file_to_spectrogram,
+    logspec_from_files,
+    melspectrogram,
+    mfcc,
+    mfcc_from_files,
+    save_spectrogram_as_wave,
+    spectrogram_to_waveform,
+    waveform_to_spectrogram,
+    wave_separate,
+    wave_slicing,
+    # deprecated aliases
+    concat_logspec,
+    concat_logspec_,
+    concat_mfcc,
+    concat_mfcc_,
+    contextual_LogSpectrogram,
+    f2s,
+    s2w,
+    spec2wav,
+    spec2wavform,
+    w2mfcc,
+    w2s,
+    wav2mel,
+    wav2mfcc,
+    wav2spec,
+    wavform2spec,
+)
+from kudio.core.io import (
+    LoadAudio,
+    check_file,
+    check_input,
+    check_path,
+    copy_waves,
+    file_load,
+    load_wave,
+    load_waves,
+    save_wave,
+)
+from kudio.core.manager import AudioDataManager
+from kudio.core.stream import (
+    LocalStreamReader,
+    Recorder,
+    RemoteStreamReader,
+    play_audio,
+    record,
+    wave_decode,
+    wave_encode,
+)
+from kudio.core.synth import Synthesizer
+
+__all__ = [
+    # buffer
+    'AudioBuffer', 'FetchBuffer',
+    # evaluator + lightweight metrics
+    'AudioEvaluate', 'eval_metrics', 'si_sdr', 'snr', 'segmental_snr',
+    # feature (canonical)
+    'denoise_spec2wav', 'denoise_wav2spec', 'features2matrix',
+    'file_to_spectrogram', 'logspec_from_files', 'melspectrogram', 'mfcc',
+    'mfcc_from_files', 'save_spectrogram_as_wave', 'spectrogram_to_waveform',
+    'waveform_to_spectrogram', 'wave_separate', 'wave_slicing',
+    # feature (deprecated aliases)
+    'concat_logspec', 'concat_logspec_', 'concat_mfcc', 'concat_mfcc_',
+    'contextual_LogSpectrogram', 'f2s', 's2w', 'spec2wav', 'spec2wavform',
+    'w2mfcc', 'w2s', 'wav2mel', 'wav2mfcc', 'wav2spec', 'wavform2spec',
+    # io
+    'LoadAudio', 'check_file', 'check_input', 'check_path', 'copy_waves',
+    'file_load', 'load_wave', 'load_waves', 'save_wave',
+    # manager
+    'AudioDataManager',
+    # stream
+    'LocalStreamReader', 'Recorder', 'RemoteStreamReader', 'play_audio',
+    'record', 'wave_decode', 'wave_encode',
+    # synth
+    'Synthesizer',
+]

kudio/core/buffer.py

@@ -0,0 +1,135 @@
+# -*- coding: utf-8 -*-
+"""Thread-safe frame buffers shared between audio producers and consumers."""
+from __future__ import annotations
+
+import logging
+import threading
+from collections import deque
+from typing import List, Optional
+
+import numpy as np
+
+__all__ = ['AudioBuffer', 'FetchBuffer']
+
+log = logging.getLogger(__name__)
+
+
+class AudioBuffer:
+    """Bounded FIFO of audio frames shared between producer/consumer threads.
+
+    A stream reader calls :meth:`add` for every incoming frame; consumers either
+    poll frames with :meth:`get` (e.g. for real-time plotting) or collect a fixed
+    number of consecutive frames with :meth:`get_fixed_size_data` (e.g. timed
+    recording). All methods are thread-safe.
+    """
+
+    def __init__(self, size: int = 2):
+        if size < 1:
+            raise ValueError(f"size must be >= 1, got {size}")
+        self.buffer_size = int(size)
+        self._frames: deque = deque()
+        self._cond = threading.Condition()
+        # fixed-size capture state (timed recording)
+        self._capture: Optional[List[np.ndarray]] = None
+        self._capture_left = 0
+        self._capture_done = threading.Event()
+
+    def add(self, data, drop_full: bool = True) -> None:
+        """Append one frame.
+
+        With ``drop_full=True`` (default) the oldest frame is dropped when the
+        buffer is full; otherwise the call blocks until a slot is free.
+        """
+        with self._cond:
+            # feed an active fixed-size capture first so timed recordings
+            # do not lose frames to a slow consumer
+            if self._capture is not None and self._capture_left > 0:
+                self._capture.append(data)
+                self._capture_left -= 1
+                if self._capture_left == 0:
+                    self._capture_done.set()
+            if drop_full:
+                if len(self._frames) >= self.buffer_size:
+                    self._frames.popleft()
+            else:
+                while len(self._frames) >= self.buffer_size:
+                    self._cond.wait()
+            self._frames.append(data)
+            self._cond.notify_all()
+
+    def get(self, timeout: Optional[float] = None):
+        """Pop the oldest frame, blocking until one is available.
+
+        Raises ``TimeoutError`` if *timeout* (seconds) elapses first.
+        """
+        with self._cond:
+            while not self._frames:
+                if not self._cond.wait(timeout=timeout):
+                    raise TimeoutError("AudioBuffer.get timed out")
+            data = self._frames.popleft()
+            self._cond.notify_all()
+            return data
+
+    def get_fixed_size_data(self, queue_size: int) -> np.ndarray:
+        """Block until *queue_size* frames have arrived, then return them
+        concatenated with ``np.hstack``."""
+        with self._cond:
+            self._capture = []
+            self._capture_left = int(queue_size)
+            self._capture_done.clear()
+        log.info("Buffer: capturing %d frames", queue_size)
+        self._capture_done.wait()
+        with self._cond:
+            frames, self._capture = self._capture, None
+        return np.hstack(frames)
+
+    def clear(self) -> bool:
+        """Drop all buffered frames. Returns True if anything was dropped."""
+        with self._cond:
+            had_data = bool(self._frames)
+            self._frames.clear()
+            self._cond.notify_all()
+        if had_data:
+            log.info("Buffer: cleared")
+        return had_data
+
+    def size(self) -> int:
+        return len(self._frames)
+
+    def max_size(self) -> int:
+        return self.buffer_size
+
+    def is_full(self) -> bool:
+        return len(self._frames) >= self.buffer_size
+
+    def is_empty(self) -> bool:
+        return not self._frames
+
+
+class FetchBuffer(threading.Thread):
+    """Collect a fixed number of frames from an :class:`AudioBuffer` in a
+    background thread.
+
+    >>> data = FetchBuffer(buffer).get_data(desired_queue_size=10)
+    """
+
+    def __init__(self, buffer: AudioBuffer):
+        super().__init__(daemon=True)
+        if not isinstance(buffer, AudioBuffer):
+            raise TypeError("buffer must be an AudioBuffer")
+        self.buffer = buffer
+        self.queue_size: Optional[int] = None
+        self.data: Optional[np.ndarray] = None
+
+    def get_data(self, desired_queue_size: int, timeout: Optional[float] = None):
+        self.queue_size = desired_queue_size
+        self.start()
+        return self.join(timeout)
+
+    def run(self) -> None:
+        if isinstance(self.queue_size, int):
+            self.data = self.buffer.get_fixed_size_data(self.queue_size)
+
+    def join(self, timeout: Optional[float] = None):
+        super().join(timeout)
+        return self.data