110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
# MurMur — Audio Bridge / Transcribe / Translate
|
||
|
||
**MurMur** is a lightweight desktop app that **routes**, **transcribes**, **translates**, and **records** system audio in real time — all locally.
|
||
|
||
- **ASR (Automatic Speech Recognition) engine:** [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) driven by a local Whisper model for fast, memory-efficient transcription.
|
||
- **Live client:** “nearly-live” Whisper pipeline for continuous updates.
|
||
- **Translation:** uses Whisper’s built-in `translate=True` path (**to English**)
|
||
- **Audio bridge:** pick input/output devices, loop back desktop audio, add **virtual gain**, and capture to MP3 (via `ffmpeg`).
|
||
- **Bonus use-case:** route desktop audio into **Shazam for Mac** for highly reliable song ID (no mic/room noise).
|
||
|
||
|
||
|
||
|
||
> **Note:** Earlier builds experimented with NLLB and SeamlessM4T for wider language translation; **current MurMur does _not_ use these**. Whisper **does** transcribe and translate nearly any language, but can only translate **to** English. In case you want to use other transcription or translation software (non-realtime), the recording-feature was implemented.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
- **Two-pane UI:** Live transcript + optional live English translation.
|
||
- **Source language:** Auto-detect (Whisper) or manually set.
|
||
- **Audio routing:** Low-latency loopback with adjustable **virtual gain**.
|
||
- **Recording:** One-click capture to MP3.
|
||
|
||
---
|
||
## Requirements
|
||
|
||
- **Python** 3.9+
|
||
- **ffmpeg** on PATH (for MP3 export) — installable via Homebrew.
|
||
- **Virtual audio sink** (macOS) — install **one** of:
|
||
- **BlackHole** (open-source, zero-latency loopback).
|
||
- **Background Music** (adds a virtual device + per-app volume).
|
||
- **Soundflower** (classic virtual device).
|
||
- **Loopback** (commercial, flexible routing UI).
|
||
|
||
These create a virtual output/input so one app’s audio can be captured by another (e.g., system output → MurMur input).
|
||
|
||
---
|
||
|
||
## Install
|
||
|
||
Create a venv and install dependencies:
|
||
|
||
```bash
|
||
python -m venv .venv && source .venv/bin/activate
|
||
python -m pip install --upgrade pip
|
||
pip install pywebview sounddevice huggingface_hub torch whisper-live numpy
|
||
```
|
||
|
||
- **[Pywebview](https://pywebview.flowrl.com/)**: lightweight native window hosting HTML/JS. ([GitHub](https://github.com/r0x0r/pywebview)
|
||
- **[python-sounddevice](https://python-sounddevice.readthedocs.io/)**: PortAudio bindings for low-latency I/O.
|
||
|
||
|
||
---
|
||
|
||
## Quick Start
|
||
|
||
1. Install and select a **virtual device** (e.g., set system output to **BlackHole 2ch**). [existential.audio](https://existential.audio/blackhole/)
|
||
2. Run the app:
|
||
```bash
|
||
python audiobridge-gui.py
|
||
```
|
||
3. In **Devices**:
|
||
- **Input** → the virtual device (captures desktop audio), or your mic.
|
||
- **Output** → your speakers/headphones (or another virtual sink or no output at all).
|
||
4. Click **Transcribe** → live captions appear; toggle **Translate** to get **English** translation output via Whisper.
|
||
5. Use the **Gain** slider for loopback level.
|
||
6. Tap the square **Record** button to capture a timestamped **MP3** (requires `ffmpeg`).
|
||
|
||
**Tip — [Shazam](https://apps.apple.com/ch/app/shazam-musikerkennung/id897118787) workflow:** set **system output = [BlackHole](https://existential.audio/blackhole/)**, **MurMur input = [BlackHole](https://existential.audio/blackhole/)**, then run **[Shazam for Mac](https://apps.apple.com/ch/app/shazam-musikerkennung/id897118787)** to ID what’s playing on your desktop with no ambient noise.
|
||
|
||
---
|
||
|
||
## Engines & Model Notes
|
||
|
||
- **Transcription:** [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) — Whisper reimplementation using CTranslate2 for speed and lower memory usage. You can swap model sizes (e.g., small/base/large-v3) as needed. [GitHub](https://github.com/SYSTRAN/faster-whisper) [Hugging Face](https://huggingface.co/Systran/faster-whisper-large-v3)
|
||
- **Live pipeline:** WhisperLive-style continuous client for “near-real-time” updates. [GitHub](https://github.com/collabora/WhisperLive)
|
||
|
||
|
||
---
|
||
|
||
## Packaging (optional)
|
||
|
||
- macOS bundles can be built with **PyInstaller** (not included here).
|
||
- Include the provided **1024×1024 icon** and ensure `ffmpeg` is present on target systems (or ship a static build).
|
||
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
- **No audio into MurMur:** ensure the **virtual device** is selected as both **system output** and **MurMur input**. For some drivers, restarting CoreAudio can help after install.
|
||
- **`sounddevice` errors:** ensure PortAudio is available/installed correctly.
|
||
- **Recording fails:** confirm `ffmpeg` is installed and on PATH.
|
||
|
||
|
||
---
|
||
|
||
## Privacy
|
||
|
||
All processing runs **locally**. Audio never leaves your machine unless you route it to cloud software yourself.
|
||
|
||
---
|
||
|
||
## Acknowledgements
|
||
|
||
- **[faster-whisper](https://github.com/SYSTRAN/faster-whisper)** by SYSTRAN.
|
||
- **[WhisperLive](https://github.com/collabora/WhisperLive)** (real-time pipeline inspiration).
|
||
- **[Pywebview](https://pywebview.flowrl.com/)** and **[python-sounddevice](https://python-sounddevice.readthedocs.io/)** communities.
|
||
- **[BlackHole](https://existential.audio/blackhole/)**, **[Background Music](https://github.com/kyleneideck/BackgroundMusic)**, **[Soundflower](https://rogueamoeba.com/freebies/soundflower/)**, **[Loopback](https://rogueamoeba.com/loopback/)** for virtual audio devices. |