@waveform-playlist/core 12.5.0 → 12.6.1

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

@@ -476,6 +476,10 @@ interface AnnotationData {
     end: number;
     lines: string[];
     language?: string;
+    /** Musical position (ticks). Authoritative when BOTH tick fields are set —
+     * start/end seconds are then a derived cache (clip startTick pattern). */
+    startTick?: number;
+    endTick?: number;
 }
 /**
  * Annotation format definition for parsing/serializing
@@ -775,6 +779,21 @@ declare const MIN_PIXELS_PER_UNIT = 8;
  * correct across meter changes.
  */
 declare function computeMusicalTicks(params: MusicalTickParams): MusicalTickData;
+/**
+ * Convert an absolute tick to a 1-based bar.beat position, honoring meter
+ * changes. Bars/beats are counted per meter segment (the same walk
+ * `computeMusicalTicks` uses to build its `barOffset` accumulator). Beat is
+ * the integer beat the tick falls WITHIN (floor, 1-based) — a tick exactly on
+ * a bar line is beat 1.
+ *
+ * Guards: empty `meterEntries` → treat as 4/4 from tick 0. `ppqn <= 0` →
+ * returns `{ bar: 1, beat: 1 }` (division-by-zero guard, matches
+ * `computeMusicalTicks`'s ppqn guard).
+ */
+declare function ticksToBarBeat(tick: number, meterEntries: MeterEntry[], ppqn: number): {
+    bar: number;
+    beat: number;
+};
 /**
  * Snaps a tick position to the nearest grid boundary defined by `snapTo`.
  *
@@ -880,6 +899,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) */
@@ -994,6 +1044,13 @@ interface KeyboardShortcut {
     description?: string;
     preventDefault?: boolean;
 }
+/** A key + modifier combination, without an action. Used for remapping maps. */
+type KeyBinding = Pick<KeyboardShortcut, 'key' | 'ctrlKey' | 'shiftKey' | 'metaKey' | 'altKey'>;
+/**
+ * Does a keyboard event match a key binding?
+ * `undefined` modifier = match any state; `false` = must NOT be pressed.
+ */
+declare function matchesKeyBinding(event: KeyboardEvent, binding: KeyBinding): boolean;
 /**
  * Handle a keyboard event against a list of shortcuts.
  * Pure function, no framework dependency.
@@ -1036,4 +1093,104 @@ 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 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, 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, parseSpectrogramCanvasId, 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;
+
+/** Edges within this distance (seconds) are considered "linked". */
+declare const LINK_THRESHOLD = 0.01;
+/** Minimum annotation duration (seconds) enforced by boundary edits. */
+declare const MIN_ANNOTATION_DURATION = 0.1;
+/** Link threshold for INTEGER TICK positions — closer than half a tick means equal. */
+declare const ANNOTATION_LINK_THRESHOLD_TICKS = 0.5;
+/** Minimum tick-annotation duration: a 128th note, floored at 1 tick. */
+declare function annotationMinDurationTicks(ppqn: number): number;
+/** Unit constants for a boundary-math run. Defaults are the seconds-domain values. */
+interface AnnotationBoundaryOptions {
+    linkThreshold?: number;
+    minDuration?: number;
+}
+interface AnnotationBoundaryUpdate {
+    annotationIndex: number;
+    newTime: number;
+    isDraggingStart: boolean;
+    annotations: AnnotationData[];
+    duration: number;
+    linkEndpoints: boolean;
+}
+/**
+ * Pure boundary-update logic shared by the React annotations package and the
+ * dawcore annotation web components. Handles linked endpoints (moving one edge
+ * drags the linked neighbor edge, with cascade) and collision push-back.
+ * Returns a NEW array; never mutates inputs.
+ */
+declare function updateAnnotationBoundaries(params: AnnotationBoundaryUpdate, options?: AnnotationBoundaryOptions): AnnotationData[];
+
+type AnnotationShortcutAction = 'selectPrevious' | 'selectNext' | 'selectFirst' | 'selectLast' | 'clearSelection' | 'moveStartEarlier' | 'moveStartLater' | 'moveEndEarlier' | 'moveEndLater' | 'playActive';
+/** Key remapping map — null on the consumer means "use defaults". */
+interface AnnotationShortcutMap {
+    selectPrevious?: KeyBinding;
+    selectNext?: KeyBinding;
+    selectFirst?: KeyBinding;
+    selectLast?: KeyBinding;
+    clearSelection?: KeyBinding;
+    moveStartEarlier?: KeyBinding;
+    moveStartLater?: KeyBinding;
+    moveEndEarlier?: KeyBinding;
+    moveEndLater?: KeyBinding;
+    playActive?: KeyBinding;
+}
+declare const DEFAULT_ANNOTATION_SHORTCUTS: Record<AnnotationShortcutAction, KeyBinding[]>;
+/**
+ * Flatten defaults + remap into a matchable list. A remapped action replaces
+ * ALL of its default bindings with the single provided binding.
+ */
+declare function resolveAnnotationShortcuts(remap: AnnotationShortcutMap | null): Array<{
+    action: AnnotationShortcutAction;
+    binding: KeyBinding;
+}>;
+
+export { ANNOTATION_LINK_THRESHOLD_TICKS, type AnnotationAction, type AnnotationActionOptions, type AnnotationBoundaryOptions, type AnnotationBoundaryUpdate, type AnnotationData, type AnnotationEventMap, type AnnotationFormat, type AnnotationListOptions, type AnnotationShortcutAction, type AnnotationShortcutMap, 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_ANNOTATION_SHORTCUTS, DEFAULT_SPECTROGRAM_COLOR_MAP, type FFTSize, type Fade, type FadeConfig, type FadeType, type Gap, InteractionState, type KeyBinding, type KeyboardShortcut, LINK_THRESHOLD, MAX_CANVAS_WIDTH, MIN_ANNOTATION_DURATION, 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, annotationMinDurationTicks, 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, matchesKeyBinding, normalizedToDb, parseSpectrogramCanvasId, pixelsToSamples, pixelsToSeconds, probeRangeSupport, resolveAnnotationShortcuts, resolveRecordingOffsetSamples, sCurveCurve, samplesToPixels, samplesToSeconds, samplesToTicks, secondsToPixels, secondsToSamples, snapTickToGrid, snapToGrid, snapToTicks, sortClipsByTime, ticksPerBar, ticksPerBeat, ticksToBarBeat, ticksToSamples, trackChannelCount, updateAnnotationBoundaries, watchMicrophoneDevices };

