@dawcore/transport 0.0.2 → 0.0.4

package/dist/index.d.ts

@@ -1,17 +1,29 @@
 import { ClipTrack } from '@waveform-playlist/core';
 import { PlayoutAdapter } from '@waveform-playlist/engine';
 
+/** Branded type for tick positions — prevents accidentally passing seconds where ticks are expected. */
+declare const __tick: unique symbol;
+type Tick = number & {
+    readonly [__tick]: never;
+};
+/** Branded type for sample counts — prevents accidentally passing seconds where samples are expected. */
+declare const __sample: unique symbol;
+type Sample = number & {
+    readonly [__sample]: never;
+};
 interface SchedulerEvent {
-    /** Transport time (elapsed seconds from timeline start) when this event should be realized */
-    transportTime: number;
+    /** Tick position (integer) on the timeline */
+    tick: Tick;
 }
 interface SchedulerListener<T extends SchedulerEvent> {
-    /** Generate events in the time window [fromTime, toTime) */
-    generate(fromTime: number, toTime: number): T[];
+    /** Generate events in the tick window [fromTick, toTick) */
+    generate(fromTick: Tick, toTick: Tick): T[];
     /** Realize an event (create audio nodes, start sources) */
     consume(event: T): void;
-    /** Position jumped (loop/seek) — stop active sources, re-schedule */
-    onPositionJump(newTime: number): void;
+    /** Position jumped (loop/seek) — listeners may stop and re-schedule as appropriate
+     *  (ClipPlayer stops sources and creates mid-clip restarts; MetronomePlayer is a no-op
+     *  since clicks are short one-shots that finish naturally) */
+    onPositionJump(newTick: Tick): void;
     /** Stop all active audio immediately */
     silence(): void;
 }
