Waveform Playlist: Multitrack Web Audio Editing in React

Waveform Playlist's Browser Editing Scope

Waveform Playlist addresses the gap between a conventional audio player and a full desktop digital audio workstation. It is aimed at developers building browser applications where users must place multiple clips on a shared timeline, inspect audio visually, record new material, annotate events, and hear the resulting arrangement. The React and TypeScript implementation is particularly relevant to product teams that already own their interface and want audio editing embedded in it.

The feature set extends beyond basic playback. Each track can contain multiple clips, and the README documents drag-to-move and trim interactions. Canvas waveforms include zoom controls, while annotations attach text to points in time and support keyboard navigation. Recording uses AudioWorklet and includes a live waveform preview. MIDI files can be parsed into piano-roll views and played with SoundFont samples. Export can target WAV, an individual track, or the full mix, with effects included according to the documented Tone.js export path.

That scope creates a clear distinction from an embedded HTML audio element. Waveform Playlist is intended for applications where timing, track organization, editing gestures, and synchronized visual information are central to the interface. It is less suitable when the requirement is merely to stream one file through a play button.

Tracks, Clips, Canvas Peaks, and Timeline Data

The README's starter example shows audio being fetched as bytes, converted into an AudioBuffer, and then represented as a track containing a time-positioned clip. `createTrack` accepts the track name and its clips, while `createClipFromSeconds` attaches an `audioBuffer` and a `startTime`. The resulting track array is passed to `WaveformPlaylistProvider`, which supplies state to `Waveform` and the transport controls.

The visual timeline is canvas based rather than a collection of waveform images. The project documents zoom controls and examples for stereo rendering, configurable bar widths, gaps, rounded bars, gradients, and themes. This makes the renderer relevant to applications that need to control density and appearance across different timeline scales. A separate waveform-data example covers pre-computed peaks for faster loading, although the README does not specify the generation format or storage backend.

Playback is separated from the React interface. The package table identifies `@waveform-playlist/engine` as a framework-agnostic timeline engine with pure operations, while `@waveform-playlist/playout` is the Tone.js audio engine. React components and hooks live in `@waveform-playlist/browser`, while clip and track construction, types, and utilities are placed in `@waveform-playlist/core`. This separation gives an application control over UI state, pure timeline operations, and sound generation, but it also means the developer must understand which package owns each responsibility.

Choosing the Web Audio or MediaElement Engine

Version 14 made playout engines optional, so installation is not a single package choice. Applications using Web Audio and Tone.js need the browser package, the playout package, and Tone.js. Applications based on HTMLMediaElement install the browser package together with `@waveform-playlist/media-element-playout`. An application with its own audio implementation can install only the browser package and provide a `createAdapter` callback.

This is a meaningful architectural decision. The Web Audio or Tone.js route aligns with the documented effects, WAV export, metering, and loaders imported from `@waveform-playlist/browser/tone`. It is the path to inspect when the application needs Tone.js processing or browser rendering of a decoded mix. The MediaElement route instead uses the browser's media element playback model and has an example focused on playback rate. A custom adapter leaves the sound engine outside the package's default stack, but the README does not document the complete adapter contract in the excerpt shown.

Effects, export, and playout are therefore related but separable concerns. Installing the UI package alone does not make every documented feature available. The Tone convenience re-export was removed in v14, so applications should import Tone directly. This is a migration boundary worth checking before copying example code from an older Waveform Playlist integration.

Installing the Browser Package and Rendering a First Track

The standard installation command shown in the README installs the main browser package, Tone.js, and the React drag-and-drop dependency:

npm install @waveform-playlist/browser tone @dnd-kit/react

The README notes that `tone` and `@dnd-kit/react` are peer dependencies. It also states that `@dnd-kit/dom` and `@dnd-kit/abstract` are declared peers which install automatically as dependencies of `@dnd-kit/react`. Version 16 requires `@dnd-kit/*` `^0.5.0`; the older `^0.3` range is not supported.

