@waveform-playlist/core

Core types, interfaces and utilities for waveform-playlist — pure functions and TypeScript types with zero runtime dependencies.

Used by nearly every @waveform-playlist/* and @dawcore/* package (engine, playout, media-element-playout, browser, ui-components, recording, annotations, spectrogram, midi, transport, dawcore, dawcore-spectrogram, dawcore-midi, webaudio-peaks, loaders, and more). Most consumers get it transitively — install it directly only if you're building on the clip model, timeline math, or fade curves yourself.

Features

• Clip & track types — AudioClip, ClipTrack, Timeline, Fade/FadeType, Peaks/Bits/PeakData, WaveformDataObject
• Sample-based timeline math — createClip/createClipFromSeconds/createClipFromTicks, clip queries (getClipsInRange, clipsOverlap, findGaps), and second-conversion helpers (clipStartTime, clipEndTime, clipPixelWidth)
• Fade curves — linear, exponential, logarithmic, and S-curve generators for native Web Audio AudioParam (no Tone.js dependency)
• Decibel utilities — gain ↔ dB ↔ normalized-0-1 conversions for meters and volume controls
• Peaks generation — real-time min/max peak extraction during recording
• Musical time — PPQN tick math, bar/beat conversion, time-signature meter detection, grid snapping
• Keyboard shortcuts — a framework-agnostic shortcut matcher shared by the React and Web Components layers
• Spectrogram canvas-ID contract — canonical build/parse helpers for the ${clipId}-ch${n}-chunk${m} canvas ID format shared by the worker pool and rendering layers
• HTTP range support probing — detect whether an audio host supports byte-range seeking

Installation

npm install @waveform-playlist/core

Zero dependencies — safe to install anywhere without pulling in Web Audio, React, or Tone.js.

Usage

import { createClipFromSeconds, clipStartTime, clipEndTime, gainToDb } from '@waveform-playlist/core';

// Build a clip from a decoded AudioBuffer, positioned at 2.5s on the timeline
const clip = createClipFromSeconds({
  audioBuffer,
  startTime: 2.5,
  offset: 0,
  fadeIn: { duration: 0.5, type: 'linear' },
});

clipStartTime(clip); // 2.5
clipEndTime(clip); // 2.5 + audioBuffer.duration

// Convert a linear gain value to dB for a Tone.js Volume node
gainToDb(0.5); // ≈ -6.02

import { buildSpectrogramCanvasId, parseSpectrogramCanvasId } from '@waveform-playlist/core';

const id = buildSpectrogramCanvasId({ clipId: 'clip-1', channelIndex: 0, chunkIndex: 3 });
// "clip-1-ch0-chunk3"

parseSpectrogramCanvasId(id);
// { clipId: 'clip-1', channelIndex: 0, chunkIndex: 3 }

API

| Module | Key exports | |---|---| | types/ | AudioClip, ClipTrack, Timeline, Track, Fade, FadeType, Peaks, Bits, PeakData, WaveformDataObject, SpectrogramConfig, RenderMode, ColorMapValue | | clipTimeHelpers | clipStartTime, clipEndTime, clipOffsetTime, clipDurationTime, clipPixelWidth, trackChannelCount | | clip constructors (types/clip) | createClip, createClipFromSeconds, createClipFromTicks, createTrack, createTimeline, getClipsInRange, getClipsAtSample, clipsOverlap, sortClipsByTime, findGaps | | fades | applyFadeIn, applyFadeOut, generateCurve, linearCurve, exponentialCurve, logarithmicCurve, sCurveCurve | | utils/dBUtils | gainToDb, dBToNormalized, normalizedToDb, gainToNormalized | | utils/conversions | samplesToSeconds, secondsToSamples, samplesToPixels, pixelsToSamples, pixelsToSeconds, secondsToPixels | | utils/beatsAndBars | PPQN, ticksPerBeat, ticksPerBar, ticksToSamples, samplesToTicks, snapToGrid | | utils/musicalTicks | computeMusicalTicks, snapToTicks, snapTickToGrid, SnapTo, MusicalTick | | utils/meterDetection | MeterEntry, detectMeterChanges | | utils/peaksGenerator | generatePeaks, appendPeaks | | utils/audioBufferUtils | concatenateAudioData, createAudioBuffer, appendToAudioBuffer, calculateDuration | | utils/latency | resolveRecordingOffsetSamples — override-vs-auto recording latency compensation (shared by React + dawcore) | | utils/carveClipRange | carveClipRange — punch-in replace: carve a sample range out of a clip list (trim/remove/split) | | keyboard | KeyboardShortcut, handleKeyboardEvent, getShortcutLabel | | spectrogramCanvasId | buildSpectrogramCanvasId, parseSpectrogramCanvasId, SpectrogramCanvasIdParts | | probeRangeSupport | probeRangeSupport, RangeSupport | | enumerateMicrophones | enumerateMicrophones, watchMicrophoneDevices, MicrophoneEnumeration — permission-free device listing with supported/hasLabels flags (labels are browser-redacted pre-permission) | | constants | MAX_CANVAS_WIDTH |

Examples & Documentation

• Guides: naomiaro.github.io/waveform-playlist

License

MIT