@dawcore/transport 0.0.2 → 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
@@ -145,14 +146,17 @@ new Transport(audioContext: AudioContext, options?: TransportOptions)
 - `setMasterVolume(volume)`
 
 **Loop:**
-- `setLoop(enabled, start, end)` — Set loop region in seconds
+- `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?)` / `getMeter(atTick?)`
-- `removeMeter(atTick)` / `clearMeters()`
-- `barToTick(bar)` / `tickToBar(tick)`
+- `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)`

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;
 }
@@ -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) */
@@ -47,7 +59,7 @@ interface MeterEntry {
 }
 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. */
@@ -58,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 {
@@ -81,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;
@@ -94,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;
 }
 
@@ -115,26 +154,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 +169,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 +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;
 }
@@ -247,9 +281,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 +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;
@@ -297,20 +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, 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): 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 +391,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 TempoEntry, TempoMap, type Tick, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };

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) */
@@ -47,7 +59,7 @@ interface MeterEntry {
 }
 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. */
@@ -58,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 {
@@ -81,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;
@@ -94,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;
 }
 
@@ -115,26 +154,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 +169,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 +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;
 }
@@ -247,9 +281,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 +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;
@@ -297,20 +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, 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): 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 +391,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 TempoEntry, TempoMap, type Tick, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };