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
