@dawcore/transport 0.0.1 → 0.0.2

package/README.md

@@ -66,7 +66,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 +75,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 +119,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:**
@@ -129,9 +147,14 @@ new Transport(audioContext: AudioContext, options?: TransportOptions)
 **Loop:**
 - `setLoop(enabled, start, end)` — Set loop region in seconds
 
-**Tempo & Metronome:**
-- `setTempo(bpm)` / `getTempo()`
-- `setBeatsPerBar(beats)`
+**Tempo & Meter:**
+- `setTempo(bpm, atTick?)` / `getTempo(atTick?)`
+- `clearTempos()` — remove all tempo entries
+- `setMeter(numerator, denominator, atTick?)` / `getMeter(atTick?)`
+- `removeMeter(atTick)` / `clearMeters()`
+- `barToTick(bar)` / `tickToBar(tick)`
+
+**Metronome:**
 - `setMetronomeEnabled(enabled)`
 - `setMetronomeClickSounds(accent, normal)`
 

package/dist/index.d.mts

@@ -22,11 +22,29 @@ 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: number;
+    /** 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;
@@ -103,16 +121,6 @@ declare class SampleTimeline {
     secondsToSamples(seconds: number): number;
 }
 
-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 {
     private _ppqn;
     private _entries;
@@ -123,11 +131,41 @@ declare class TempoMap {
     secondsToTicks(seconds: number): number;
     beatsToSeconds(beats: number): number;
     secondsToBeats(seconds: number): number;
+    clearTempos(): void;
     private _ticksToSecondsInternal;
     private _entryAt;
     private _recomputeCache;
 }
 
+declare class MeterMap {
+    private _ppqn;
+    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;
+    clearMeters(): void;
+    ticksPerBeat(atTick?: number): number;
+    ticksPerBar(atTick?: number): number;
+    barToTick(bar: number): number;
+    tickToBar(tick: number): number;
+    isBarBoundary(tick: number): boolean;
+    /** Internal: get the full entry at a tick (for MetronomePlayer beat grid anchoring) */
+    getEntryAt(tick: number): 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 {
     private _gainNode;
     constructor(audioContext: AudioContext);
@@ -199,17 +237,15 @@ 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[];
     consume(event: MetronomeEvent): void;
@@ -223,6 +259,7 @@ interface TransportEvents {
     stop: () => void;
     loop: () => void;
     tempochange: () => void;
+    meterchange: () => void;
 }
 type TransportEventType = keyof TransportEvents;
 declare class Transport {
@@ -231,7 +268,7 @@ declare class Transport {
     private _scheduler;
     private _timer;
     private _sampleTimeline;
-    private _tickTimeline;
+    private _meterMap;
     private _tempoMap;
     private _clipPlayer;
     private _metronomePlayer;
@@ -261,9 +298,19 @@ declare class Transport {
     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;
+    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;
+    clearMeters(): void;
+    clearTempos(): void;
+    barToTick(bar: number): number;
+    tickToBar(tick: number): number;
+    /** Convert transport time (seconds) to tick position, using the tempo map. */
+    timeToTick(seconds: number): number;
+    /** Convert tick position to transport time (seconds), using the tempo map. */
+    tickToTime(tick: number): number;
     setMetronomeEnabled(enabled: boolean): void;
     setMetronomeClickSounds(accent: AudioBuffer, normal: AudioBuffer): void;
     connectTrackOutput(trackId: string, node: AudioNode): void;
@@ -303,4 +350,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, SampleTimeline, Scheduler, type SchedulerEvent, type SchedulerListener, type SchedulerOptions, type TempoEntry, TempoMap, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };

package/dist/index.d.ts

@@ -22,11 +22,29 @@ 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: number;
+    /** 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;
@@ -103,16 +121,6 @@ declare class SampleTimeline {
     secondsToSamples(seconds: number): number;
 }
 
-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 {
     private _ppqn;
     private _entries;
@@ -123,11 +131,41 @@ declare class TempoMap {
     secondsToTicks(seconds: number): number;
     beatsToSeconds(beats: number): number;
     secondsToBeats(seconds: number): number;
+    clearTempos(): void;
     private _ticksToSecondsInternal;
     private _entryAt;
     private _recomputeCache;
 }
 
+declare class MeterMap {
+    private _ppqn;
+    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;
+    clearMeters(): void;
+    ticksPerBeat(atTick?: number): number;
+    ticksPerBar(atTick?: number): number;
+    barToTick(bar: number): number;
+    tickToBar(tick: number): number;
+    isBarBoundary(tick: number): boolean;
+    /** Internal: get the full entry at a tick (for MetronomePlayer beat grid anchoring) */
+    getEntryAt(tick: number): 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 {
     private _gainNode;
     constructor(audioContext: AudioContext);
@@ -199,17 +237,15 @@ 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[];
     consume(event: MetronomeEvent): void;
@@ -223,6 +259,7 @@ interface TransportEvents {
     stop: () => void;
     loop: () => void;
     tempochange: () => void;
+    meterchange: () => void;
 }
 type TransportEventType = keyof TransportEvents;
 declare class Transport {
@@ -231,7 +268,7 @@ declare class Transport {
     private _scheduler;
     private _timer;
     private _sampleTimeline;
-    private _tickTimeline;
+    private _meterMap;
     private _tempoMap;
     private _clipPlayer;
     private _metronomePlayer;
@@ -261,9 +298,19 @@ declare class Transport {
     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;
+    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;
+    clearMeters(): void;
+    clearTempos(): void;
+    barToTick(bar: number): number;
+    tickToBar(tick: number): number;
+    /** Convert transport time (seconds) to tick position, using the tempo map. */
+    timeToTick(seconds: number): number;
+    /** Convert tick position to transport time (seconds), using the tempo map. */
+    tickToTime(tick: number): number;
     setMetronomeEnabled(enabled: boolean): void;
     setMetronomeClickSounds(accent: AudioBuffer, normal: AudioBuffer): void;
     connectTrackOutput(trackId: string, node: AudioNode): void;
@@ -303,4 +350,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, SampleTimeline, Scheduler, type SchedulerEvent, type SchedulerListener, type SchedulerOptions, type TempoEntry, TempoMap, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };