@dawcore/transport 0.0.1 → 0.0.3

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: non-finite tick values (" + startTick + ", " + endTick + ")"
+      );
+      return;
+    }
+    if (enabled && startTick >= endTick) {
       console.warn(
-        "[waveform-playlist] Scheduler.setLoop: start (" + start + ") must be less than end (" + end + ")"
+        "[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,44 +181,36 @@ 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);
   }
-};
-
-// src/timeline/tick-timeline.ts
-var TickTimeline = class {
-  constructor(ppqn = 960) {
-    this._ppqn = ppqn;
-  }
-  get ppqn() {
-    return this._ppqn;
-  }
-  ticksPerBeat() {
-    return this._ppqn;
-  }
-  ticksPerBar(beatsPerBar) {
-    return this._ppqn * beatsPerBar;
-  }
-  toPosition(ticks, beatsPerBar) {
-    const ticksPerBar = this.ticksPerBar(beatsPerBar);
-    const bar = Math.floor(ticks / ticksPerBar) + 1;
-    const remaining = ticks % ticksPerBar;
-    const beat = Math.floor(remaining / this._ppqn) + 1;
-    const tick = remaining % this._ppqn;
-    return { bar, beat, tick };
+  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);
   }
-  fromPosition(bar, beat, tick, beatsPerBar) {
-    const ticksPerBar = this.ticksPerBar(beatsPerBar);
-    return (bar - 1) * ticksPerBar + (beat - 1) * this._ppqn + tick;
+  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);
   }
 };
 
@@ -244,7 +258,7 @@ var TempoMap = class {
     const entry = this._entries[lo];
     const secondsIntoSegment = seconds - entry.secondsAtTick;
     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);
