docker-audiolla

# audiolla

[![Docker Pulls](https://img.shields.io/docker/pulls/psyb0t/audiolla?style=flat-square)](https://hub.docker.com/r/psyb0t/audiolla)
[![Docker Hub](https://img.shields.io/docker/v/psyb0t/audiolla?sort=semver&label=Docker%20Hub&style=flat-square)](https://hub.docker.com/r/psyb0t/audiolla)
[![License: WTFPL](https://img.shields.io/badge/License-WTFPL-brightgreen.svg?style=flat-square)](http://www.wtfpl.net/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg?style=flat-square)](https://www.python.org/downloads/)

**Thirty audio engines. One port. Zero cloud. Fire-and-forget async jobs. Webhooks.**

You needed Demucs for stems. Then librosa for BPM and key. Then basic-pitch for MIDI transcription. Then pyannote for speaker diarization. Then DeepFilterNet for speech enhancement. Then you spent three days debugging Python version conflicts and now you hate everything.

audiolla is what happens when you stop doing that.

Every audio processing tool worth using — wrapped in one HTTP API, running in one Docker container. POST a file. Get audio, JSON, or MIDI back. Drive it from curl, shell scripts, Python notebooks, Makefiles, or point an LLM agent at the MCP endpoint and let it rip.

No account. No subscription. No per-minute billing. No vendor lock-in. `docker run` and you're done.

---

## What's in the box

| | |
|--|--|
| 🎛️ **Stem separation** | Demucs — htdemucs, fine-tuned, 6-stem, MDX variants |
| 🎚️ **Mastering** | Reference mastering (matchering) + custom pedalboard chains |
| 📊 **Analysis** | BPM · key · LUFS · beats · onsets · melody · structural segments |
| 🎹 **Chords + key** | Chord detection + Krumhansl-Schmuckler key estimation |
| 🎵 **Audio → MIDI** | Polyphonic transcription via Spotify's basic-pitch (ONNX, no TF) |
| 🧹 **Restoration** | De-reverb · de-echo · de-noise via UVR BS-Roformer + MelBand Roformer |
| 🗣️ **Speech** | Enhancement (DeepFilterNet) · VAD (silero-vad) · diarization (pyannote) |
| 🖼️ **Visuals** | Spectrogram + waveform PNGs + 8-mode animated MP4/WebM |
| 🔍 **Fingerprint** | Chromaprint acoustic fingerprinting (AcoustID-compatible) |
| ✂️ **Silence** | Detect gaps · trim edges · strip all silence |
| 🎼 **MIDI pipeline** | Compose from JSON · inspect · transform · render via fluidsynth |
| 🎸 **Effects** | 23-effect pedalboard chain — Compressor, Reverb, PitchShift, filters… |
| 🔧 **Transforms** | Sox DSP — pitch, tempo, EQ, reverb, gain |
| 📢 **Loudness** | Measure LUFS · normalize to target |
| 🥁 **HPSS** | Harmonic/percussive source separation via librosa median filter |
| 🔇 **Noise reduction** | Spectral noise reduction via noisereduce — stationary + adaptive modes |
| ⏩ **Time-stretch** | Independent tempo factor + pitch shift via librosa phase vocoder |
| 🏷️ **Audio tagging** | Top-K AudioSet class labels via Audio Spectrogram Transformer |
| 🔗 **Audio embeddings** | 512-dim semantic embeddings via LAION CLAP + optional text similarity |
| 🏷️ **Zero-shot classify** | CLAP cosine similarity against any free-form text labels — genres, moods, instruments |
| 📋 **Audio info** | ffprobe metadata — duration, sample rate, channels, codec, bit depth |
| ✂️ **Trim** | Cut a clip by start/end seconds — any format in, any format out |
| 🎚️ **Mix** | Combine N staged tracks with per-track gain_db — pure ffmpeg, no model |
| 🔗 **Concat** | Stitch N audio files end-to-end in order |
| ⏩ **Speed** | Change playback speed without pitch shift (0.1× – 10×) via ffmpeg atempo |
| 🔄 **Convert** | Re-encode: format, sample rate, channel count in one call |
| 🔍 **Similar** | Cosine similarity between two audio files via CLAP embeddings |
| 🎹 **MIDI quantize** | Snap MIDI note timings to a rhythmic grid (16th, 8th, quarter…) |
| 🌅 **Fade** | Fade-in and/or fade-out with 13 curve shapes |
| ⏪ **Reverse** | Flip audio backwards |
| 🔁 **Loop** | Repeat audio N times |
| 🎯 **BPM match** | Auto-detect BPM then stretch to a target — no manual math |
| 📈 **Loudness curve** | RMS envelope over time — time-stamped dB values for gain automation |
| 🎤 **Pitch correct** | Auto-tune toward nearest chromatic semitone — configurable strength |
| 🔧 **Repair** | Declip + dehum — fix clipped peaks and remove power-line hum |
| 🔁 **Loop point** | Find best seamless loop boundary — score, bar count, candidates list |
| 🥁 **Drum machine** | Step-sequencer spec → GM drum MIDI — 16-step pattern, swing, tempo |
| 🎼 **Chords to MIDI** | Chord progression → MIDI file — root+3rd+5th voicings per segment |
| ↔️ **Stereo width** | Widen or collapse the stereo image via M/S processing |
| ✂️ **Split** | Split into N equal parts or on silence — returns ZIP of segments |
| 🔊 **Pan** | Position audio in the stereo field (-1 left → 0 center → 1 right) |
| 🎚️ **EQ** | Parametric EQ — JSON array of freq/gain_db/width_hz bands |
| 🎵 **Key match** | Detect source key then pitch-shift to a target key |
| 🎙️ **Sidechain duck** | Duck music when a trigger track (voice) is loud |
| 🏷️ **Metadata** | Read and write ID3/Vorbis/FLAC/WAV audio tags via mutagen |
| 🔴 **Clip detect** | Detect digital clipping — count, ratio, peak dBFS |
| ↔️ **Mid/Side** | Encode L/R → Mid+Side or decode Mid+Side → L/R |
| ✂️ **Beat slice** | Slice audio at detected beat positions — returns ZIP of segments |
| 🏟️ **Conv reverb** | Convolution reverb via impulse response — wet_mix control |
| 🥁 **Transient shaper** | Attack/sustain dual-compressor — punch up drums, cut room tail |
| 🎚️ **Multiband compress** | N-band compressor with zero-phase LR4 crossovers — mastering-grade dynamics |
| 🎛️ **DJ prep** | One call: BPM + key + Camelot wheel position + integrated LUFS |
| 📦 **Batch** | Run trim/convert/fade/reverse/speed/eq on staged files in sequence |
| 🧩 **Presets + pipeline** | Curated YAML workflows (`master-for-spotify`, `podcast-cleanup`, …) + ad-hoc op chaining server-side |
| 🗂️ **Catalog** | `GET /v1/catalog` — machine-readable endpoint list grouped by category for discovery |
| ⚡ **Async jobs** | Every endpoint supports `async_job=true` — fire-and-forget + webhook callbacks |

---

## Table of Contents

- [Run it](#run-it)
- [Quick start](#quick-start)
- [What it can do](#what-it-can-do)
  - [Split stems](#split-stems)
  - [Master](#master)
  - [Analyze](#analyze)
  - [Beats, onsets, melody, segments](#beats-onsets-melody-segments)
  - [Silence detection and trimming](#silence-detection-and-trimming)
  - [Visualize (spectrogram, waveform, video)](#visualize-spectrogram-waveform-video)
  - [Acoustic fingerprint](#acoustic-fingerprint)
  - [De-reverb, de-echo, de-noise](#de-reverb-de-echo-de-noise)
  - [Audio-to-MIDI transcription](#audio-to-midi-transcription)
  - [Neural speech and vocal enhancement](#neural-speech-and-vocal-enhancement)
  - [Chord and key detection](#chord-and-key-detection)
  - [Voice activity detection](#voice-activity-detection)
  - [Speaker diarization](#speaker-diarization)
  - [Transform](#transform)
  - [Loudness measurement](#loudness-measurement)
  - [Loudness curve](#loudness-curve)
  - [Loudness normalization](#loudness-normalization)
  - [HPSS (harmonic/percussive split)](#hpss-harmonicpercussive-split)
  - [Spectral noise reduction](#spectral-noise-reduction)
  - [Time-stretch and pitch-shift](#time-stretch-and-pitch-shift)
  - [Pitch correct](#pitch-correct)
  - [Repair](#repair)
  - [Audio tagging](#audio-tagging)
  - [Audio embeddings](#audio-embeddings)
  - [Zero-shot classification](#zero-shot-classification)
  - [Audio info](#audio-info)
  - [Trim](#trim)
  - [Mix](#mix)
  - [Concat](#concat)
  - [Speed](#speed)
  - [Convert](#convert)
  - [Similar](#similar)
  - [MIDI quantize](#midi-quantize)
  - [Fade](#fade)
  - [Reverse](#reverse)
  - [Loop](#loop)
  - [BPM match](#bpm-match)
  - [Stereo width](#stereo-width)
  - [Split](#split)
  - [Pan](#pan)
  - [EQ](#eq)
  - [Key match](#key-match)
  - [Sidechain duck](#sidechain-duck)
  - [Effects chain](#effects-chain)
  - [Loop point](#loop-point)
  - [Compose MIDI](#compose-midi)
  - [Inspect MIDI](#inspect-midi)
  - [Transform MIDI](#transform-midi)
  - [Render MIDI to audio](#render-midi-to-audio)
  - [Generate music from a spec](#generate-music-from-a-spec)
  - [Drum pattern](#drum-pattern)
  - [Chords to MIDI](#chords-to-midi)
  - [Audio metadata tags](#audio-metadata-tags)
  - [Clip detection](#clip-detection)
  - [Mid/Side encode and decode](#midside-encode-and-decode)
  - [Beat slice](#beat-slice)
  - [Convolution reverb](#convolution-reverb)
  - [Transient shaper](#transient-shaper)
  - [Multiband compression](#multiband-compression)
  - [DJ prep](#dj-prep)
  - [De-ess](#de-ess)
  - [Stereo field analysis](#stereo-field-analysis)
  - [Audio thumbnail](#audio-thumbnail)
  - [MIDI humanize](#midi-humanize)
  - [Batch operations](#batch-operations)
  - [Async jobs and webhooks](#async-jobs-and-webhooks)
  - [Stage files](#stage-files)
  - [Remote URLs](#remote-urls)
- [Engines](#engines)
- [Workflows — presets + pipeline](#workflows--presets--pipeline)
- [API catalog](#api-catalog)
- [Endpoints](#endpoints)
- [MCP](#mcp)
- [Configuration](#configuration)
- [What's not in here](#whats-not-in-here)
- [Build & dev](#build--dev)
- [Supply chain](#supply-chain)
- [License](#license)

---

## Run it

```bash
# no GPU
docker run --rm -it \
  -v $HOME/.audiolla-data:/data \
  -p 8000:8000 \
  psyb0t/audiolla:latest

# GPU
docker run --rm -it --gpus all \
  -v $HOME/.audiolla-data:/data \
  -e AUDIOLLA_DEVICE=cuda \
  -p 8000:8000 \
  psyb0t/audiolla:latest-cuda
```

Demucs weights prefetch at container startup (for whichever variants are enabled) and cache in `/data/torch_cache/`. First boot downloads them; same `-v` mount next time and they're already there. Other engines (matchering, pedalboard, librosa, sox, fx, midi) have no weights — they're ready as soon as `/healthz` is green.

---

## Migration from v0.23.x → v1.0.0

**v1.0.0 is a breaking API release.** Every existing client breaks. The new s