The starter code fetches `/audio/song.mp3`, decodes it with the Web Audio API, creates one track, and renders playback controls with the waveform:

import { WaveformPlaylistProvider, Waveform, PlayButton, PauseButton, StopButton } from '@waveform-playlist/browser';
import { createTrack, createClipFromSeconds } from '@waveform-playlist/core';

function App() {
  const [tracks, setTracks] = useState([]);

The complete example then loads audio in `useEffect`, calls `audioContext.decodeAudioData`, creates the clip with `startTime: 0`, and passes `tracks` to `WaveformPlaylistProvider`. The provider surrounds the controls and `<Waveform />`, which is the first point at which the decoded track becomes a visible, playable timeline. The README also links a React starter example, an installation guide, and interactive examples for stems, effects, recording, MIDI, and annotations.

Recording, MIDI, Effects, and Export Boundaries

Recording is implemented through AudioWorklet according to the feature list and recording example. The project presents a live waveform preview and a VU meter, which makes it possible to build an interface that captures audio into the same track model used for loaded clips. The README does not provide the complete recording callback sequence in the quoted material, so the recording example is the relevant place to verify microphone permission handling, recording state, and the resulting clip format.

MIDI support is narrower than native instrument editing. The documented behavior is parsing MIDI files, drawing a piano roll, and playing SoundFont samples. The repository does not claim arbitrary virtual instrument hosting, synthesis, or advanced routing in this feature description. Users who need those capabilities would still need an external instrument or audio engine.

Effects are described as 20 or more Tone.js processors, including reverb, delay, filters, and distortion. The effects example includes real-time parameter control. Export is documented as WAV, either for individual tracks or the full mix, and the v14 note ties WAV export to the Tone.js browser entry point. This creates a practical dependency boundary: a MediaElement integration should not be assumed to expose the same Tone.js effects and export chain without checking the package APIs.

The repository also contains a WAM example for hosting WAM 2.0 plugins and combining them with Tone.js. That example indicates an extension path for native-style browser plug-ins, but the main README does not describe WAM support as part of the minimal installation.

Dnd-kit Migration, Repository Scope, and Upgrade Cost

The recent release history shows active package-level change, including `dnd-kit-0-5` on 2026-09-28, `track-order-on-load` on 2026-08-17, and `track-reordering` on 2026-07-27. The repository is not archived, and its last push was on 2026-10-06. These facts establish recent repository activity, but they do not guarantee compatibility with every existing Waveform Playlist application.

The clearest documented upgrade issue is dnd-kit. Version 16 requires `@dnd-kit/*` `^0.5.0`, while `^0.3` is no longer supported. The README also says `noDropAnimationPlugins` was removed. `Clip`, `AnnotationBox`, and `SortableTrackControls` now configure their own Feedback behavior, so a custom `DragDropProvider` does not need the former `plugins` prop. An application that depended on removed options or older dnd-kit APIs will need source changes, not just a package update.

The top-level `package.json` describes a private monorepo named `waveform-playlist-monorepo`. Its scripts build packages with `pnpm`, run Playwright tests, perform formatting and linting, and build the website. The MIT license applies to the repository. Consumers still need to account for their own browser compatibility, microphone permissions, audio asset delivery, and any external Tone.js, dnd-kit, MediaElement, SoundFont, or WAM dependencies.

Editorial conclusion

Adopt Waveform Playlist when a React product needs a browser-native multitrack timeline and the team can manage the package's engine and peer dependency requirements. Do not choose it as a drop-in replacement for a full desktop DAW, or when a single HTMLMediaElement control is sufficient. Before adoption, verify that the selected playout adapter, `@dnd-kit` version, browser audio permissions, and export requirements match the product. The strongest fit is a project that specifically needs Waveform Playlist's component and timeline model rather than a general media player.

Frequently asked questions

Official sources

1. License: MIT
2. naomiaro/waveform-playlist on GitHub
3. Project website
4. README
5. Releases