sybl 0.1.0__py3-none-any.whl

sybl/__init__.py

@@ -0,0 +1,3 @@
+"""sybl — open-source BYOK voice dictation."""
+
+__version__ = "0.1.0"

sybl/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m sybl`."""
+
+from sybl.cli import app
+
+app()

sybl/audio/__init__.py

@@ -0,0 +1,38 @@
+"""Audio capture pipeline (Phase 1)."""
+
+from sybl.audio.debug import (
+    debug_recording_dir,
+    default_recording_path,
+    save_wav,
+)
+from sybl.audio.devices import list_input_devices, resolve_device
+from sybl.audio.errors import (
+    AudioError,
+    DeviceNotFoundError,
+    SessionError,
+    StreamError,
+)
+from sybl.audio.session import AudioCaptureSession
+from sybl.audio.types import (
+    TARGET_SAMPLE_RATE,
+    AudioChunk,
+    CaptureStats,
+    DeviceInfo,
+)
+
+__all__ = [
+    "TARGET_SAMPLE_RATE",
+    "AudioCaptureSession",
+    "AudioChunk",
+    "AudioError",
+    "CaptureStats",
+    "DeviceInfo",
+    "DeviceNotFoundError",
+    "SessionError",
+    "StreamError",
+    "default_recording_path",
+    "debug_recording_dir",
+    "list_input_devices",
+    "resolve_device",
+    "save_wav",
+]

sybl/audio/debug.py

@@ -0,0 +1,41 @@
+"""Debug utilities for audio capture."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+
+from sybl.audio.types import TARGET_SAMPLE_RATE
+from sybl.config.paths import state_dir
+
+DEBUG_RECORDING_DIRNAME = "debug recording"
+LAST_RECORDING_FILENAME = "last_recording.wav"
+
+
+def debug_recording_dir() -> Path:
+    path = state_dir() / DEBUG_RECORDING_DIRNAME
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def default_recording_path() -> Path:
+    return debug_recording_dir() / LAST_RECORDING_FILENAME
+
+
+def timestamped_recording_path() -> Path:
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    return debug_recording_dir() / f"recording_{stamp}.wav"
+
+
+def save_wav(
+    path: Path,
+    pcm: bytes,
+    sample_rate: int = TARGET_SAMPLE_RATE,
+) -> None:
+    """Write mono int16 PCM bytes to a WAV file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    samples = np.frombuffer(pcm, dtype=np.int16)
+    sf.write(path, samples, sample_rate, subtype="PCM_16")

sybl/audio/devices.py

@@ -0,0 +1,224 @@
+"""Input device discovery and resolution."""
+
+from __future__ import annotations
+
+import re
+import sys
+
+import sounddevice as sd
+
+from sybl.audio.errors import DeviceNotFoundError
+from sybl.audio.types import TARGET_SAMPLE_RATE, DeviceInfo
+
+
+def _normalize_device_name(name: str) -> str:
+    return re.sub(r"\s+", " ", name.strip().lower())
+
+
+def _hostapi_rank(hostapi_index: int) -> int:
+    hostapis = sd.query_hostapis()
+    api_name = str(hostapis[hostapi_index]["name"]).lower()
+    if sys.platform == "win32":
+        for rank, key in enumerate(("wasapi", "wdm", "directsound", "mme")):
+            if key in api_name:
+                return rank
+        return 99
+    if sys.platform == "darwin":
+        return 0 if "core" in api_name else 1
+    return 0 if "alsa" in api_name or "jack" in api_name else 1
+
+
+def _can_open_input(device_index: int, samplerate: float) -> bool:
+    for rate in (int(samplerate), TARGET_SAMPLE_RATE, 44100, 48000):
+        try:
+            sd.check_input_settings(device=device_index, channels=1, samplerate=rate)
+            return True
+        except Exception:
+            continue
+    try:
+        sd.check_input_settings(device=device_index, channels=1)
+        return True
+    except Exception:
+        return False
+
+
+def _dedupe_devices(devices: list[DeviceInfo]) -> list[DeviceInfo]:
+    best_by_name: dict[str, DeviceInfo] = {}
+    rank_by_name: dict[str, tuple[int, int, int]] = {}
+
+    for device in devices:
+        key = _normalize_device_name(device.name)
+        hostapi = sd.query_devices(device.index)["hostapi"]
+        rank = (
+            0 if device.is_default else 1,
+            _hostapi_rank(int(hostapi)),
+            device.index,
+        )
+        existing = rank_by_name.get(key)
+        if existing is None or rank < existing:
+            best_by_name[key] = device
+            rank_by_name[key] = rank
+
+    return sorted(best_by_name.values(), key=lambda d: (not d.is_default, d.index))
+
+
+def _wasapi_hostapi_index() -> int | None:
+    if sys.platform != "win32":
+        return None
+    for index, hostapi in enumerate(sd.query_hostapis()):
+        if "wasapi" in str(hostapi["name"]).lower():
+            return index
+    return None
+
+
+def _is_likely_microphone(name: str) -> bool:
+    lowered = name.lower()
+    excluded = (
+        "stereo mix",
+        "loopback",
+        "wave out mix",
+        "what u hear",
+        "pc speaker",
+        "sound mapper",
+        "primary sound capture driver",
+        "mapper - output",
+        "input ()",
+    )
+    if any(token in lowered for token in excluded):
+        return False
+    if lowered.endswith(" output") or lowered.endswith(" output)"):
+        return False
+    return True
+
+
+def list_input_devices(*, available_only: bool = True) -> list[DeviceInfo]:
+    """Return input-capable audio devices, optionally filtered to openable mics."""
+    default_input = sd.default.device[0]
+    wasapi_index = _wasapi_hostapi_index()
+    devices: list[DeviceInfo] = []
+
+    for index, device in enumerate(sd.query_devices()):
+        if device["max_input_channels"] <= 0:
+            continue
+        if wasapi_index is not None and int(device["hostapi"]) != wasapi_index:
+            continue
+        name = str(device["name"])
+        if available_only and not _is_likely_microphone(name):
+            continue
+        devices.append(
+            DeviceInfo(
+                index=index,
+                name=name,
+                default_samplerate=float(device["default_samplerate"]),
+                max_input_channels=int(device["max_input_channels"]),
+                is_default=index == default_input,
+            )
+        )
+
+    if available_only:
+        devices = [
+            device
+            for device in devices
+            if _can_open_input(device.index, device.default_samplerate)
+        ]
+        devices = _dedupe_devices(devices)
+        devices = _mark_default_device(devices, default_input)
+
+    return devices
+
+
+def _mark_default_device(
+    devices: list[DeviceInfo],
+    default_input: int | None,
+) -> list[DeviceInfo]:
+    if not devices:
+        return devices
+    if any(device.is_default for device in devices):
+        return devices
+
+    default_name = ""
+    if default_input is not None and default_input >= 0:
+        default_name = _normalize_device_name(get_device_name(int(default_input)))
+
+    marked: list[DeviceInfo] = []
+    best_index: int | None = None
+    for device in devices:
+        name = _normalize_device_name(device.name)
+        if default_name and (
+            name == default_name or default_name in name or name in default_name
+        ):
+            best_index = device.index
+            break
+
+    if best_index is None:
+        best_index = devices[0].index
+
+    for device in devices:
+        marked.append(
+            DeviceInfo(
+                index=device.index,
+                name=device.name,
+                default_samplerate=device.default_samplerate,
+                max_input_channels=device.max_input_channels,
+                is_default=device.index == best_index,
+            )
+        )
+    return marked
+
+
+def _format_device_list(devices: list[DeviceInfo]) -> str:
+    if not devices:
+        return "(no input devices found)"
+    lines = [f"  [{d.index}] {d.name}" for d in devices]
+    return "\n".join(lines)
+
+
+def resolve_device(spec: str | None) -> int:
+    """Resolve a device spec (None, index, or name substring) to a device index."""
+    devices = list_input_devices()
+
+    if spec is None or spec.strip() == "":
+        default_index = sd.default.device[0]
+        available_indices = {d.index for d in devices}
+        if default_index in available_indices:
+            return int(default_index)
+        if devices:
+            default_device = next((d for d in devices if d.is_default), devices[0])
+            return default_device.index
+        raise DeviceNotFoundError(
+            "No usable input device found.\n"
+            f"Available devices:\n{_format_device_list(devices)}"
+        )
+
+    spec_stripped = spec.strip()
+
+    if spec_stripped.isdigit():
+        index = int(spec_stripped)
+        device_indices = {d.index for d in devices}
+        if index not in device_indices:
+            raise DeviceNotFoundError(
+                f"Device index {index} not found.\n"
+                f"Available devices:\n{_format_device_list(devices)}"
+            )
+        return index
+
+    spec_lower = spec_stripped.lower()
+    matches = [d for d in devices if spec_lower in d.name.lower()]
+    if not matches:
+        raise DeviceNotFoundError(
+            f"No input device matching {spec_stripped!r}.\n"
+            f"Available devices:\n{_format_device_list(devices)}"
+        )
+
+    exact = [d for d in matches if d.name.lower() == spec_lower]
+    if exact:
+        return exact[0].index
+
+    matches.sort(key=lambda d: len(d.name))
+    return matches[0].index
+
+
+def get_device_name(device_index: int) -> str:
+    """Return the human-readable name for a device index."""
+    device = sd.query_devices(device_index)
+    return str(device["name"])

sybl/audio/errors.py

@@ -0,0 +1,17 @@
+"""Audio capture exceptions."""
+
+
+class AudioError(Exception):
+    """Base exception for audio capture errors."""
+
+
+class DeviceNotFoundError(AudioError):
+    """Raised when the configured input device cannot be resolved."""
+
+
+class StreamError(AudioError):
+    """Raised when the audio stream fails or is interrupted."""
+
+
+class SessionError(AudioError):
+    """Raised when session lifecycle operations are invalid."""

sybl/audio/metering.py

@@ -0,0 +1,77 @@
+"""Signal level metering."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+INT16_MAX = 32768.0
+SILENCE_DBFS = -80.0
+METER_FLOOR_DBFS = -55.0
+METER_CEILING_DBFS = -10.0
+
+
+def compute_rms(pcm: bytes) -> float:
+    """Return normalized RMS level in 0.0–1.0 from int16 PCM bytes."""
+    if not pcm:
+        return 0.0
+    samples = np.frombuffer(pcm, dtype=np.int16).astype(np.float64)
+    if samples.size == 0:
+        return 0.0
+    rms = float(np.sqrt(np.mean(samples**2)))
+    return min(rms / INT16_MAX, 1.0)
+
+
+def compute_peak(pcm: bytes) -> float:
+    """Return normalized peak level in 0.0–1.0 from int16 PCM bytes."""
+    if not pcm:
+        return 0.0
+    samples = np.frombuffer(pcm, dtype=np.int16)
+    if samples.size == 0:
+        return 0.0
+    peak = float(np.max(np.abs(samples.astype(np.int32))))
+    return min(peak / INT16_MAX, 1.0)
+
+
+def level_to_dbfs(normalized: float) -> float:
+    """Convert a normalized 0–1 level to dBFS."""
+    if normalized <= 0.0:
+        return SILENCE_DBFS
+    return max(SILENCE_DBFS, 20.0 * math.log10(normalized))
+
+
+def pcm_peak_dbfs(pcm: bytes) -> float:
+    return level_to_dbfs(compute_peak(pcm))
+
+
+def display_level_from_dbfs(
+    dbfs: float,
+    *,
+    floor_dbfs: float = METER_FLOOR_DBFS,
+    ceiling_dbfs: float = METER_CEILING_DBFS,
+) -> float:
+    """Map dBFS into 0.0–1.0 for a responsive level meter."""
+    if dbfs <= floor_dbfs:
+        return 0.0
+    if dbfs >= ceiling_dbfs:
+        return 1.0
+    return (dbfs - floor_dbfs) / (ceiling_dbfs - floor_dbfs)
+
+
+def level_from_display(display: float) -> float:
+    """Convert smoothed 0–1 meter level back to dBFS for display."""
+    return METER_FLOOR_DBFS + display * (METER_CEILING_DBFS - METER_FLOOR_DBFS)
+
+
+def apply_meter_ballistics(
+    current: float,
+    new_peak: float,
+    *,
+    attack: float = 0.55,
+    release: float = 0.12,
+) -> float:
+    """Fast attack, slower release — snappy but readable meter."""
+    if new_peak >= current:
+        return current + (new_peak - current) * attack
+    return current + (new_peak - current) * release

sybl/audio/resample.py

@@ -0,0 +1,25 @@
+"""PCM resampling to the STT target format."""
+
+from __future__ import annotations
+
+import numpy as np
+import soxr
+
+from sybl.audio.types import TARGET_SAMPLE_RATE
+
+
+def resample_pcm(
+    pcm: bytes,
+    source_rate: int,
+    target_rate: int = TARGET_SAMPLE_RATE,
+) -> bytes:
+    """Resample mono int16 PCM from source_rate to target_rate."""
+    if source_rate == target_rate:
+        return pcm
+    if not pcm:
+        return b""
+
+    samples = np.frombuffer(pcm, dtype=np.int16).astype(np.float32)
+    resampled = soxr.resample(samples, source_rate, target_rate, quality="HQ")
+    clipped = np.clip(resampled, -32768, 32767).astype(np.int16)
+    return clipped.tobytes()