package/dist/index.d.ts

@@ -476,6 +476,10 @@ interface AnnotationData {
     end: number;
     lines: string[];
     language?: string;
+    /** Musical position (ticks). Authoritative when BOTH tick fields are set —
+     * start/end seconds are then a derived cache (clip startTick pattern). */
+    startTick?: number;
+    endTick?: number;
 }
 /**
  * Annotation format definition for parsing/serializing
@@ -775,6 +779,21 @@ declare const MIN_PIXELS_PER_UNIT = 8;
  * correct across meter changes.
  */
 declare function computeMusicalTicks(params: MusicalTickParams): MusicalTickData;
+/**
+ * Convert an absolute tick to a 1-based bar.beat position, honoring meter
+ * changes. Bars/beats are counted per meter segment (the same walk
+ * `computeMusicalTicks` uses to build its `barOffset` accumulator). Beat is
+ * the integer beat the tick falls WITHIN (floor, 1-based) — a tick exactly on
+ * a bar line is beat 1.
+ *
+ * Guards: empty `meterEntries` → treat as 4/4 from tick 0. `ppqn <= 0` →
+ * returns `{ bar: 1, beat: 1 }` (division-by-zero guard, matches
+ * `computeMusicalTicks`'s ppqn guard).
+ */
+declare function ticksToBarBeat(tick: number, meterEntries: MeterEntry[], ppqn: number): {
+    bar: number;
+    beat: number;
+};
 /**
  * Snaps a tick position to the nearest grid boundary defined by `snapTo`.
  *
@@ -880,6 +899,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) */
@@ -994,6 +1044,13 @@ interface KeyboardShortcut {
     description?: string;
     preventDefault?: boolean;
 }
