@dawcore/transport 0.0.1 → 0.0.3

package/README.md

@@ -10,6 +10,7 @@ Native Web Audio transport for multi-track audio scheduling, looping, tempo, and
 - **Built-in metronome** — Beat-grid click scheduling with accent on beat 1. Just another scheduler listener.
 - **Per-track signal chain** — Native GainNode (volume) → StereoPannerNode → GainNode (mute) → effects hook → master output.
 - **Effects plugin hook** — `connectTrackOutput(trackId, node)` inserts any `AudioNode` chain (Tone.js effects, WAM plugins, native nodes).
+- **Type-safe coordinates** — Branded `Tick` and `Sample` types prevent accidentally passing seconds where ticks or samples are expected. Zero runtime cost.
 - **PlayoutAdapter bridge** — `NativePlayoutAdapter` implements the `PlayoutAdapter` interface from `@waveform-playlist/engine`.
 
 ## Installation
@@ -66,7 +67,8 @@ editor.adapterFactory = () => new NativePlayoutAdapter(audioContext);
 ```typescript
 const transport = new Transport(audioContext, {
   tempo: 120,
-  beatsPerBar: 4,
+  numerator: 4,
+  denominator: 4,
 });
 
 transport.setMetronomeEnabled(true);
@@ -74,6 +76,22 @@ transport.setMetronomeClickSounds(accentBuffer, normalBuffer);
 transport.play();
 ```
 
