audio-transcript-mcp 0.1.0__py3-none-any.whl

audio_transcript_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Real-time audio transcription MCP server."""
+
+__version__ = "0.1.0"

audio_transcript_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m audio_transcript_mcp`."""
+
+from audio_transcript_mcp.server import main
+
+main()

audio_transcript_mcp/audio_utils.py

@@ -0,0 +1,15 @@
+"""Audio format conversion utilities."""
+
+import numpy as np
+
+
+def float32_to_int16(data: bytes) -> bytes:
+    """Convert float32 PCM bytes to int16 PCM bytes."""
+    arr = np.frombuffer(data, dtype=np.float32)
+    return np.clip(arr * 32767, -32768, 32767).astype(np.int16).tobytes()
+
+
+def stereo_to_mono_f32(data: bytes, channels: int = 2) -> bytes:
+    """Downmix multi-channel float32 to mono by averaging channels."""
+    arr = np.frombuffer(data, dtype=np.float32).reshape(-1, channels)
+    return arr.mean(axis=1).astype(np.float32).tobytes()

audio_transcript_mcp/backends/__init__.py

@@ -0,0 +1,12 @@
+"""STT backend factory."""
+
+from audio_transcript_mcp.backends.deepgram import DeepgramBackend
+from audio_transcript_mcp.backends.whisper import WhisperBackend
+
+
+def create_backend(backend_type, label, sample_rate, channels, is_float32, buf, config):
+    """Create a backend instance based on type string."""
+    if backend_type == "local":
+        return WhisperBackend(label, sample_rate, channels, is_float32, buf, config)
+    else:
+        return DeepgramBackend(label, sample_rate, channels, is_float32, buf, config)

audio_transcript_mcp/backends/deepgram.py

@@ -0,0 +1,91 @@
+"""Deepgram WebSocket STT backend."""
+
+import json
+import threading
+
+from audio_transcript_mcp.audio_utils import float32_to_int16
+
+
+class DeepgramBackend:
+    """Streams audio to Deepgram via WebSocket. One instance per audio source."""
+
+    def __init__(self, label, sample_rate, channels, is_float32, buf, config):
+        self.label = label
+        self.sample_rate = sample_rate
+        self.channels = channels
+        self._is_float32 = is_float32
+        self._buf = buf
+        self._language = config.get("deepgram_language", "ru")
+        self._api_key = config.get("deepgram_api_key", "")
+        self._model = config.get("deepgram_model", "nova-3")
+        self._utterance_end_ms = config.get("deepgram_utterance_end_ms", "2500")
+        self._endpointing = config.get("deepgram_endpointing", "500")
+        self._ws = None
+        self._recv_thread = None
+        self._recv_stop = threading.Event()
+
+    def connect(self):
+        from websockets.sync.client import connect as ws_connect
+        url = (
+            f"wss://api.deepgram.com/v1/listen"
+            f"?encoding=linear16"
+            f"&sample_rate={self.sample_rate}"
+            f"&channels={self.channels}"
+            f"&language={self._language}"
+            f"&model={self._model}"
+            f"&punctuate=true"
+            f"&smart_format=true"
+            f"&interim_results=true"
+            f"&utterance_end_ms={self._utterance_end_ms}"
+            f"&endpointing={self._endpointing}"
+        )
+        headers = {"Authorization": f"Token {self._api_key}"}
+        try:
+            self._ws = ws_connect(url, additional_headers=headers)
+        except Exception:
+            return False
+
+        self._recv_stop.clear()
+        self._recv_thread = threading.Thread(target=self._receiver, daemon=True)
+        self._recv_thread.start()
+        return True
+
+    def send(self, data):
+        """Send audio chunk. Converts float32 to int16 if needed."""
+        if self._is_float32:
+            data = float32_to_int16(data)
+        try:
+            self._ws.send(data)
+            return True
+        except Exception:
+            return False
+
+    def close(self):
+        self._recv_stop.set()
+        try:
+            self._ws.send(json.dumps({"type": "CloseStream"}))
+            self._ws.close()
+        except Exception:
+            pass
+        if self._recv_thread:
+            self._recv_thread.join(timeout=2)
+
+    def _receiver(self):
+        while not self._recv_stop.is_set():
+            try:
+                raw = self._ws.recv(timeout=1.0)
+            except TimeoutError:
+                continue
+            except Exception:
+                break
+            if not isinstance(raw, str):
+                continue
+            try:
+                msg = json.loads(raw)
+            except json.JSONDecodeError:
+                continue
+            ch = msg.get("channel", {})
+            alt = ch.get("alternatives", [{}])[0]
+            text = alt.get("transcript", "").strip()
+            if text and msg.get("is_final"):
+                self._buf.add(self.label, text)

audio_transcript_mcp/backends/whisper.py