@@ -252,6 +266,10 @@ var TempoMap = class {
   secondsToBeats(seconds) {
     return this.secondsToTicks(seconds) / this._ppqn;
   }
+  clearTempos() {
+    const first = this._entries[0];
+    this._entries = [{ tick: 0, bpm: first.bpm, secondsAtTick: 0 }];
+  }
   _ticksToSecondsInternal(ticks) {
     const entry = this._entryAt(ticks);
     const ticksIntoSegment = ticks - entry.tick;
@@ -284,6 +302,179 @@ var TempoMap = class {
   }
 };
 
+// src/timeline/meter-map.ts
+function isPowerOf2(n) {
+  return n > 0 && (n & n - 1) === 0;
+}
+var MeterMap = class {
+  constructor(ppqn, numerator = 4, denominator = 4) {
+    this._ppqn = ppqn;
+    this._entries = [{ tick: 0, numerator, denominator, barAtTick: 0 }];
+  }
+  get ppqn() {
+    return this._ppqn;
+  }
+  getMeter(atTick = 0) {
+    const entry = this._entryAt(atTick);
+    return { numerator: entry.numerator, denominator: entry.denominator };
+  }
+  setMeter(numerator, denominator, atTick = 0) {
+    this._validateMeter(numerator, denominator);
+    if (atTick < 0) {
+      throw new Error("[waveform-playlist] MeterMap: atTick must be non-negative, got " + atTick);
+    }
+    if (atTick === 0) {
+      this._entries[0] = { ...this._entries[0], numerator, denominator };
+      this._resnapDownstreamEntries(0);
+      this._recomputeCache(0);
+      return;
+    }
+    const snapped = this._snapToBarBoundary(atTick);
+    if (snapped !== atTick) {
+      console.warn(
+        "[waveform-playlist] MeterMap.setMeter: tick " + atTick + " is not on a bar boundary, snapped to " + snapped
+      );
+    }
+    let i = this._entries.length - 1;
+    while (i > 0 && this._entries[i].tick > snapped) i--;
+    if (this._entries[i].tick === snapped) {
+      this._entries[i] = { ...this._entries[i], numerator, denominator };
+    } else {
+      const barAtTick = this._computeBarAtTick(snapped);
+      this._entries.splice(i + 1, 0, { tick: snapped, numerator, denominator, barAtTick });
+      i = i + 1;
+    }
+    this._resnapDownstreamEntries(i);
+    this._recomputeCache(i);
+  }
+  removeMeter(atTick) {
+    if (atTick === 0) {
+      throw new Error("[waveform-playlist] MeterMap: cannot remove meter at tick 0");
+    }
+    const idx = this._entries.findIndex((e) => e.tick === atTick);
+    if (idx > 0) {
+      this._entries.splice(idx, 1);
+      this._recomputeCache(idx);
+    } else if (idx === -1) {
+      console.warn("[waveform-playlist] MeterMap.removeMeter: no entry at tick " + atTick);
+    }
+  }
+  clearMeters() {
+    const first = this._entries[0];
+    this._entries = [{ ...first, barAtTick: 0 }];
+  }
+  ticksPerBeat(atTick = 0) {
+    const entry = this._entryAt(atTick);
+    return this._ppqn * (4 / entry.denominator);
+  }
+  ticksPerBar(atTick = 0) {
+    const entry = this._entryAt(atTick);
+    return entry.numerator * this._ppqn * (4 / entry.denominator);
+  }
+  barToTick(bar) {
+    if (bar < 1) {
+      throw new Error("[waveform-playlist] MeterMap: bar must be >= 1, got " + bar);
+    }
+    const targetBar = bar - 1;
+    for (let i = 0; i < this._entries.length; i++) {
+      const nextBar = i < this._entries.length - 1 ? this._entries[i + 1].barAtTick : Infinity;
+      if (targetBar < nextBar) {
+        const barsInto = targetBar - this._entries[i].barAtTick;
+        const tpb = this._ticksPerBarForEntry(this._entries[i]);
+        return this._entries[i].tick + barsInto * tpb;
+      }
+    }
+    return 0;
+  }
+  tickToBar(tick) {
+    const entry = this._entryAt(tick);
+    const ticksInto = tick - entry.tick;
+    const tpb = this._ticksPerBarForEntry(entry);
+    return entry.barAtTick + Math.floor(ticksInto / tpb) + 1;
+  }
+  isBarBoundary(tick) {
+    const entry = this._entryAt(tick);
+    const ticksInto = tick - entry.tick;
+    const tpb = this._ticksPerBarForEntry(entry);
+    return ticksInto % tpb === 0;
+  }
+  /** Internal: get the full entry at a tick (for MetronomePlayer beat grid anchoring) */
+  getEntryAt(tick) {
+    return this._entryAt(tick);
+  }
+  _entryAt(tick) {
+    let lo = 0;
+    let hi = this._entries.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if (this._entries[mid].tick <= tick) {
+        lo = mid;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    return this._entries[lo];
+  }
+  _ticksPerBarForEntry(entry) {
+    return entry.numerator * this._ppqn * (4 / entry.denominator);
+  }
+  _snapToBarBoundary(atTick) {
+    const entry = this._entryAt(atTick);
+    const tpb = this._ticksPerBarForEntry(entry);
+    const ticksInto = atTick - entry.tick;
+    if (ticksInto % tpb === 0) return atTick;
+    return entry.tick + Math.ceil(ticksInto / tpb) * tpb;
+  }
+  _computeBarAtTick(tick) {
+    const entry = this._entryAt(tick);
+    const ticksInto = tick - entry.tick;
+    const tpb = this._ticksPerBarForEntry(entry);
+    return entry.barAtTick + ticksInto / tpb;
+  }
+  _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 tpb = this._ticksPerBarForEntry(prev);
+      this._entries[i] = {
+        ...this._entries[i],
+        barAtTick: prev.barAtTick + tickDelta / tpb
+      };
+    }
+  }
+  /**
+   * After changing a meter entry, re-snap downstream entries to bar boundaries
+   * of their preceding meter so barAtTick stays integer.
+   */
+  _resnapDownstreamEntries(fromIndex) {
+    for (let i = Math.max(1, fromIndex + 1); i < this._entries.length; i++) {
+      const prev = this._entries[i - 1];
+      const tpb = this._ticksPerBarForEntry(prev);
+      const tick = this._entries[i].tick;
+      const ticksIntoPrev = tick - prev.tick;
+      if (ticksIntoPrev % tpb !== 0) {
+        const snapped = prev.tick + Math.ceil(ticksIntoPrev / tpb) * tpb;
+        console.warn(
+          "[waveform-playlist] MeterMap: meter change moved entry from tick " + tick + " to " + snapped + " (bar boundary alignment)"
+        );
+        this._entries[i] = { ...this._entries[i], tick: snapped };
+      }
+    }
+  }
+  _validateMeter(numerator, denominator) {
+    if (!Number.isInteger(numerator) || numerator < 1 || numerator > 32) {
+      throw new Error(
+        "[waveform-playlist] MeterMap: numerator must be an integer 1-32, got " + numerator
+      );
+    }
+    if (!isPowerOf2(denominator) || denominator > 32) {
+      throw new Error(
+        "[waveform-playlist] MeterMap: denominator must be a power of 2 (1-32), got " + denominator
+      );
+    }
+  }
+};
+
 // src/audio/master-node.ts
 var MasterNode = class {
   constructor(audioContext) {
@@ -369,14 +560,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) {
@@ -386,41 +578,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
         });
       }
     }
