@waveform-playlist/core 12.4.0 → 12.6.0

package/README.md

@@ -0,0 +1,86 @@
+# @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
+
+```bash
+npm install @waveform-playlist/core
+```
+
+Zero dependencies — safe to install anywhere without pulling in Web Audio, React, or Tone.js.
+
+## Usage
+
+```typescript
+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
+```
+
+```typescript
+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](https://naomiaro.github.io/waveform-playlist/)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -880,6 +880,37 @@ declare const SPECTROGRAM_DEFAULTS: Required<Omit<SpectrogramConfig, 'maxFrequen
 /** Default color map when none is specified. */
 declare const DEFAULT_SPECTROGRAM_COLOR_MAP: ColorMapValue;
 
+/**
+ * Punch-in replace: carve a sample range out of a clip list.
+ *
+ * Used when a newly recorded clip lands at the playhead and must REPLACE any
+ * existing clip content between its start and end (issue #579): partial
+ * overlaps are trimmed, fully-covered clips are removed, and a clip that
+ * spans the whole range is split into two.
+ */
+
+/**
+ * Return a new clip list with the sample range [rangeStart, rangeEnd)
+ * removed from every clip that overlaps it.
+ *
+ * - Clips outside the range are returned by reference (untouched).
+ * - Clips fully inside the range are dropped.
+ * - A clip overlapping only the range's start keeps its head (right-trim).
+ * - A clip overlapping only the range's end keeps its tail: its start moves
+ *   to rangeEnd and `offsetSamples` advances by the carved amount.
+ * - A clip containing the whole range splits into head + tail; the tail is a
+ *   new clip (deterministic id `<original>-carve-<rangeEnd>`) sharing the
+ *   same audioBuffer.
+ *
+ * Clips whose `startSample` changes lose their `startTick` — a sample-space
+ * carve cannot recompute ticks, and the engine re-enriches clips without
+ * `startTick` on ingestion (see AudioClip.startTick).
+ *
+ * Pure and immutable: input clips are never mutated. An empty or inverted
+ * range returns the input list unchanged.
+ */
+declare function carveClipRange(clips: readonly AudioClip[], rangeStart: number, rangeEnd: number): AudioClip[];
+
 /** Clip start position in seconds */
 declare function clipStartTime(clip: AudioClip): number;
 /** Clip end position in seconds (start + duration) */
@@ -901,6 +932,35 @@ declare function trackChannelCount(track: ClipTrack): number;
  */
 declare function clipPixelWidth(startSample: number, durationSamples: number, samplesPerPixel: number): number;
 
+/**
+ * Canonical spectrogram canvas-ID contract.
+ *
+ * Spectrogram canvases are identified by `${clipId}-ch${channelIndex}-chunk${chunkIndex}`.
+ * This format is produced (builders) and consumed (parsers) by several packages
+ * — the React `SpectrogramProvider`/`SpectrogramChannel`, the `<daw-spectrogram>`
+ * Lit element, and the `@dawcore/spectrogram` worker pool. Single-sourcing the
+ * build + parse here prevents the drift class where a format change lands in some
+ * sites but not others (the pool's no-match fallback then routes every channel to
+ * worker 0 → channel 0's data rendered for all channels — #556).
+ *
+ * `@waveform-playlist/core` is the home because it is zero-dependency and already
+ * a dependency of every producer and consumer (unlike `@dawcore/spectrogram`,
+ * which `@waveform-playlist/ui-components` does not depend on). The format is a
+ * pure string contract with no FFT/compute dependency.
+ */
+interface SpectrogramCanvasIdParts {
+    clipId: string;
+    channelIndex: number;
+    chunkIndex: number;
+}
+/** Build a spectrogram canvas ID from its parts. */
+declare function buildSpectrogramCanvasId(parts: SpectrogramCanvasIdParts): string;
+/**
+ * Parse a spectrogram canvas ID into its parts, or `null` when it doesn't match
+ * the `${clipId}-ch${channelIndex}-chunk${chunkIndex}` format.
+ */
+declare function parseSpectrogramCanvasId(canvasId: string): SpectrogramCanvasIdParts | null;
+
 /**
  * Fade curve utilities for Web Audio API
  *
@@ -1007,4 +1067,51 @@ type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
  */
 declare function probeRangeSupport(url: string, fetchImpl?: FetchLike): Promise<RangeSupport>;
 
-export { type AnnotationAction, type AnnotationActionOptions, type AnnotationData, type AnnotationEventMap, type AnnotationFormat, type AnnotationListOptions, type AudioBuffer$1 as AudioBuffer, type AudioClip, type Bits, type ClipTrack, type ColorMapEntry, type ColorMapName, type ColorMapValue, type CreateClipOptions, type CreateClipOptionsSeconds, type CreateClipOptionsTicks, type CreateTrackOptions, DEFAULT_SPECTROGRAM_COLOR_MAP, type FFTSize, type Fade, type FadeConfig, type FadeType, type Gap, InteractionState, type KeyboardShortcut, MAX_CANVAS_WIDTH, MIN_PIXELS_PER_UNIT, type MeterEntry, type MidiNoteData, type MusicalTick, type MusicalTickData, type MusicalTickParams, PPQN, type PeakData, type Peaks, type PlaylistConfig, type PlayoutState, type RangeSupport, type RenderAnnotationItemProps, type RenderMode, SPECTROGRAM_DEFAULTS, type SnapTo, type SpectrogramComputeConfig, type SpectrogramConfig, type SpectrogramData, type SpectrogramDisplayConfig, type TickType, type TimeSelection, type Timeline, type Track, type TrackEffectsFunction, type TrackSpectrogramOverrides, type WaveformConfig, type WaveformDataObject, type ZoomLevel, appendPeaks, appendToAudioBuffer, applyFadeIn, applyFadeOut, audibleLatencySamples, calculateDuration, clipDurationTime, clipEndTime, clipOffsetTime, clipPixelWidth, clipStartTime, clipsOverlap, computeMusicalTicks, concatenateAudioData, createAudioBuffer, createClip, createClipFromSeconds, createClipFromTicks, createTimeline, createTrack, dBToNormalized, detectMeterChanges, exponentialCurve, findGaps, gainToDb, gainToNormalized, generateCurve, generatePeaks, getClipsAtSample, getClipsInRange, getShortcutLabel, handleKeyboardEvent, linearCurve, logarithmicCurve, normalizedToDb, pixelsToSamples, pixelsToSeconds, probeRangeSupport, resolveRecordingOffsetSamples, sCurveCurve, samplesToPixels, samplesToSeconds, samplesToTicks, secondsToPixels, secondsToSamples, snapTickToGrid, snapToGrid, snapToTicks, sortClipsByTime, ticksPerBar, ticksPerBeat, ticksToSamples, trackChannelCount };
+/**
+ * Framework-agnostic microphone enumeration.
+ *
+ * Works without requesting a stream, but browsers redact device information
+ * until microphone permission is granted: labels are empty everywhere, and
+ * Chrome/Safari typically also redact deviceIds (often exposing a single
+ * placeholder entry). The `hasLabels` flag tells consumers whether the list
+ * is a usable picker or just a "microphones exist" signal — re-enumerate
+ * after a successful getUserMedia to get the real list.
+ *
+ * Follows the probeRangeSupport pattern: the browser API is injectable for
+ * tests and non-browser environments degrade gracefully.
+ */
+interface MicrophoneDeviceInfo {
+    deviceId: string;
+    /** Real device label, or a generated fallback name when redacted. */
+    label: string;
+    groupId: string;
+}
+interface MicrophoneEnumeration {
+    /** False when enumeration is unavailable — SSR/Node, insecure context
+     * (mediaDevices requires HTTPS or localhost), or a very old browser. */
+    supported: boolean;
+    /** True when the browser exposed real device labels. False before
+     * microphone permission is granted (labels — and often deviceIds — are
+     * redacted); the `devices` labels are then generated fallbacks. */
+    hasLabels: boolean;
+    devices: MicrophoneDeviceInfo[];
+}
+/**
+ * List audio input devices without requesting a stream.
+ *
+ * @param mediaDevices - Injectable for tests; defaults to `navigator.mediaDevices`.
+ */
+declare function enumerateMicrophones(mediaDevices?: MediaDevices): Promise<MicrophoneEnumeration>;
+/**
+ * Subscribe to the microphone device list: the listener fires once with the
+ * initial enumeration and again on every `devicechange` (hot-plug, permission
+ * grant in some browsers). Returns an unsubscribe function.
+ *
+ * Enumeration failures are logged and skipped — the subscription survives a
+ * transient failure and delivers the next successful enumeration.
+ *
+ * @param mediaDevices - Injectable for tests; defaults to `navigator.mediaDevices`.
+ */
+declare function watchMicrophoneDevices(listener: (enumeration: MicrophoneEnumeration) => void, mediaDevices?: MediaDevices): () => void;
+
+export { type AnnotationAction, type AnnotationActionOptions, type AnnotationData, type AnnotationEventMap, type AnnotationFormat, type AnnotationListOptions, type AudioBuffer$1 as AudioBuffer, type AudioClip, type Bits, type ClipTrack, type ColorMapEntry, type ColorMapName, type ColorMapValue, type CreateClipOptions, type CreateClipOptionsSeconds, type CreateClipOptionsTicks, type CreateTrackOptions, DEFAULT_SPECTROGRAM_COLOR_MAP, type FFTSize, type Fade, type FadeConfig, type FadeType, type Gap, InteractionState, type KeyboardShortcut, MAX_CANVAS_WIDTH, MIN_PIXELS_PER_UNIT, type MeterEntry, type MicrophoneDeviceInfo, type MicrophoneEnumeration, type MidiNoteData, type MusicalTick, type MusicalTickData, type MusicalTickParams, PPQN, type PeakData, type Peaks, type PlaylistConfig, type PlayoutState, type RangeSupport, type RenderAnnotationItemProps, type RenderMode, SPECTROGRAM_DEFAULTS, type SnapTo, type SpectrogramCanvasIdParts, type SpectrogramComputeConfig, type SpectrogramConfig, type SpectrogramData, type SpectrogramDisplayConfig, type TickType, type TimeSelection, type Timeline, type Track, type TrackEffectsFunction, type TrackSpectrogramOverrides, type WaveformConfig, type WaveformDataObject, type ZoomLevel, appendPeaks, appendToAudioBuffer, applyFadeIn, applyFadeOut, audibleLatencySamples, buildSpectrogramCanvasId, calculateDuration, carveClipRange, clipDurationTime, clipEndTime, clipOffsetTime, clipPixelWidth, clipStartTime, clipsOverlap, computeMusicalTicks, concatenateAudioData, createAudioBuffer, createClip, createClipFromSeconds, createClipFromTicks, createTimeline, createTrack, dBToNormalized, detectMeterChanges, enumerateMicrophones, exponentialCurve, findGaps, gainToDb, gainToNormalized, generateCurve, generatePeaks, getClipsAtSample, getClipsInRange, getShortcutLabel, handleKeyboardEvent, linearCurve, logarithmicCurve, normalizedToDb, parseSpectrogramCanvasId, pixelsToSamples, pixelsToSeconds, probeRangeSupport, resolveRecordingOffsetSamples, sCurveCurve, samplesToPixels, samplesToSeconds, samplesToTicks, secondsToPixels, secondsToSamples, snapTickToGrid, snapToGrid, snapToTicks, sortClipsByTime, ticksPerBar, ticksPerBeat, ticksToSamples, trackChannelCount, watchMicrophoneDevices };

package/dist/index.d.ts

@@ -880,6 +880,37 @@ declare const SPECTROGRAM_DEFAULTS: Required<Omit<SpectrogramConfig, 'maxFrequen
 /** Default color map when none is specified. */
 declare const DEFAULT_SPECTROGRAM_COLOR_MAP: ColorMapValue;
 
+/**
+ * Punch-in replace: carve a sample range out of a clip list.
+ *
+ * Used when a newly recorded clip lands at the playhead and must REPLACE any
+ * existing clip content between its start and end (issue #579): partial
+ * overlaps are trimmed, fully-covered clips are removed, and a clip that
+ * spans the whole range is split into two.
+ */
+
+/**
+ * Return a new clip list with the sample range [rangeStart, rangeEnd)
+ * removed from every clip that overlaps it.
+ *
+ * - Clips outside the range are returned by reference (untouched).
+ * - Clips fully inside the range are dropped.
+ * - A clip overlapping only the range's start keeps its head (right-trim).
+ * - A clip overlapping only the range's end keeps its tail: its start moves
+ *   to rangeEnd and `offsetSamples` advances by the carved amount.
+ * - A clip containing the whole range splits into head + tail; the tail is a
+ *   new clip (deterministic id `<original>-carve-<rangeEnd>`) sharing the
+ *   same audioBuffer.
+ *
+ * Clips whose `startSample` changes lose their `startTick` — a sample-space
+ * carve cannot recompute ticks, and the engine re-enriches clips without
+ * `startTick` on ingestion (see AudioClip.startTick).
+ *
+ * Pure and immutable: input clips are never mutated. An empty or inverted
+ * range returns the input list unchanged.
+ */
+declare function carveClipRange(clips: readonly AudioClip[], rangeStart: number, rangeEnd: number): AudioClip[];
+
 /** Clip start position in seconds */
 declare function clipStartTime(clip: AudioClip): number;
 /** Clip end position in seconds (start + duration) */
@@ -901,6 +932,35 @@ declare function trackChannelCount(track: ClipTrack): number;
  */
 declare function clipPixelWidth(startSample: number, durationSamples: number, samplesPerPixel: number): number;
 
+/**
+ * Canonical spectrogram canvas-ID contract.
+ *
+ * Spectrogram canvases are identified by `${clipId}-ch${channelIndex}-chunk${chunkIndex}`.
+ * This format is produced (builders) and consumed (parsers) by several packages
+ * — the React `SpectrogramProvider`/`SpectrogramChannel`, the `<daw-spectrogram>`
+ * Lit element, and the `@dawcore/spectrogram` worker pool. Single-sourcing the
+ * build + parse here prevents the drift class where a format change lands in some
+ * sites but not others (the pool's no-match fallback then routes every channel to
+ * worker 0 → channel 0's data rendered for all channels — #556).
+ *
+ * `@waveform-playlist/core` is the home because it is zero-dependency and already
+ * a dependency of every producer and consumer (unlike `@dawcore/spectrogram`,
+ * which `@waveform-playlist/ui-components` does not depend on). The format is a
+ * pure string contract with no FFT/compute dependency.
+ */
+interface SpectrogramCanvasIdParts {
+    clipId: string;
+    channelIndex: number;
+    chunkIndex: number;
+}
+/** Build a spectrogram canvas ID from its parts. */
+declare function buildSpectrogramCanvasId(parts: SpectrogramCanvasIdParts): string;
+/**
+ * Parse a spectrogram canvas ID into its parts, or `null` when it doesn't match
+ * the `${clipId}-ch${channelIndex}-chunk${chunkIndex}` format.
+ */
+declare function parseSpectrogramCanvasId(canvasId: string): SpectrogramCanvasIdParts | null;
+
 /**
  * Fade curve utilities for Web Audio API
  *
@@ -1007,4 +1067,51 @@ type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
  */
 declare function probeRangeSupport(url: string, fetchImpl?: FetchLike): Promise<RangeSupport>;
 
-export { type AnnotationAction, type AnnotationActionOptions, type AnnotationData, type AnnotationEventMap, type AnnotationFormat, type AnnotationListOptions, type AudioBuffer$1 as AudioBuffer, type AudioClip, type Bits, type ClipTrack, type ColorMapEntry, type ColorMapName, type ColorMapValue, type CreateClipOptions, type CreateClipOptionsSeconds, type CreateClipOptionsTicks, type CreateTrackOptions, DEFAULT_SPECTROGRAM_COLOR_MAP, type FFTSize, type Fade, type FadeConfig, type FadeType, type Gap, InteractionState, type KeyboardShortcut, MAX_CANVAS_WIDTH, MIN_PIXELS_PER_UNIT, type MeterEntry, type MidiNoteData, type MusicalTick, type MusicalTickData, type MusicalTickParams, PPQN, type PeakData, type Peaks, type PlaylistConfig, type PlayoutState, type RangeSupport, type RenderAnnotationItemProps, type RenderMode, SPECTROGRAM_DEFAULTS, type SnapTo, type SpectrogramComputeConfig, type SpectrogramConfig, type SpectrogramData, type SpectrogramDisplayConfig, type TickType, type TimeSelection, type Timeline, type Track, type TrackEffectsFunction, type TrackSpectrogramOverrides, type WaveformConfig, type WaveformDataObject, type ZoomLevel, appendPeaks, appendToAudioBuffer, applyFadeIn, applyFadeOut, audibleLatencySamples, calculateDuration, clipDurationTime, clipEndTime, clipOffsetTime, clipPixelWidth, clipStartTime, clipsOverlap, computeMusicalTicks, concatenateAudioData, createAudioBuffer, createClip, createClipFromSeconds, createClipFromTicks, createTimeline, createTrack, dBToNormalized, detectMeterChanges, exponentialCurve, findGaps, gainToDb, gainToNormalized, generateCurve, generatePeaks, getClipsAtSample, getClipsInRange, getShortcutLabel, handleKeyboardEvent, linearCurve, logarithmicCurve, normalizedToDb, pixelsToSamples, pixelsToSeconds, probeRangeSupport, resolveRecordingOffsetSamples, sCurveCurve, samplesToPixels, samplesToSeconds, samplesToTicks, secondsToPixels, secondsToSamples, snapTickToGrid, snapToGrid, snapToTicks, sortClipsByTime, ticksPerBar, ticksPerBeat, ticksToSamples, trackChannelCount };
+/**
+ * Framework-agnostic microphone enumeration.
+ *
+ * Works without requesting a stream, but browsers redact device information
+ * until microphone permission is granted: labels are empty everywhere, and
+ * Chrome/Safari typically also redact deviceIds (often exposing a single
+ * placeholder entry). The `hasLabels` flag tells consumers whether the list
+ * is a usable picker or just a "microphones exist" signal — re-enumerate
+ * after a successful getUserMedia to get the real list.
+ *
+ * Follows the probeRangeSupport pattern: the browser API is injectable for
+ * tests and non-browser environments degrade gracefully.
+ */
+interface MicrophoneDeviceInfo {
+    deviceId: string;
+    /** Real device label, or a generated fallback name when redacted. */
+    label: string;
+    groupId: string;
+}
+interface MicrophoneEnumeration {
+    /** False when enumeration is unavailable — SSR/Node, insecure context
+     * (mediaDevices requires HTTPS or localhost), or a very old browser. */
+    supported: boolean;
+    /** True when the browser exposed real device labels. False before
+     * microphone permission is granted (labels — and often deviceIds — are
+     * redacted); the `devices` labels are then generated fallbacks. */
+    hasLabels: boolean;
+    devices: MicrophoneDeviceInfo[];
+}
+/**
+ * List audio input devices without requesting a stream.
+ *
+ * @param mediaDevices - Injectable for tests; defaults to `navigator.mediaDevices`.
+ */
+declare function enumerateMicrophones(mediaDevices?: MediaDevices): Promise<MicrophoneEnumeration>;
+/**
+ * Subscribe to the microphone device list: the listener fires once with the
+ * initial enumeration and again on every `devicechange` (hot-plug, permission
+ * grant in some browsers). Returns an unsubscribe function.
+ *
+ * Enumeration failures are logged and skipped — the subscription survives a
+ * transient failure and delivers the next successful enumeration.
+ *
+ * @param mediaDevices - Injectable for tests; defaults to `navigator.mediaDevices`.
+ */
+declare function watchMicrophoneDevices(listener: (enumeration: MicrophoneEnumeration) => void, mediaDevices?: MediaDevices): () => void;
+
+export { type AnnotationAction, type AnnotationActionOptions, type AnnotationData, type AnnotationEventMap, type AnnotationFormat, type AnnotationListOptions, type AudioBuffer$1 as AudioBuffer, type AudioClip, type Bits, type ClipTrack, type ColorMapEntry, type ColorMapName, type ColorMapValue, type CreateClipOptions, type CreateClipOptionsSeconds, type CreateClipOptionsTicks, type CreateTrackOptions, DEFAULT_SPECTROGRAM_COLOR_MAP, type FFTSize, type Fade, type FadeConfig, type FadeType, type Gap, InteractionState, type KeyboardShortcut, MAX_CANVAS_WIDTH, MIN_PIXELS_PER_UNIT, type MeterEntry, type MicrophoneDeviceInfo, type MicrophoneEnumeration, type MidiNoteData, type MusicalTick, type MusicalTickData, type MusicalTickParams, PPQN, type PeakData, type Peaks, type PlaylistConfig, type PlayoutState, type RangeSupport, type RenderAnnotationItemProps, type RenderMode, SPECTROGRAM_DEFAULTS, type SnapTo, type SpectrogramCanvasIdParts, type SpectrogramComputeConfig, type SpectrogramConfig, type SpectrogramData, type SpectrogramDisplayConfig, type TickType, type TimeSelection, type Timeline, type Track, type TrackEffectsFunction, type TrackSpectrogramOverrides, type WaveformConfig, type WaveformDataObject, type ZoomLevel, appendPeaks, appendToAudioBuffer, applyFadeIn, applyFadeOut, audibleLatencySamples, buildSpectrogramCanvasId, calculateDuration, carveClipRange, clipDurationTime, clipEndTime, clipOffsetTime, clipPixelWidth, clipStartTime, clipsOverlap, computeMusicalTicks, concatenateAudioData, createAudioBuffer, createClip, createClipFromSeconds, createClipFromTicks, createTimeline, createTrack, dBToNormalized, detectMeterChanges, enumerateMicrophones, exponentialCurve, findGaps, gainToDb, gainToNormalized, generateCurve, generatePeaks, getClipsAtSample, getClipsInRange, getShortcutLabel, handleKeyboardEvent, linearCurve, logarithmicCurve, normalizedToDb, parseSpectrogramCanvasId, pixelsToSamples, pixelsToSeconds, probeRangeSupport, resolveRecordingOffsetSamples, sCurveCurve, samplesToPixels, samplesToSeconds, samplesToTicks, secondsToPixels, secondsToSamples, snapTickToGrid, snapToGrid, snapToTicks, sortClipsByTime, ticksPerBar, ticksPerBeat, ticksToSamples, trackChannelCount, watchMicrophoneDevices };

package/dist/index.js

@@ -31,7 +31,9 @@ __export(index_exports, {
   applyFadeIn: () => applyFadeIn,
   applyFadeOut: () => applyFadeOut,
   audibleLatencySamples: () => audibleLatencySamples,
+  buildSpectrogramCanvasId: () => buildSpectrogramCanvasId,
   calculateDuration: () => calculateDuration,
+  carveClipRange: () => carveClipRange,
   clipDurationTime: () => clipDurationTime,
   clipEndTime: () => clipEndTime,
   clipOffsetTime: () => clipOffsetTime,
@@ -48,6 +50,7 @@ __export(index_exports, {
   createTrack: () => createTrack,
   dBToNormalized: () => dBToNormalized,
   detectMeterChanges: () => detectMeterChanges,
+  enumerateMicrophones: () => enumerateMicrophones,
   exponentialCurve: () => exponentialCurve,
   findGaps: () => findGaps,
   gainToDb: () => gainToDb,
@@ -61,6 +64,7 @@ __export(index_exports, {
   linearCurve: () => linearCurve,
   logarithmicCurve: () => logarithmicCurve,
   normalizedToDb: () => normalizedToDb,
+  parseSpectrogramCanvasId: () => parseSpectrogramCanvasId,
   pixelsToSamples: () => pixelsToSamples,
   pixelsToSeconds: () => pixelsToSeconds,
   probeRangeSupport: () => probeRangeSupport,
@@ -78,7 +82,8 @@ __export(index_exports, {
   ticksPerBar: () => ticksPerBar,
   ticksPerBeat: () => ticksPerBeat,
   ticksToSamples: () => ticksToSamples,
-  trackChannelCount: () => trackChannelCount
+  trackChannelCount: () => trackChannelCount,
+  watchMicrophoneDevices: () => watchMicrophoneDevices
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -719,6 +724,44 @@ var SPECTROGRAM_DEFAULTS = {
 };
 var DEFAULT_SPECTROGRAM_COLOR_MAP = "viridis";
 
+// src/utils/carveClipRange.ts
+function carveClipRange(clips, rangeStart, rangeEnd) {
+  if (!(rangeEnd > rangeStart)) {
+    return [...clips];
+  }
+  const result = [];
+  for (const clip of clips) {
+    const clipStart = clip.startSample;
+    const clipEnd = clip.startSample + clip.durationSamples;
+    if (clipEnd <= rangeStart || clipStart >= rangeEnd) {
+      result.push(clip);
+      continue;
+    }
+    const keepHead = clipStart < rangeStart;
+    const keepTail = clipEnd > rangeEnd;
+    if (keepHead) {
+      result.push({
+        ...clip,
+        durationSamples: rangeStart - clipStart
+      });
+    }
+    if (keepTail) {
+      const carvedFromClipStart = rangeEnd - clipStart;
+      const tail = {
+        ...clip,
+        // Head + tail from one clip must not share an id
+        id: keepHead ? `${clip.id}-carve-${rangeEnd}` : clip.id,
+        startSample: rangeEnd,
+        durationSamples: clipEnd - rangeEnd,
+        offsetSamples: clip.offsetSamples + carvedFromClipStart
+      };
+      delete tail.startTick;
+      result.push(tail);
+    }
+  }
+  return result;
+}
+
 // src/clipTimeHelpers.ts
 function clipStartTime(clip) {
   return clip.startSample / clip.sampleRate;
@@ -742,6 +785,21 @@ function clipPixelWidth(startSample, durationSamples, samplesPerPixel) {
   return Math.floor((startSample + durationSamples) / samplesPerPixel) - Math.floor(startSample / samplesPerPixel);
 }
 
+// src/spectrogramCanvasId.ts
+var CANVAS_ID_RE = /^(.+)-ch(\d+)-chunk(\d+)$/;
+function buildSpectrogramCanvasId(parts) {
+  return `${parts.clipId}-ch${parts.channelIndex}-chunk${parts.chunkIndex}`;
+}
+function parseSpectrogramCanvasId(canvasId) {
+  const match = canvasId.match(CANVAS_ID_RE);
+  if (!match) return null;
+  return {
+    clipId: match[1],
+    channelIndex: parseInt(match[2], 10),
+    chunkIndex: parseInt(match[3], 10)
+  };
+}
+
 // src/fades.ts
 function linearCurve(length, fadeIn) {
   const curve = new Float32Array(length);
@@ -893,6 +951,59 @@ async function probeRangeSupport(url, fetchImpl = fetch) {
     controller.abort();
   }
 }
+
+// src/enumerateMicrophones.ts
+var UNSUPPORTED = Object.freeze({
+  supported: false,
+  hasLabels: false,
+  devices: []
+});
+function resolveMediaDevices(mediaDevices) {
+  if (mediaDevices) return mediaDevices;
+  return typeof navigator !== "undefined" ? navigator.mediaDevices : void 0;
+}
+async function enumerateMicrophones(mediaDevices) {
+  const md = resolveMediaDevices(mediaDevices);
+  if (!md || typeof md.enumerateDevices !== "function") {
+    return UNSUPPORTED;
+  }
+  const all = await md.enumerateDevices();
+  const inputs = all.filter((device) => device.kind === "audioinput");
+  const hasLabels = inputs.some((device) => device.label.length > 0);
+  return {
+    supported: true,
+    hasLabels,
+    devices: inputs.map((device, index) => ({
+      deviceId: device.deviceId,
+      label: device.label || // Pre-permission fallbacks: Chrome redacts deviceId to '' as well,
+      // so fall through to a positional name when there's nothing to slice.
+      (device.deviceId ? `Microphone ${device.deviceId.slice(0, 8)}` : `Microphone ${index + 1}`),
+      groupId: device.groupId
+    }))
+  };
+}
+function watchMicrophoneDevices(listener, mediaDevices) {
+  const md = resolveMediaDevices(mediaDevices);
+  if (!md || typeof md.enumerateDevices !== "function") {
+    queueMicrotask(() => listener(UNSUPPORTED));
+    return () => {
+    };
+  }
+  let active = true;
+  const deliver = () => {
+    enumerateMicrophones(md).then((result) => {
+      if (active) listener(result);
+    }).catch((err) => {
+      console.warn("[waveform-playlist] Microphone enumeration failed:", String(err));
+    });
+  };
+  md.addEventListener("devicechange", deliver);
+  deliver();
+  return () => {
+    active = false;
+    md.removeEventListener("devicechange", deliver);
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_SPECTROGRAM_COLOR_MAP,
@@ -906,7 +1017,9 @@ async function probeRangeSupport(url, fetchImpl = fetch) {
   applyFadeIn,
   applyFadeOut,
   audibleLatencySamples,
+  buildSpectrogramCanvasId,
   calculateDuration,
+  carveClipRange,
   clipDurationTime,
   clipEndTime,
   clipOffsetTime,
@@ -923,6 +1036,7 @@ async function probeRangeSupport(url, fetchImpl = fetch) {
   createTrack,
   dBToNormalized,
   detectMeterChanges,
+  enumerateMicrophones,
   exponentialCurve,
   findGaps,
   gainToDb,
@@ -936,6 +1050,7 @@ async function probeRangeSupport(url, fetchImpl = fetch) {
   linearCurve,
   logarithmicCurve,
   normalizedToDb,
+  parseSpectrogramCanvasId,
   pixelsToSamples,
   pixelsToSeconds,
   probeRangeSupport,
@@ -953,6 +1068,7 @@ async function probeRangeSupport(url, fetchImpl = fetch) {
   ticksPerBar,
   ticksPerBeat,
   ticksToSamples,
-  trackChannelCount
+  trackChannelCount,
+  watchMicrophoneDevices
 });
 //# sourceMappingURL=index.js.map