+/** A key + modifier combination, without an action. Used for remapping maps. */
+type KeyBinding = Pick<KeyboardShortcut, 'key' | 'ctrlKey' | 'shiftKey' | 'metaKey' | 'altKey'>;
+/**
+ * Does a keyboard event match a key binding?
+ * `undefined` modifier = match any state; `false` = must NOT be pressed.
+ */
+declare function matchesKeyBinding(event: KeyboardEvent, binding: KeyBinding): boolean;
 /**
  * Handle a keyboard event against a list of shortcuts.
  * Pure function, no framework dependency.
@@ -1036,4 +1093,104 @@ 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 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, 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, parseSpectrogramCanvasId, 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;
+
+/** Edges within this distance (seconds) are considered "linked". */
+declare const LINK_THRESHOLD = 0.01;
+/** Minimum annotation duration (seconds) enforced by boundary edits. */
+declare const MIN_ANNOTATION_DURATION = 0.1;
+/** Link threshold for INTEGER TICK positions — closer than half a tick means equal. */
+declare const ANNOTATION_LINK_THRESHOLD_TICKS = 0.5;
+/** Minimum tick-annotation duration: a 128th note, floored at 1 tick. */
+declare function annotationMinDurationTicks(ppqn: number): number;
+/** Unit constants for a boundary-math run. Defaults are the seconds-domain values. */
+interface AnnotationBoundaryOptions {
+    linkThreshold?: number;
+    minDuration?: number;
+}
+interface AnnotationBoundaryUpdate {
+    annotationIndex: number;
+    newTime: number;
+    isDraggingStart: boolean;
+    annotations: AnnotationData[];
+    duration: number;
+    linkEndpoints: boolean;
+}
+/**
+ * Pure boundary-update logic shared by the React annotations package and the
+ * dawcore annotation web components. Handles linked endpoints (moving one edge
+ * drags the linked neighbor edge, with cascade) and collision push-back.
+ * Returns a NEW array; never mutates inputs.
+ */
+declare function updateAnnotationBoundaries(params: AnnotationBoundaryUpdate, options?: AnnotationBoundaryOptions): AnnotationData[];
+
+type AnnotationShortcutAction = 'selectPrevious' | 'selectNext' | 'selectFirst' | 'selectLast' | 'clearSelection' | 'moveStartEarlier' | 'moveStartLater' | 'moveEndEarlier' | 'moveEndLater' | 'playActive';
+/** Key remapping map — null on the consumer means "use defaults". */
+interface AnnotationShortcutMap {
+    selectPrevious?: KeyBinding;
+    selectNext?: KeyBinding;
+    selectFirst?: KeyBinding;
+    selectLast?: KeyBinding;
+    clearSelection?: KeyBinding;
+    moveStartEarlier?: KeyBinding;
+    moveStartLater?: KeyBinding;
+    moveEndEarlier?: KeyBinding;
+    moveEndLater?: KeyBinding;
+    playActive?: KeyBinding;
+}
+declare const DEFAULT_ANNOTATION_SHORTCUTS: Record<AnnotationShortcutAction, KeyBinding[]>;
+/**
+ * Flatten defaults + remap into a matchable list. A remapped action replaces
+ * ALL of its default bindings with the single provided binding.
+ */
+declare function resolveAnnotationShortcuts(remap: AnnotationShortcutMap | null): Array<{
+    action: AnnotationShortcutAction;
+    binding: KeyBinding;
+}>;
+
+export { ANNOTATION_LINK_THRESHOLD_TICKS, type AnnotationAction, type AnnotationActionOptions, type AnnotationBoundaryOptions, type AnnotationBoundaryUpdate, type AnnotationData, type AnnotationEventMap, type AnnotationFormat, type AnnotationListOptions, type AnnotationShortcutAction, type AnnotationShortcutMap, 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_ANNOTATION_SHORTCUTS, DEFAULT_SPECTROGRAM_COLOR_MAP, type FFTSize, type Fade, type FadeConfig, type FadeType, type Gap, InteractionState, type KeyBinding, type KeyboardShortcut, LINK_THRESHOLD, MAX_CANVAS_WIDTH, MIN_ANNOTATION_DURATION, 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, annotationMinDurationTicks, 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, matchesKeyBinding, normalizedToDb, parseSpectrogramCanvasId, pixelsToSamples, pixelsToSeconds, probeRangeSupport, resolveAnnotationShortcuts, resolveRecordingOffsetSamples, sCurveCurve, samplesToPixels, samplesToSeconds, samplesToTicks, secondsToPixels, secondsToSamples, snapTickToGrid, snapToGrid, snapToTicks, sortClipsByTime, ticksPerBar, ticksPerBeat, ticksToBarBeat, ticksToSamples, trackChannelCount, updateAnnotationBoundaries, watchMicrophoneDevices };