audiowaveform

What this skill does

# Audiowaveform

## Overview

Generate waveform visualizations from audio files using BBC's audiowaveform tool. Renders PNG/SVG waveform images and outputs peak data as JSON or binary for web-based audio players (wavesurfer.js, peaks.js). Ideal for podcast players, music platforms, social media audio previews, and any UI that shows audio waveforms.

## Instructions

### Step 1: Installation

```bash
# Ubuntu/Debian
apt install -y audiowaveform

# macOS
brew install audiowaveform

# From source (if not in repos)
apt install -y cmake g++ libmad0-dev libsndfile1-dev libgd-dev libboost-filesystem-dev libboost-program-options-dev libboost-regex-dev
git clone https://github.com/bbc/audiowaveform.git
cd audiowaveform && mkdir build && cd build
cmake .. && make && make install

# Verify
audiowaveform --version
```

### Step 2: Generate Waveform Images

**Basic PNG waveform:**
```bash
audiowaveform -i episode.wav -o waveform.png
```

**Customized waveform:**
```bash
audiowaveform -i episode.mp3 -o waveform.png \
  --width 1800 \
  --height 200 \
  --colors audacity \
  --background-color ffffff \
  --waveform-color 3b82f6 \
  --axis-label-color 666666 \
  --border-color ffffff \
  --zoom auto
```

**Color schemes:**
- `audacity` — classic Audacity look
- Custom: use hex `--waveform-color`, `--background-color`

**High-res for social media (1200x630 — OG image size):**
```bash
audiowaveform -i episode.wav -o social-preview.png \
  --width 1200 --height 630 \
  --background-color 1a1a2e \
  --waveform-color 00d4ff \
  --no-axis-labels
```

**Specific time range:**
```bash
audiowaveform -i episode.wav -o clip.png \
  --start 60 --end 180 \
  --width 800 --height 150
```

**Split channels (stereo):**
```bash
audiowaveform -i stereo.wav -o waveform.png --split-channels
```

### Step 3: Generate Waveform Data (JSON)

For web players that render waveforms client-side:

```bash
# JSON output (peaks data)
audiowaveform -i episode.wav -o peaks.json \
  --pixels-per-second 20 \
  --bits 8

# Binary format (smaller files)
audiowaveform -i episode.wav -o peaks.dat \
  --pixels-per-second 20 \
  --bits 8
```

**JSON structure:**
```json
{
  "version": 2,
  "channels": 1,
  "sample_rate": 44100,
  "samples_per_pixel": 2205,
  "bits": 8,
  "length": 1200,
  "data": [0, 45, -3, 67, 12, 89, ...]
}
```

**Pixels-per-second guidelines:**
- `20` — good for full episode overview (podcast, 1-2h)
- `50` — detailed view for songs (3-5 min)
- `100` — very detailed, for short clips
- `200+` — waveform editing precision

### Step 4: Web Player Integration

**With wavesurfer.js:**
```html
<div id="waveform"></div>
<button onclick="wavesurfer.playPause()">Play/Pause</button>

<script src="https://unpkg.com/wavesurfer.js@7"></script>
<script>
const wavesurfer = WaveSurfer.create({
  container: "#waveform",
  waveColor: "#3b82f6",
  progressColor: "#1d4ed8",
  cursorColor: "#ef4444",
  barWidth: 2,
  barRadius: 2,
  barGap: 1,
  height: 80,
  responsive: true,
  // Use pre-generated peaks for instant rendering
  peaks: null, // Will load from JSON
  url: "/audio/episode.mp3",
});

// Load pre-generated peaks (skip client-side decoding)
fetch("/waveforms/episode-peaks.json")
  .then(r => r.json())
  .then(data => {
    wavesurfer.load("/audio/episode.mp3", [data.data]);
  });
</script>
```