+### Mixed Meter
+
+```typescript
+const transport = new Transport(audioContext, { tempo: 120, numerator: 4, denominator: 4 });
+
+// Switch to 7/8 at bar 5
+transport.setMeter(7, 8, transport.barToTick(5));
+
+// Query active meter at any tick
+const { numerator, denominator } = transport.getMeter(transport.barToTick(5));
+// → { numerator: 7, denominator: 8 }
+
+transport.setMetronomeEnabled(true);
+transport.play();
+```
+
 ### Effects
 
 ```typescript
@@ -102,7 +120,8 @@ new Transport(audioContext: AudioContext, options?: TransportOptions)
 | `sampleRate` | `audioContext.sampleRate` | Sample rate for timeline conversions |
 | `ppqn` | `960` | Ticks per quarter note |
 | `tempo` | `120` | Initial tempo in BPM |
-| `beatsPerBar` | `4` | Beats per bar |
+| `numerator` | `4` | Beats per bar (time signature numerator) |
+| `denominator` | `4` | Beat unit (time signature denominator) |
 | `schedulerLookahead` | `0.2` | How far ahead to schedule (seconds) |
 
 **Playback:**
@@ -127,11 +146,19 @@ new Transport(audioContext: AudioContext, options?: TransportOptions)
 - `setMasterVolume(volume)`
 
 **Loop:**
-- `setLoop(enabled, start, end)` — Set loop region in seconds
-
-**Tempo & Metronome:**
-- `setTempo(bpm)` / `getTempo()`
-- `setBeatsPerBar(beats)`
+- `setLoop(enabled, startTick: Tick, endTick: Tick)` — Set loop region in ticks (primary API)
+- `setLoopSeconds(enabled, start, end)` — Set loop region in seconds (convenience)
+- `setLoopSamples(enabled, startSample: Sample, endSample: Sample)` — Set loop region in samples (convenience)
+
+**Tempo & Meter:**
+- `setTempo(bpm, atTick?)` / `getTempo(atTick?)`
+- `clearTempos()` — remove all tempo entries
+- `setMeter(numerator, denominator, atTick?: Tick)` / `getMeter(atTick?: Tick)`
+- `removeMeter(atTick: Tick)` / `clearMeters()`
+- `barToTick(bar): Tick` / `tickToBar(tick: Tick)`
+- `timeToTick(seconds): Tick` / `tickToTime(tick: Tick)`
+
+**Metronome:**
 - `setMetronomeEnabled(enabled)`
 - `setMetronomeClickSounds(accent, normal)`
 

package/dist/index.d.mts

@@ -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;
 }
@@ -22,14 +34,32 @@ interface TransportOptions {
     ppqn?: number;
     /** Initial tempo in BPM. Default: 120 */
     tempo?: number;
-    /** Beats per bar. Default: 4 */
-    beatsPerBar?: number;
+    /** Time signature numerator. Default: 4 */
+    numerator?: number;
+    /** Time signature denominator. Default: 4 */
+    denominator?: number;
     /** How far ahead to schedule audio, in seconds. Default: 0.2 */
     schedulerLookahead?: number;
 }
+/** Public return type for getMeter() */
+interface MeterSignature {
+    numerator: number;
+    denominator: number;
+}
+/** Storage entry for MeterMap */
+interface MeterEntry {
+    /** Tick position where this meter starts */
+    tick: Tick;
+    /** Time signature numerator (e.g., 6 in 6/8) */
+    numerator: number;
+    /** Time signature denominator (e.g., 8 in 6/8) */
+    denominator: number;
+    /** Cached cumulative bar count from tick 0 to this entry. Derived — do not set manually. */
+    readonly barAtTick: number;
+}
 interface TempoEntry {
     /** Tick position where this tempo starts */
-    tick: number;
+    tick: Tick;
     /** Beats per minute */
     bpm: number;
     /** Cached cumulative seconds up to this tick (for O(log n) lookup). Derived — do not set manually. */
@@ -40,8 +70,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 {
@@ -63,10 +95,29 @@ declare class Clock {
     isRunning(): boolean;
 }
 
+declare class TempoMap {
+    private _ppqn;
+    private _entries;
+    constructor(ppqn?: number, initialBpm?: number);
+    getTempo(atTick?: Tick): number;
+    setTempo(bpm: number, atTick?: Tick): void;
+    ticksToSeconds(ticks: Tick): number;
+    secondsToTicks(seconds: number): Tick;
+    beatsToSeconds(beats: number): number;
+    secondsToBeats(seconds: number): number;
+    clearTempos(): void;
+    private _ticksToSecondsInternal;
+    private _entryAt;
+    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;
@@ -76,12 +127,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;
 }
 
@@ -97,35 +154,43 @@ declare class Timer {
 
 declare class SampleTimeline {
     private _sampleRate;
+    private _tempoMap;
     constructor(sampleRate: number);
     get sampleRate(): number;
-    samplesToSeconds(samples: number): number;
-    secondsToSamples(seconds: number): number;
+    setTempoMap(tempoMap: TempoMap): void;
+    samplesToSeconds(samples: Sample): number;
+    secondsToSamples(seconds: number): Sample;
+    ticksToSamples(ticks: Tick): Sample;
+    samplesToTicks(samples: Sample): Tick;
 }
 
-declare class TickTimeline {
-    private _ppqn;
-    constructor(ppqn?: number);
-    get ppqn(): number;
-    ticksPerBeat(): number;
-    ticksPerBar(beatsPerBar: number): number;
-    toPosition(ticks: number, beatsPerBar: number): TransportPosition;
-    fromPosition(bar: number, beat: number, tick: number, beatsPerBar: number): number;
-}
-
-declare class TempoMap {
+declare class MeterMap {
     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;
-    private _ticksToSecondsInternal;
+    constructor(ppqn: number, numerator?: number, denominator?: number);
+    get ppqn(): number;
+    getMeter(atTick?: Tick): MeterSignature;
+    setMeter(numerator: number, denominator: number, atTick?: Tick): void;
+    removeMeter(atTick: Tick): void;
+    clearMeters(): void;
+    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: Tick): MeterEntry;
     private _entryAt;
+    private _ticksPerBarForEntry;
+    private _snapToBarBoundary;
+    private _computeBarAtTick;
     private _recomputeCache;
+    /**
+     * After changing a meter entry, re-snap downstream entries to bar boundaries
+     * of their preceding meter so barAtTick stays integer.
+     */
+    private _resnapDownstreamEntries;
+    private _validateMeter;
 }
 
 declare class MasterNode {
@@ -161,33 +226,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;
 }
@@ -199,21 +271,19 @@ interface MetronomeEvent extends SchedulerEvent {
 declare class MetronomePlayer implements SchedulerListener<MetronomeEvent> {
     private _audioContext;
     private _tempoMap;
-    private _tickTimeline;
+    private _meterMap;
     private _destination;
     private _toAudioTime;
     private _enabled;
-    private _beatsPerBar;
     private _accentBuffer;
     private _normalBuffer;
     private _activeSources;
-    constructor(audioContext: AudioContext, tempoMap: TempoMap, tickTimeline: TickTimeline, destination: AudioNode, toAudioTime: (transportTime: number) => number);
+    constructor(audioContext: AudioContext, tempoMap: TempoMap, meterMap: MeterMap, destination: AudioNode, toAudioTime: (transportTime: number) => number);
     setEnabled(enabled: boolean): void;
-    setBeatsPerBar(beats: number): 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;
 }
 
@@ -223,6 +293,7 @@ interface TransportEvents {
     stop: () => void;
     loop: () => void;
     tempochange: () => void;
+    meterchange: () => void;
 }
 type TransportEventType = keyof TransportEvents;
 declare class Transport {
@@ -231,7 +302,7 @@ declare class Transport {
     private _scheduler;
     private _timer;
     private _sampleTimeline;
-    private _tickTimeline;
+    private _meterMap;
     private _tempoMap;
     private _clipPlayer;
     private _metronomePlayer;
@@ -242,6 +313,8 @@ declare class Transport {
     private _mutedTrackIds;
     private _playing;
     private _endTime;
+    private _loopEnabled;
+    private _loopStartSeconds;
     private _listeners;
     constructor(audioContext: AudioContext, options?: TransportOptions);
     get audioContext(): AudioContext;
@@ -260,10 +333,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): void;
-    getTempo(): number;
-    setBeatsPerBar(beats: 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): 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): Tick;
+    tickToBar(tick: Tick): number;
+    /** Convert transport time (seconds) to tick position, using the tempo map. */
+    timeToTick(seconds: number): Tick;
+    /** Convert tick position to transport time (seconds), using the tempo map. */
+    tickToTime(tick: Tick): number;
     setMetronomeEnabled(enabled: boolean): void;
     setMetronomeClickSounds(accent: AudioBuffer, normal: AudioBuffer): void;
     connectTrackOutput(trackId: string, node: AudioNode): void;
@@ -303,4 +391,4 @@ declare class NativePlayoutAdapter implements PlayoutAdapter {
     dispose(): void;
 }
 
-export { type ClipEvent, ClipPlayer, Clock, MasterNode, type MetronomeEvent, MetronomePlayer, NativePlayoutAdapter, SampleTimeline, Scheduler, type SchedulerEvent, type SchedulerListener, type SchedulerOptions, type TempoEntry, TempoMap, TickTimeline, 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 TempoEntry, TempoMap, type Tick, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };