Initial Commit

packages/media/audio/audio-transport/src/tick-source/tick-source.md

@@ -0,0 +1,67 @@
+# TickSource
+
+The `TickSource` class converts between audio time (seconds) and musical ticks, integrating tempo curves for sample-accurate scheduling.
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`TickSource` is the mathematical engine behind `Transport`. It translates wall-clock seconds into musical ticks and back, accounting for tempo ramps and anchors. The integration is exact for constant, linear, and exponential tempo segments, ensuring that `getTicksAtTime` and `getTimeOfTick` remain mutual inverses within floating-point tolerance.
+
+## Features
+
+- Exact inverse conversions under constant tempo
+- Integration of linear and exponential tempo ramps
+- `forEachTickBetween` for sample-accurate tick iteration
+- `setTicksAtTime` for anchoring the counter
+- Start, stop, and pause lifecycle
+- No wall-clock reads — all methods take explicit times
+
+## Usage: Basic
+
+```ts
+import { TickSource, Signal } from "@suaveplan/audio-transport";
+
+const ts = new TickSource({ ppq: 192, bpm: new Signal({ initialValue: 120 }) });
+ts.start(0);
+const ticks = ts.getTicksAtTime(1); // 384
+```
+
+## Usage: Advanced
+
+```ts
+const bpm = new Signal({ initialValue: 120 });
+bpm.linearRampToValueAtTime(240, 1);
+const ts = new TickSource({ ppq: 192, bpm });
+ts.start(0);
+ts.forEachTickBetween(0, 1, (time, tick) => {
+    console.log("tick", tick, "at", time);
+});
+```
+
+## API Reference
+
+### Constructor
+
+`new TickSource(options?)`
+
+### Properties
+
+- `ppq` — pulses per quarter note
+- `bpm` — `SignalLike` tempo curve
+
+### Methods
+
+- `getTicksAtTime(time)` — ticks at audio time
+- `getTimeOfTick(tick, before?)` — audio time of tick
+- `setTicksAtTime(ticks, time)` — anchor counter
+- `start(time, offset?)` — begin counting
+- `stop(time)` — stop counting
+- `pause(time)` — pause counting
+- `forEachTickBetween(start, end, callback)` — iterate ticks
+
+## Implementation Notes
+
+Tick integration uses closed-form integrals for constant, linear, and exponential tempo segments. `getTimeOfTick` uses binary search over the integrated curve. The `forEachTickBetween` method guarantees no duplicate or skipped ticks across consecutive windows. The source maintains an internal `_running` flag and `_offsetTicks` value so that start, stop, and pause operations preserve the accumulated tick count correctly.