Waveform Installer

Overview

Waveform Installer (@jadujoel/waveform-installer) solves a common pain point in audio tooling: getting the BBC’s audiowaveform binary onto developer and CI machines without platform-specific manual setup. Instead of writing Dockerfiles or conditional install scripts, you add one dependency and the correct native binary is installed automatically — on macOS, Linux, or Windows.

The package is designed for projects that need to precompute waveform data (for Peaks.js visualisations, audio editors, or DAW-style UIs) as part of a build pipeline or backend service.

Features

• Cross-Platform Binary Management — Automatically installs the correct audiowaveform binary for macOS (arm64/x64 via Homebrew), Linux (arm64/x64 from .deb packages), and Windows (x64/ia32 from zip archives)
• Zero-Config Postinstall — A single bun install triggers the platform-detection and binary download; no manual steps required
• Typed Library API — Exports getAudiowaveformPath(), getAudiowaveformCommand(), hasAudiowaveformBinary(), and a generate() helper for direct waveform generation
• Shell Template Literal — A $ tagged template that auto-installs the binary on first use and forwards commands, making one-liners trivial
• Linux Dependency Auto-Fix — Runs ldd against the binary after install, maps missing shared libraries (libsndfile, libmad, libgd, etc.) to their apt packages, and installs them automatically when possible
• CI-Ready — Tested on macOS arm64, Linux arm64/x64, and Windows x64 via a GitHub Actions matrix with both smoke and integration workflows

How It Works

The installer in scripts/install.ts selects a strategy per platform:

Platform	Strategy
macOS	Checks for an existing audiowaveform on $PATH (excluding node_modules), falls back to brew install, then symlinks into the local .audiowaveform/ directory
Linux	Downloads the official .deb from GitHub Releases, extracts the binary with ar + tar, then verifies shared library dependencies with ldd
Windows	Downloads the official .zip, extracts with PowerShell’s Expand-Archive, and copies the .exe locally

Usage

As a Library

import { generate, $ } from "@jadujoel/waveform-installer";

// Generate a waveform PNG from an audio file
await generate({
  input: "track.wav",
  output: "track-waveform.png",
  bits: 8,
  zoom: 64,
});

// Or use the shell template literal for full CLI access
const result = await $`-i track.wav -o track.dat --output-format dat`;

The generate() function handles binary resolution, spawns the process, and throws with the full stderr on failure — no path juggling needed.

As a CLI

After install, the binary is available directly:

./bin/audiowaveform -i input.wav -o output.png --zoom 128

Testing

The test suite in tests/smoke.test.ts covers 11 tests including:

• Binary existence and version verification
• Path resolution to the local .audiowaveform/ directory
• Real PNG generation from a bundled tone.wav (validated by checking the PNG file header bytes)
• The $ template literal with both static and interpolated arguments
• Install idempotency — verifies that install() works both when the binary exists and after it’s been temporarily removed
• Error handling for invalid input files

A separate integration workflow runs after smoke tests pass, installing the package from the main branch on all four platform targets to verify end-to-end install behavior.

Tech Stack

Language	TypeScript (strict mode)
Runtime	Bun
Upstream Binary	bbc/audiowaveform v1.10.2
CI/CD	GitHub Actions (smoke + integration matrix)
Platforms	macOS arm64/x64, Linux arm64/x64, Windows x64/ia32

Source Code

The source code is available on the project’s GitHub repository.