@@ -37,7 +49,7 @@ interface MeterSignature {
 /** Storage entry for MeterMap */
 interface MeterEntry {
     /** Tick position where this meter starts */
-    tick: number;
+    tick: Tick;
     /** Time signature numerator (e.g., 6 in 6/8) */
     numerator: number;
     /** Time signature denominator (e.g., 8 in 6/8) */
@@ -45,11 +57,20 @@ interface MeterEntry {
     /** Cached cumulative bar count from tick 0 to this entry. Derived — do not set manually. */
     readonly barAtTick: number;
 }
+/** How to interpolate tempo from the previous entry to this one.
+ *  'step' = instant jump (default). 'linear' = linear ramp.
+ *  { type: 'curve', slope } = Möbius-Ease curve (slope 0-1 exclusive). */
+type TempoInterpolation = 'step' | 'linear' | {
+    type: 'curve';
+    slope: number;
+};
 interface TempoEntry {
     /** Tick position where this tempo starts */
-    tick: number;
+    tick: Tick;
     /** Beats per minute */
     bpm: number;
+    /** How to arrive at this BPM from the previous entry */
+    readonly interpolation: TempoInterpolation;
     /** Cached cumulative seconds up to this tick (for O(log n) lookup). Derived — do not set manually. */
     readonly secondsAtTick: number;
 }
@@ -58,8 +79,10 @@ interface TransportPosition {
     bar: number;
     /** 1-indexed beat within bar */
     beat: number;
-    /** Sub-beat tick (0 to ppqn-1) */
-    tick: number;
+    /** Sub-beat tick remainder (0 to ppqn-1). Named subTick to avoid
+     *  collision with SchedulerEvent.tick (absolute timeline position).
+     *  Not branded Tick — a remainder within a beat, not an absolute position. */
+    subTick: number;
 }
 
 declare class Clock {
@@ -81,10 +104,62 @@ declare class Clock {
     isRunning(): boolean;
 }
 
+interface SetTempoOptions {
+    interpolation?: TempoInterpolation;
+}
+declare class TempoMap {
+    private _ppqn;
+    private _entries;
+    constructor(ppqn?: number, initialBpm?: number);
+    getTempo(atTick?: Tick): 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;
+    /** Get the interpolated BPM at a tick position */
+    private _getTempoAt;
+    private _ticksToSecondsInternal;
+    /**
+     * 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)
+     */
+    private _ticksToSecondsLinear;
+    /**
+     * 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.
+     */
+    private _secondsToTicksLinear;
+    /**
+     * 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.
+     */
+    private _ticksToSecondsCurve;
+    /**
+     * Inverse of _ticksToSecondsCurve: given seconds into a curved segment,
+     * return ticks. Uses binary search since there's no closed-form inverse.
+     */
+    private _secondsToTicksCurve;
+    private _entryIndexAt;
+    private _recomputeCache;
+}
+
 interface SchedulerOptions {
     lookahead?: number;
-    /** Called when the scheduler wraps at loopEnd — Transport uses this to seek the clock */
-    onLoop?: (loopStartTime: number) => void;
+    /** Called when the scheduler wraps at loopEnd.
+     *  Receives loopStart, loopEnd, and the currentTimeSeconds snapshot from
+     *  advance() so the Transport can compute the correct clock seek target
+     *  without re-reading the live AudioContext.currentTime. */
+    onLoop?: (loopStartSeconds: number, loopEndSeconds: number, currentTimeSeconds: number) => void;
 }
 declare class Scheduler<T extends SchedulerEvent> {
     private _lookahead;
@@ -94,12 +169,18 @@ declare class Scheduler<T extends SchedulerEvent> {
     private _loopStart;
     private _loopEnd;
     private _onLoop;
-    constructor(options?: SchedulerOptions);
+    private _tempoMap;
+    constructor(tempoMap: TempoMap, options?: SchedulerOptions);
     addListener(listener: SchedulerListener<T>): void;
     removeListener(listener: SchedulerListener<T>): void;
-    setLoop(enabled: boolean, start: number, end: number): void;
-    reset(time: number): void;
-    advance(currentTime: number): void;
+    /** Primary API — ticks as source of truth */
+    setLoop(enabled: boolean, startTick: Tick, endTick: Tick): void;
+    /** Convenience — converts seconds to ticks via TempoMap */
+    setLoopSeconds(enabled: boolean, startSec: number, endSec: number): void;
+    /** Reset scheduling cursor. Takes seconds (from Clock), converts to ticks. */
+    reset(timeSeconds: number): void;
+    /** Advance the scheduling window. Takes seconds (from Clock), converts to ticks. */
+    advance(currentTimeSeconds: number): void;
     private _generateAndConsume;
 }
 
@@ -115,26 +196,14 @@ declare class Timer {
 
 declare class SampleTimeline {
     private _sampleRate;
+    private _tempoMap;
     constructor(sampleRate: number);
     get sampleRate(): number;
-    samplesToSeconds(samples: number): number;
-    secondsToSamples(seconds: number): number;
-}
-
-declare class TempoMap {
-    private _ppqn;
-    private _entries;
-    constructor(ppqn?: number, initialBpm?: number);
-    getTempo(atTick?: number): number;
-    setTempo(bpm: number, atTick?: number): void;
-    ticksToSeconds(ticks: number): number;
-    secondsToTicks(seconds: number): number;
-    beatsToSeconds(beats: number): number;
-    secondsToBeats(seconds: number): number;
-    clearTempos(): void;
-    private _ticksToSecondsInternal;
-    private _entryAt;
-    private _recomputeCache;
+    setTempoMap(tempoMap: TempoMap): void;
+    samplesToSeconds(samples: Sample): number;
+    secondsToSamples(seconds: number): Sample;
+    ticksToSamples(ticks: Tick): Sample;
+    samplesToTicks(samples: Sample): Tick;
 }
 
 declare class MeterMap {
@@ -142,17 +211,17 @@ declare class MeterMap {
     private _entries;
     constructor(ppqn: number, numerator?: number, denominator?: number);
     get ppqn(): number;
-    getMeter(atTick?: number): MeterSignature;
-    setMeter(numerator: number, denominator: number, atTick?: number): void;
-    removeMeter(atTick: number): void;
+    getMeter(atTick?: Tick): MeterSignature;
+    setMeter(numerator: number, denominator: number, atTick?: Tick): void;
+    removeMeter(atTick: Tick): void;
     clearMeters(): void;
-    ticksPerBeat(atTick?: number): number;
-    ticksPerBar(atTick?: number): number;
-    barToTick(bar: number): number;
-    tickToBar(tick: number): number;
-    isBarBoundary(tick: number): boolean;
+    ticksPerBeat(atTick?: Tick): number;
+    ticksPerBar(atTick?: Tick): number;
+    barToTick(bar: number): Tick;
+    tickToBar(tick: Tick): number;
+    isBarBoundary(tick: Tick): boolean;
     /** Internal: get the full entry at a tick (for MetronomePlayer beat grid anchoring) */
-    getEntryAt(tick: number): MeterEntry;
+    getEntryAt(tick: Tick): MeterEntry;
     private _entryAt;
     private _ticksPerBarForEntry;
     private _snapToBarBoundary;
@@ -199,33 +268,40 @@ interface ClipEvent extends SchedulerEvent {
     trackId: string;
     clipId: string;
     audioBuffer: AudioBuffer;
-    /** Offset into the audioBuffer (seconds) */
-    offset: number;
-    /** Duration to play (seconds) */
-    duration: number;
+    /** Clip position on timeline (integer samples) */
+    startSample: Sample;
+    /** Offset into audioBuffer (integer samples) */
+    offsetSamples: Sample;
+    /** Duration to play (integer samples) */
+    durationSamples: Sample;
     /** Clip gain multiplier */
     gain: number;
-    /** Fade in duration in seconds */
-    fadeInDuration: number;
-    /** Fade out duration in seconds */
-    fadeOutDuration: number;
+    /** Fade in duration (integer samples) */
+    fadeInDurationSamples: Sample;
+    /** Fade out duration (integer samples) */
+    fadeOutDurationSamples: Sample;
 }
 declare class ClipPlayer implements SchedulerListener<ClipEvent> {
     private _audioContext;
     private _sampleTimeline;
+    private _tempoMap;
     private _toAudioTime;
     private _tracks;
     private _trackNodes;
     private _activeSources;
     private _loopEnabled;
-    private _loopEnd;
-    constructor(audioContext: AudioContext, sampleTimeline: SampleTimeline, toAudioTime: (transportTime: number) => number);
+    private _loopEndSamples;
+    constructor(audioContext: AudioContext, sampleTimeline: SampleTimeline, tempoMap: TempoMap, toAudioTime: (transportTime: number) => number);
     setTracks(tracks: ClipTrack[], trackNodes: Map<string, TrackNode>): void;
-    setLoop(enabled: boolean, _start: number, end: number): void;
+    /** 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: boolean, _startTick: Tick, endTick: Tick): void;
+    /** Set loop region using samples directly */
+    setLoopSamples(enabled: boolean, _startSample: Sample, endSample: Sample): void;
     updateTrack(trackId: string, track: ClipTrack): void;
-    generate(fromTime: number, toTime: number): ClipEvent[];
+    generate(fromTick: Tick, toTick: Tick): ClipEvent[];
     consume(event: ClipEvent): void;
-    onPositionJump(newTime: number): void;
+    onPositionJump(newTick: Tick): void;
     silence(): void;
     private _silenceTrack;
 }
@@ -247,9 +323,9 @@ declare class MetronomePlayer implements SchedulerListener<MetronomeEvent> {
     constructor(audioContext: AudioContext, tempoMap: TempoMap, meterMap: MeterMap, destination: AudioNode, toAudioTime: (transportTime: number) => number);
     setEnabled(enabled: boolean): void;
     setClickSounds(accent: AudioBuffer, normal: AudioBuffer): void;
-    generate(fromTime: number, toTime: number): MetronomeEvent[];
+    generate(fromTick: Tick, toTick: Tick): MetronomeEvent[];
     consume(event: MetronomeEvent): void;
-    onPositionJump(_newTime: number): void;
+    onPositionJump(_newTick: Tick): void;
     silence(): void;
 }
 
@@ -279,6 +355,9 @@ declare class Transport {
     private _mutedTrackIds;
     private _playing;
     private _endTime;
+    private _loopEnabled;
+    private _loopStartTick;
+    private _loopStartSeconds;
     private _listeners;
     constructor(audioContext: AudioContext, options?: TransportOptions);
     get audioContext(): AudioContext;
@@ -297,20 +376,25 @@ declare class Transport {
     setTrackMute(trackId: string, muted: boolean): void;
     setTrackSolo(trackId: string, soloed: boolean): void;
     setMasterVolume(volume: number): void;
-    setLoop(enabled: boolean, start: number, end: number): void;
-    setTempo(bpm: number, atTick?: number): void;
-    getTempo(atTick?: number): number;
-    setMeter(numerator: number, denominator: number, atTick?: number): void;
-    getMeter(atTick?: number): MeterSignature;
-    removeMeter(atTick: number): void;
+    /** Primary loop API — ticks as source of truth */
+    setLoop(enabled: boolean, startTick: Tick, endTick: Tick): void;
+    /** Convenience — converts seconds to ticks */
+    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;
+    getTempo(atTick?: Tick): number;
+    setMeter(numerator: number, denominator: number, atTick?: Tick): void;
+    getMeter(atTick?: Tick): MeterSignature;
+    removeMeter(atTick: Tick): void;
     clearMeters(): void;
     clearTempos(): void;
-    barToTick(bar: number): number;
-    tickToBar(tick: number): number;
+    barToTick(bar: number): Tick;
+    tickToBar(tick: Tick): number;
     /** Convert transport time (seconds) to tick position, using the tempo map. */
-    timeToTick(seconds: number): number;
+    timeToTick(seconds: number): Tick;
     /** Convert tick position to transport time (seconds), using the tempo map. */
-    tickToTime(tick: number): number;
+    tickToTime(tick: Tick): number;
     setMetronomeEnabled(enabled: boolean): void;
     setMetronomeClickSounds(accent: AudioBuffer, normal: AudioBuffer): void;
     connectTrackOutput(trackId: string, node: AudioNode): void;
@@ -350,4 +434,4 @@ declare class NativePlayoutAdapter implements PlayoutAdapter {
     dispose(): void;
 }
 
-export { type ClipEvent, ClipPlayer, Clock, MasterNode, type MeterEntry, MeterMap, type MeterSignature, type MetronomeEvent, MetronomePlayer, NativePlayoutAdapter, SampleTimeline, Scheduler, type SchedulerEvent, type SchedulerListener, type SchedulerOptions, type TempoEntry, TempoMap, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };
+export { type ClipEvent, ClipPlayer, Clock, MasterNode, type MeterEntry, MeterMap, type MeterSignature, type MetronomeEvent, MetronomePlayer, NativePlayoutAdapter, type Sample, SampleTimeline, Scheduler, type SchedulerEvent, type SchedulerListener, type SchedulerOptions, type SetTempoOptions, type TempoEntry, type TempoInterpolation, TempoMap, type Tick, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };