Add VoiceBridge: real-time AI voice changer to a virtual game mic

.claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "effortLevel": "xhigh",
+  "env": {
+    "CLAUDE_CODE_EFFORT_LEVEL": "max"
+  }
+}

voicebridge/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: ci
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (core + dev, no torch/audio hardware)
+        run: |
+          python -m pip install --upgrade pip
+          pip install numpy PyYAML soxr soundfile pytest
+          pip install -e . --no-deps
+      - name: Run unit tests
+        run: pytest -q

voicebridge/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.python-version
+
+# VoiceBridge data & models (never commit voice data or weights)
+models/
+*.pth
+*.index
+*.onnx
+*.pt
+*.ckpt
+data/
+recordings/
+datasets/
+logs/
+*.wav
+*.flac
+*.mp3
+*.npy
+
+# Local config (may contain device names / personal paths)
+config.yaml
+config.local.yaml
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.log

voicebridge/LICENSE

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

voicebridge/README.md

@@ -0,0 +1,119 @@
+# VoiceBridge
+
+**Real-time AI voice conversion that turns one person's microphone into a
+cloned-voice virtual mic for games on Windows.** Sub-300 ms, neural speaker
+conversion (RVC / Seed-VC) — *not* a pitch shifter.
+
+> Built for a specific use: record yourself, train a model of your voice, and
+> let your girlfriend speak with **your** voice in Rust, Discord, or any app —
+> live, through a virtual microphone.
+
+```
+   Her real mic ──► VoiceBridge engine ──► your cloned voice ──► VB-CABLE ──► Rust / Discord
+                    (GPU, ~200-300 ms)        (RVC model)         (virtual mic)
+```
+
+---
+
+## How it works (30-second version)
+
+Three independent pieces (full detail in **[docs/DESIGN.md](docs/DESIGN.md)**):
+
+1. **Clone your voice** — record ~10 min of yourself, train an **RVC** model →
+   `your_voice.pth`. Done once. ([docs/TRAINING.md](docs/TRAINING.md))
+2. **Convert in real time** — this repo's engine captures her mic, runs it
+   through the model on her GPU, and hides chunk boundaries with a context
+   window + equal-power crossfade for clean, low-latency audio.
+3. **Become a microphone** — output goes to **VB-CABLE**, a virtual audio
+   device, so any game/app can select it as the mic. Game-agnostic.
+
+The neural quality comes from the RVC model family (the community standard for
+voice cloning); VoiceBridge is the real-time engine, the recording/training
+workflow, the routing, and a one-click control panel around it.
+
+## Requirements
+
+- **Windows 10/11** on the PC that uses the voice.
+- **NVIDIA GPU** (RTX 2060/3060 or better recommended) for real-time. CPU works
+  only for the no-AI `passthrough` test.
+- **Python 3.10/3.11**, and **VB-CABLE** (free virtual mic).
+
+## Quickstart
+
+```powershell
+# 1. install
+python -m venv .venv ; .\.venv\Scripts\Activate.ps1
+pip install -e .
+
+# 2. see your devices
+python -m voicebridge devices
+
+# 3. configure
+copy config.example.yaml config.yaml      # then edit input/output devices
+
+# 4a. PROVE THE ROUTING (no GPU, no model): backend: passthrough
+python -m voicebridge run
+#     -> set the game's mic to "CABLE Output"; you should hear yourself routed.
+
+# 4b. THE REAL THING: train a voice (docs/TRAINING.md), set backend: rvc, then:
+python -m voicebridge gui        # friendly control panel, or `run` for headless
+```
+
+Full step-by-step (VB-CABLE, GPU PyTorch, model deploy):
+**[docs/SETUP_WINDOWS.md](docs/SETUP_WINDOWS.md)**.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `python -m voicebridge devices` | list audio input/output devices |
+| `python -m voicebridge record` | guided recording of your training data |
+| `python -m voicebridge record --reference` | one ~30s clip for zero-shot Seed-VC |
+| `python -m voicebridge train --check` | validate your dataset |
+| `python -m voicebridge train` | print the exact training plan |
+| `python -m voicebridge run` | start the real-time engine (headless) |
+| `python -m voicebridge gui` | open the control panel |
+
+## Backends
+
+Set `backend:` in `config.yaml`:
+
+- **`passthrough`** — not AI; proves mic→cable→game works on any machine today.
+- **`rvc`** — your fine-tuned cloned voice. The real product. Needs a GPU + `.pth`.
+- **`seedvc`** — zero-shot from a reference clip, no training. Quick first test.
+
+## Latency
+
+Target is "feels live in voice chat," ~200–300 ms mouth-to-game on a decent
+NVIDIA GPU. Tune it in **[docs/LATENCY.md](docs/LATENCY.md)**. It will never be
+literally zero — neural conversion needs a small chunk of audio to work on.
+
+## Project layout
+
+See [docs/DESIGN.md §10](docs/DESIGN.md). The streaming algorithm is in
+`src/voicebridge/engine.py`; the audio plumbing in `audio_io.py`; backends in
+`backends/`. Pure-DSP/streaming logic is unit-tested in `tests/` (no GPU needed):
+
+```powershell
+pip install pytest ; pytest
+```
+
+## Ethics & fair use
+
+This exists to let you share **your own** voice, with your consent, with your
+partner, for fun in games. Don't:
+- impersonate real people who haven't agreed,
+- use it for fraud, harassment, scams, or to evade bans/identity checks,
+- record or convert anyone without their knowledge.
+
+VoiceBridge only creates/uses a virtual **audio device** — it does not inject
+into or modify any game process, so it isn't a game hack. Still, follow each
+game's and platform's rules on voice/streaming software.
+
+## Status
+
+v0.1. The real-time engine, audio routing, recording tool, config, GUI, and the
+passthrough backend are implemented and unit-tested. The `rvc`/`seedvc` neural
+backends are wired as clearly-marked integration seams that must be validated on
+a Windows + NVIDIA GPU machine (see notes in `backends/`); the trained model
+also runs as-is in w-okada/voice-changer if you want a turnkey runner. License: MIT.

