micforge 1.3.0__py3-none-any.whl

micforge/__init__.py

@@ -0,0 +1,3 @@
+"""micforge - real-time microphone clean-up for voice chat."""
+
+__version__ = "1.3.0"

micforge/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

micforge/analysis/stats.py

@@ -0,0 +1,133 @@
+"""Offline speech-signal statistics and plain-language diagnosis."""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.signal import welch
+
+_EPS = 1e-12
+
+
+@dataclass(frozen=True)
+class AudioStats:
+    duration_s: float
+    peak_db: float
+    rms_db: float
+    active_rms_db: float | None  # level while talking
+    noise_floor_db: float
+    snr_db: float | None
+    clip_samples: int
+    presence_db: float | None  # energy 2.5-8 kHz relative to 100-2.5 kHz (higher = brighter)
+    centroid_hz: float | None
+    active_pct: float
+
+
+@dataclass(frozen=True)
+class Finding:
+    level: str  # ok | warn | bad
+    text: str
+
+
+def _db(p: float) -> float:
+    return 10.0 * math.log10(max(p, _EPS))
+
+
+def analyze(x: np.ndarray, sr: int) -> AudioStats:
+    x = np.asarray(x, dtype=np.float64)
+    n = x.shape[0]
+    if n < sr // 5:
+        raise ValueError("recording too short to analyse")
+    frame = max(1, int(0.02 * sr))
+    m = n // frame
+    frames = x[: m * frame].reshape(m, frame)
+    fr_db = 10.0 * np.log10(np.maximum(np.mean(frames**2, axis=1), _EPS))
+    noise_floor = float(np.percentile(fr_db, 10))
+    loud = float(np.percentile(fr_db, 95))
+
+    has_speech = (loud - noise_floor) >= 12.0
+    active_rms = snr = presence = centroid = None
+    active_pct = 0.0
+    if has_speech:
+        thr = max(noise_floor + 10.0, loud - 30.0)
+        mask = fr_db > thr
+        active_pct = 100.0 * float(np.mean(mask))
+        if mask.any():
+            active = frames[mask]
+            active_rms = _db(float(np.mean(active**2)))
+            snr = active_rms - noise_floor
+            if active.size >= int(0.3 * sr):
+                f, p = welch(active.reshape(-1), sr, nperseg=min(1024, active.size))
+                hi_edge = min(8000.0, 0.45 * sr)
+                lo = (f >= 100) & (f < 2500)
+                hi = (f >= 2500) & (f < hi_edge)
+                if lo.any() and hi.any():
+                    presence = _db(float(p[hi].sum())) - _db(float(p[lo].sum()))
+                band = (f >= 100) & (f <= hi_edge)
+                if band.any() and p[band].sum() > 0:
+                    centroid = float(np.sum(f[band] * p[band]) / np.sum(p[band]))
+
+    return AudioStats(
+        duration_s=n / sr,
+        peak_db=_db(float(np.max(np.abs(x))) ** 2),
+        rms_db=_db(float(np.mean(x**2))),
+        active_rms_db=active_rms,
+        noise_floor_db=noise_floor,
+        snr_db=snr,
+        clip_samples=int(np.count_nonzero(np.abs(x) >= 0.999)),
+        presence_db=presence,
+        centroid_hz=centroid,
+        active_pct=active_pct,
+    )
+
+
+def band_levels_db(x: np.ndarray, sr: int, n_bands: int = 32, f_lo: float = 60.0, f_hi: float = 16000.0) -> np.ndarray:
+    """Long-term average spectrum in log-spaced bands (dB, relative scale)."""
+    f_hi = min(f_hi, 0.45 * sr)
+    f, p = welch(np.asarray(x, dtype=np.float64), sr, nperseg=2048)
+    edges = np.geomspace(f_lo, f_hi, n_bands + 1)
+    out = np.full(n_bands, -120.0)
+    for i in range(n_bands):
+        sel = (f >= edges[i]) & (f < edges[i + 1])
+        if sel.any():
+            out[i] = _db(float(p[sel].mean()))
+    return out
+
+
+def clarity_label(presence_db: float | None) -> str:
+    """Heuristic label; calibrated for typical close-mic speech, treat as a hint, not a measurement."""
+    if presence_db is None:
+        return "n/a"
+    if presence_db >= -22.0:
+        return "clear"
+    if presence_db >= -30.0:
+        return "a bit dull"
+    return "muffled"
+
+
+def diagnose(s: AudioStats) -> list[Finding]:
+    out: list[Finding] = []
+    if s.active_rms_db is None:
+        out.append(Finding("warn", "Not enough speech detected - speak louder or closer to the mic for a reliable read."))
+        return out
+    if s.clip_samples > 0 or s.peak_db > -1.0:
+        out.append(Finding("bad", "Clipping detected. Lower the mic level in system settings (and turn off mic boost)."))
+    if s.active_rms_db < -35.0:
+        out.append(Finding("warn", "Very quiet voice. Raise the mic level in system settings; the leveler can only add ~9 dB."))
+    elif s.active_rms_db > -12.0:
+        out.append(Finding("warn", "Very hot signal. Lower the mic level a little to leave headroom."))
+    if s.noise_floor_db > -40.0:
+        out.append(Finding("bad", "Very high noise floor. Use the `noisy_room` preset, or move the mic closer / away from fans."))
+    elif s.noise_floor_db > -52.0:
+        out.append(Finding("warn", "Noticeable background noise. Run `micforge calibrate` in your usual room conditions."))
+    if s.snr_db is not None and s.snr_db < 20.0:
+        out.append(Finding("warn", f"Low signal-to-noise ratio ({s.snr_db:.0f} dB). Closer mic placement helps more than any filter."))
+    label = clarity_label(s.presence_db)
+    if label == "muffled":
+        out.append(Finding("bad", "Voice sounds muffled. Try the `de_muffle` preset, and check mic position (aim at your mouth, no cloth/foam blocking it)."))
+    elif label == "a bit dull":
+        out.append(Finding("warn", "Slightly dull top end. The `discord` or `de_muffle` preset should help."))
+    if not out:
+        out.append(Finding("ok", "Signal looks healthy: good level, low noise, clear top end."))
+    return out

