Skip to main content
Glama
README.md
# loudgate

Open-source, clean-room broadcast audio post-production engine in Python + FFmpeg, featuring a local loopback **Studio GUI (`loudgate ui`)**, deterministic CLI, Python API, and `stdio` MCP server.

Everything runs locally on CPU with zero cloud uploads, zero model weight downloads, and zero subscription paywalls.

![loudgate Studio GUI](docs/assets/gui-desktop-probe.png)

## Documentation

- **English**: [Overview](docs/index.md) | [Studio GUI Guide](docs/gui-guide.md) | [CLI & Python Reference](docs/cli-reference.md) | [MCP Setup](docs/mcp-setup.md)
- **Francais**: [Presentation](docs/fr/index.md) | [Guide Interface Studio](docs/fr/gui-guide.md) | [Reference CLI & Python](docs/fr/cli-reference.md) | [Configuration MCP](docs/fr/mcp-setup.md)

## Why loudgate

| Workflow | Proprietary paywalls | loudgate (MIT) |
| :--- | :--- | :--- |
| Visual Audio Console & A/B Audition | Desktop GUI suites ($399+) | Local loopback `loudgate ui` / `loudgate-ui` with Canvas waveform & EBU R128 meters |
| Spectral denoise, de-click, HPF | Per-plugin licenses | Deterministic STFT WOLA + zero-phase Butterworth SOS |
| Loudness audit & mastering | Monthly NLE add-ons ($22.99/mo) | Two-pass FFmpeg `loudnorm` + 4x oversampled true-peak ceiling |
| Silence removal + NLE cut export | Per-seat podcast editors ($24-$65/mo) | Energy/ZCR VAD + `.otio` / CMX 3600 `.edl` / `.srt` / `.vtt` / WAV |
| Automation & editor integration | Closed plugins | Scriptable CLI, Python API, and `stdio` MCP server |

## Requirements

- Python 3.10+
- `ffmpeg` and `ffprobe` on `PATH`
- Python packages: `numpy`, `scipy`, `soundfile`

## Installation

```bash
git clone https://github.com/eldertek/loudgate.git
cd loudgate
pip install -e ".[dev]"
```

## Quick Start: Studio GUI (`loudgate ui`)

Launch the local broadcast console (binds strictly to `127.0.0.1`, default port `8742`):

```bash
loudgate ui
# or standalone command:
loudgate-ui --workspace-dir ./episodes --no-open
```

Inside the browser Studio (`EN` / `FR` language toggle built in):
1. Click **Load Built-in Broadcast Speech+Silence Sample WAV** (or drop/upload any local file or select from `--workspace-dir`).
2. Inspect the interactive Canvas waveform and **EBU R128 Probe** meters (`LUFS`, `LRA`, `True Peak`, `4x OS Peak`, `SNR`, `DC offset`).
3. Clean rumble, clicks, hiss, and sibilance in **STFT Spectral Denoiser**, audition **A vs B**, or click **Use as Active Source**.
4. Normalize in **Broadcast Mastering** (`podcast -14`, `mobile -16`, `broadcast -23 LUFS`, etc. loaded from `MASTER_PRESETS`).
5. Segment speech vs silence in **Silence Cutter & Timeline** with green/red waveform markers and download `.otio`, `.edl`, `.srt`, `.vtt`, and trimmed `.wav`.

## Quick Start (CLI)

### 1. Audit loudness, peaks, clipping, DC offset, and SNR

```bash
loudgate probe episode_raw.wav --json
```

Reports EBU R128 integrated loudness (`LUFS`), loudness range (`LRA`), FFmpeg true peak (`dBTP`), 4x polyphase oversampled inter-sample peak excess, DC offset per channel, clipped sample ratio, and estimated SNR (`dB`).

### 2. Clean noise, rumble, and clicks

```bash
loudgate clean episode_raw.wav episode_clean.wav --highpass-hz 80 --denoise-strength 1.0 --deess
```