@@ -0,0 +1,182 @@
+"""Local faster-whisper STT backend."""
+
+import os
+import threading
+import time
+
+import numpy as np
+
+WHISPER_DEBUG = os.environ.get("WHISPER_DEBUG", "").lower() in ("1", "true", "yes")
+
+from audio_transcript_mcp.audio_utils import stereo_to_mono_f32
+
+try:
+    from faster_whisper import WhisperModel
+except ImportError:
+    WhisperModel = None
+
+try:
+    import soxr
+except ImportError:
+    soxr = None
+
+
+class WhisperBackend:
+    """Accumulates audio chunks and transcribes locally with faster-whisper."""
+
+    _model = None
+    _model_lock = threading.Lock()
+
+    def __init__(self, label, sample_rate, channels, is_float32, buf, config):
+        self.label = label
+        self.sample_rate = sample_rate
+        self.channels = channels
+        self._is_float32 = is_float32
+        self._buf = buf
+        self._model_name = config.get("whisper_model", "large-v3")
+        self._device = config.get("whisper_device", "cuda")
+        self._language = config.get("whisper_language", "")
+        self._chunk_sec = config.get("whisper_chunk_sec", 5.0)
+        self._overlap_sec = config.get("whisper_overlap_sec", 2.0)
+        self._pcm_buf = bytearray()
+        # mono float32 = 4 bytes/sample
+        self._chunk_bytes = int(self._chunk_sec * sample_rate * 4)
+        self._overlap_bytes = int(self._overlap_sec * sample_rate * 4)
+        self._step_bytes = self._chunk_bytes - self._overlap_bytes
+        self._prev_words: list[str] = []
+
+    @classmethod
+    def _ensure_model(cls, buf, model_name, device):
+        with cls._model_lock:
+            if cls._model is not None and cls._model.model.model_is_loaded:
+                return
+            if cls._model is not None:
+                buf.add("system", f"[Reloading whisper model to {device}...]")
+                cls._model.model.load_model()
+                buf.add("system", "[Whisper model reloaded]")
+            else:
+                buf.add("system", f"[Loading whisper model '{model_name}' on {device}...]")
+                cls._model = WhisperModel(
+                    model_name,
+                    device=device,
+                    compute_type="float16" if device == "cuda" else "int8",
+                )
+                buf.add("system", "[Whisper model loaded]")
+
+    def connect(self):
+        try:
+            self._ensure_model(self._buf, self._model_name, self._device)
+            return True
+        except Exception as exc:
+            self._buf.add(self.label, f"[ERROR: whisper load failed: {exc}]")
+            return False
+
+    def send(self, data):
+        """Accumulate audio. Converts to mono float32 internally."""
+        if self._is_float32:
+            if self.channels >= 2:
+                data = stereo_to_mono_f32(data, self.channels)
+        else:
+            arr = np.frombuffer(data, dtype=np.int16).astype(np.float32) / 32768.0
+            if self.channels >= 2:
+                arr = arr.reshape(-1, self.channels).mean(axis=1)
+            data = arr.tobytes()
+        self._pcm_buf.extend(data)
+
+        if len(self._pcm_buf) >= self._chunk_bytes:
+            chunk = bytes(self._pcm_buf[:self._chunk_bytes])
+            self._pcm_buf = self._pcm_buf[self._step_bytes:]
+            try:
+                self._transcribe(chunk)
+            except Exception as exc:
+                self._buf.add(self.label, f"[TRANSCRIBE ERROR: {exc}]")
+        return True
+
+    def close(self):
+        if len(self._pcm_buf) > self.sample_rate:
+            self._transcribe(bytes(self._pcm_buf), is_tail=True)
+        self._pcm_buf.clear()
+
+    def _transcribe(self, mono_f32, is_tail=False):
+        audio = np.frombuffer(mono_f32, dtype=np.float32)
+        duration_sec = len(audio) / self.sample_rate
+
+        if self.sample_rate != 16000:
+            audio = soxr.resample(audio, self.sample_rate, 16000, quality="HQ").astype(np.float32)
+
+        peak = float(np.max(np.abs(audio)))
+        rms = float(np.sqrt(np.mean(audio ** 2)))
+
+        if WHISPER_DEBUG:
+            self._buf.add("debug", f"[chunk {duration_sec:.1f}s | peak={peak:.4f} rms={rms:.4f}]")
+
+        if peak < 0.01:
+            if WHISPER_DEBUG:
+                self._buf.add("debug", "[skipped: silence]")
+            return
+
+        lang = self._language or None
+        t0 = time.monotonic()
+        segments, info = self._model.transcribe(
+            audio,
+            language=lang,
+            beam_size=3,
+            vad_filter=True,
+            vad_parameters=dict(min_silence_duration_ms=500),
+            condition_on_previous_text=False,
+        )
+
+        step_sec = self._chunk_sec - self._overlap_sec
+        all_segs = []
+        texts = []
+        for seg in segments:
+            all_segs.append(seg)
+            if not is_tail and self._overlap_sec > 0 and seg.start >= step_sec:
+                break
+            if seg.no_speech_prob > 0.5:
+                if WHISPER_DEBUG:
+                    self._buf.add("debug", f"[hallucination filtered: nsp={seg.no_speech_prob:.2f}] {seg.text.strip()}")
+                continue
+            text = seg.text.strip()
+            if text:
+                texts.append(text)
+        elapsed = time.monotonic() - t0
+
+        if WHISPER_DEBUG:
+            seg_details = " | ".join(
+                f"[{s.start:.1f}-{s.end:.1f} p={s.avg_logprob:.2f} nsp={s.no_speech_prob:.2f}] {s.text.strip()}"
+                for s in all_segs
+            )
+            self._buf.add("debug",
+                f"[whisper {elapsed:.2f}s | lang={info.language} prob={info.language_probability:.2f} "
+                f"| segs={len(all_segs)} kept={len(texts)}] {seg_details}"
+            )
+
+        if not texts:
+            return
+
+        combined = " ".join(texts)
+        words = combined.split()
+
+        if self._prev_words and self._overlap_sec > 0:
+            before = len(words)
+            words = self._strip_overlap(self._prev_words, words)
+            if WHISPER_DEBUG and before != len(words):
+                self._buf.add("debug", f"[dedup: stripped {before - len(words)} words]")
+
+        self._prev_words = combined.split()
+        if words:
+            self._buf.add(self.label, " ".join(words))
+
+    @staticmethod
+    def _strip_overlap(prev, new):
+        """Remove the longest prefix of `new` that matches a suffix of `prev`."""
+        def norm(w):
+            return w.strip(".,!?;:\"'()[]{}«»\u2014\u2013-").lower()
+
+        max_check = min(len(prev), len(new), 12)
+        best = 0
+        for n in range(1, max_check + 1):
+            if all(norm(a) == norm(b) for a, b in zip(prev[-n:], new[:n])):
+                best = n
+        return new[best:] if best > 0 else new

