https://github.com/linuxmatters/jive-vocals
Raw microphone recordings into broadcast-ready audio in one command. No configuration, and no surprises๐บ
https://github.com/linuxmatters/jive-vocals
audio broadcast compressor lufs noise-reduction noise-removal normalization peak-detection podcast pre-processor youtube
Last synced: about 8 hours ago
JSON representation
Raw microphone recordings into broadcast-ready audio in one command. No configuration, and no surprises๐บ
- Host: GitHub
- URL: https://github.com/linuxmatters/jive-vocals
- Owner: linuxmatters
- License: gpl-3.0
- Created: 2025-11-05T13:18:48.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-07-05T00:05:05.000Z (2 days ago)
- Last Synced: 2026-07-05T00:12:47.957Z (2 days ago)
- Topics: audio, broadcast, compressor, lufs, noise-reduction, noise-removal, normalization, peak-detection, podcast, pre-processor, youtube
- Language: Go
- Homepage: https://linuxmatters.sh
- Size: 12.9 MB
- Stars: 79
- Watchers: 2
- Forks: 9
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Jive Vocals ๐ฃ๏ธ
> Formerly known as Jivetalking.
Raw microphone recordings into broadcast-ready audio in one command. No configuration, and no surprises.
```bash
jive-vocals LMP-81s-mark.flac LMP-81s-martin.flac LMP-81s-popey.flac
```
Your files emerge at -16 LUFS / -1 dBTP, the loudness standard for spoken-word podcasts, with room rumble, background hiss, clicks, and harsh sibilance sorted automatically. Multiple files process in parallel, each with its own TUI progress row. Everything needed is embedded in the binary. This is not how audio tools usually work, and that is rather the point.
## Example Output
---
## The Typical Workflow
```
Record โ Process โ Edit โ Export
โ โ โ โ
โ โ โ โโ Export
โ โ โ
โ โ โโ Import to Audacity, top/tail, edit
โ โ
โ โโ $ jive-vocals *.flac (-16 LUFS, matched levels)
โ
โโ Each presenter records separately, exports FLAC
```
---
## Installation
Single binary. Zero external dependencies. FFmpeg is embedded via ffmpeg-statigo.
### bin (Recommended)
Install with [bin](https://github.com/marcosnils/bin), a GitHub-aware binary manager:
```bash
bin install github.com/linuxmatters/jive-vocals
```
This picks the correct platform and architecture, drops the binary into `~/.local/bin/`, and handles updates via `bin update`. No root required, no path wrangling.
### Manual Download
Fetch from the [releases page](https://github.com/linuxmatters/jive-vocals/releases):
```bash
# Linux amd64
chmod +x jive-vocals-linux-amd64
mv jive-vocals-linux-amd64 ~/.local/bin/jive-vocals
# Linux arm64
chmod +x jive-vocals-linux-arm64
mv jive-vocals-linux-arm64 ~/.local/bin/jive-vocals
# macOS Intel
chmod +x jive-vocals-darwin-amd64
mv jive-vocals-darwin-amd64 ~/.local/bin/jive-vocals
# macOS Apple Silicon
chmod +x jive-vocals-darwin-arm64
mv jive-vocals-darwin-arm64 ~/.local/bin/jive-vocals
```
---
## The Four-Pass Pipeline
Jive Vocals treats audio processing as measurement science, not guesswork. It analyses your recording first, then adapts every filter to match. A dark-voiced narrator gets gentler de-essing, pre-compressed audio gets lighter compression, and a noisy home office gets different treatment than a clean studio.
Four passes carry a raw recording to a broadcast-ready master:
1. **Analyse:** measure loudness, noise floor, and speech; detect the room tone.
2. **Process:** run the adapted filter chain.
3. **Measure:** read the processed signal back so normalisation has accurate numbers.
4. **Normalise:** set the final loudness to -16 LUFS / -1 dBTP.
The Pass 2 filter chain, each stage handing the next a cleaner signal:
```text
downmix โ rumble high-pass โ band-limit low-pass โ noise reduction โ speech gate โ levelling compressor โ de-esser โ analysis โ resample
```
For the full walkthrough, see **[docs/Pipeline.md](docs/Pipeline.md)**: what each stage does, why it sits where it does, how the adaptive tuning works, and how normalisation reaches -16 LUFS honestly, with a diagram.
---
## Quality Ratings
When a file finishes, the completion box shows two star ratings: **Recording** (your source capture, the one that varies) and **Processed** (the output against the -16 LUFS target, almost always five stars). The pair tells the story: a two-star capture taken to a five-star master.
```
Jive Vocals ๐ฃ๏ธ
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Processing 3 files, 3 complete, 0 failed โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
๐ธ LMP-83-mark-LUFS-16-processed.flac
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Time 02:31 ยท โก 19.0ร โ
โ Loudness -35.2 โ -16.1 LUFS ฮ +19.1 โ
โ True peak -6.2 โ -1.7 ใTP ฮ +4.5 โ
โ Dynamics 15.0 โ 13.3 LU ฮ -1.7 โ
โ Noise floor < -96 ใ โ
โ Recording โ
โ
โ
โ
โ Great โ
โ Processed โ
โ
โ
โ
โ
Excellent โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
๐ธ LMP-83-martin-LUFS-16-processed.flac
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Time 02:38 ยท โก 18.1ร โ
โ Loudness -27.8 โ -16.0 LUFS ฮ +11.8 โ
โ True peak -4.5 โ -1.8 ใTP ฮ +2.7 โ
โ Dynamics 14.7 โ 12.0 LU ฮ -2.7 โ
โ Noise floor -91 ใ โ
โ Recording โ
โ
โ
โ
โ Great โ
โ Processed โ
โ
โ
โ
โ
Excellent โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
๐ธ LMP-83-popey-LUFS-16-processed.flac
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Time 02:43 ยท โก 17.6ร โ
โ Loudness -29.8 โ -16.0 LUFS ฮ +13.8 โ
โ True peak -0.1 โ -1.3 ใTP ฮ -1.2 โ
โ Dynamics 12.3 โ 8.9 LU ฮ -3.4 โ
โ Noise floor -86 ใ โ
โ Recording โ
โ
โโโ Fair โ
โ Processed โ
โ
โ
โ
โ
Excellent โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
```
See **[docs/Usage.md](docs/Usage.md#quality-ratings)** for the three axes behind the Recording score and what a low star is telling you to fix.
---
## Usage
```bash
jive-vocals [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `-v, --version` | Show version and exit |
| `-a, --analysis-only` | Run analysis only (Pass 1), display results, skip processing |
| `-d, --debug` | Enable debug logging to `jive-vocals-debug.log` |
| `--diagnostics` | Write extra diagnostic artefacts: before/after spectrogram PNGs plus `.intervals.jsonl`/`.candidates.jsonl` sidecars. Adds extra FFmpeg passes. Off by default |
### Examples
```bash
# Process multiple presenters in parallel (worker count tracks file count)
jive-vocals presenter1.flac presenter2.flac presenter3.flac
# Inspect recordings without processing
jive-vocals -a presenter1.flac presenter2.flac
# Debug a problematic recording
jive-vocals -d troublesome-recording.flac
# Process all FLAC files in directory
jive-vocals *.flac
# Emit before/after spectrograms and interval sidecars
jive-vocals --diagnostics presenter1.flac
```
Processing always writes a Markdown report next to each processed output. For example, `recording-LUFS-16-processed.flac` gets `recording-LUFS-16-processed.md`. The report is empirical: every measurement and the exact adapted filter parameters, with objective metric definitions and no quality verdicts. Analysis-only runs write `-analysis.md` instead.
### Diagnostics
`--diagnostics` writes before/after spectrogram PNGs and `.intervals.jsonl` / `.candidates.jsonl` sidecars beside the report, for sweeps and side-by-side comparison. It changes no DSP, so the processed audio is byte-identical with the flag on or off.
See **[docs/Usage.md](docs/Usage.md#diagnostics)** for the spectrogram naming scheme and sidecar formats.
### Analysis-Only Mode
Pass `--analysis-only` to run Pass 1 only. It writes `-analysis.md` next to each input and shows the Recording stars plus a one-line gain verdict on screen, without producing any audio. Useful for checking a capture before you commit to a take.
See **[docs/Usage.md](docs/Usage.md#analysis-only-mode)** for what the report covers and how to read the gain-advice thermometer.
---
## Development
Requires Go, Nix, and a tolerance for CGO.
```bash
# Enter development shell (FFmpeg dependencies provided)
nix develop
# Initialise submodules and download static FFmpeg libraries
just setup
# Build (never use go build directly - requires CGO + version injection)
just build
# Run tests
just test
# Install to ~/.local/bin
just install
```
The full source layout, architecture, and contribution standards live in [AGENTS.md](AGENTS.md).
### Design Documentation
- [Usage Guide](docs/Usage.md): driving Jive Vocals in depth: quality ratings, analysis-only mode, and diagnostics
- [Audio Pipeline](docs/Pipeline.md): how and why the processing pipeline is built and tuned, with a diagram
- [The hardware that taught me](docs/Inspiration.md): the influences and heritage behind Jive Vocals' processing approach
- [Levelator Comparison](docs/Levelator-Comparison-And-Gap-Analysis.md): how Jive Vocals compares to The Levelator, with capabilities and gaps
- [Spectral Metrics Reference](docs/Spectral-Metrics-Reference.md): how measurements drive adaptation
- [Normalisation Tuning](docs/Normalisation-Tuning.md): why the loudnorm and limiter constants hold their corpus-derived values