voicebridge/config.example.yaml

@@ -0,0 +1,60 @@
+# ============================================================================
+# VoiceBridge configuration
+# ----------------------------------------------------------------------------
+# Copy this file to `config.yaml` and edit it for your machine.
+#   cp config.example.yaml config.yaml      (Windows: copy config.example.yaml config.yaml)
+#
+# Find your device names/IDs with:   python -m voicebridge devices
+# ============================================================================
+
+audio:
+  # Input = her real microphone. Output = the virtual cable the game listens to.
+  # Use the exact substring of the device name (case-insensitive) OR a numeric id.
+  input_device: "default"          # e.g. "Microphone (USB)"  -> her physical mic
+  output_device: "CABLE Input"     # VB-CABLE playback device -> game reads "CABLE Output"
+  monitor_device: null             # optional: also play converted audio to headphones to hear herself
+
+  samplerate: 48000                # device sample rate (Hz). 48000 is the safe default on Windows.
+  channels: 1                      # mono in/out
+
+# Real-time streaming parameters. These trade latency against quality/stability.
+# See docs/LATENCY.md for tuning. Total added latency ~= block_ms + crossfade_ms + inference.
+stream:
+  block_ms: 150                    # audio captured per inference step. Lower = less latency, more CPU/GPU load.
+  crossfade_ms: 40                 # overlap blended between chunks to hide seams. 25-60 is reasonable.
+  context_ms: 200                  # past audio fed to the model for continuity (not played, just context).
+  pipeline_samplerate: 16000       # internal SR the engine resamples to for the model (HuBERT-style = 16000).
+
+# Which conversion backend to use: passthrough | rvc | seedvc
+backend: passthrough
+
+# ---- Backend: passthrough -------------------------------------------------
+# Not AI. Proves the mic -> cable -> game routing works on ANY machine, today.
+# Optional toy pitch shift so you can *hear* a change while testing routing.
+passthrough:
+  pitch_semitones: 0               # e.g. -4 to sound deeper. Formants NOT preserved; it's only a test tone.
+
+# ---- Backend: rvc (your cloned voice) -------------------------------------
+# This is the real product: a model trained on YOUR voice (see docs/TRAINING.md).
+rvc:
+  model_path: "models/your_voice.pth"     # the trained RVC generator
+  index_path: "models/your_voice.index"   # retrieval index (improves timbre); optional
+  index_rate: 0.5                          # 0..1 how strongly to pull toward the trained timbre
+  f0_method: "rmvpe"                       # pitch estimator: rmvpe (best), crepe, harvest, pm
+  f0_up_key: 0                             # pitch shift in semitones. If she is higher-pitched than you,
+                                           #   try +0 first; the model already retargets timbre. Tune by ear.
+  protect: 0.33                            # protect unvoiced consonants (reduces artifacts); 0..0.5
+  device: "cuda:0"                         # "cuda:0" for NVIDIA GPU (required for real time), or "cpu" (slow)
+
+# ---- Backend: seedvc (zero-shot, no training) -----------------------------
+# Point it at a reference clip of your voice; no training step. Lower quality
+# than a fine-tuned RVC model but instant. Good for a quick first test.
+seedvc:
+  reference_wav: "recordings/reference.wav"
+  checkpoint: null                 # null = use the default pretrained Seed-VC checkpoint
+  diffusion_steps: 4               # fewer steps = lower latency, rougher quality
+  device: "cuda:0"
+
+logging:
+  level: INFO                      # DEBUG | INFO | WARNING
+  show_latency: true               # print rolling input->output latency while running