**With peaks.js (BBC):**
```html
<div id="zoomview-container"></div>
<div id="overview-container"></div>

<script src="https://unpkg.com/peaks.js"></script>
<script>
const audioElement = document.getElementById("audio");

Peaks.init({
  containers: {
    zoomview: document.getElementById("zoomview-container"),
    overview: document.getElementById("overview-container"),
  },
  mediaElement: audioElement,
  dataUri: {
    json: "/waveforms/episode-peaks.json",
  },
  zoomLevels: [256, 512, 1024, 2048],
  overview: {
    waveformColor: "#3b82f6",
    playedWaveformColor: "#1d4ed8",
  },
  zoomview: {
    waveformColor: "#3b82f6",
    playedWaveformColor: "#1d4ed8",
  },
}, (err, peaks) => {
  if (err) console.error(err);
  // peaks instance ready
});
</script>
```

### Step 5: Batch Processing & Pipeline

**Generate waveforms for all episodes:**
```bash
#!/bin/bash
# generate-waveforms.sh
AUDIO_DIR="./episodes"
OUT_DIR="./waveforms"
mkdir -p "$OUT_DIR"

for f in "$AUDIO_DIR"/*.{mp3,wav}; do
  [ -f "$f" ] || continue
  base=$(basename "$f" | sed 's/\.[^.]*$//')
  
  # PNG preview
  audiowaveform -i "$f" -o "$OUT_DIR/${base}.png" \
    --width 1200 --height 150 \
    --background-color ffffff --waveform-color 3b82f6

  # JSON peaks for web player
  audiowaveform -i "$f" -o "$OUT_DIR/${base}.json" \
    --pixels-per-second 20 --bits 8

  # Social media preview
  audiowaveform -i "$f" -o "$OUT_DIR/${base}-social.png" \
    --width 1200 --height 630 \
    --background-color 0f172a --waveform-color 38bdf8 --no-axis-labels

  echo "✅ $base"
done
```

### Step 6: Convert Between Formats

```bash
# Binary → JSON
audiowaveform -i peaks.dat -o peaks.json

# JSON → PNG (render from pre-computed data)
audiowaveform -i peaks.json -o waveform.png \
  --width 1200 --height 200 \
  --zoom auto

# From raw audio → multiple outputs
audiowaveform -i input.wav -o peaks.dat --bits 8 --pixels-per-second 20
audiowaveform -i peaks.dat -o overview.png --width 2000 --height 100
audiowaveform -i peaks.dat -o detail.png --start 60 --end 120 --width 800 --height 200
```

## Examples

### Example 1: Generate waveform previews for a podcast website
**User prompt:** "I have 50 podcast episodes as MP3 files in ./episodes/. Generate PNG waveform previews and JSON peak data for each one so I can use them with wavesurfer.js on my Next.js site."

The agent will:
1. Verify audiowaveform is installed, install it via `apt` or `brew` if missing.
2. Create output directories `./waveforms/png/` and `./waveforms/json/`.
3. Write a bash loop that iterates over all `.mp3` files in `./episodes/`, generating a 1200x150 PNG with brand colors and a JSON peaks file at 20 pixels-per-second with 8-bit depth for each episode.
4. Run the batch script and report how many waveforms were generated.
5. Show a wavesurfer.js code snippet that loads the pre-generated JSON peaks for instant waveform rendering without client-side audio decoding.

### Example 2: Create social media audio preview images
**User prompt:** "I need OG-image-sized waveform graphics for sharing podcast episodes on Twitter. Dark background, cyan waveform, no axis labels. Do episodes 10 through 15."

The agent will:
1. Identify the audio files for episodes 10-15 in the episodes directory.
2. Run audiowaveform for each file with `--width 1200 --height 630` (OG image dimensions), `--background-color 0f172a`, `--waveform-color 06b6d4`, and `--no-axis-labels`.
3. Save output files as `episode-10-social.png` through `episode-15-social.png`.
4. Confirm the files were generated and note their file sizes.

## Guidelines

- Always check that audiowaveform is installed before running commands; it is not available in most default package managers and may require building from source on older systems.
- Use `--pixels-per-second 20` with `--bits 8` for JSON peaks data intended for web players; higher values produce unnecessarily large files for overview waveforms.
- Pre-generate waveform JSON server-side rather than decoding audio client-side; this eliminates multi-second load times for listeners on the web.
- For social media images, use `--no-axis-labels` to produce cleaner graphics without time markers that clutter the visual at small sizes.
- When processing large batches, generate the binary `.dat` format first, then render PNGs and JSONs from the `.dat` file to avoid re-reading the audio multiple times.