@dawcore/transport 0.0.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Naomi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @dawcore/transport
+
+Native Web Audio transport for multi-track audio scheduling, looping, tempo, and metronome. Zero npm dependencies.
+
+## Features
+
+- **Native Web Audio** — No Tone.js, no `standardized-audio-context`. Direct `AudioContext` with full `sampleRate` and `latencyHint` control.
+- **Sliding window scheduler** — Schedules audio 200ms ahead via `requestAnimationFrame` for glitch-free playback.
+- **Dual timeline** — Sample-absolute positions for audio clips, PPQN tick positions for metronome/MIDI.
+- **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).
+- **PlayoutAdapter bridge** — `NativePlayoutAdapter` implements the `PlayoutAdapter` interface from `@waveform-playlist/engine`.
+
+## Installation
+
+```bash
+npm install @dawcore/transport
+```
+
+Peer dependencies:
+```bash
+npm install @waveform-playlist/core @waveform-playlist/engine
+```
+
+## Quick Start
+
+### Standalone Transport
+
+```typescript
+import { Transport } from '@dawcore/transport';
+
+const audioContext = new AudioContext({ sampleRate: 48000, latencyHint: 0 });
+const transport = new Transport(audioContext, { tempo: 120 });
+
+transport.setTracks([
+  {
+    id: 'drums',
+    name: 'Drums',
+    clips: [{ id: 'clip-1', audioBuffer: drumBuffer, startSample: 0, durationSamples: 48000, offsetSamples: 0, sampleRate: 48000, sourceDurationSamples: 48000, gain: 1 }],
+    volume: 1,
+    pan: 0,
+    muted: false,
+    soloed: false,
+  },
+]);
+
+transport.play();
+```
+
+### With PlaylistEngine (dawcore)
+
+```typescript
+import { NativePlayoutAdapter } from '@dawcore/transport';
+
+const audioContext = new AudioContext({ sampleRate: 48000 });
+const adapter = new NativePlayoutAdapter(audioContext);
+
+// Use as daw-editor's adapter factory
+const editor = document.querySelector('daw-editor');
+editor.adapterFactory = () => new NativePlayoutAdapter(audioContext);
+```
+
+### Metronome
+
+```typescript
+const transport = new Transport(audioContext, {
+  tempo: 120,
+  beatsPerBar: 4,
+});
+
+transport.setMetronomeEnabled(true);
+transport.setMetronomeClickSounds(accentBuffer, normalBuffer);
+transport.play();
+```
+
+### Effects
+
+```typescript
+// Insert any AudioNode chain between track output and master
+const reverb = audioContext.createConvolver();
+reverb.buffer = impulseResponse;
+reverb.connect(transport.audioContext.destination);
+
+transport.connectTrackOutput('vocals', reverb);
+
+// Remove effects — restores direct routing to master
+transport.disconnectTrackOutput('vocals');
+```
+
+## API
+
+### Transport
+
+```typescript
+new Transport(audioContext: AudioContext, options?: TransportOptions)
+```
+
+**TransportOptions:**
+| Option | Default | Description |
+|--------|---------|-------------|
+| `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 |
+| `schedulerLookahead` | `0.2` | How far ahead to schedule (seconds) |
+
+**Playback:**
+- `play(startTime?, endTime?)` — Start or resume playback
+- `pause()` — Pause, preserving position
+- `stop()` — Stop and reset to beginning
+- `seek(time)` — Jump to a position (works during playback)
+- `getCurrentTime()` — Current transport position in seconds
+- `isPlaying()` — Whether transport is playing
+
+**Tracks:**
+- `setTracks(tracks)` — Set all tracks (rebuilds audio graph)
+- `addTrack(track)` — Add a single track
+- `removeTrack(trackId)` — Remove a track
+- `updateTrack(trackId, track)` — Update a track's clips
+
+**Track Controls:**
+- `setTrackVolume(trackId, volume)`
+- `setTrackPan(trackId, pan)`
+- `setTrackMute(trackId, muted)`
+- `setTrackSolo(trackId, soloed)`
+- `setMasterVolume(volume)`
+
+**Loop:**
+- `setLoop(enabled, start, end)` — Set loop region in seconds
+
+**Tempo & Metronome:**
+- `setTempo(bpm)` / `getTempo()`
+- `setBeatsPerBar(beats)`
+- `setMetronomeEnabled(enabled)`
+- `setMetronomeClickSounds(accent, normal)`
+
+**Effects:**
+- `connectTrackOutput(trackId, node)` — Insert effects chain
+- `disconnectTrackOutput(trackId)` — Remove effects chain
+
+**Events:**
+- `on(event, callback)` / `off(event, callback)`
+- Events: `play`, `pause`, `stop`, `loop`, `tempochange`
+
+**Cleanup:**
+- `dispose()` — Stop playback, disconnect all nodes, remove listeners
+
+### NativePlayoutAdapter
+
+```typescript
+new NativePlayoutAdapter(audioContext: AudioContext, options?: TransportOptions)
+```
+
+Implements `PlayoutAdapter` from `@waveform-playlist/engine`. All methods delegate to the internal `Transport` instance.
+
+- `adapter.transport` — Direct access to the `Transport` for tempo, metronome, and effects APIs
+
+## Architecture
+
+See [TRANSPORT.md](./TRANSPORT.md) for the full architecture guide.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,306 @@
+import { ClipTrack } from '@waveform-playlist/core';
+import { PlayoutAdapter } from '@waveform-playlist/engine';
+
+interface SchedulerEvent {
+    /** Transport time (elapsed seconds from timeline start) when this event should be realized */
+    transportTime: number;
+}
+interface SchedulerListener<T extends SchedulerEvent> {
+    /** Generate events in the time window [fromTime, toTime) */
+    generate(fromTime: number, toTime: number): 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;
+    /** Stop all active audio immediately */
+    silence(): void;
+}
+interface TransportOptions {
+    /** Sample rate for SampleTimeline. Default: audioContext.sampleRate */
+    sampleRate?: number;
+    /** Ticks per quarter note. Default: 960 */
+    ppqn?: number;
+    /** Initial tempo in BPM. Default: 120 */
+    tempo?: number;
+    /** Beats per bar. Default: 4 */
+    beatsPerBar?: number;
+    /** How far ahead to schedule audio, in seconds. Default: 0.2 */
+    schedulerLookahead?: number;
+}
+interface TempoEntry {
+    /** Tick position where this tempo starts */
+    tick: number;
+    /** Beats per minute */
+    bpm: number;
+    /** Cached cumulative seconds up to this tick (for O(log n) lookup). Derived — do not set manually. */
+    readonly secondsAtTick: number;
+}
+interface TransportPosition {
+    /** 1-indexed bar number */
+    bar: number;
+    /** 1-indexed beat within bar */
+    beat: number;
+    /** Sub-beat tick (0 to ppqn-1) */
+    tick: number;
+}
+
+declare class Clock {
+    private _audioContext;
+    private _running;
+    private _audioTimeAtStart;
+    private _clockTimeAtStart;
+    constructor(audioContext: AudioContext);
+    start(): void;
+    stop(): void;
+    reset(): void;
+    getTime(): number;
+    seekTo(time: number): void;
+    /**
+     * Convert transport time to AudioContext.currentTime space.
+     * Used by players to schedule AudioBufferSourceNode.start(when).
+     */
+    toAudioTime(transportTime: number): number;
+    isRunning(): boolean;
+}
+
+interface SchedulerOptions {
+    lookahead?: number;
+    /** Called when the scheduler wraps at loopEnd — Transport uses this to seek the clock */
+    onLoop?: (loopStartTime: number) => void;
+}
+declare class Scheduler<T extends SchedulerEvent> {
+    private _lookahead;
+    private _rightEdge;
+    private _listeners;
+    private _loopEnabled;
+    private _loopStart;
+    private _loopEnd;
+    private _onLoop;
+    constructor(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;
+    private _generateAndConsume;
+}
+
+declare class Timer {
+    private _onTick;
+    private _rafId;
+    private _running;
+    constructor(onTick: () => void);
+    start(): void;
+    stop(): void;
+    private _scheduleFrame;
+}
+
+declare class SampleTimeline {
+    private _sampleRate;
+    constructor(sampleRate: number);
+    get sampleRate(): number;
+    samplesToSeconds(samples: number): number;
+    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;
+    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;
+    private _entryAt;
+    private _recomputeCache;
+}
+
+declare class MasterNode {
+    private _gainNode;
+    constructor(audioContext: AudioContext);
+    get input(): AudioNode;
+    get output(): AudioNode;
+    setVolume(value: number): void;
+    dispose(): void;
+}
+
+declare class TrackNode {
+    readonly id: string;
+    private _volumeNode;
+    private _panNode;
+    private _muteNode;
+    private _destination;
+    private _effectsInput;
+    constructor(id: string, audioContext: AudioContext);
+    /** Where clip sources connect */
+    get input(): GainNode;
+    /** Connect this track's output to a destination (master node) */
+    connectOutput(destination: AudioNode): void;
+    setVolume(value: number): void;
+    setPan(value: number): void;
+    setMute(muted: boolean): void;
+    connectEffects(effectsInput: AudioNode): void;
+    disconnectEffects(): void;
+    dispose(): void;
+}
+
+interface ClipEvent extends SchedulerEvent {
+    trackId: string;
+    clipId: string;
+    audioBuffer: AudioBuffer;
+    /** Offset into the audioBuffer (seconds) */
+    offset: number;
+    /** Duration to play (seconds) */
+    duration: number;
+    /** Clip gain multiplier */
+    gain: number;
+    /** Fade in duration in seconds */
+    fadeInDuration: number;
+    /** Fade out duration in seconds */
+    fadeOutDuration: number;
+}
+declare class ClipPlayer implements SchedulerListener<ClipEvent> {
+    private _audioContext;
+    private _sampleTimeline;
+    private _toAudioTime;
+    private _tracks;
+    private _trackNodes;
+    private _activeSources;
+    private _loopEnabled;
+    private _loopEnd;
+    constructor(audioContext: AudioContext, sampleTimeline: SampleTimeline, toAudioTime: (transportTime: number) => number);
+    setTracks(tracks: ClipTrack[], trackNodes: Map<string, TrackNode>): void;
+    setLoop(enabled: boolean, _start: number, end: number): void;
+    updateTrack(trackId: string, track: ClipTrack): void;
+    generate(fromTime: number, toTime: number): ClipEvent[];
+    consume(event: ClipEvent): void;
+    onPositionJump(newTime: number): void;
+    silence(): void;
+    private _silenceTrack;
+}
+
+interface MetronomeEvent extends SchedulerEvent {
+    isAccent: boolean;
+    buffer: AudioBuffer;
+}
+declare class MetronomePlayer implements SchedulerListener<MetronomeEvent> {
+    private _audioContext;
+    private _tempoMap;
+    private _tickTimeline;
+    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);
+    setEnabled(enabled: boolean): void;
+    setBeatsPerBar(beats: number): void;
+    setClickSounds(accent: AudioBuffer, normal: AudioBuffer): void;
+    generate(fromTime: number, toTime: number): MetronomeEvent[];
+    consume(event: MetronomeEvent): void;
+    onPositionJump(_newTime: number): void;
+    silence(): void;
+}
+
+interface TransportEvents {
+    play: () => void;
+    pause: () => void;
+    stop: () => void;
+    loop: () => void;
+    tempochange: () => void;
+}
+type TransportEventType = keyof TransportEvents;
+declare class Transport {
+    private _audioContext;
+    private _clock;
+    private _scheduler;
+    private _timer;
+    private _sampleTimeline;
+    private _tickTimeline;
+    private _tempoMap;
+    private _clipPlayer;
+    private _metronomePlayer;
+    private _masterNode;
+    private _trackNodes;
+    private _tracks;
+    private _soloedTrackIds;
+    private _mutedTrackIds;
+    private _playing;
+    private _endTime;
+    private _listeners;
+    constructor(audioContext: AudioContext, options?: TransportOptions);
+    get audioContext(): AudioContext;
+    play(startTime?: number, endTime?: number): void;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    getCurrentTime(): number;
+    isPlaying(): boolean;
+    setTracks(tracks: ClipTrack[]): void;
+    addTrack(track: ClipTrack): void;
+    removeTrack(trackId: string): void;
+    updateTrack(trackId: string, track: ClipTrack): void;
+    setTrackVolume(trackId: string, volume: number): void;
+    setTrackPan(trackId: string, pan: number): void;
+    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;
+    setMetronomeEnabled(enabled: boolean): void;
+    setMetronomeClickSounds(accent: AudioBuffer, normal: AudioBuffer): void;
+    connectTrackOutput(trackId: string, node: AudioNode): void;
+    disconnectTrackOutput(trackId: string): void;
+    on<K extends TransportEventType>(event: K, cb: TransportEvents[K]): void;
+    off<K extends TransportEventType>(event: K, cb: TransportEvents[K]): void;
+    dispose(): void;
+    private static _validateOptions;
+    private _initAudioGraph;
+    private _silenceAll;
+    private _applyMuteState;
+    private _emit;
+}
+
+declare class NativePlayoutAdapter implements PlayoutAdapter {
+    private _transport;
+    private _audioContext;
+    constructor(audioContext: AudioContext, options?: TransportOptions);
+    get transport(): Transport;
+    init(): Promise<void>;
+    setTracks(tracks: ClipTrack[]): void;
+    addTrack(track: ClipTrack): void;
+    removeTrack(trackId: string): void;
+    updateTrack(trackId: string, track: ClipTrack): void;
+    play(startTime: number, endTime?: number): void;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    getCurrentTime(): number;
+    isPlaying(): boolean;
+    setMasterVolume(volume: number): void;
+    setTrackVolume(trackId: string, volume: number): void;
+    setTrackMute(trackId: string, muted: boolean): void;
+    setTrackSolo(trackId: string, soloed: boolean): void;
+    setTrackPan(trackId: string, pan: number): void;
+    setLoop(enabled: boolean, start: number, end: number): void;
+    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 };