micforge 1.3.0__py3-none-any.whl

micforge/audio/noise_profile.py

@@ -0,0 +1,250 @@
+"""Adaptive noise profiling: continuous voice-aware learning, environment profiles, and safe bounds."""
+from __future__ import annotations
+
+import json
+import logging
+import math
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from ..config import config_dir
+
+log = logging.getLogger("micforge.noise_profile")
+
+ENVIRONMENTS_DIR_NAME = "noise_profiles"
+
+
+def _profiles_dir() -> Path:
+    p = config_dir() / ENVIRONMENTS_DIR_NAME
+    try:
+        p.mkdir(parents=True, exist_ok=True)
+    except Exception:
+        pass
+    return p
+
+
+@dataclass
+class NoiseProfile:
+    """Snapshot of ambient noise characteristics."""
+    name: str = "quiet_room"
+    noise_floor_db: float = -62.0
+    gate_threshold_db: float = -50.0
+    spectral_tilt: float = 0.0  # ratio of high vs low band energy
+    sample_rate: int = 48000
+    bands: list[float] = field(default_factory=lambda: [-65.0] * 32)
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    sample_count: int = 0
+    frozen: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> NoiseProfile:
+        return cls(
+            name=str(data.get("name", "custom")),
+            noise_floor_db=float(data.get("noise_floor_db", -62.0)),
+            gate_threshold_db=float(data.get("gate_threshold_db", -50.0)),
+            spectral_tilt=float(data.get("spectral_tilt", 0.0)),
+            sample_rate=int(data.get("sample_rate", 48000)),
+            bands=list(data.get("bands", [-65.0] * 32)),
+            created_at=float(data.get("created_at", time.time())),
+            updated_at=float(data.get("updated_at", time.time())),
+            sample_count=int(data.get("sample_count", 0)),
+            frozen=bool(data.get("frozen", False)),
+        )
+
+
+# Standard environment baseline presets
+BUILTIN_ENVIRONMENTS: dict[str, NoiseProfile] = {
+    "quiet_room": NoiseProfile(
+        name="quiet_room",
+        noise_floor_db=-64.0,
+        gate_threshold_db=-52.0,
+        spectral_tilt=-0.3,
+        bands=[-65.0] * 32,
+    ),
+    "fan_on": NoiseProfile(
+        name="fan_on",
+        noise_floor_db=-52.0,
+        gate_threshold_db=-42.0,
+        spectral_tilt=-0.8,  # strong low-frequency motor rumble
+        bands=[-50.0 if i < 8 else -56.0 for i in range(32)],
+    ),
+    "mechanical_keyboard": NoiseProfile(
+        name="mechanical_keyboard",
+        noise_floor_db=-56.0,
+        gate_threshold_db=-38.0,
+        spectral_tilt=0.4,  # transient click presence
+        bands=[-58.0 if i < 16 else -52.0 for i in range(32)],
+    ),
+}
+
+
+class AdaptiveNoiseProfiler:
+    """Continuous low-rate, voice-aware background noise learner."""
+
+    def __init__(
+        self,
+        sample_rate: int = 48000,
+        environment: str = "quiet_room",
+        adaptation_rate: float = 0.005,  # smooth update ~3-5s time constant
+        max_rate_change_db_per_sec: float = 1.0,
+    ) -> None:
+        self.sample_rate = sample_rate
+        self.adaptation_rate = adaptation_rate
+        self.max_rate_change_db_per_sec = max_rate_change_db_per_sec
+        self.current_profile: NoiseProfile = self._load_or_create(environment)
+
+        self._n_bands = 32
+        self._band_powers = np.full(self._n_bands, 10.0 ** (self.current_profile.noise_floor_db / 10.0), dtype=np.float64)
+        self._last_update_time = time.monotonic()
+        self._consecutive_quiet_blocks = 0
+        self._learning_enabled = True
+
+    def _load_or_create(self, name: str) -> NoiseProfile:
+        path = _profiles_dir() / f"{name}.json"
+        if path.is_file():
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                prof = NoiseProfile.from_dict(data)
+                prof.sample_rate = self.sample_rate
+                return prof
+            except Exception as exc:
+                log.warning("Could not read profile %s: %s", path, exc)
+
+        if name in BUILTIN_ENVIRONMENTS:
+            base = BUILTIN_ENVIRONMENTS[name]
+            return NoiseProfile(
+                name=base.name,
+                noise_floor_db=base.noise_floor_db,
+                gate_threshold_db=base.gate_threshold_db,
+                spectral_tilt=base.spectral_tilt,
+                sample_rate=self.sample_rate,
+                bands=list(base.bands),
+            )
+        return NoiseProfile(name=name, sample_rate=self.sample_rate)
+
+    @property
+    def is_frozen(self) -> bool:
+        return self.current_profile.frozen or not self._learning_enabled
+
+    def freeze(self) -> None:
+        """Freeze adaptation so noise profile remains static."""
+        self.current_profile.frozen = True
+
+    def unfreeze(self) -> None:
+        """Resume continuous background learning."""
+        self.current_profile.frozen = False
+        self._learning_enabled = True
+
+    def update(
+        self,
+        block: np.ndarray,
+        is_voiced: bool = False,
+        speech_prob: float = 0.0,
+    ) -> bool:
+        """Feed audio block. Returns True if adaptation took place."""
+        if self.is_frozen:
+            return False
+
+        if block is None or len(block) == 0:
+            return False
+
+        # SAFE ADAPTATION RULE 1: Never learn during voiced speech or high speech probability
+        if is_voiced or speech_prob > 0.25:
+            self._consecutive_quiet_blocks = 0
+            return False
+
+        # Instantaneous RMS
+        sq_mean = float(np.mean(block * block))
+        if sq_mean < 1e-12:
+            return False
+        rms_db = 10.0 * math.log10(sq_mean)
+
+        # SAFE ADAPTATION RULE 2: Don't learn transient spikes (>16 dB above current noise floor)
+        cur_floor = self.current_profile.noise_floor_db
+        if rms_db > cur_floor + 16.0:
+            self._consecutive_quiet_blocks = 0
+            return False
+
+        self._consecutive_quiet_blocks += 1
+        # Require at least 3 consecutive quiet blocks before updating (prevents speech syllable bleed)
+        if self._consecutive_quiet_blocks < 3:
+            return False
+
+        now = time.monotonic()
+        dt = max(0.001, now - self._last_update_time)
+        self._last_update_time = now
+
+        # SAFE ADAPTATION RULE 3: Bounded rate of change per second
+        target_db = rms_db
+        max_delta = self.max_rate_change_db_per_sec * dt
+        diff = target_db - cur_floor
+        clipped_diff = max(-max_delta, min(max_delta, diff))
+        new_floor = cur_floor + self.adaptation_rate * diff
+
+        # Bound overall noise floor within physically reasonable microphone ranges
+        new_floor = max(-85.0, min(-35.0, new_floor))
+        self.current_profile.noise_floor_db = float(new_floor)
+
+        # Gate threshold tracks noise floor with 10 dB headroom (clamped between -60 and -30 dBFS)
+        self.current_profile.gate_threshold_db = float(max(-60.0, min(-30.0, new_floor + 10.0)))
+        self.current_profile.sample_count += 1
+        self.current_profile.updated_at = time.time()
+        return True
+
+    def relearn(self, duration_s: float = 1.0) -> None:
+        """Prepare for quick immediate noise capture (e.g. user requested 'relearn')."""
+        self._consecutive_quiet_blocks = 5
+        self.current_profile.sample_count = 0
+        self.unfreeze()
+
+    def switch_environment(self, name: str) -> NoiseProfile:
+        """Switch active noise profile to a named environment."""
+        self.current_profile = self._load_or_create(name)
+        self._last_update_time = time.monotonic()
+        self._consecutive_quiet_blocks = 0
+        return self.current_profile
+
+    def save(self, name: str | None = None) -> Path | None:
+        """Persist current noise profile to disk."""
+        target_name = name or self.current_profile.name
+        self.current_profile.name = target_name
+        self.current_profile.updated_at = time.time()
+        try:
+            d = _profiles_dir()
+            path = d / f"{target_name}.json"
+            path.write_text(json.dumps(self.current_profile.to_dict(), indent=2), encoding="utf-8")
+            log.info("Saved noise profile '%s' to %s", target_name, path)
+            return path
+        except Exception as exc:
+            log.warning("Could not persist noise profile '%s': %s", target_name, exc)
+            return None
+
+    def reset_to_default(self) -> None:
+        """Reset current profile to baseline preset values."""
+        name = self.current_profile.name
+        if name in BUILTIN_ENVIRONMENTS:
+            base = BUILTIN_ENVIRONMENTS[name]
+            self.current_profile.noise_floor_db = base.noise_floor_db
+            self.current_profile.gate_threshold_db = base.gate_threshold_db
+            self.current_profile.spectral_tilt = base.spectral_tilt
+        else:
+            self.current_profile.noise_floor_db = -62.0
+            self.current_profile.gate_threshold_db = -50.0
+        self.current_profile.updated_at = time.time()
+
+
+def list_noise_profiles() -> list[str]:
+    """List all available environment noise profile names."""
+    names = set(BUILTIN_ENVIRONMENTS.keys())
+    d = _profiles_dir()
+    for f in d.glob("*.json"):
+        names.add(f.stem)
+    return sorted(names)

