@dawcore/transport 0.0.10 → 0.0.12

package/dist/index.d.mts

@@ -142,13 +142,26 @@ declare class TempoMap {
     private _ppqn;
     private _entries;
     constructor(ppqn?: number, initialBpm?: number);
+    /** A non-finite or non-positive BPM silently corrupts the secondsAtTick
+     *  cache (Infinity, or non-monotonic values that break the binary search
+     *  in secondsToTicks) — reject it at the boundary instead. */
+    private static _validateBpm;
     getTempo(atTick?: Tick): number;
+    /** Number of tempo entries in the map. Always >= 1 — the tick-0 entry is
+     *  permanent. Used by Transport.setTempo to detect multi-entry maps. */
+    get entryCount(): number;
     setTempo(bpm: number, atTick?: Tick, options?: SetTempoOptions): void;
     ticksToSeconds(ticks: Tick): number;
     secondsToTicks(seconds: number): Tick;
     beatsToSeconds(beats: number): number;
     secondsToBeats(seconds: number): number;
     clearTempos(): void;
+    /** Remove the tempo entry at exactly `atTick`, if one exists. The tick-0
+     *  entry is permanent (a map must always have a tempo) — removing it is a
+     *  no-op, matching removeMeter's treatment of the initial meter. The
+     *  seconds cache is recomputed from the removal point, the same partial
+     *  update setTempo uses. */
+    removeTempo(atTick: Tick): void;
     /** Get the interpolated BPM at a tick position */
     private _getTempoAt;
     private _ticksToSecondsInternal;
@@ -299,17 +312,18 @@ interface ClipEvent extends SchedulerEvent {
     trackId: string;
     clipId: string;
     audioBuffer: AudioBuffer;
-    /** Clip position on timeline (integer samples) */
+    /** Clip position on timeline (integer samples, at the TIMELINE sample rate) */
     startSample: Sample;
-    /** Offset into audioBuffer (integer samples) */
+    /** Offset into audioBuffer (integer samples, at the BUFFER's own sample
+     *  rate — they index the buffer, not the timeline) */
     offsetSamples: Sample;
-    /** Duration to play (integer samples) */
+    /** Duration to play (integer samples, at the BUFFER's own sample rate) */
     durationSamples: Sample;
     /** Clip gain multiplier */
     gain: number;
-    /** Fade in duration (integer samples) */
+    /** Fade in duration (integer samples, at the TIMELINE sample rate) */
     fadeInDurationSamples: Sample;
-    /** Fade out duration (integer samples) */
+    /** Fade out duration (integer samples, at the TIMELINE sample rate) */
     fadeOutDurationSamples: Sample;
 }
 declare class ClipPlayer implements SchedulerListener<ClipEvent> {
@@ -443,13 +457,21 @@ declare class Transport {
     setLoopSeconds(enabled: boolean, startSec: number, endSec: number): void;
     /** Convenience — sets loop in samples */
     setLoopSamples(enabled: boolean, startSample: Sample, endSample: Sample): void;
-    setTempo(bpm: number, atTick?: Tick, options?: SetTempoOptions): void;
+    /** Returns true when the tempo was applied, false when a defaulted (no
+     *  atTick) write was refused because the tempo map has multiple entries —
+     *  pass an explicit atTick to modify a multi-entry map (#407). */
+    setTempo(bpm: number, atTick?: Tick, options?: SetTempoOptions): boolean;
     getTempo(atTick?: Tick): number;
     setMeter(numerator: number, denominator: number, atTick?: Tick): void;
     getMeter(atTick?: Tick): MeterSignature;
     removeMeter(atTick: Tick): void;
     clearMeters(): void;
     clearTempos(): void;
+    /** Remove the tempo entry at exactly `atTick` (tick 0 is permanent — a
+     *  no-op, like removeMeter's initial entry). Mirrors setTempo's loop-cache
+     *  invalidation and event; the emitted bpm is the tempo now in force at
+     *  the removed position. */
+    removeTempo(atTick: Tick): void;
     barToTick(bar: number): Tick;
     tickToBar(tick: Tick): number;
     /** Convert transport time (seconds) to tick position, using the tempo map. */
@@ -514,7 +536,7 @@ declare class NativePlayoutAdapter implements PlayoutAdapter {
     setCountInMode(mode: CountInMode): void;
     setRecording(recording: boolean): void;
     isCountingIn(): boolean;
-    setTempo(bpm: number, atTick?: number): void;
+    setTempo(bpm: number, atTick?: number): boolean;
     setMeter(numerator: number, denominator: number, atTick?: number): void;
     ticksToSeconds(tick: number): number;
     secondsToTicks(seconds: number): number;

package/dist/index.d.ts

@@ -142,13 +142,26 @@ declare class TempoMap {
     private _ppqn;
     private _entries;
     constructor(ppqn?: number, initialBpm?: number);
+    /** A non-finite or non-positive BPM silently corrupts the secondsAtTick
+     *  cache (Infinity, or non-monotonic values that break the binary search
+     *  in secondsToTicks) — reject it at the boundary instead. */
+    private static _validateBpm;
     getTempo(atTick?: Tick): number;
+    /** Number of tempo entries in the map. Always >= 1 — the tick-0 entry is
+     *  permanent. Used by Transport.setTempo to detect multi-entry maps. */
+    get entryCount(): number;
     setTempo(bpm: number, atTick?: Tick, options?: SetTempoOptions): void;
     ticksToSeconds(ticks: Tick): number;
     secondsToTicks(seconds: number): Tick;
     beatsToSeconds(beats: number): number;
     secondsToBeats(seconds: number): number;
     clearTempos(): void;
+    /** Remove the tempo entry at exactly `atTick`, if one exists. The tick-0
+     *  entry is permanent (a map must always have a tempo) — removing it is a
+     *  no-op, matching removeMeter's treatment of the initial meter. The
+     *  seconds cache is recomputed from the removal point, the same partial
+     *  update setTempo uses. */
+    removeTempo(atTick: Tick): void;
     /** Get the interpolated BPM at a tick position */
     private _getTempoAt;
     private _ticksToSecondsInternal;
@@ -299,17 +312,18 @@ interface ClipEvent extends SchedulerEvent {
     trackId: string;
     clipId: string;
     audioBuffer: AudioBuffer;
-    /** Clip position on timeline (integer samples) */
+    /** Clip position on timeline (integer samples, at the TIMELINE sample rate) */
     startSample: Sample;
-    /** Offset into audioBuffer (integer samples) */
+    /** Offset into audioBuffer (integer samples, at the BUFFER's own sample
+     *  rate — they index the buffer, not the timeline) */
     offsetSamples: Sample;
-    /** Duration to play (integer samples) */
+    /** Duration to play (integer samples, at the BUFFER's own sample rate) */
     durationSamples: Sample;
     /** Clip gain multiplier */
     gain: number;
-    /** Fade in duration (integer samples) */
+    /** Fade in duration (integer samples, at the TIMELINE sample rate) */
     fadeInDurationSamples: Sample;
-    /** Fade out duration (integer samples) */
+    /** Fade out duration (integer samples, at the TIMELINE sample rate) */
     fadeOutDurationSamples: Sample;
 }
 declare class ClipPlayer implements SchedulerListener<ClipEvent> {
@@ -443,13 +457,21 @@ declare class Transport {
     setLoopSeconds(enabled: boolean, startSec: number, endSec: number): void;
     /** Convenience — sets loop in samples */
     setLoopSamples(enabled: boolean, startSample: Sample, endSample: Sample): void;
-    setTempo(bpm: number, atTick?: Tick, options?: SetTempoOptions): void;
+    /** Returns true when the tempo was applied, false when a defaulted (no
+     *  atTick) write was refused because the tempo map has multiple entries —
+     *  pass an explicit atTick to modify a multi-entry map (#407). */
+    setTempo(bpm: number, atTick?: Tick, options?: SetTempoOptions): boolean;
     getTempo(atTick?: Tick): number;
     setMeter(numerator: number, denominator: number, atTick?: Tick): void;
     getMeter(atTick?: Tick): MeterSignature;
     removeMeter(atTick: Tick): void;
     clearMeters(): void;
     clearTempos(): void;
+    /** Remove the tempo entry at exactly `atTick` (tick 0 is permanent — a
+     *  no-op, like removeMeter's initial entry). Mirrors setTempo's loop-cache
+     *  invalidation and event; the emitted bpm is the tempo now in force at
+     *  the removed position. */
+    removeTempo(atTick: Tick): void;
     barToTick(bar: number): Tick;
     tickToBar(tick: Tick): number;
     /** Convert transport time (seconds) to tick position, using the tempo map. */
@@ -514,7 +536,7 @@ declare class NativePlayoutAdapter implements PlayoutAdapter {
     setCountInMode(mode: CountInMode): void;
     setRecording(recording: boolean): void;
     isCountingIn(): boolean;
-    setTempo(bpm: number, atTick?: number): void;
+    setTempo(bpm: number, atTick?: number): boolean;
     setMeter(numerator: number, denominator: number, atTick?: number): void;
     ticksToSeconds(tick: number): number;
     secondsToTicks(seconds: number): number;

package/dist/index.js

@@ -249,7 +249,7 @@ var SampleTimeline = class {
         "[waveform-playlist] SampleTimeline: tempoMap not set \u2014 call setTempoMap() first"
       );
     }
-    return this._tempoMap.secondsToTicks(samples / this._sampleRate);
+    return Math.round(this._tempoMap.secondsToTicks(samples / this._sampleRate));
   }
 };
 
@@ -261,15 +261,32 @@ function curveNormalizedAt(x, slope) {
   const p = Math.max(CURVE_EPSILON, Math.min(1 - CURVE_EPSILON, slope));
   return p * p / (1 - p * 2) * (Math.pow((1 - p) / p, 2 * x) - 1);
 }
-var TempoMap = class {
+var TempoMap = class _TempoMap {
   constructor(ppqn = 960, initialBpm = 120) {
+    _TempoMap._validateBpm(initialBpm);
     this._ppqn = ppqn;
     this._entries = [{ tick: 0, bpm: initialBpm, interpolation: "step", secondsAtTick: 0 }];
   }
+  /** A non-finite or non-positive BPM silently corrupts the secondsAtTick
+   *  cache (Infinity, or non-monotonic values that break the binary search
+   *  in secondsToTicks) — reject it at the boundary instead. */
+  static _validateBpm(bpm) {
+    if (!Number.isFinite(bpm) || bpm <= 0) {
+      throw new Error(
+        "[waveform-playlist] TempoMap: bpm must be a finite positive number, got " + bpm
+      );
+    }
+  }
   getTempo(atTick = 0) {
     return this._getTempoAt(atTick);
   }
+  /** Number of tempo entries in the map. Always >= 1 — the tick-0 entry is
+   *  permanent. Used by Transport.setTempo to detect multi-entry maps. */
+  get entryCount() {
+    return this._entries.length;
+  }
   setTempo(bpm, atTick = 0, options) {
+    _TempoMap._validateBpm(bpm);
     const interpolation = options?.interpolation ?? "step";
     if (typeof interpolation === "object" && interpolation.type === "curve") {
       const s = interpolation.slope;
@@ -346,6 +363,18 @@ var TempoMap = class {
     const first = this._entries[0];
     this._entries = [{ tick: 0, bpm: first.bpm, interpolation: "step", secondsAtTick: 0 }];
   }
+  /** Remove the tempo entry at exactly `atTick`, if one exists. The tick-0
+   *  entry is permanent (a map must always have a tempo) — removing it is a
+   *  no-op, matching removeMeter's treatment of the initial meter. The
+   *  seconds cache is recomputed from the removal point, the same partial
+   *  update setTempo uses. */
+  removeTempo(atTick) {
+    if (atTick === 0) return;
+    const i = this._entries.findIndex((e) => e.tick === atTick);
+    if (i === -1) return;
+    this._entries = [...this._entries.slice(0, i), ...this._entries.slice(i + 1)];
+    this._recomputeCache(i);
+  }
   /** Get the interpolated BPM at a tick position */
   _getTempoAt(atTick) {
     const entryIndex = this._entryIndexAt(atTick);
@@ -507,6 +536,7 @@ function isPowerOf2(n) {
 var MeterMap = class {
   constructor(ppqn, numerator = 4, denominator = 4) {
     this._ppqn = ppqn;
+    this._validateMeter(numerator, denominator);
     this._entries = [{ tick: 0, numerator, denominator, barAtTick: 0 }];
   }
   get ppqn() {
@@ -670,6 +700,11 @@ var MeterMap = class {
         "[waveform-playlist] MeterMap: denominator must be a power of 2 (1-32), got " + denominator
       );
     }
+    if (!Number.isInteger(this._ppqn * 4 / denominator)) {
+      throw new Error(
+        "[waveform-playlist] MeterMap: ppqn (" + this._ppqn + ") * 4 is not divisible by denominator (" + denominator + ") \u2014 bar boundaries would fall on fractional ticks"
+      );
+    }
   }
 };
 
@@ -800,11 +835,19 @@ var ClipPlayer = class {
         const clipTick = clip.startTick !== void 0 ? clip.startTick : this._sampleTimeline.samplesToTicks(clip.startSample);
         if (clipTick < fromTick) continue;
         if (clipTick >= toTick) continue;
-        const fadeInDurationSamples = clip.fadeIn ? clip.fadeIn.duration ?? 0 : 0;
-        const fadeOutDurationSamples = clip.fadeOut ? clip.fadeOut.duration ?? 0 : 0;
+        const timelineRate = this._sampleTimeline.sampleRate;
+        const bufferRate = clip.audioBuffer.sampleRate;
+        const fadeInDurationSamples = clip.fadeIn ? Math.round((clip.fadeIn.duration ?? 0) * timelineRate) : 0;
+        const fadeOutDurationSamples = clip.fadeOut ? Math.round((clip.fadeOut.duration ?? 0) * timelineRate) : 0;
         let durationSamples = clip.durationSamples;
-        if (this._loopEnabled && clip.startSample + durationSamples > this._loopEndSamples) {
-          durationSamples = this._loopEndSamples - clip.startSample;
+        if (this._loopEnabled) {
+          const durationTimelineSamples = Math.round(
+            clip.durationSamples / bufferRate * timelineRate
+          );
+          const allowedTimelineSamples = this._loopEndSamples - clip.startSample;
+          if (durationTimelineSamples > allowedTimelineSamples) {
+            durationSamples = Math.round(allowedTimelineSamples / timelineRate * bufferRate);
+          }
         }
         events.push({
           trackId,
@@ -830,9 +873,9 @@ var ClipPlayer = class {
       );
       return;
     }
-    const sampleRate = this._sampleTimeline.sampleRate;
-    const offsetSeconds = event.offsetSamples / sampleRate;
-    const durationSeconds = event.durationSamples / sampleRate;
+    const bufferRate = event.audioBuffer.sampleRate;
+    const offsetSeconds = event.offsetSamples / bufferRate;
+    const durationSeconds = event.durationSamples / bufferRate;
     if (offsetSeconds >= event.audioBuffer.duration) {
       console.warn(
         "[waveform-playlist] ClipPlayer.consume: offset (" + offsetSeconds + "s) exceeds audioBuffer.duration (" + event.audioBuffer.duration + 's) for clipId "' + event.clipId + '" \u2014 clip will not play'
@@ -845,8 +888,9 @@ var ClipPlayer = class {
     const when = this._toAudioTime(transportSeconds);
     const gainNode = this._audioContext.createGain();
     gainNode.gain.value = event.gain;
-    let fadeIn = event.fadeInDurationSamples / sampleRate;
-    let fadeOut = event.fadeOutDurationSamples / sampleRate;
+    const timelineRate = this._sampleTimeline.sampleRate;
+    let fadeIn = event.fadeInDurationSamples / timelineRate;
+    let fadeOut = event.fadeOutDurationSamples / timelineRate;
     if (fadeIn + fadeOut > durationSeconds) {
       const ratio = durationSeconds / (fadeIn + fadeOut);
       fadeIn *= ratio;
@@ -886,16 +930,21 @@ var ClipPlayer = class {
         if (!clip.audioBuffer) continue;
         const clipTick = clip.startTick !== void 0 ? clip.startTick : this._sampleTimeline.samplesToTicks(clip.startSample);
         if (clipTick >= newTick) continue;
-        const clipEndSample = clip.startSample + clip.durationSamples;
+        const timelineRate = this._sampleTimeline.sampleRate;
+        const bufferRate = clip.audioBuffer.sampleRate;
+        const bufToTimeline = (n) => Math.round(n / bufferRate * timelineRate);
+        const timelineToBuf = (n) => Math.round(n / timelineRate * bufferRate);
+        const clipEndSample = clip.startSample + bufToTimeline(clip.durationSamples);
         if (clipEndSample <= newSample) continue;
         const offsetIntoClipSamples = newSample - clip.startSample;
-        const offsetSamples = clip.offsetSamples + offsetIntoClipSamples;
-        let durationSamples = clipEndSample - newSample;
-        if (this._loopEnabled && newSample + durationSamples > this._loopEndSamples) {
-          durationSamples = this._loopEndSamples - newSample;
+        const offsetSamples = clip.offsetSamples + timelineToBuf(offsetIntoClipSamples);
+        let remainingTimelineSamples = clipEndSample - newSample;
+        if (this._loopEnabled && newSample + remainingTimelineSamples > this._loopEndSamples) {
+          remainingTimelineSamples = this._loopEndSamples - newSample;
         }
-        if (durationSamples <= 0) continue;
-        const fadeOutDurationSamples = clip.fadeOut ? clip.fadeOut.duration ?? 0 : 0;
+        if (remainingTimelineSamples <= 0) continue;
+        const durationSamples = timelineToBuf(remainingTimelineSamples);
+        const fadeOutDurationSamples = clip.fadeOut ? Math.round((clip.fadeOut.duration ?? 0) * timelineRate) : 0;
         this.consume({
           trackId,
           clipId: clip.id,
@@ -1499,12 +1548,22 @@ var _Transport = class _Transport {
     this._emit("loop");
   }
   // --- Tempo ---
+  /** Returns true when the tempo was applied, false when a defaulted (no
+   *  atTick) write was refused because the tempo map has multiple entries —
+   *  pass an explicit atTick to modify a multi-entry map (#407). */
   setTempo(bpm, atTick, options) {
+    if (atTick === void 0 && this._tempoMap.entryCount > 1) {
+      console.warn(
+        "[waveform-playlist] Transport.setTempo: refusing defaulted tick-0 write of " + bpm + " BPM \u2014 the tempo map has " + this._tempoMap.entryCount + " entries. Pass an explicit atTick to modify a multi-entry tempo map."
+      );
+      return false;
+    }
     this._tempoMap.setTempo(bpm, atTick, options);
     if (this._loopEnabled) {
       this._loopStartSeconds = this._tempoMap.ticksToSeconds(this._loopStartTick);
     }
     this._emit("tempochange", { bpm, atTick: atTick ?? 0 });
+    return true;
   }
   getTempo(atTick) {
     return this._tempoMap.getTempo(atTick);
@@ -1542,6 +1601,17 @@ var _Transport = class _Transport {
     }
     this._emit("tempochange", { bpm: this._tempoMap.getTempo(), atTick: 0 });
   }
+  /** Remove the tempo entry at exactly `atTick` (tick 0 is permanent — a
+   *  no-op, like removeMeter's initial entry). Mirrors setTempo's loop-cache
+   *  invalidation and event; the emitted bpm is the tempo now in force at
+   *  the removed position. */
+  removeTempo(atTick) {
+    this._tempoMap.removeTempo(atTick);
+    if (this._loopEnabled) {
+      this._loopStartSeconds = this._tempoMap.ticksToSeconds(this._loopStartTick);
+    }
+    this._emit("tempochange", { bpm: this._tempoMap.getTempo(atTick), atTick });
+  }
   barToTick(bar) {
     return this._meterMap.barToTick(bar);
   }
@@ -1914,7 +1984,7 @@ var NativePlayoutAdapter = class {
     return this._transport.isCountingIn();
   }
   setTempo(bpm, atTick) {
-    this._transport.setTempo(bpm, atTick !== void 0 ? atTick : void 0);
+    return this._transport.setTempo(bpm, atTick !== void 0 ? atTick : void 0);
   }
   setMeter(numerator, denominator, atTick) {
     this._transport.setMeter(