Build a Custom Soundboard

Why This Project?

Every livestream has a soundboard. The pro ones cost hundreds of dollars and lock you into specific hardware. This chapter builds one entirely in the browser — no install, no driver, no subscription. You upload audio files, assign keyboard shortcuts, and fire sounds with a keypress during a live show.

The core new concept is the Web Audio API — a low-level browser audio engine that gives you programmatic control over playback, gain, routing, and timing. You'll also learn how to store binary audio data in the browser using base64 encoding via the FileReader API and localStorage.

The AI Angle for This Chapter

The Web Audio API has a quirk that catches everyone: AudioBufferSourceNode is single-use. You cannot call source.start() twice on the same node — you must create a new one each time the pad fires. If you ask AI to "make the pad play audio," it may give you code that works once and then silently fails.

The entire playback system reduces to: base64 string → fetch → ArrayBuffer → AudioBuffer → SourceNode → GainNode → speakers. Once you see that pipeline clearly, every Web Audio feature is just adding a new node in the chain.

Before You Build — Map the Audio Graph

Draw the signal chain before writing any code:

Build It

Layout: 260px sidebar + flexible main area.
Sidebar contains:
- Add Pad form: label input, key capture input, color picker, file upload
- Board Settings: board name, grid columns select
- Actions: Stop All, Export JSON, Import JSON, Clear Board
- Shortcuts reference
Main: board title, pad grid div, empty state
Bottom: sticky master volume bar with range input + Stop All button

Pad data shape:
{ id, label, key, color, audioData: base64|null, duration: number|null }

function readFileAsBase64(file) {
  return new Promise((res, rej) => {
    const reader = new FileReader();
    reader.onload = e => res(e.target.result); // data:audio/...;base64,...
    reader.onerror = rej;
    reader.readAsDataURL(file);
  });
}

function getAudioDuration(base64) {
  return new Promise(res => {
    const audio = new Audio(base64);
    audio.addEventListener('loadedmetadata', () => res(audio.duration));
    audio.addEventListener('error', () => res(0));
  });
}

async function playPad(id) {
  const pad = pads.find(p => p.id === id);
  const ctx = getAudioCtx(); // creates AudioContext if needed

  // Fetch the base64 data URI as an ArrayBuffer
  const response = await fetch(pad.audioData);
  const arrayBuf = await response.arrayBuffer();

  // Decode into an AudioBuffer
  const audioBuf = await ctx.decodeAudioData(arrayBuf);

  // Create nodes (must be fresh per play)
  const source = ctx.createBufferSource();
  source.buffer = audioBuf;
  const gain = ctx.createGain();
  gain.gain.value = 1;

  // Connect: source → gain → masterGain → speakers
  source.connect(gain);
  gain.connect(masterGain);
  source.start(0);

  // Track for stop-all
  activeSources[id] = { source, gainNode: gain };
  source.onended = () => { delete activeSources[id]; updateUI(); };
}

document.addEventListener('keydown', e => {
  // Skip if user is typing
  if (['INPUT','TEXTAREA'].includes(document.activeElement.tagName)) return;
  if (e.key === ' ') { e.preventDefault(); stopAll(); return; }
  const pad = pads.find(p => p.key === e.key.toUpperCase());
  if (pad && pad.audioData) playPad(pad.id);
});

// Visual feedback on the pad element:
// - Add class 'playing' on start (CSS: scale down, red border)
// - Animate .pad-progress bar: width 0% → 100% over audioBuf.duration seconds
// - Remove 'playing' class and reset bar in source.onended callback

savePads(): JSON.stringify({ boardName, masterVolume, gridCols, pads })
  → localStorage.setItem('it_ch07_board', ...)

Note: base64 audio data can be large. Wrap in try/catch —
localStorage throws a QuotaExceededError if full.

exportBoard(): same Blob download pattern as Ch05/06
  → downloads as boardname.json

importBoard(file): FileReader reads the JSON text,
  JSON.parse restores state, call renderPads() + savePads()

Concepts You Just Used

• AudioContext — the root of the Web Audio graph; must be created or resumed on a user gesture due to browser autoplay policy
• AudioBufferSourceNode — single-use playback node; create a new one on every trigger, never reuse
• GainNode — a volume multiplier in the audio graph; connect in series between source and destination
• decodeAudioData() — async method that converts a raw ArrayBuffer into a playable AudioBuffer
• FileReader.readAsDataURL() — converts a local file into a base64 data URI string for in-memory storage
• fetch() on a data URI — you can fetch(base64String) and call .arrayBuffer() on the result; a clean way to convert base64 back to binary
• localStorage quota — base64 audio is ~33% larger than the raw binary; plan for QuotaExceededError on large files
• source.onended — fires when playback completes naturally; use it to clean up state and reset visual feedback

Reflect

Go Further