micforge/audio/recorder.py

@@ -0,0 +1,100 @@
+"""Simple microphone recorder + file-style player used by `test` and `calibrate`."""
+from __future__ import annotations
+
+import threading
+from typing import Any, Callable
+
+import numpy as np
+
+from ..errors import DeviceError
+from .backend import get_sd
+from .devices import DeviceInfo, extra_settings
+from .metrics import LevelMeter, LevelSnapshot
+
+
+class Recorder:
+    def __init__(self, device: DeviceInfo, sample_rate: int, channel: int = 0, block: int = 480) -> None:
+        self.device, self.sr, self.channel, self.block = device, sample_rate, channel, block
+        self.meter = LevelMeter(sample_rate)
+        self._chunks: list[np.ndarray] = []
+        self._n = 0
+        self._stream: Any = None
+
+    def start(self) -> None:
+        sd = get_sd()
+        try:
+            self._stream = sd.InputStream(
+                device=self.device.index,
+                samplerate=self.sr,
+                blocksize=self.block,
+                channels=max(1, min(self.device.max_input, self.channel + 1)),
+                dtype="float32",
+                callback=self._cb,
+                extra_settings=extra_settings(self.device, "input"),
+            )
+            self._stream.start()
+        except Exception as exc:  # noqa: BLE001
+            raise DeviceError(f"Cannot open microphone '{self.device.name}': {exc}") from exc
+
+    def _cb(self, indata: np.ndarray, frames: int, _t: Any, _s: Any) -> None:
+        x = indata[:, self.channel].copy()
+        self._chunks.append(x)
+        self._n += frames
+        self.meter.update(x)
+
+    @property
+    def seconds(self) -> float:
+        return self._n / self.sr
+
+    @property
+    def level(self) -> LevelSnapshot:
+        return self.meter.snapshot
+
+    def stop(self) -> np.ndarray:
+        if self._stream is not None:
+            self._stream.stop()
+            self._stream.close()
+            self._stream = None
+        return np.concatenate(self._chunks) if self._chunks else np.zeros(0, dtype=np.float32)
+
+
+def play(
+    x: np.ndarray,
+    sample_rate: int,
+    device: DeviceInfo,
+    on_tick: Callable[[float], None] | None = None,
+) -> None:
+    """Blocking playback. Ctrl+C stops it cleanly."""
+    sd = get_sd()
+    data = np.ascontiguousarray(x, dtype=np.float32)
+    channels = max(1, min(2, device.max_output))
+    pos = [0]
+    done = threading.Event()
+
+    def cb(outdata: np.ndarray, frames: int, _t: Any, _s: Any) -> None:
+        chunk = data[pos[0] : pos[0] + frames]
+        outdata[: chunk.shape[0]] = chunk[:, None]
+        if chunk.shape[0] < frames:
+            outdata[chunk.shape[0] :] = 0
+            raise sd.CallbackStop
+        pos[0] += frames
+
+    try:
+        stream = sd.OutputStream(
+            device=device.index,
+            samplerate=sample_rate,
+            channels=channels,
+            dtype="float32",
+            callback=cb,
+            finished_callback=done.set,
+            extra_settings=extra_settings(device, "output"),
+        )
+    except Exception as exc:  # noqa: BLE001
+        raise DeviceError(f"Cannot open output '{device.name}': {exc}") from exc
+    with stream:
+        try:
+            while not done.wait(0.05):
+                if on_tick:
+                    on_tick(pos[0] / sample_rate)
+        except KeyboardInterrupt:
+            pass