micforge/audio/backend.py

@@ -0,0 +1,32 @@
+"""Lazy access to sounddevice so `--help`, tests and offline commands work without PortAudio."""
+from __future__ import annotations
+
+from types import ModuleType
+
+from ..errors import AudioBackendError
+
+_sd: ModuleType | None = None
+
+
+def get_sd() -> ModuleType:
+    global _sd
+    if _sd is None:
+        try:
+            import sounddevice as sd  # noqa: PLC0415
+        except ImportError as exc:
+            raise AudioBackendError(
+                "The 'sounddevice' package is not installed.", hint="pip install sounddevice"
+            ) from exc
+        except OSError as exc:
+            raise AudioBackendError(
+                f"PortAudio library not found ({exc}).",
+                hint="Linux: sudo apt install libportaudio2   |   macOS: brew install portaudio",
+            ) from exc
+        _sd = sd
+    return _sd
+
+
+def set_backend(module: ModuleType | None) -> None:
+    """Inject a backend (used by tests)."""
+    global _sd
+    _sd = module

micforge/audio/cues.py

@@ -0,0 +1,110 @@
+"""Procedural audio feedback chimes (blip for mute, chirp for unmute).
+
+Synthesized dynamically in NumPy with zero external sound files and zero disk I/O.
+Mixed directly into the headphone/monitor sink so Discord/callers never hear them.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any
+
+import numpy as np
+
+log = logging.getLogger("micforge.cues")
+
+
+class CuePlayer:
+    """Thread-safe procedural audio cue synthesizer and mixer."""
+
+    def __init__(self, sample_rate: int = 48000, volume: float = 0.5, enabled: bool = True) -> None:
+        self.sr = sample_rate
+        self.volume = max(0.0, min(1.0, float(volume)))
+        self.enabled = enabled
+        self._buf = np.zeros(0, dtype=np.float32)
+        self._lock = threading.Lock()
+        self._cache: dict[str, np.ndarray] = {}
+        self._pregenerate()
+
+    def set_volume(self, vol: float) -> None:
+        self.volume = max(0.0, min(1.0, float(vol)))
+
+    def set_enabled(self, on: bool) -> None:
+        self.enabled = bool(on)
+
+    def _pregenerate(self) -> None:
+        """Pre-render chime waveforms into cache to avoid any runtime allocation."""
+        sr = self.sr
+        # 1. Blip (Mute): gentle descending chirp 460 Hz -> 280 Hz over 70ms
+        dur = 0.075
+        n = int(sr * dur)
+        t = np.linspace(0, dur, n, endpoint=False)
+        freq = np.linspace(460, 280, n)
+        phase = 2 * np.pi * np.cumsum(freq) / sr
+        env = np.sin(np.pi * np.linspace(0, 1, n)) ** 2
+        blip = (0.28 * np.sin(phase) * env).astype(np.float32)
+
+        # 2. Chirp (Unmute): gentle ascending chirp 280 Hz -> 540 Hz over 70ms
+        freq_up = np.linspace(280, 540, n)
+        phase_up = 2 * np.pi * np.cumsum(freq_up) / sr
+        chirp = (0.28 * np.sin(phase_up) * env).astype(np.float32)
+
+        # 3. Toggle (Bypass): subtle double-pip
+        pip_dur = 0.02
+        pip_n = int(sr * pip_dur)
+        pip_t = np.linspace(0, pip_dur, pip_n, endpoint=False)
+        pip_env = np.sin(np.pi * np.linspace(0, 1, pip_n)) ** 2
+        pip = 0.22 * np.sin(2 * np.pi * 580 * pip_t) * pip_env
+        gap = np.zeros(int(sr * 0.025), dtype=np.float32)
+        toggle = np.concatenate([pip, gap, pip]).astype(np.float32)
+
+        self._cache = {
+            "mute": blip,
+            "unmute": chirp,
+            "toggle": toggle,
+        }
+
+    def play(self, kind: str) -> None:
+        """Queue a chime to be mixed into the next outgoing headphone blocks."""
+        if not self.enabled or self.volume <= 0.0:
+            return
+        wave = self._cache.get(kind)
+        if wave is None:
+            return
+        scaled = wave * np.float32(self.volume)
+        with self._lock:
+            # Overwrite or append seamlessly
+            self._buf = scaled.copy()
+
+    def mix_into(self, out: np.ndarray) -> np.ndarray:
+        """Mix queued chime samples directly into headphone/monitor audio block."""
+        if not self.enabled or self._buf.size == 0:
+            return out
+        with self._lock:
+            if self._buf.size == 0:
+                return out
+            n = min(out.shape[0], self._buf.shape[0])
+            res = out.copy()
+            res[:n] += self._buf[:n]
+            self._buf = self._buf[n:]
+            return res
+
+    def play_standalone(self, kind: str, device: Any = None) -> None:
+        """Play a cue directly through sounddevice if headphone monitoring is not active."""
+        if not self.enabled or self.volume <= 0.0:
+            return
+        wave = self._cache.get(kind)
+        if wave is None:
+            return
+        scaled = wave * np.float32(self.volume)
+
+        def _worker():
+            try:
+                import sounddevice as sd
+
+                sd.play(scaled, samplerate=self.sr, device=device, blocking=False)
+            except Exception as exc:  # noqa: BLE001
+                log.debug("Standalone cue playback failed: %s", exc)
+
+        threading.Thread(target=_worker, daemon=True).start()
+

micforge/audio/device_watch.py

@@ -0,0 +1,237 @@
+"""Hot-plug detection and auto-recovery for audio devices."""
+from __future__ import annotations
+
+import enum
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .devices import DeviceInfo, list_devices
+
+log = logging.getLogger("micforge.device_watch")
+
+
+class DeviceEventType(str, enum.Enum):
+    DEVICE_ADDED = "device_added"
+    DEVICE_REMOVED = "device_removed"
+    DEFAULT_CHANGED = "default_changed"
+    STREAM_ERROR = "stream_error"
+    RECOVERY_STARTED = "recovery_started"
+    RECOVERY_SUCCEEDED = "recovery_succeeded"
+    RECOVERY_FAILED = "recovery_failed"
+
+
+@dataclass
+class DeviceWatchEvent:
+    event_type: DeviceEventType
+    message: str
+    device_name: str | None = None
+    device_index: int | None = None
+    timestamp: float = 0.0
+
+    def __post_init__(self) -> None:
+        if self.timestamp == 0.0:
+            self.timestamp = time.time()
+
+
+class DeviceWatcher:
+    """Monitors audio device topology changes and initiates auto-recovery on disconnects."""
+
+    def __init__(
+        self,
+        poll_interval_s: float = 1.5,
+        max_retries: int = 5,
+        backoff_base_s: float = 0.5,
+        on_recovery_attempt: Callable[[str, int | str | None], bool] | None = None,
+        on_fallback: Callable[[], None] | None = None,
+    ) -> None:
+        self.poll_interval = poll_interval_s
+        self.max_retries = max_retries
+        self.backoff_base = backoff_base_s
+        self.on_recovery_attempt = on_recovery_attempt
+        self.on_fallback = on_fallback
+
+        self._listeners: list[Callable[[DeviceWatchEvent], None]] = []
+        self._thread: threading.Thread | None = None
+        self._running = False
+        self._lock = threading.Lock()
+
+        # Cached device state
+        self._cached_inputs: set[str] = set()
+        self._cached_outputs: set[str] = set()
+        self._cached_default_in: int | None = None
+        self._cached_default_out: int | None = None
+        self._recovering = False
+
+        self._refresh_cached_state()
+
+    @property
+    def is_recovering(self) -> bool:
+        with self._lock:
+            return self._recovering
+
+    def add_listener(self, cb: Callable[[DeviceWatchEvent], None]) -> None:
+        with self._lock:
+            if cb not in self._listeners:
+                self._listeners.append(cb)
+
+    def remove_listener(self, cb: Callable[[DeviceWatchEvent], None]) -> None:
+        with self._lock:
+            if cb in self._listeners:
+                self._listeners.remove(cb)
+
+    def _emit(self, event_type: DeviceEventType, message: str, dev_name: str | None = None, dev_idx: int | None = None) -> DeviceWatchEvent:
+        evt = DeviceWatchEvent(
+            event_type=event_type,
+            message=message,
+            device_name=dev_name,
+            device_index=dev_idx,
+        )
+        log.info("DeviceWatch event [%s]: %s (dev=%s)", event_type.value, message, dev_name or "none")
+        with self._lock:
+            listeners = list(self._listeners)
+        for cb in listeners:
+            try:
+                cb(evt)
+            except Exception as exc:
+                log.debug("Listener callback exception: %s", exc)
+        return evt
+
+    def _refresh_cached_state(self) -> list[DeviceInfo]:
+        try:
+            devs = list_devices()
+            self._cached_inputs = {d.name for d in devs if d.max_input > 0}
+            self._cached_outputs = {d.name for d in devs if d.max_output > 0}
+            def_in = next((d.index for d in devs if d.is_default_input), None)
+            def_out = next((d.index for d in devs if d.is_default_output), None)
+            self._cached_default_in = def_in
+            self._cached_default_out = def_out
+            return devs
+        except Exception as exc:
+            log.debug("Device query failure in watcher: %s", exc)
+            return []
+
+    def start(self) -> None:
+        if self._running:
+            return
+        self._running = True
+        self._thread = threading.Thread(target=self._run_loop, name="micforge-dev-watch", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._running = False
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=1.0)
+        self._thread = None
+
+    def trigger_stream_error(self, stream_kind: str, device_name: str | None = None) -> None:
+        """Called by audio engine if a stream callback or write raises a device error."""
+        self._emit(
+            DeviceEventType.STREAM_ERROR,
+            f"Audio stream error on {stream_kind} stream ({device_name or 'unknown device'})",
+            dev_name=device_name,
+        )
+        self.schedule_recovery(stream_kind, device_name)
+
+    def schedule_recovery(self, kind: str, target_device: int | str | None = None) -> None:
+        """Asynchronously initiate bounded retry recovery with backoff."""
+        if self._recovering:
+            return
+        threading.Thread(target=self._perform_recovery, args=(kind, target_device), daemon=True).start()
+
+    def _perform_recovery(self, kind: str, target_device: int | str | None) -> bool:
+        with self._lock:
+            if self._recovering:
+                return False
+            self._recovering = True
+
+        self._emit(DeviceEventType.RECOVERY_STARTED, f"Starting auto-recovery for {kind}...", dev_name=str(target_device))
+
+        recovered = False
+        for attempt in range(1, self.max_retries + 1):
+            delay = self.backoff_base * (1.6 ** (attempt - 1))
+            log.info("Recovery attempt %d/%d in %.2fs...", attempt, self.max_retries, delay)
+            time.sleep(delay)
+
+            try:
+                # Refresh hardware list
+                self._refresh_cached_state()
+                if self.on_recovery_attempt is not None:
+                    success = self.on_recovery_attempt(kind, target_device)
+                    if success:
+                        self._emit(
+                            DeviceEventType.RECOVERY_SUCCEEDED,
+                            f"Successfully recovered {kind} stream on attempt {attempt}!",
+                            dev_name=str(target_device),
+                        )
+                        recovered = True
+                        break
+            except Exception as exc:
+                log.warning("Recovery attempt %d failed: %s", attempt, exc)
+
+        if not recovered:
+            self._emit(
+                DeviceEventType.RECOVERY_FAILED,
+                f"Auto-recovery failed after {self.max_retries} attempts. Engaging safe passthrough fallback.",
+                dev_name=str(target_device),
+            )
+            if self.on_fallback is not None:
+                try:
+                    self.on_fallback()
+                except Exception as exc:
+                    log.error("Fallback handler error: %s", exc)
+
+        with self._lock:
+            self._recovering = False
+        return recovered
+
+    def check_devices(self, devs: list[DeviceInfo] | None = None) -> list[DeviceWatchEvent]:
+        """Check given (or current) device list against cached state, emitting events on changes."""
+        if devs is None:
+            devs = list_devices()
+        curr_inputs = {d.name for d in devs if d.max_input > 0}
+        curr_outputs = {d.name for d in devs if d.max_output > 0}
+        curr_def_in = next((d.index for d in devs if d.is_default_input), None)
+        curr_def_out = next((d.index for d in devs if d.is_default_output), None)
+
+        events: list[DeviceWatchEvent] = []
+        removed_in = self._cached_inputs - curr_inputs
+        for name in removed_in:
+            events.append(self._emit(DeviceEventType.DEVICE_REMOVED, f"Input device disconnected: {name}", dev_name=name))
+
+        removed_out = self._cached_outputs - curr_outputs
+        for name in removed_out:
+            events.append(self._emit(DeviceEventType.DEVICE_REMOVED, f"Output device disconnected: {name}", dev_name=name))
+
+        added_in = curr_inputs - self._cached_inputs
+        for name in added_in:
+            events.append(self._emit(DeviceEventType.DEVICE_ADDED, f"New input device detected: {name}", dev_name=name))
+
+        added_out = curr_outputs - self._cached_outputs
+        for name in added_out:
+            events.append(self._emit(DeviceEventType.DEVICE_ADDED, f"New output device detected: {name}", dev_name=name))
+
+        if curr_def_in != self._cached_default_in or curr_def_out != self._cached_default_out:
+            events.append(self._emit(
+                DeviceEventType.DEFAULT_CHANGED,
+                f"Default audio endpoint changed (in: {curr_def_in}, out: {curr_def_out})",
+            ))
+
+        self._cached_inputs = curr_inputs
+        self._cached_outputs = curr_outputs
+        self._cached_default_in = curr_def_in
+        self._cached_default_out = curr_def_out
+        return events
+
+    def _run_loop(self) -> None:
+        while self._running:
+            time.sleep(self.poll_interval)
+            if not self._running or self._recovering:
+                continue
+
+            try:
+                self.check_devices()
+            except Exception as exc:
+                log.debug("Device watcher check error: %s", exc)

micforge/audio/devices.py

@@ -0,0 +1,160 @@
+"""Device discovery and selection, with host-API de-duplication and virtual-cable detection."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from ..errors import DeviceError
+from .backend import get_sd
+
+HOSTAPI_PRIORITY = [
+    "Windows WASAPI",
+    "Core Audio",
+    "JACK Audio Connection Kit",
+    "ALSA",
+    "Windows DirectSound",
+    "MME",
+    "OSS",
+    "Windows WDM-KS",
+]
+
+# Playback-side names of virtual cables, best first. Discord then picks the matching *recording* end.
+VIRTUAL_OUTPUT_PATTERNS = [
+    r"cable input",
+    r"vb-audio",
+    r"voicemeeter (aux )?input",
+    r"blackhole",
+    r"soundflower",
+    r"loopback",
+    r"virtual",
+    r"null",
+]
+
+
+@dataclass(frozen=True)
+class DeviceInfo:
+    index: int
+    name: str
+    hostapi: str
+    max_input: int
+    max_output: int
+    default_rate: float
+    is_default_input: bool
+    is_default_output: bool
+
+    @property
+    def is_virtual(self) -> bool:
+        low = self.name.lower()
+        return any(re.search(p, low) for p in VIRTUAL_OUTPUT_PATTERNS)
+
+    @property
+    def is_wasapi(self) -> bool:
+        return "WASAPI" in self.hostapi
+
+
+def _priority(api: str) -> int:
+    return HOSTAPI_PRIORITY.index(api) if api in HOSTAPI_PRIORITY else len(HOSTAPI_PRIORITY)
+
+
+def list_devices(all_apis: bool = False) -> list[DeviceInfo]:
+    """All devices; by default only those on the best host API available (hides MME/DirectSound dupes)."""
+    sd = get_sd()
+    apis = sd.query_hostapis()
+
+    # Identify default devices from the highest-priority Host API available.
+    # On Windows, this ensures WASAPI default devices are selected rather than legacy MME defaults.
+    sorted_apis = sorted(apis, key=lambda a: _priority(str(a.get("name", ""))))
+    best_in = next(
+        (a["default_input_device"] for a in sorted_apis if a.get("default_input_device", -1) >= 0),
+        -1,
+    )
+    best_out = next(
+        (a["default_output_device"] for a in sorted_apis if a.get("default_output_device", -1) >= 0),
+        -1,
+    )
+
+    default_in, default_out = sd.default.device
+    effective_in = best_in if best_in >= 0 else default_in
+    effective_out = best_out if best_out >= 0 else default_out
+
+    infos = []
+    for i, d in enumerate(sd.query_devices()):
+        infos.append(
+            DeviceInfo(
+                index=i,
+                name=str(d["name"]),
+                hostapi=str(apis[d["hostapi"]]["name"]),
+                max_input=int(d["max_input_channels"]),
+                max_output=int(d["max_output_channels"]),
+                default_rate=float(d["default_samplerate"]),
+                is_default_input=(i == effective_in),
+                is_default_output=(i == effective_out),
+            )
+        )
+    if all_apis or not infos:
+        return infos
+    best = min((_priority(d.hostapi) for d in infos), default=0)
+    # keep the best API, but never hide the system default device
+    return [d for d in infos if _priority(d.hostapi) == best or d.is_default_input or d.is_default_output]
+
+
+def _usable(d: DeviceInfo, kind: str) -> bool:
+    return (d.max_input if kind == "input" else d.max_output) > 0
+
+
+def find_device(spec: Any, kind: str, devices: list[DeviceInfo] | None = None) -> DeviceInfo:
+    """Resolve an index / name substring / None (=default) to a device."""
+    if kind not in ("input", "output"):
+        raise ValueError(kind)
+    pool = devices if devices is not None else list_devices()
+    candidates = [d for d in pool if _usable(d, kind)]
+    if not candidates:
+        raise DeviceError(f"No {kind} devices found.", hint="Plug one in, or run `micforge doctor`.")
+
+    if spec in (None, ""):
+        defaults = [d for d in candidates if (d.is_default_input if kind == "input" else d.is_default_output)]
+        if defaults:
+            defaults.sort(key=lambda d: (_priority(d.hostapi), d.index))
+            return defaults[0]
+        candidates.sort(key=lambda d: (_priority(d.hostapi), d.index))
+        return candidates[0]
+
+    if isinstance(spec, int) or (isinstance(spec, str) and spec.strip().isdigit()):
+        idx = int(spec)
+        for d in get_all(devices):
+            if d.index == idx and _usable(d, kind):
+                return d
+        raise DeviceError(f"Device index {idx} is not a valid {kind} device.", hint="See `micforge devices`.")
+
+    needle = str(spec).lower()
+    matches = [d for d in get_all(devices) if needle in d.name.lower() and _usable(d, kind)]
+    if not matches:
+        raise DeviceError(f"No {kind} device matches {spec!r}.", hint="See `micforge devices`.")
+    matches.sort(key=lambda d: (_priority(d.hostapi), d.index))
+    return matches[0]
+
+
+def get_all(devices: list[DeviceInfo] | None) -> list[DeviceInfo]:
+    return devices if devices is not None else list_devices(all_apis=True)
+
+
+def detect_virtual_output(devices: list[DeviceInfo] | None = None) -> DeviceInfo | None:
+    pool = [d for d in get_all(devices) if d.max_output > 0]
+    for pat in VIRTUAL_OUTPUT_PATTERNS:
+        hits = [d for d in pool if re.search(pat, d.name.lower())]
+        if hits:
+            hits.sort(key=lambda d: (_priority(d.hostapi), d.index))
+            return hits[0]
+    return None
+
+
+def extra_settings(device: DeviceInfo, kind: str):
+    """WASAPI shared-mode auto-conversion lets us run at 48 kHz regardless of the mixer format."""
+    sd = get_sd()
+    if device.is_wasapi and hasattr(sd, "WasapiSettings"):
+        try:
+            return sd.WasapiSettings(auto_convert=True)
+        except TypeError:
+            return None
+    return None