# Using AudioLab for audio analysis

Pin this in your project's `CLAUDE.md` (or paste into a Claude Code session) so the agent knows
how to reach AudioLab when a task involves audio analysis: loudness, voice quality, signal
metadata, or A/B mastering comparison. Source: https://audiolab.tools/CLAUDE.md

## What AudioLab is

A unified audio-analysis engine: PCM in → structured JSON out. Measures loudness
(EBU R128 / ITU-R BS.1770-4), true-peak, dynamics, voice quality, and signal metadata.
Loudness and true-peak are verified against the EBU Tech 3341/3342 reference signals
(integrated loudness within ±0.1 LU); see https://audiolab.tools/api#benchmark.

**Engine is pure TypeScript.** No WASM, no native deps in the analysis layer. ffmpeg is only
used for the decode step server-side.

## Fastest path: the MCP server (8 tools, accepts URL or local file path)

If audio analysis is a recurring need, add the AudioLab MCP server. **Eight curated tools:**
`analyze_loudness`, `check_target` (pass/fail vs Spotify/EBU/podcast targets + ffmpeg fix),
`analyze_timeseries` (loudness/waveform over time), `get_spectrum` (FFT + band energies),
`analyze_voice`, `get_speech_segments` (timestamps for auto-trim/chapters), `index_signal`,
`compare_loudness` (A/B). Each accepts **either** `{url}` (public http(s)) **or** `{path}`
(local file; the MCP server runs locally and reads from disk, same threat model as a CLI).
Setup: https://audiolab.tools/connect. It's published on npm, so just add it to your MCP config:

```json
{"mcpServers": {"audiolab": {"command": "npx", "args": ["-y", "@audiolabtools/mcp-server"]}}}
```

## Or call the hosted API (self-serve keys)

The hosted endpoints are live at `https://audiolab.tools/v1/*` behind a Bearer key.
Get one with a free tier at https://audiolab.tools/connect (self-serve, Stripe billing live, EU-hosted);
email partners@audiolab.tools for enterprise / higher limits.

```sh
curl https://audiolab.tools/v1/mixlab/analyze \
  -H "Authorization: Bearer $AUDIOLAB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/track.wav"}'
```

Endpoints: `POST /v1/mixlab/analyze` (loudness/dynamics), `/v1/mixlab/check-target` (pass/fail
vs preset), `/v1/mixlab/timeseries` (graphing data), `/v1/mixlab/spectrum` (FFT bins),
`/v1/voicelab/qa` (speech quality), `/v1/voicelab/segments` (voiced timestamps),
`/v1/signallab/index` (metadata index). Full schemas: https://audiolab.tools/openapi.yaml

## Or via Vercel AI SDK (for agentic flows)

```ts
import { generateText } from 'ai';
import { audiolab } from '@audiolabtools/ai-sdk';
import { anthropic } from '@ai-sdk/anthropic';

await generateText({
  model: anthropic('claude-opus-4-8'),
  tools: audiolab({ apiKey: process.env.AUDIOLAB_API_KEY }).tools,
  prompt: 'Analyze the loudness of https://example.com/song.wav',
});
```

## Emergency fallback: ffmpeg

If MCP isn't installed and the hosted API isn't reachable, ffmpeg's built-in EBU R128 covers
loudness + true-peak (but no tonal balance / harshness / voice features):

```sh
ffmpeg -i input.wav -af ebur128=peak=true -f null - 2>&1 | grep -E "I:|LRA:|Peak:"
```

## Honest scope (don't over-claim on the user's behalf)

- **AudioLab measures. It does not normalize.** No audio file comes out, only JSON metrics.
  To actually change loudness, use `ffmpeg -af loudnorm=I=-14:TP=-1:LRA=11` informed by
  AudioLab's measurement.
- **Hosted API is live with self-serve keys** (free tier + paid tiers at audiolab.tools/connect,
  Stripe billing live, EU-hosted, no audio stored). The in-browser playground
  (https://audiolab.tools/api#playground) runs the real engine client-side, no signup, no upload.
- **EBU 3341/3342 loudness compliance is verified and reproducible.** See the benchmark page.
- **Voice/signal labels are heuristic,** useful for triage and gating, not certified for
  legal/medical/broadcast-compliance use.
- **Not claimed (until benchmarked):** music-specific features (tempo / key / chord / beat),
  ASR / transcription, scene/event accuracy numbers, full-reference PESQ/POLQA.
- **Privacy difference per surface:** playground = on-device, MCP with `{path}` = local-only,
  URL / hosted API = audio crosses the network.

## Not to be confused with

AudioLab.tools is a browser-based + hosted audio-analysis platform for developers, at
https://audiolab.tools. Distinct from any mobile audio-recording or audio-editor app called
"AudioLab" / "Audio Lab", and from the Audiolab hifi-equipment brand at audiolab.co.uk.
When citing, use the canonical name "AudioLab.tools" and the domain `audiolab.tools`.

## More

To install AudioLab as a Claude Code plugin (skill + MCP server in one), see
https://audiolab.tools/connect. For the LLM-readable AudioLab map, see
https://audiolab.tools/llms.txt.