audio_transcript_mcp/recorder/__init__.py

@@ -0,0 +1,5 @@
+"""Audio recorder module."""
+
+from audio_transcript_mcp.recorder.opus import StereoOpusRecorder
+
+__all__ = ["StereoOpusRecorder"]

audio_transcript_mcp/recorder/opus.py

@@ -0,0 +1,64 @@
+"""Stereo Opus streaming recorder using PyOgg."""
+
+import pathlib
+import threading
+
+import numpy as np
+
+
+class StereoOpusRecorder:
+    """Collects mono int16@48kHz from two sources into one stereo opus file.
+
+    Left channel = "me" (microphone), Right channel = "others" (system audio).
+    Both worker threads call write() concurrently; internal lock keeps it safe.
+    """
+
+    FRAME_SAMPLES = 960  # 20ms at 48kHz
+
+    def __init__(self, path: pathlib.Path):
+        from pyogg import OggOpusWriter, OpusBufferedEncoder
+
+        enc = OpusBufferedEncoder()
+        enc.set_application("audio")
+        enc.set_sampling_frequency(48000)
+        enc.set_channels(2)
+        enc.set_frame_size(20)  # ms
+
+        self._writer = OggOpusWriter(str(path), enc)
+        self._bufs = {"me": bytearray(), "others": bytearray()}
+        self._lock = threading.Lock()
+        self._frame_bytes = self.FRAME_SAMPLES * 2  # int16 = 2 bytes/sample
+        self.path = path
+
+    def write(self, label: str, mono_i16: bytes):
+        """Append mono int16 PCM to the given channel and flush full frames."""
+        with self._lock:
+            self._bufs[label].extend(mono_i16)
+            # If one channel is >5s ahead, pad the other with silence
+            for lbl in self._bufs:
+                if lbl != label and len(self._bufs[lbl]) + 48000 * 2 * 5 < len(self._bufs[label]):
+                    pad = len(self._bufs[label]) - len(self._bufs[lbl])
+                    self._bufs[lbl].extend(b'\x00' * pad)
+            self._flush()
+
+    def _flush(self):
+        fb = self._frame_bytes
+        while len(self._bufs["me"]) >= fb and len(self._bufs["others"]) >= fb:
+            left = np.frombuffer(bytes(self._bufs["me"][:fb]), dtype=np.int16)
+            right = np.frombuffer(bytes(self._bufs["others"][:fb]), dtype=np.int16)
+            del self._bufs["me"][:fb]
+            del self._bufs["others"][:fb]
+            stereo = np.column_stack([left, right]).astype(np.int16)
+            self._writer.write(memoryview(bytearray(stereo.tobytes())))
+
+    def close(self):
+        """Flush remaining audio (pad shorter channel) and close the file."""
+        with self._lock:
+            max_len = max(len(b) for b in self._bufs.values())
+            if max_len > 0:
+                pad_to = ((max_len + self._frame_bytes - 1) // self._frame_bytes) * self._frame_bytes
+                for lbl in self._bufs:
+                    if len(self._bufs[lbl]) < pad_to:
+                        self._bufs[lbl].extend(b'\x00' * (pad_to - len(self._bufs[lbl])))
+                self._flush()
+            self._writer.close()

audio_transcript_mcp/server.py

@@ -0,0 +1,448 @@
+#!/usr/bin/env python3
+"""Real-time audio transcription MCP server for Claude Code.
+
+Captures mic + system audio (WASAPI loopback) on Windows,
+transcribes via Deepgram OR local faster-whisper model.
+
+Backend switchable at runtime via set_backend() tool.
+"""
+
+import gc
+import os
+import pathlib
+import queue
+import threading
+import time
+from dataclasses import dataclass
+
+import numpy as np
+import soxr
+
+from mcp.server.fastmcp import FastMCP
+
+from audio_transcript_mcp.backends import create_backend
+from audio_transcript_mcp.backends.whisper import WhisperBackend
+from audio_transcript_mcp.recorder import StereoOpusRecorder
+
+# ── config ──────────────────────────────────────────────────────────
+
+stt_backend = os.environ.get("STT_BACKEND", "deepgram").lower()
+
+CONFIG = {
+    "deepgram_api_key": os.environ.get("DEEPGRAM_API_KEY", ""),
+    "deepgram_language": os.environ.get("DEEPGRAM_LANGUAGE", "ru"),
+    "deepgram_model": os.environ.get("DEEPGRAM_MODEL", "nova-3"),
+    "deepgram_utterance_end_ms": os.environ.get("DEEPGRAM_UTTERANCE_END_MS", "2500"),
+    "deepgram_endpointing": os.environ.get("DEEPGRAM_ENDPOINTING", "500"),
+    "whisper_model": os.environ.get("WHISPER_MODEL", "large-v3"),
+    "whisper_device": os.environ.get("WHISPER_DEVICE", "cuda"),
+    "whisper_language": os.environ.get("WHISPER_LANGUAGE", ""),
+    "whisper_chunk_sec": float(os.environ.get("WHISPER_CHUNK_SEC", "5")),
+    "whisper_overlap_sec": float(os.environ.get("WHISPER_OVERLAP_SEC", "2")),
+}
+
+BUFFER_MAX_AGE = int(os.environ.get("TRANSCRIPT_MAX_AGE", "3600"))
+TRANSCRIPT_DIR = pathlib.Path(os.environ.get("TRANSCRIPT_DIR", pathlib.Path.home() / ".audio-transcript-mcp" / "transcripts"))
+RECONNECT_DELAY = 3
+
+
+# ── transcript buffer ───────────────────────────────────────────────
+
+@dataclass
+class Entry:
+    ts: float
+    speaker: str
+    text: str
+
+
+class Buffer:
+    def __init__(self, max_age: int = 3600):
+        self._entries: list[Entry] = []
+        self._lock = threading.Lock()
+        self._max_age = max_age
+
+    def add(self, speaker: str, text: str):
+        with self._lock:
+            self._entries.append(Entry(time.time(), speaker, text))
+            cutoff = time.time() - self._max_age
+            self._entries = [e for e in self._entries if e.ts > cutoff]
+
+    def since(self, ts: float) -> list[Entry]:
+        with self._lock:
+            return [e for e in self._entries if e.ts >= ts]
+
+    def last(self, seconds: float) -> list[Entry]:
+        return self.since(time.time() - seconds)
+
+    def all(self) -> list[Entry]:
+        with self._lock:
+            return list(self._entries)
+
+    def clear(self):
+        with self._lock:
+            self._entries.clear()
+
+    @staticmethod
+    def format(entries: list[Entry]) -> str:
+        if not entries:
+            return "(empty transcript)"
+        lines = []
+        for e in entries:
+            t = time.strftime("%H:%M:%S", time.localtime(e.ts))
+            lines.append(f"[{t}] {e.speaker}: {e.text}")
+        return "\n".join(lines)
+
+
+buf = Buffer(BUFFER_MAX_AGE)
+
+
+# ── audio engine ────────────────────────────────────────────────────
+
+class AudioEngine:
+    """Captures mic + loopback via PyAudioWPatch callbacks,
+    sends to chosen STT backend. Auto-reconnects on drop."""
+
+    def __init__(self):
+        self._running = False
+        self._stop = threading.Event()
+        self._threads: list[threading.Thread] = []
+        self._streams = []
+        self._pa = None
+        self._session_start: float = 0.0
+        self._recorder: StereoOpusRecorder | None = None
+
+    @property
+    def running(self) -> bool:
+        return self._running
+
+    def start(self) -> str:
+        if self._running:
+            return "Already listening."
+
+        try:
+            import ctypes
+            ctypes.windll.ole32.CoInitializeEx(0, 0)
+        except Exception:
+            pass
+
+        try:
+            import pyaudiowpatch as pyaudio
+        except ImportError:
+            return "ERROR: PyAudioWPatch not installed."
+
+        self._stop.clear()
+        self._running = True
+        self._session_start = time.time()
+        self._pa = pyaudio.PyAudio()
+
+        # Create per-session directory and open stereo opus recorder
+        self._recorder = None
+        self._session_dir = None
+        if TRANSCRIPT_DIR:
+            try:
+                ts = time.strftime("%Y-%m-%d_%H-%M-%S", time.localtime(self._session_start))
+                self._session_dir = TRANSCRIPT_DIR / ts
+                self._session_dir.mkdir(parents=True, exist_ok=True)
+                self._recorder = StereoOpusRecorder(self._session_dir / "audio.opus")
+            except Exception:
+                pass
+
+        for label, use_loopback in [("me", False), ("others", True)]:
+            t = threading.Thread(
+                target=self._worker,
+                args=(label, use_loopback),
+                daemon=True,
+                name=f"{label}-worker",
+            )
+            self._threads.append(t)
+            t.start()
+
+        backend_name = "local (faster-whisper)" if stt_backend == "local" else "Deepgram"
+        return f"Listening started (mic + system audio) via {backend_name}."
+
+    def stop(self) -> str:
+        if not self._running:
+            return "Not listening."
+        self._stop.set()
+        for s in self._streams:
+            try:
+                s.stop_stream()
+                s.close()
+            except Exception:
+                pass
+        self._streams.clear()
+        for t in self._threads:
+            t.join(timeout=10)
+        self._threads.clear()
+        if self._pa:
+            try:
+                self._pa.terminate()
+            except Exception:
+                pass
+            self._pa = None
+        self._running = False
+        return "Listening stopped."
+
+    def _worker(self, label: str, use_loopback: bool):
+        import pyaudiowpatch as pyaudio
+
+        p = self._pa
+
+        try:
+            if use_loopback:
+                device = p.get_default_wasapi_loopback()
+            else:
+                device = p.get_default_input_device_info()
+        except Exception as exc:
+            buf.add("system", f"[ERROR: device not found: {exc}]")
+            return
+
+        sample_rate = int(device["defaultSampleRate"])
+        channels = max(1, int(device["maxInputChannels"]))
+        pa_format = pyaudio.paFloat32 if use_loopback else pyaudio.paInt16
+        chunk_frames = sample_rate // 10  # 100ms
+
+        audio_q: queue.Queue[bytes | None] = queue.Queue(maxsize=100)
+
+        def audio_callback(in_data, frame_count, time_info, status):
+            if self._stop.is_set():
+                return (None, pyaudio.paComplete)
+            try:
+                audio_q.put_nowait(in_data)
+            except queue.Full:
+                pass
+            return (None, pyaudio.paContinue)
+
+        try:
+            stream = p.open(
+                format=pa_format,
+                channels=channels,
+                rate=sample_rate,
+                input=True,
+                input_device_index=device["index"],
+                frames_per_buffer=chunk_frames,
+                stream_callback=audio_callback,
+            )
+            stream.start_stream()
+            self._streams.append(stream)
+        except Exception as exc:
+            buf.add("system", f"[ERROR: audio open failed: {exc}]")
+            return
+
+        buf.add("system", f"[STARTED: {device['name']}, {sample_rate}Hz, {channels}ch]")
+
+        is_float32 = pa_format == pyaudio.paFloat32
+
+        # Stateful resampler for opus recording (avoids boundary artifacts)
+        opus_resampler = None
+        if self._recorder and sample_rate != 48000:
+            opus_resampler = soxr.ResampleStream(sample_rate, 48000, 1, dtype="float32", quality="HQ")
+
+        while not self._stop.is_set():
+            backend = create_backend(stt_backend, label, sample_rate, channels, is_float32, buf, CONFIG)
+            if not backend.connect():
+                buf.add("system", f"[RECONNECT: backend connect failed, retry in {RECONNECT_DELAY}s]")
+                self._stop.wait(RECONNECT_DELAY)
+                continue
+
+            # Drain stale audio
+            while not audio_q.empty():
+                try:
+                    audio_q.get_nowait()
+                except queue.Empty:
+                    break
+
+            disconnected = False
+            while not self._stop.is_set():
+                try:
+                    data = audio_q.get(timeout=0.5)
+                except queue.Empty:
+                    continue
+                if data is None:
+                    break
+
+                # Record to stereo opus
+                if self._recorder:
+                    try:
+                        if is_float32:
+                            arr = np.frombuffer(data, dtype=np.float32)
+                            if channels >= 2:
+                                arr = arr.reshape(-1, channels).mean(axis=1)
+                        else:
+                            arr = np.frombuffer(data, dtype=np.int16).astype(np.float32) / 32768.0
+                            if channels >= 2:
+                                arr = arr.reshape(-1, channels).mean(axis=1)
+                        if opus_resampler is not None:
+                            arr = opus_resampler.resample_chunk(arr)
+                        mono_i16 = np.clip(arr * 32767, -32768, 32767).astype(np.int16)
+                        self._recorder.write(label, mono_i16.tobytes())
+                    except Exception:
+                        pass
+
+                if not backend.send(data):
+                    disconnected = True
+                    break
+
+            backend.close()
+
+            if disconnected and not self._stop.is_set():
+                buf.add("system", f"[RECONNECT: connection lost, retry in {RECONNECT_DELAY}s...]")
+                self._stop.wait(RECONNECT_DELAY)
+
+            if stt_backend == "local" and not disconnected:
+                break
+
+        # Flush remaining resampler state into opus recorder
+        if opus_resampler is not None and self._recorder:
+            try:
+                tail = opus_resampler.resample_chunk(np.empty(0, dtype=np.float32), last=True)
+                if len(tail) > 0:
+                    mono_i16 = np.clip(tail * 32767, -32768, 32767).astype(np.int16)
+                    self._recorder.write(label, mono_i16.tobytes())
+            except Exception:
+                pass
+
+        try:
+            stream.stop_stream()
+            stream.close()
+        except Exception:
+            pass
+        buf.add("system", "[STOPPED]")
+
+
+engine = AudioEngine()
+
+
+# ── MCP tools ───────────────────────────────────────────────────────
+
+mcp = FastMCP("audio-transcript")
+
+
+@mcp.tool()
+async def start_listening() -> str:
+    """Start capturing mic + system audio and transcribing via current backend.
+    Returns status message.
+    """
+    if stt_backend == "deepgram" and not CONFIG["deepgram_api_key"]:
+        return "ERROR: Set DEEPGRAM_API_KEY env var first."
+    return engine.start()
+
+
+@mcp.tool()
+async def stop_listening() -> str:
+    """Stop audio capture and transcription."""
+    session_start = engine._session_start
+    result = engine.stop()
+    with WhisperBackend._model_lock:
+        if WhisperBackend._model is not None:
+            WhisperBackend._model.model.unload_model()
+    gc.collect()
+
+    # Save session transcript to file
+    session_dir = engine._session_dir
+    if session_start and session_dir:
+        try:
+            session_dir.mkdir(parents=True, exist_ok=True)
+            entries = buf.since(session_start)
+            path = session_dir / "transcript.txt"
+            lines = []
+            for e in entries:
+                if e.speaker in ("debug",):
+                    continue
+                t = time.strftime("%H:%M:%S", time.localtime(e.ts))
+                lines.append(f"[{t}] {e.speaker} — {e.text}")
+            path.write_text("\n\n".join(lines) + "\n", encoding="utf-8")
+            result += f" Transcript saved to {path}."
+        except Exception as exc:
+            result += f" (transcript save failed: {exc})"
+
+    # Close stereo opus recorder
+    if engine._recorder:
+        try:
+            engine._recorder.close()
+            p = engine._recorder.path
+            size_kb = p.stat().st_size / 1024
+            result += f" Audio saved to {p} ({size_kb:.0f} KB)."
+        except Exception as exc:
+            result += f" (opus save failed: {exc})"
+        engine._recorder = None
+
+    return result
+
+
+@mcp.tool()
+async def is_listening() -> str:
+    """Check if audio capture is currently active."""
+    return f"Listening: {engine.running}"
+
+
+@mcp.tool()
+async def get_transcript(last_seconds: float = 60) -> str:
+    """Get transcript for the last N seconds.
+
+    Args:
+        last_seconds: how far back in seconds (default 60)
+    """
+    return buf.format(buf.last(last_seconds))
+
+
+@mcp.tool()
+async def get_full_transcript() -> str:
+    """Get the entire accumulated transcript (up to max buffer age)."""
+    return buf.format(buf.all())
+
+
+@mcp.tool()
+async def get_transcript_since(timestamp: float) -> str:
+    """Get transcript entries since a Unix timestamp.
+
+    Args:
+        timestamp: Unix epoch timestamp (e.g. from time.time())
+    """
+    return buf.format(buf.since(timestamp))
+
+
+@mcp.tool()
+async def clear_transcript() -> str:
+    """Clear the transcript buffer."""
+    buf.clear()
+    return "Transcript cleared."
+
+
+@mcp.tool()
+async def get_backend() -> str:
+    """Get current STT backend name ("deepgram" or "local")."""
+    return f"Current backend: {stt_backend}"
+
+
+@mcp.tool()
+async def set_backend(backend: str) -> str:
+    """Switch STT backend. If currently listening, restarts capture automatically.
+
+    Args:
+        backend: "deepgram" or "local"
+    """
+    global stt_backend
+    backend = backend.strip().lower()
+    if backend not in ("deepgram", "local"):
+        return f"ERROR: unknown backend '{backend}'. Use 'deepgram' or 'local'."
+    if backend == stt_backend:
+        return f"Already using '{stt_backend}'."
+    old = stt_backend
+    stt_backend = backend
+    if engine.running:
+        engine.stop()
+        msg = engine.start()
+        return f"Switched {old} -> {stt_backend} and restarted. {msg}"
+    return f"Switched {old} -> {stt_backend}. Start listening when ready."
+
+
+# ── entrypoint ──────────────────────────────────────────────────────
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

audio_transcript_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: audio-transcript-mcp
+Version: 0.1.0
+Summary: Real-time audio transcription MCP server for Claude Code
+Project-URL: Homepage, https://github.com/llilakoblock/audio-transcript-mcp
+Project-URL: Repository, https://github.com/llilakoblock/audio-transcript-mcp
+Project-URL: Issues, https://github.com/llilakoblock/audio-transcript-mcp/issues
+Author: llilakoblock
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,deepgram,mcp,transcription,whisper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Requires-Dist: faster-whisper>=1.0
+Requires-Dist: mcp[cli]>=1.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyaudiowpatch>=0.2.12
+Requires-Dist: pyogg>=0.7
+Requires-Dist: soxr>=0.3
+Requires-Dist: websockets>=12.0
+Description-Content-Type: text/markdown
+
+# audio-transcript-mcp
+
+Real-time audio transcription MCP server for Claude Code.
+
+Captures **microphone + system audio** (WASAPI loopback on Windows) and transcribes via **Deepgram** (cloud) or **faster-whisper** (local, GPU/CPU).
+
+## Features
+
+- **Dual audio capture**: mic + system sound simultaneously
+- **Two STT backends** switchable at runtime (Deepgram nova-3 / faster-whisper)
+- **Stereo opus recording**: each session saves a stereo opus file (L=mic, R=system audio)
+- **Per-session directories**: transcript + audio saved to `~/.audio-transcript-mcp/transcripts/<timestamp>/`
+- Chunk overlap with text deduplication (no cut words at boundaries)
+- Native float32 audio pipeline for whisper (no lossy int16 round-trip)
+- High-quality stateful resampling via soxr (no boundary artifacts)
+- Whisper hallucination filter (no_speech_prob + avg_logprob thresholds)
+- Transcript buffer with time-based queries
+- Auto-reconnect for Deepgram WebSocket
+- GPU model unload/reload on stop/start (CUDA memory management)
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────┐     ┌─────────────────┐
+│  Mic (int16) ├────►│          │     │  STT Backend    │
+│  WASAPI      │     │  Worker  ├────►│  whisper / DG   ├──► Transcript buffer
+└─────────────┘     │  Thread  │     └─────────────────┘
+                    │          ├────►┌─────────────────┐
+┌─────────────┐     │          │     │ StereoOpusRec   │
+│ System audio ├────►│          │     │ L=me R=others   ├──► audio.opus
+│ Loopback f32 │     └──────────┘     └─────────────────┘
+└─────────────┘
+
+Audio pipeline: native capture → stereo→mono → soxr resample → backend/opus
+```
+
+Each audio source runs in its own worker thread. Audio is captured in the device's native format (float32 for loopback, int16 for mic), converted to mono, and routed to both the STT backend and the stereo opus recorder.
+
+## Requirements
+
+- Python 3.10+
+- Windows (WASAPI loopback for system audio capture); mic-only on macOS/Linux
+- NVIDIA GPU recommended for local whisper backend
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install audio-transcript-mcp
+```
+
+Or run without installing via `uvx`:
+
+```bash
+uvx audio-transcript-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/llilakoblock/audio-transcript-mcp.git
+cd audio-transcript-mcp
+pip install -e .
+```
+
+## MCP Configuration
+
+Add to your `mcp.json` (Claude Code settings):
+
+### Using PyPI install
+
+```json
+{
+  "audio-transcript": {
+    "type": "stdio",
+    "command": "audio-transcript-mcp",
+    "env": {
+      "STT_BACKEND": "local",
+      "DEEPGRAM_API_KEY": "your-deepgram-api-key",
+      "DEEPGRAM_LANGUAGE": "ru",
+      "DEEPGRAM_MODEL": "nova-3",
+      "DEEPGRAM_UTTERANCE_END_MS": "2500",
+      "DEEPGRAM_ENDPOINTING": "500",
+      "WHISPER_MODEL": "large-v3",
+      "WHISPER_DEVICE": "cuda",
+      "WHISPER_LANGUAGE": "ru",
+      "WHISPER_CHUNK_SEC": "10",
+      "WHISPER_OVERLAP_SEC": "2",
+      "TRANSCRIPT_MAX_AGE": "3600"
+    }
+  }
+}
+```
+
+### Using uvx (no install needed)
+
+```json
+{
+  "audio-transcript": {
+    "type": "stdio",
+    "command": "uvx",
+    "args": ["audio-transcript-mcp"],
+    "env": {
+      "STT_BACKEND": "deepgram",
+      "DEEPGRAM_API_KEY": "your-deepgram-api-key"
+    }
+  }
+}
+```
+
+> **Note:** System audio capture (loopback) uses WASAPI and is Windows-only. On macOS/Linux only microphone input works out of the box.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `STT_BACKEND` | `deepgram` | `"deepgram"` (cloud) or `"local"` (faster-whisper) |
+| `DEEPGRAM_API_KEY` | — | API key for Deepgram (required if backend=deepgram) |
+| `DEEPGRAM_LANGUAGE` | `ru` | Language code for Deepgram |
+| `DEEPGRAM_MODEL` | `nova-3` | Deepgram model (`nova-3`, `nova-2`, etc.) |
+| `DEEPGRAM_UTTERANCE_END_MS` | `2500` | Silence duration (ms) before finalizing utterance |
+| `DEEPGRAM_ENDPOINTING` | `500` | Endpointing sensitivity (ms) |
+| `WHISPER_MODEL` | `large-v3` | Model size: `tiny`, `base`, `small`, `medium`, `large-v3` |
+| `WHISPER_DEVICE` | `cuda` | `"cuda"` or `"cpu"` |
+| `WHISPER_LANGUAGE` | — | Language hint for whisper (empty = auto-detect) |
+| `WHISPER_CHUNK_SEC` | `5` | Audio chunk duration in seconds |
+| `WHISPER_OVERLAP_SEC` | `2` | Overlap between consecutive chunks (avoids cut words) |
+| `TRANSCRIPT_MAX_AGE` | `3600` | Max transcript buffer age in seconds |
+| `TRANSCRIPT_DIR` | `~/.audio-transcript-mcp/transcripts` | Directory for per-session transcript/audio files |
+
+## Session Output
+
+Each recording session creates a timestamped directory:
+
+```
+~/.audio-transcript-mcp/transcripts/
+  2026-03-06_23-24-48/
+    transcript.txt    # Plain text transcript
+    audio.opus        # Stereo opus (L=mic, R=system)
+```
+
+The transcript is plain text:
+```
+[23:24:50] me — Hello, can you hear me?
+
+[23:24:52] others — Yes, I can hear you fine.
+
+[23:24:55] system — [STARTED: Microphone, 44100Hz, 2ch]
+```
+
+## MCP Tools
+
+| Tool | Description |
+|---|---|
+| `start_listening` | Start capturing mic + system audio and transcribing |
+| `stop_listening` | Stop capture, save transcript and opus recording |
+| `is_listening` | Check if capture is active |
+| `get_transcript` | Get transcript for the last N seconds (default 60) |
+| `get_full_transcript` | Get entire transcript buffer |
+| `get_transcript_since` | Get transcript since a Unix timestamp |
+| `clear_transcript` | Clear the transcript buffer |
+| `get_backend` | Show current STT backend |
+| `set_backend` | Switch backend (`"deepgram"` / `"local"`) at runtime |
+
+## Project Structure
+
+```
+src/audio_transcript_mcp/
+  __init__.py            # Package version
+  __main__.py            # python -m entry point
+  server.py              # MCP server, AudioEngine, config
+  audio_utils.py         # Format conversion (float32↔int16, stereo→mono)
+  backends/
+    __init__.py          # Backend factory
+    whisper.py           # Local faster-whisper STT
+    deepgram.py          # Deepgram WebSocket STT
+  recorder/
+    __init__.py
+    opus.py              # StereoOpusRecorder (PyOgg)
+```
+
+## Releasing
+
+Releases are automated via GitHub Actions:
+
+```bash
+# Update version in src/audio_transcript_mcp/__init__.py
+git tag v0.1.0
+git push origin v0.1.0
+# CI automatically builds, publishes to PyPI, and creates a GitHub Release
+```
+
+## License
+
+MIT

audio_transcript_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+audio_transcript_mcp/__init__.py,sha256=Q552b2DKL8KTpkvEbL9XjWOHBi_lybCpeD1XyOO5C_0,71
+audio_transcript_mcp/__main__.py,sha256=i-qaCM9yraBkuIO2Aa7JwQ-K-i7kiF4rkn6foylEEgk,111
+audio_transcript_mcp/audio_utils.py,sha256=EtQVN3W9aGm-SSG2hxOZGjGBsEhH_X8Cgb7vyF_TNCk,550
+audio_transcript_mcp/server.py,sha256=UQ5B7J1-Ptoz9JKjpkQO8ux0XeGZtzhtNHBq9EZPR2s,15474
+audio_transcript_mcp/backends/__init__.py,sha256=sItMvJITF6TCT8BHa8_O5PWrPuFKbvseY7dwl7ri5UQ,522
+audio_transcript_mcp/backends/deepgram.py,sha256=kdJwjkg1V-9C2CLtR_XyOATW_TP_x5xCzhD2uDsrpWI,3078
+audio_transcript_mcp/backends/whisper.py,sha256=ict5STAU6XMe4PgTrSRS4Acopl2BodrujjwyT6SBxn0,6601
+audio_transcript_mcp/recorder/__init__.py,sha256=fk6GkQjL5Bd2N4qZCzVplTPWG7DvJh0Y_bnTzO51S1g,130
+audio_transcript_mcp/recorder/opus.py,sha256=wIqWoMVcrYfJquBXdlbz85Uf6ntJAps5uGBfwYOqDsQ,2607
+audio_transcript_mcp-0.1.0.dist-info/METADATA,sha256=MoQmQqE2oneMEVtYa5NYqrmztxc9hyh5JTtJU_SFQBg,7941
+audio_transcript_mcp-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+audio_transcript_mcp-0.1.0.dist-info/entry_points.txt,sha256=YcoWhvqE7zIWV-X9lTg4iJAJ6bi5Ge661dJOfl1wEC8,74
+audio_transcript_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=rKBHD0FlJSZl_ZqhA4Hr8k7L2aRoWaX8cTUsuGC_nSw,1069
+audio_transcript_mcp-0.1.0.dist-info/RECORD,,

audio_transcript_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

audio_transcript_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+audio-transcript-mcp = audio_transcript_mcp.server:main

audio_transcript_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llilakoblock
+
+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.