@@ -434,18 +635,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;
     }
@@ -454,9 +662,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);
@@ -472,33 +680,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
           });
         }
       }
@@ -550,15 +762,14 @@ var ClipPlayer = class {
 
 // src/audio/metronome-player.ts
 var MetronomePlayer = class {
-  constructor(audioContext, tempoMap, tickTimeline, destination, toAudioTime) {
+  constructor(audioContext, tempoMap, meterMap, destination, toAudioTime) {
     this._enabled = false;
-    this._beatsPerBar = 4;
     this._accentBuffer = null;
     this._normalBuffer = null;
     this._activeSources = /* @__PURE__ */ new Set();
     this._audioContext = audioContext;
     this._tempoMap = tempoMap;
-    this._tickTimeline = tickTimeline;
+    this._meterMap = meterMap;
     this._destination = destination;
     this._toAudioTime = toAudioTime;
   }
@@ -568,31 +779,34 @@ var MetronomePlayer = class {
       this.silence();
     }
   }
-  setBeatsPerBar(beats) {
-    this._beatsPerBar = beats;
-  }
   setClickSounds(accent, normal) {
     this._accentBuffer = accent;
     this._normalBuffer = normal;
   }
-  generate(fromTime, toTime) {
+  generate(fromTick, toTick) {
     if (!this._enabled || !this._accentBuffer || !this._normalBuffer) {
       return [];
     }
     const events = [];
-    const ppqn = this._tickTimeline.ppqn;
-    const fromTicks = this._tempoMap.secondsToTicks(fromTime);
-    const toTicks = this._tempoMap.secondsToTicks(toTime);
-    const firstBeatTick = Math.ceil(fromTicks / ppqn) * ppqn;
-    for (let tick = firstBeatTick; tick < toTicks; tick += ppqn) {
-      const transportTime = this._tempoMap.ticksToSeconds(tick);
-      const ticksPerBar = this._tickTimeline.ticksPerBar(this._beatsPerBar);
-      const isAccent = tick % ticksPerBar === 0;
+    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 < toTick) {
+      const tickPos = tick;
+      const currentEntry = this._meterMap.getEntryAt(tickPos);
+      if (currentEntry.tick !== entry.tick) {
+        entry = currentEntry;
+        beatSize = this._meterMap.ticksPerBeat(tickPos);
+      }
+      const isAccent = this._meterMap.isBarBoundary(tickPos);
       events.push({
-        transportTime,
+        tick: tickPos,
         isAccent,
         buffer: isAccent ? this._accentBuffer : this._normalBuffer
       });
+      beatSize = this._meterMap.ticksPerBeat(tickPos);
+      tick += beatSize;
     }
     return events;
   }
@@ -612,10 +826,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) {
@@ -648,25 +862,30 @@ var Transport = class _Transport {
     this._soloedTrackIds = /* @__PURE__ */ new Set();
     this._mutedTrackIds = /* @__PURE__ */ new Set();
     this._playing = false;
+    this._loopEnabled = false;
+    this._loopStartSeconds = 0;
     this._listeners = /* @__PURE__ */ new Map();
     this._audioContext = audioContext;
     const sampleRate = options.sampleRate ?? audioContext.sampleRate;
     const ppqn = options.ppqn ?? 960;
     const tempo = options.tempo ?? 120;
-    const beatsPerBar = options.beatsPerBar ?? 4;
+    const numerator = options.numerator ?? 4;
+    const denominator = options.denominator ?? 4;
     const lookahead = options.schedulerLookahead ?? 0.2;
-    _Transport._validateOptions(sampleRate, ppqn, tempo, beatsPerBar, lookahead);
+    _Transport._validateOptions(sampleRate, ppqn, tempo, numerator, denominator, lookahead);
     this._clock = new Clock(audioContext);
-    this._scheduler = new Scheduler({
+    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: (loopStartTime) => {
-        this._clock.seekTo(loopStartTime);
+      onLoop: (loopStartSeconds, loopEndSeconds, currentTimeSeconds) => {
+        const timeToBoundary = loopEndSeconds - currentTimeSeconds;
+        this._clock.seekTo(loopStartSeconds - timeToBoundary);
       }
     });
-    this._sampleTimeline = new SampleTimeline(sampleRate);
-    this._tickTimeline = new TickTimeline(ppqn);
-    this._tempoMap = new TempoMap(ppqn, tempo);
-    this._initAudioGraph(audioContext, beatsPerBar);
+    this._sampleTimeline.setTempoMap(this._tempoMap);
+    this._initAudioGraph(audioContext);
     this._timer = new Timer(() => {
       const time = this._clock.getTime();
       if (this._endTime !== void 0 && time >= this._endTime) {
@@ -689,7 +908,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");
@@ -725,12 +945,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;
@@ -846,27 +1071,89 @@ 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._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._loopStartSeconds = this._tempoMap.ticksToSeconds(startTick);
+    this._clipPlayer.setLoopSamples(enabled, startSample, endSample);
+    this._scheduler.setLoop(enabled, startTick, endTick);
     this._emit("loop");
   }
   // --- Tempo ---
-  setTempo(bpm) {
-    this._tempoMap.setTempo(bpm);
+  setTempo(bpm, atTick) {
+    this._tempoMap.setTempo(bpm, atTick);
+    this._emit("tempochange");
+  }
+  getTempo(atTick) {
+    return this._tempoMap.getTempo(atTick);
+  }
+  // --- Meter ---
+  setMeter(numerator, denominator, atTick) {
+    this._meterMap.setMeter(numerator, denominator, atTick);
+    this._emit("meterchange");
+  }
+  getMeter(atTick) {
+    return this._meterMap.getMeter(atTick);
+  }
+  removeMeter(atTick) {
+    this._meterMap.removeMeter(atTick);
+    this._emit("meterchange");
+  }
+  clearMeters() {
+    this._meterMap.clearMeters();
+    this._emit("meterchange");
+  }
+  clearTempos() {
+    this._tempoMap.clearTempos();
     this._emit("tempochange");
   }
-  getTempo() {
-    return this._tempoMap.getTempo();
+  barToTick(bar) {
+    return this._meterMap.barToTick(bar);
   }
-  setBeatsPerBar(beats) {
-    this._metronomePlayer.setBeatsPerBar(beats);
+  tickToBar(tick) {
+    return this._meterMap.tickToBar(tick);
+  }
+  /** Convert transport time (seconds) to tick position, using the tempo map. */
+  timeToTick(seconds) {
+    return this._tempoMap.secondsToTicks(seconds);
+  }
+  /** Convert tick position to transport time (seconds), using the tempo map. */
+  tickToTime(tick) {
+    return this._tempoMap.ticksToSeconds(tick);
   }
   // --- Metronome ---
   setMetronomeEnabled(enabled) {
@@ -913,7 +1200,7 @@ var Transport = class _Transport {
     this._listeners.clear();
   }
   // --- Private ---
-  static _validateOptions(sampleRate, ppqn, tempo, beatsPerBar, lookahead) {
+  static _validateOptions(sampleRate, ppqn, tempo, numerator, denominator, lookahead) {
     if (sampleRate <= 0) {
       throw new Error(
         "[waveform-playlist] Transport: sampleRate must be positive, got " + sampleRate
@@ -927,9 +1214,14 @@ var Transport = class _Transport {
     if (tempo <= 0) {
       throw new Error("[waveform-playlist] Transport: tempo must be positive, got " + tempo);
     }
-    if (beatsPerBar <= 0 || !Number.isInteger(beatsPerBar)) {
+    if (!Number.isInteger(numerator) || numerator < 1 || numerator > 32) {
+      throw new Error(
+        "[waveform-playlist] Transport: numerator must be an integer 1-32, got " + numerator
+      );
+    }
+    if (denominator <= 0 || (denominator & denominator - 1) !== 0 || denominator > 32) {
       throw new Error(
-        "[waveform-playlist] Transport: beatsPerBar must be a positive integer, got " + beatsPerBar
+        "[waveform-playlist] Transport: denominator must be a power of 2 (1-32), got " + denominator
       );
     }
     if (lookahead <= 0) {
@@ -938,19 +1230,23 @@ var Transport = class _Transport {
       );
     }
   }
-  _initAudioGraph(audioContext, beatsPerBar) {
+  _initAudioGraph(audioContext) {
     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,
-      this._tickTimeline,
+      this._meterMap,
       this._masterNode.input,
       toAudioTime
     );
-    this._metronomePlayer.setBeatsPerBar(beatsPerBar);
     this._scheduler.addListener(this._clipPlayer);
     this._scheduler.addListener(this._metronomePlayer);
   }
@@ -1046,7 +1342,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();
@@ -1056,12 +1352,12 @@ export {
   ClipPlayer,
   Clock,
   MasterNode,
+  MeterMap,
   MetronomePlayer,
   NativePlayoutAdapter,
   SampleTimeline,
   Scheduler,
   TempoMap,
-  TickTimeline,
   Timer,
   TrackNode,
   Transport