micforge/audio/ring.py

@@ -0,0 +1,89 @@
+"""Thread-safe float32 ring buffer used to hand audio from the input callback to output callbacks.
+
+Lock-free Single-Producer Single-Consumer (SPSC) design:
+The write side (input callback) owns `_w`, and the read side (output callback) owns `_r`.
+Both pointers increase monotonically without wrap-around (Python arbitrary-precision integers
+never overflow 32-bit or 64-bit bounds).  Fill level is computed directly as `_w - _r`,
+completely eliminating shared mutable counters (`_n`) and cross-thread GIL race conditions
+which previously caused false buffer starvation and runaway underrun cascades.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+class RingBuffer:
+    def __init__(self, capacity: int) -> None:
+        self._cap = int(capacity)
+        self._buf = np.zeros(self._cap, dtype=np.float32)
+        self._r = 0
+        self._w = 0
+
+    @property
+    def fill(self) -> int:
+        return max(0, self._w - self._r)
+
+    def clear(self) -> None:
+        self._r = self._w
+
+    def write(self, x: np.ndarray) -> int:
+        """Append samples. Returns how many *old* samples were dropped to make room."""
+        x = np.asarray(x, dtype=np.float32)
+        if x.shape[0] > self._cap:
+            x = x[-self._cap :]
+        n = x.shape[0]
+        w = self._w
+        r = self._r
+
+        # Overflow: drop oldest samples to make room
+        dropped = max(0, (w + n) - r - self._cap)
+        if dropped:
+            self._r = r + dropped
+
+        # Copy data into the circular buffer
+        w_idx = w % self._cap
+        first = min(n, self._cap - w_idx)
+        self._buf[w_idx : w_idx + first] = x[:first]
+        if first < n:
+            self._buf[: n - first] = x[first:]
+        self._w = w + n
+        return dropped
+
+    def read(self, n: int) -> tuple[np.ndarray, int]:
+        """Read up to n samples. Returns (array of length n, zero-padded; samples actually read)."""
+        out = np.zeros(n, dtype=np.float32)
+        w = self._w
+        r = self._r
+        avail = max(0, w - r)
+        got = min(n, avail)
+        if got > 0:
+            r_idx = r % self._cap
+            first = min(got, self._cap - r_idx)
+            out[:first] = self._buf[r_idx : r_idx + first]
+            if first < got:
+                out[first:got] = self._buf[: got - first]
+            self._r = r + got
+        return out, got
+
+    def read_into(self, dest: np.ndarray) -> int:
+        """Read up to len(dest) samples directly into a pre-allocated buffer.
+
+        This avoids allocating a new array on every output callback – critical
+        for real-time audio threads where allocation → GC → click.
+        Returns the number of samples actually read; unread portion of dest is zeroed.
+        """
+        n = dest.shape[0]
+        w = self._w
+        r = self._r
+        avail = max(0, w - r)
+        got = min(n, avail)
+        if got > 0:
+            r_idx = r % self._cap
+            first = min(got, self._cap - r_idx)
+            dest[:first] = self._buf[r_idx : r_idx + first]
+            if first < got:
+                dest[first:got] = self._buf[: got - first]
+            self._r = r + got
+        if got < n:
+            dest[got:] = 0.0
+        return got