Pipeline stages:
- DC offset removal
- Zero-phase 4th-order Butterworth high-pass filter (`scipy.signal.sosfiltfilt`, zero group-delay distortion)
- MAD second-difference de-clicker for isolated digital impulses
- Tight-frame periodic root-Hann STFT WOLA spectral Wiener denoising (`n_fft=2048`, `hop_length=512`)
- Optional split-band sibilance attenuator (`--deess`) and downward noise gate (`--gate`)

### 3. Master to broadcast or podcast targets

```bash
# Podcast / Web (-14 LUFS, <= -1.0 dBTP)
loudgate master episode_clean.wav episode_podcast.wav --preset podcast

# EBU R128 Broadcast (-23 LUFS, <= -1.0 dBTP)
loudgate master episode_clean.wav episode_broadcast.wav --preset broadcast

# Mobile / Stereo (-16 LUFS, <= -1.0 dBTP) + MP3 export
loudgate master episode_clean.wav episode_mobile.mp3 --preset mobile --bitrate 192k
```

Uses two-pass linear FFmpeg `loudnorm` followed by a post-render `ebur128` verification pass and a 4x oversampled PCM true-peak safety limiter when needed.

### 4. Cut silences and export NLE timelines + subtitles

```bash
loudgate cut episode_podcast.wav ./cuts/ --thresh-db -40 --min-silence-ms 400 --pad-ms 80 --fps 25
```

Outputs into `./cuts/`:
- `episode_podcast.otio` (OpenTimelineIO JSON timeline for DaVinci Resolve / Premiere workflows)
- `episode_podcast.edl` (CMX 3600 EDL)
- `episode_podcast.srt` and `episode_podcast.vtt` (cue timestamps aligned to the trimmed timeline)
- `episode_podcast_cut.wav` (rendered via FFmpeg `atrim` + micro-fades + `concat`)

### 5. Run as an MCP `stdio` server

```bash
loudgate mcp
```

Exposed MCP tools:
- `probe_loudness`
- `clean_spectral`
- `master_broadcast`
- `cut_silences_otio`

Example MCP client configuration:

```json
{
  "mcpServers": {
    "loudgate": {
      "command": "loudgate",
      "args": ["mcp"]
    }
  }
}
```

## Python API

```python
from loudgate import CleanConfig, MasterConfig, clean_file, cut_silences, master_file, probe_file

report = probe_file("raw.wav")
clean_file("raw.wav", "clean.wav", CleanConfig(highpass_hz=80.0, denoise_strength=1.0))
master = master_file("clean.wav", "master.wav", MasterConfig(preset="podcast"))
cuts = cut_silences("master.wav", "exports/")
```

## v0.1 Scope and Known Limitations

- The STFT Wiener denoiser targets stationary background noise (room floor, fan hiss, hum) rather than heavy room dereverberation or overlapping-speaker separation.
- Silence cutting uses RMS energy + zero-crossing rate VAD; it does not perform ASR transcription or speaker diarization.
- Mastering and container transcoding rely on a local `ffmpeg` / `ffprobe` binary installed on `PATH`.

## Running Tests

```bash
pytest -v
```

The test suite verifies DSP invariants and UI integration:
- Parseval energy conservation across the tight-frame STFT/ISTFT (`relative error < 1e-12`)
- Zero-phase high-pass attenuation and impulse click repair
- Real FFmpeg `ebur128` verification before and after two-pass `loudnorm` at `-14`, `-16`, and `-23 LUFS` with `true_peak_dbtp <= -1.0`
- VAD/silence segmentation, valid OTIO/EDL/SRT/VTT generation, and FFmpeg `atrim` rendering
- MCP JSON-RPC 2.0 `stdio` protocol round-trips
- Studio UI loopback HTTP endpoints, CSP & path traversal rejections, byte-range streaming, and full DSP round-trips

## Commercial Support & Custom Pipelines

Need custom audio post-production automation, broadcast QA integration, or dedicated maintenance? See [Eclipse Technology Open Source Pro](https://eclipse-technology.eu/open-source-pro.html).

## License

MIT License. See [LICENSE](LICENSE).