@dawcore/transport 0.0.2 → 0.0.4

package/dist/index.mjs

@@ -49,12 +49,15 @@ var Clock = class {
 
 // src/core/scheduler.ts
 var Scheduler = class {
-  constructor(options = {}) {
+  constructor(tempoMap, options = {}) {
     this._rightEdge = 0;
+    // integer ticks
     this._listeners = /* @__PURE__ */ new Set();
     this._loopEnabled = false;
     this._loopStart = 0;
+    // integer ticks
     this._loopEnd = 0;
+    this._tempoMap = tempoMap;
     this._lookahead = options.lookahead ?? 0.2;
     this._onLoop = options.onLoop;
   }
@@ -64,25 +67,40 @@ var Scheduler = class {
   removeListener(listener) {
     this._listeners.delete(listener);
   }
-  setLoop(enabled, start, end) {
-    if (enabled && start >= end) {
+  /** Primary API — ticks as source of truth */
+  setLoop(enabled, startTick, endTick) {
+    if (enabled && (!Number.isFinite(startTick) || !Number.isFinite(endTick))) {
       console.warn(
-        "[waveform-playlist] Scheduler.setLoop: start (" + start + ") must be less than end (" + end + ")"
+        "[waveform-playlist] Scheduler.setLoop: non-finite tick values (" + startTick + ", " + endTick + ")"
+      );
+      return;
+    }
+    if (enabled && startTick >= endTick) {
+      console.warn(
+        "[waveform-playlist] Scheduler.setLoop: startTick (" + startTick + ") must be less than endTick (" + endTick + ")"
       );
       return;
     }
     this._loopEnabled = enabled;
-    this._loopStart = start;
-    this._loopEnd = end;
-  }
-  reset(time) {
-    this._rightEdge = time;
-  }
-  advance(currentTime) {
-    const targetEdge = currentTime + this._lookahead;
+    this._loopStart = Math.round(startTick);
+    this._loopEnd = Math.round(endTick);
+  }
+  /** Convenience — converts seconds to ticks via TempoMap */
+  setLoopSeconds(enabled, startSec, endSec) {
+    const startTick = this._tempoMap.secondsToTicks(startSec);
+    const endTick = this._tempoMap.secondsToTicks(endSec);
+    this.setLoop(enabled, startTick, endTick);
+  }
+  /** Reset scheduling cursor. Takes seconds (from Clock), converts to ticks. */
+  reset(timeSeconds) {
+    this._rightEdge = this._tempoMap.secondsToTicks(timeSeconds);
+  }
+  /** Advance the scheduling window. Takes seconds (from Clock), converts to ticks. */
+  advance(currentTimeSeconds) {
+    const targetTick = this._tempoMap.secondsToTicks(currentTimeSeconds + this._lookahead);
     if (this._loopEnabled && this._loopEnd > this._loopStart) {
       const loopDuration = this._loopEnd - this._loopStart;
-      let remaining = targetEdge - this._rightEdge;
+      let remaining = targetTick - this._rightEdge;
       while (remaining > 0) {
         const distToEnd = this._loopEnd - this._rightEdge;
         if (distToEnd <= 0 || distToEnd > remaining) {
@@ -95,21 +113,25 @@ var Scheduler = class {
         for (const listener of this._listeners) {
           listener.onPositionJump(this._loopStart);
         }
-        this._onLoop?.(this._loopStart);
+        this._onLoop?.(
+          this._tempoMap.ticksToSeconds(this._loopStart),
+          this._tempoMap.ticksToSeconds(this._loopEnd),
+          currentTimeSeconds
+        );
         this._rightEdge = this._loopStart;
         if (loopDuration <= 0) break;
       }
       return;
     }
-    if (targetEdge > this._rightEdge) {
-      this._generateAndConsume(this._rightEdge, targetEdge);
-      this._rightEdge = targetEdge;
+    if (targetTick > this._rightEdge) {
+      this._generateAndConsume(this._rightEdge, targetTick);
+      this._rightEdge = targetTick;
     }
   }
-  _generateAndConsume(from, to) {
+  _generateAndConsume(fromTick, toTick) {
     for (const listener of this._listeners) {
       try {
-        const events = listener.generate(from, to);
+        const events = listener.generate(fromTick, toTick);
         for (const event of events) {
           try {
             listener.consume(event);
@@ -159,42 +181,77 @@ var Timer = class {
 // src/timeline/sample-timeline.ts
 var SampleTimeline = class {
   constructor(sampleRate) {
+    this._tempoMap = null;
     this._sampleRate = sampleRate;
   }
   get sampleRate() {
     return this._sampleRate;
   }
+  setTempoMap(tempoMap) {
+    this._tempoMap = tempoMap;
+  }
   samplesToSeconds(samples) {
     return samples / this._sampleRate;
   }
   secondsToSamples(seconds) {
     return Math.round(seconds * this._sampleRate);
   }
+  ticksToSamples(ticks) {
+    if (!this._tempoMap) {
+      throw new Error(
+        "[waveform-playlist] SampleTimeline: tempoMap not set \u2014 call setTempoMap() first"
+      );
+    }
+    return Math.round(this._tempoMap.ticksToSeconds(ticks) * this._sampleRate);
+  }
+  samplesToTicks(samples) {
+    if (!this._tempoMap) {
+      throw new Error(
+        "[waveform-playlist] SampleTimeline: tempoMap not set \u2014 call setTempoMap() first"
+      );
+    }
+    return this._tempoMap.secondsToTicks(samples / this._sampleRate);
+  }
 };
 
 // src/timeline/tempo-map.ts
+var CURVE_EPSILON = 1e-15;
+var CURVE_SUBDIVISIONS = 64;
+function curveNormalizedAt(x, slope) {
+  if (slope > 0.499999 && slope < 0.500001) return x;
+  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 {
   constructor(ppqn = 960, initialBpm = 120) {
     this._ppqn = ppqn;
-    this._entries = [{ tick: 0, bpm: initialBpm, secondsAtTick: 0 }];
+    this._entries = [{ tick: 0, bpm: initialBpm, interpolation: "step", secondsAtTick: 0 }];
   }
   getTempo(atTick = 0) {
-    const entry = this._entryAt(atTick);
-    return entry.bpm;
-  }
-  setTempo(bpm, atTick = 0) {
+    return this._getTempoAt(atTick);
+  }
+  setTempo(bpm, atTick = 0, options) {
+    const interpolation = options?.interpolation ?? "step";
+    if (typeof interpolation === "object" && interpolation.type === "curve") {
+      const s = interpolation.slope;
+      if (!Number.isFinite(s) || s <= 0 || s >= 1) {
+        throw new Error(
+          "[waveform-playlist] TempoMap: curve slope must be between 0 and 1 (exclusive), got " + s
+        );
+      }
+    }
     if (atTick === 0) {
-      this._entries[0] = { ...this._entries[0], bpm };
+      this._entries[0] = { ...this._entries[0], bpm, interpolation: "step" };
       this._recomputeCache(0);
       return;
     }
     let i = this._entries.length - 1;
     while (i > 0 && this._entries[i].tick > atTick) i--;
     if (this._entries[i].tick === atTick) {
-      this._entries[i] = { ...this._entries[i], bpm };
+      this._entries[i] = { ...this._entries[i], bpm, interpolation };
     } else {
       const secondsAtTick = this._ticksToSecondsInternal(atTick);
-      this._entries.splice(i + 1, 0, { tick: atTick, bpm, secondsAtTick });
+      this._entries.splice(i + 1, 0, { tick: atTick, bpm, interpolation, secondsAtTick });
       i = i + 1;
     }
     this._recomputeCache(i);
@@ -215,8 +272,30 @@ var TempoMap = class {
     }
     const entry = this._entries[lo];
     const secondsIntoSegment = seconds - entry.secondsAtTick;
+    const nextEntry = lo < this._entries.length - 1 ? this._entries[lo + 1] : null;
+    if (nextEntry && nextEntry.interpolation === "linear") {
+      return Math.round(
+        entry.tick + this._secondsToTicksLinear(
+          secondsIntoSegment,
+          entry.bpm,
+          nextEntry.bpm,
+          nextEntry.tick - entry.tick
+        )
+      );
+    }
+    if (nextEntry && typeof nextEntry.interpolation === "object") {
+      return Math.round(
+        entry.tick + this._secondsToTicksCurve(
+          secondsIntoSegment,
+          entry.bpm,
+          nextEntry.bpm,
+          nextEntry.tick - entry.tick,
+          nextEntry.interpolation.slope
+        )
+      );
+    }
     const ticksPerSecond = entry.bpm / 60 * this._ppqn;
-    return entry.tick + secondsIntoSegment * ticksPerSecond;
+    return Math.round(entry.tick + secondsIntoSegment * ticksPerSecond);
   }
   beatsToSeconds(beats) {
     return this.ticksToSeconds(beats * this._ppqn);
@@ -226,15 +305,122 @@ var TempoMap = class {
   }
   clearTempos() {
     const first = this._entries[0];
-    this._entries = [{ tick: 0, bpm: first.bpm, secondsAtTick: 0 }];
+    this._entries = [{ tick: 0, bpm: first.bpm, interpolation: "step", secondsAtTick: 0 }];
+  }
+  /** Get the interpolated BPM at a tick position */
+  _getTempoAt(atTick) {
+    const entryIndex = this._entryIndexAt(atTick);
+    const entry = this._entries[entryIndex];
+    const nextEntry = entryIndex < this._entries.length - 1 ? this._entries[entryIndex + 1] : null;
+    if (nextEntry && nextEntry.interpolation !== "step") {
+      const segmentTicks = nextEntry.tick - entry.tick;
+      const ticksInto = atTick - entry.tick;
+      if (segmentTicks > 0) {
+        const progress = ticksInto / segmentTicks;
+        if (nextEntry.interpolation === "linear") {
+          return entry.bpm + (nextEntry.bpm - entry.bpm) * progress;
+        }
+        const t = curveNormalizedAt(progress, nextEntry.interpolation.slope);
+        return entry.bpm + (nextEntry.bpm - entry.bpm) * t;
+      }
+    }
+    return entry.bpm;
   }
   _ticksToSecondsInternal(ticks) {
-    const entry = this._entryAt(ticks);
+    const entryIndex = this._entryIndexAt(ticks);
+    const entry = this._entries[entryIndex];
     const ticksIntoSegment = ticks - entry.tick;
+    const nextEntry = entryIndex < this._entries.length - 1 ? this._entries[entryIndex + 1] : null;
+    if (nextEntry && nextEntry.interpolation === "linear") {
+      const segmentTicks = nextEntry.tick - entry.tick;
+      return entry.secondsAtTick + this._ticksToSecondsLinear(ticksIntoSegment, entry.bpm, nextEntry.bpm, segmentTicks);
+    }
+    if (nextEntry && typeof nextEntry.interpolation === "object") {
+      const segmentTicks = nextEntry.tick - entry.tick;
+      return entry.secondsAtTick + this._ticksToSecondsCurve(
+        ticksIntoSegment,
+        entry.bpm,
+        nextEntry.bpm,
+        segmentTicks,
+        nextEntry.interpolation.slope
+      );
+    }
     const secondsPerTick = 60 / (entry.bpm * this._ppqn);
     return entry.secondsAtTick + ticksIntoSegment * secondsPerTick;
   }
-  _entryAt(tick) {
+  /**
+   * Exact integration for a linear BPM ramp using the logarithmic formula.
+   * For bpm(t) = bpm0 + r*t where r = (bpm1-bpm0)/T:
+   *   seconds = (T * 60) / (ppqn * (bpm1-bpm0)) * ln(bpmAtTick / bpm0)
+   */
+  _ticksToSecondsLinear(ticks, bpm0, bpm1, totalSegmentTicks) {
+    if (totalSegmentTicks === 0) return 0;
+    const bpmAtTick = bpm0 + (bpm1 - bpm0) * (ticks / totalSegmentTicks);
+    if (Math.abs(bpm1 - bpm0) < 1e-10) {
+      return ticks * 60 / (bpm0 * this._ppqn);
+    }
+    const deltaBpm = bpm1 - bpm0;
+    return totalSegmentTicks * 60 / (this._ppqn * deltaBpm) * Math.log(bpmAtTick / bpm0);
+  }
+  /**
+   * Inverse of _ticksToSecondsLinear: given seconds, return ticks.
+   * Closed-form via exponential: bpmAtTick = bpm0 * exp(seconds * deltaBpm * ppqn / (60 * T))
+   * then ticks = (bpmAtTick - bpm0) * T / deltaBpm
+   *
+   * Note: exp(log(x)) has ~1 ULP floating-point error, so round-trips depend on
+   * Math.round() in the caller (secondsToTicks). This is sufficient for all tested
+   * BPM ranges (10–300 BPM) but is not algebraically exact like the previous
+   * trapezoidal/quadratic approach was.
+   */
+  _secondsToTicksLinear(seconds, bpm0, bpm1, totalSegmentTicks) {
+    if (totalSegmentTicks === 0 || seconds === 0) return 0;
+    if (Math.abs(bpm1 - bpm0) < 1e-10) {
+      return seconds * bpm0 * this._ppqn / 60;
+    }
+    const deltaBpm = bpm1 - bpm0;
+    const bpmAtTick = bpm0 * Math.exp(seconds * deltaBpm * this._ppqn / (60 * totalSegmentTicks));
+    return (bpmAtTick - bpm0) / deltaBpm * totalSegmentTicks;
+  }
+  /**
+   * Subdivided trapezoidal integration for a Möbius-Ease tempo curve.
+   * The BPM at progress p is: bpm0 + curveNormalizedAt(p, slope) * (bpm1 - bpm0).
+   * We subdivide into CURVE_SUBDIVISIONS intervals and apply trapezoidal rule.
+   */
+  _ticksToSecondsCurve(ticks, bpm0, bpm1, totalSegmentTicks, slope) {
+    if (totalSegmentTicks === 0 || ticks === 0) return 0;
+    const n = CURVE_SUBDIVISIONS;
+    const dt = ticks / n;
+    let seconds = 0;
+    let prevBpm = bpm0;
+    for (let i = 1; i <= n; i++) {
+      const progress = dt * i / totalSegmentTicks;
+      const curBpm = bpm0 + curveNormalizedAt(progress, slope) * (bpm1 - bpm0);
+      seconds += dt * 60 / this._ppqn * (1 / prevBpm + 1 / curBpm) / 2;
+      prevBpm = curBpm;
+    }
+    return seconds;
+  }
+  /**
+   * Inverse of _ticksToSecondsCurve: given seconds into a curved segment,
+   * return ticks. Uses binary search since there's no closed-form inverse.
+   */
+  _secondsToTicksCurve(seconds, bpm0, bpm1, totalSegmentTicks, slope) {
+    if (totalSegmentTicks === 0 || seconds === 0) return 0;
+    const iterations = Math.min(40, Math.max(1, Math.ceil(Math.log2(2 * totalSegmentTicks))));
+    let lo = 0;
+    let hi = totalSegmentTicks;
+    for (let i = 0; i < iterations; i++) {
+      const mid = (lo + hi) / 2;
+      const midSeconds = this._ticksToSecondsCurve(mid, bpm0, bpm1, totalSegmentTicks, slope);
+      if (midSeconds < seconds) {
+        lo = mid;
+      } else {
+        hi = mid;
+      }
+    }
+    return (lo + hi) / 2;
+  }
+  _entryIndexAt(tick) {
     let lo = 0;
     let hi = this._entries.length - 1;
     while (lo < hi) {
@@ -245,16 +431,31 @@ var TempoMap = class {
         hi = mid - 1;
       }
     }
-    return this._entries[lo];
+    return lo;
   }
   _recomputeCache(fromIndex) {
     for (let i = Math.max(1, fromIndex); i < this._entries.length; i++) {
       const prev = this._entries[i - 1];
       const tickDelta = this._entries[i].tick - prev.tick;
-      const secondsPerTick = 60 / (prev.bpm * this._ppqn);
+      const entry = this._entries[i];
+      let segmentSeconds;
+      if (entry.interpolation === "linear") {
+        segmentSeconds = this._ticksToSecondsLinear(tickDelta, prev.bpm, entry.bpm, tickDelta);
+      } else if (typeof entry.interpolation === "object") {
+        segmentSeconds = this._ticksToSecondsCurve(
+          tickDelta,
+          prev.bpm,
+          entry.bpm,
+          tickDelta,
+          entry.interpolation.slope
+        );
+      } else {
+        const secondsPerTick = 60 / (prev.bpm * this._ppqn);
+        segmentSeconds = tickDelta * secondsPerTick;
+      }
       this._entries[i] = {
-        ...this._entries[i],
-        secondsAtTick: prev.secondsAtTick + tickDelta * secondsPerTick
+        ...entry,
+        secondsAtTick: prev.secondsAtTick + segmentSeconds
       };
     }
   }
@@ -518,14 +719,15 @@ var TrackNode = class {
 
 // src/audio/clip-player.ts
 var ClipPlayer = class {
-  constructor(audioContext, sampleTimeline, toAudioTime) {
+  constructor(audioContext, sampleTimeline, tempoMap, toAudioTime) {
     this._tracks = /* @__PURE__ */ new Map();
     this._trackNodes = /* @__PURE__ */ new Map();
     this._activeSources = /* @__PURE__ */ new Map();
     this._loopEnabled = false;
-    this._loopEnd = 0;
+    this._loopEndSamples = 0;
     this._audioContext = audioContext;
     this._sampleTimeline = sampleTimeline;
+    this._tempoMap = tempoMap;
     this._toAudioTime = toAudioTime;
   }
   setTracks(tracks, trackNodes) {
@@ -535,41 +737,50 @@ var ClipPlayer = class {
       this._tracks.set(track.id, { track, clips: track.clips });
     }
   }
-  setLoop(enabled, _start, end) {
+  /** Set loop region using ticks. startTick is unused — loop clamping only needs
+   *  the end boundary; mid-clip restart at loopStart is handled by onPositionJump. */
+  setLoop(enabled, _startTick, endTick) {
+    this._loopEnabled = enabled;
+    this._loopEndSamples = this._sampleTimeline.ticksToSamples(endTick);
+  }
+  /** Set loop region using samples directly */
+  setLoopSamples(enabled, _startSample, endSample) {
     this._loopEnabled = enabled;
-    this._loopEnd = end;
+    this._loopEndSamples = endSample;
   }
   updateTrack(trackId, track) {
     this._tracks.set(trackId, { track, clips: track.clips });
     this._silenceTrack(trackId);
   }
-  generate(fromTime, toTime) {
+  generate(fromTick, toTick) {
     const events = [];
+    const fromSample = this._sampleTimeline.ticksToSamples(fromTick);
+    const toSample = this._sampleTimeline.ticksToSamples(toTick);
     for (const [trackId, state] of this._tracks) {
       for (const clip of state.clips) {
         if (clip.durationSamples === 0) continue;
         if (!clip.audioBuffer) continue;
-        const clipStartTime = this._sampleTimeline.samplesToSeconds(clip.startSample);
-        const clipDuration = this._sampleTimeline.samplesToSeconds(clip.durationSamples);
-        const clipOffsetTime = this._sampleTimeline.samplesToSeconds(clip.offsetSamples);
-        if (clipStartTime < fromTime) continue;
-        if (clipStartTime >= toTime) continue;
-        const fadeInDuration = clip.fadeIn ? this._sampleTimeline.samplesToSeconds(clip.fadeIn.duration ?? 0) : 0;
-        const fadeOutDuration = clip.fadeOut ? this._sampleTimeline.samplesToSeconds(clip.fadeOut.duration ?? 0) : 0;
-        let duration = clipDuration;
-        if (this._loopEnabled && clipStartTime + duration > this._loopEnd) {
-          duration = this._loopEnd - clipStartTime;
+        const clipStartSample = clip.startSample;
+        if (clipStartSample < fromSample) continue;
+        if (clipStartSample >= toSample) continue;
+        const fadeInDurationSamples = clip.fadeIn ? clip.fadeIn.duration ?? 0 : 0;
+        const fadeOutDurationSamples = clip.fadeOut ? clip.fadeOut.duration ?? 0 : 0;
+        let durationSamples = clip.durationSamples;
+        if (this._loopEnabled && clipStartSample + durationSamples > this._loopEndSamples) {
+          durationSamples = this._loopEndSamples - clipStartSample;
         }
+        const clipTick = this._sampleTimeline.samplesToTicks(clipStartSample);
         events.push({
           trackId,
           clipId: clip.id,
           audioBuffer: clip.audioBuffer,
-          transportTime: clipStartTime,
-          offset: clipOffsetTime,
-          duration,
+          tick: clipTick,
+          startSample: clipStartSample,
+          offsetSamples: clip.offsetSamples,
+          durationSamples,
           gain: clip.gain,
-          fadeInDuration,
-          fadeOutDuration
+          fadeInDurationSamples,
+          fadeOutDurationSamples
         });
       }
     }
@@ -583,18 +794,25 @@ var ClipPlayer = class {
       );
       return;
     }
-    if (event.offset >= event.audioBuffer.duration) {
+    const sampleRate = this._sampleTimeline.sampleRate;
+    const offsetSeconds = event.offsetSamples / sampleRate;
+    const durationSeconds = event.durationSamples / sampleRate;
+    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'
+      );
       return;
     }
     const source = this._audioContext.createBufferSource();
     source.buffer = event.audioBuffer;
-    const when = this._toAudioTime(event.transportTime);
+    const transportSeconds = this._tempoMap.ticksToSeconds(event.tick);
+    const when = this._toAudioTime(transportSeconds);
     const gainNode = this._audioContext.createGain();
     gainNode.gain.value = event.gain;
-    let fadeIn = event.fadeInDuration;
-    let fadeOut = event.fadeOutDuration;
-    if (fadeIn + fadeOut > event.duration) {
-      const ratio = event.duration / (fadeIn + fadeOut);
+    let fadeIn = event.fadeInDurationSamples / sampleRate;
+    let fadeOut = event.fadeOutDurationSamples / sampleRate;
+    if (fadeIn + fadeOut > durationSeconds) {
+      const ratio = durationSeconds / (fadeIn + fadeOut);
       fadeIn *= ratio;
       fadeOut *= ratio;
     }
@@ -603,9 +821,9 @@ var ClipPlayer = class {
       gainNode.gain.linearRampToValueAtTime(event.gain, when + fadeIn);
     }
     if (fadeOut > 0) {
-      const fadeOutStart = when + event.duration - fadeOut;
+      const fadeOutStart = when + durationSeconds - fadeOut;
       gainNode.gain.setValueAtTime(event.gain, fadeOutStart);
-      gainNode.gain.linearRampToValueAtTime(0, when + event.duration);
+      gainNode.gain.linearRampToValueAtTime(0, when + durationSeconds);
     }
     source.connect(gainNode);
     gainNode.connect(trackNode.input);
@@ -621,33 +839,37 @@ var ClipPlayer = class {
         console.warn("[waveform-playlist] ClipPlayer: error disconnecting gain node:", String(err));
       }
     });
-    source.start(when, event.offset, event.duration);
+    source.start(when, offsetSeconds, durationSeconds);
   }
-  onPositionJump(newTime) {
+  onPositionJump(newTick) {
     this.silence();
+    const newSample = this._sampleTimeline.ticksToSamples(newTick);
     for (const [trackId, state] of this._tracks) {
       for (const clip of state.clips) {
         if (clip.durationSamples === 0) continue;
         if (!clip.audioBuffer) continue;
-        const clipStartTime = this._sampleTimeline.samplesToSeconds(clip.startSample);
-        const clipDuration = this._sampleTimeline.samplesToSeconds(clip.durationSamples);
-        const clipEndTime = clipStartTime + clipDuration;
-        const clipOffsetTime = this._sampleTimeline.samplesToSeconds(clip.offsetSamples);
-        if (clipStartTime <= newTime && clipEndTime > newTime) {
-          const offsetIntoClip = newTime - clipStartTime;
-          const offset = clipOffsetTime + offsetIntoClip;
-          const duration = clipEndTime - newTime;
-          const fadeOutDuration = clip.fadeOut ? this._sampleTimeline.samplesToSeconds(clip.fadeOut.duration ?? 0) : 0;
+        const clipStartSample = clip.startSample;
+        const clipEndSample = clipStartSample + clip.durationSamples;
+        if (clipStartSample <= newSample && clipEndSample > newSample) {
+          const offsetIntoClipSamples = newSample - clipStartSample;
+          const offsetSamples = clip.offsetSamples + offsetIntoClipSamples;
+          let durationSamples = clipEndSample - newSample;
+          if (this._loopEnabled && newSample + durationSamples > this._loopEndSamples) {
+            durationSamples = this._loopEndSamples - newSample;
+          }
+          if (durationSamples <= 0) continue;
+          const fadeOutDurationSamples = clip.fadeOut ? clip.fadeOut.duration ?? 0 : 0;
           this.consume({
             trackId,
             clipId: clip.id,
             audioBuffer: clip.audioBuffer,
-            transportTime: newTime,
-            offset,
-            duration,
+            tick: newTick,
+            startSample: newSample,
+            offsetSamples,
+            durationSamples,
             gain: clip.gain,
-            fadeInDuration: 0,
-            fadeOutDuration
+            fadeInDurationSamples: 0,
+            fadeOutDurationSamples
           });
         }
       }
@@ -720,31 +942,29 @@ var MetronomePlayer = class {
     this._accentBuffer = accent;
     this._normalBuffer = normal;
   }
-  generate(fromTime, toTime) {
+  generate(fromTick, toTick) {
     if (!this._enabled || !this._accentBuffer || !this._normalBuffer) {
       return [];
     }
     const events = [];
-    const fromTicks = this._tempoMap.secondsToTicks(fromTime);
-    const toTicks = this._tempoMap.secondsToTicks(toTime);
-    let entry = this._meterMap.getEntryAt(fromTicks);
-    let beatSize = this._meterMap.ticksPerBeat(fromTicks);
-    const tickIntoSection = fromTicks - entry.tick;
+    let entry = this._meterMap.getEntryAt(fromTick);
+    let beatSize = this._meterMap.ticksPerBeat(fromTick);
+    const tickIntoSection = fromTick - entry.tick;
     let tick = entry.tick + Math.ceil(tickIntoSection / beatSize) * beatSize;
-    while (tick < toTicks) {
-      const currentEntry = this._meterMap.getEntryAt(tick);
+    while (tick < toTick) {
+      const tickPos = tick;
+      const currentEntry = this._meterMap.getEntryAt(tickPos);
       if (currentEntry.tick !== entry.tick) {
         entry = currentEntry;
-        beatSize = this._meterMap.ticksPerBeat(tick);
+        beatSize = this._meterMap.ticksPerBeat(tickPos);
       }
-      const isAccent = this._meterMap.isBarBoundary(tick);
-      const transportTime = this._tempoMap.ticksToSeconds(tick);
+      const isAccent = this._meterMap.isBarBoundary(tickPos);
       events.push({
-        transportTime,
+        tick: tickPos,
         isAccent,
         buffer: isAccent ? this._accentBuffer : this._normalBuffer
       });
-      beatSize = this._meterMap.ticksPerBeat(tick);
+      beatSize = this._meterMap.ticksPerBeat(tickPos);
       tick += beatSize;
     }
     return events;
@@ -765,10 +985,10 @@ var MetronomePlayer = class {
         );
       }
     });
-    source.start(this._toAudioTime(event.transportTime));
+    const transportTime = this._tempoMap.ticksToSeconds(event.tick);
+    source.start(this._toAudioTime(transportTime));
   }
-  onPositionJump(_newTime) {
-    this.silence();
+  onPositionJump(_newTick) {
   }
   silence() {
     for (const source of this._activeSources) {
@@ -801,6 +1021,9 @@ var Transport = class _Transport {
     this._soloedTrackIds = /* @__PURE__ */ new Set();
     this._mutedTrackIds = /* @__PURE__ */ new Set();
     this._playing = false;
+    this._loopEnabled = false;
+    this._loopStartTick = 0;
+    this._loopStartSeconds = 0;
     this._listeners = /* @__PURE__ */ new Map();
     this._audioContext = audioContext;
     const sampleRate = options.sampleRate ?? audioContext.sampleRate;
@@ -811,15 +1034,17 @@ var Transport = class _Transport {
     const lookahead = options.schedulerLookahead ?? 0.2;
     _Transport._validateOptions(sampleRate, ppqn, tempo, numerator, denominator, lookahead);
     this._clock = new Clock(audioContext);
-    this._scheduler = new Scheduler({
-      lookahead,
-      onLoop: (loopStartTime) => {
-        this._clock.seekTo(loopStartTime);
-      }
-    });
     this._sampleTimeline = new SampleTimeline(sampleRate);
     this._meterMap = new MeterMap(ppqn, numerator, denominator);
     this._tempoMap = new TempoMap(ppqn, tempo);
+    this._scheduler = new Scheduler(this._tempoMap, {
+      lookahead,
+      onLoop: (loopStartSeconds, loopEndSeconds, currentTimeSeconds) => {
+        const timeToBoundary = loopEndSeconds - currentTimeSeconds;
+        this._clock.seekTo(loopStartSeconds - timeToBoundary);
+      }
+    });
+    this._sampleTimeline.setTempoMap(this._tempoMap);
     this._initAudioGraph(audioContext);
     this._timer = new Timer(() => {
       const time = this._clock.getTime();
@@ -843,7 +1068,8 @@ var Transport = class _Transport {
     this._scheduler.reset(currentTime);
     this._endTime = endTime;
     this._clock.start();
-    this._clipPlayer.onPositionJump(currentTime);
+    const currentTick = this._tempoMap.secondsToTicks(currentTime);
+    this._clipPlayer.onPositionJump(currentTick);
     this._timer.start();
     this._playing = true;
     this._emit("play");
@@ -879,12 +1105,17 @@ var Transport = class _Transport {
     this._endTime = void 0;
     if (wasPlaying) {
       this._clock.start();
-      this._clipPlayer.onPositionJump(time);
+      const seekTick = this._tempoMap.secondsToTicks(time);
+      this._clipPlayer.onPositionJump(seekTick);
       this._timer.start();
     }
   }
   getCurrentTime() {
-    return this._clock.getTime();
+    const t = this._clock.getTime();
+    if (this._loopEnabled && t < this._loopStartSeconds) {
+      return this._loopStartSeconds;
+    }
+    return t;
   }
   isPlaying() {
     return this._playing;
@@ -1000,20 +1231,56 @@ var Transport = class _Transport {
     this._masterNode.setVolume(volume);
   }
   // --- Loop ---
-  setLoop(enabled, start, end) {
-    if (enabled && start >= end) {
+  /** Primary loop API — ticks as source of truth */
+  setLoop(enabled, startTick, endTick) {
+    if (enabled && startTick >= endTick) {
+      console.warn(
+        "[waveform-playlist] Transport.setLoop: startTick (" + startTick + ") must be less than endTick (" + endTick + ")"
+      );
+      return;
+    }
+    this._loopEnabled = enabled;
+    this._loopStartTick = startTick;
+    this._loopStartSeconds = this._tempoMap.ticksToSeconds(startTick);
+    this._scheduler.setLoop(enabled, startTick, endTick);
+    this._clipPlayer.setLoop(enabled, startTick, endTick);
+    this._emit("loop");
+  }
+  /** Convenience — converts seconds to ticks */
+  setLoopSeconds(enabled, startSec, endSec) {
+    const startTick = this._tempoMap.secondsToTicks(startSec);
+    const endTick = this._tempoMap.secondsToTicks(endSec);
+    this.setLoop(enabled, startTick, endTick);
+  }
+  /** Convenience — sets loop in samples */
+  setLoopSamples(enabled, startSample, endSample) {
+    if (enabled && (!Number.isFinite(startSample) || !Number.isFinite(endSample))) {
+      console.warn(
+        "[waveform-playlist] Transport.setLoopSamples: non-finite sample values (" + startSample + ", " + endSample + ")"
+      );
+      return;
+    }
+    if (enabled && startSample >= endSample) {
       console.warn(
-        "[waveform-playlist] Transport.setLoop: start (" + start + ") must be less than end (" + end + ")"
+        "[waveform-playlist] Transport.setLoopSamples: startSample (" + startSample + ") must be less than endSample (" + endSample + ")"
       );
       return;
     }
-    this._scheduler.setLoop(enabled, start, end);
-    this._clipPlayer.setLoop(enabled, start, end);
+    const startTick = this._sampleTimeline.samplesToTicks(startSample);
+    const endTick = this._sampleTimeline.samplesToTicks(endSample);
+    this._loopEnabled = enabled;
+    this._loopStartTick = startTick;
+    this._loopStartSeconds = this._tempoMap.ticksToSeconds(startTick);
+    this._clipPlayer.setLoopSamples(enabled, startSample, endSample);
+    this._scheduler.setLoop(enabled, startTick, endTick);
     this._emit("loop");
   }
   // --- Tempo ---
-  setTempo(bpm, atTick) {
-    this._tempoMap.setTempo(bpm, atTick);
+  setTempo(bpm, atTick, options) {
+    this._tempoMap.setTempo(bpm, atTick, options);
+    if (this._loopEnabled) {
+      this._loopStartSeconds = this._tempoMap.ticksToSeconds(this._loopStartTick);
+    }
     this._emit("tempochange");
   }
   getTempo(atTick) {
@@ -1037,6 +1304,9 @@ var Transport = class _Transport {
   }
   clearTempos() {
     this._tempoMap.clearTempos();
+    if (this._loopEnabled) {
+      this._loopStartSeconds = this._tempoMap.ticksToSeconds(this._loopStartTick);
+    }
     this._emit("tempochange");
   }
   barToTick(bar) {
@@ -1132,7 +1402,12 @@ var Transport = class _Transport {
     this._masterNode = new MasterNode(audioContext);
     this._masterNode.output.connect(audioContext.destination);
     const toAudioTime = (transportTime) => this._clock.toAudioTime(transportTime);
-    this._clipPlayer = new ClipPlayer(audioContext, this._sampleTimeline, toAudioTime);
+    this._clipPlayer = new ClipPlayer(
+      audioContext,
+      this._sampleTimeline,
+      this._tempoMap,
+      toAudioTime
+    );
     this._metronomePlayer = new MetronomePlayer(
       audioContext,
       this._tempoMap,
@@ -1235,7 +1510,7 @@ var NativePlayoutAdapter = class {
     this._transport.setTrackPan(trackId, pan);
   }
   setLoop(enabled, start, end) {
-    this._transport.setLoop(enabled, start, end);
+    this._transport.setLoopSeconds(enabled, start, end);
   }
   dispose() {
     this._transport.dispose();