@dawcore/transport 0.0.12 → 0.0.13

package/README.md

@@ -10,7 +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. Default synthesized click sounds out of the box.
 - **Count-in (pre-roll)** — Configurable bars of click sounds before playback begins. Beat-by-beat events for UI countdown.
 - **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).
+- **Effects plugin hook** — `connectTrackOutput(trackId, node)` and `connectMasterOutput(node)` insert any `AudioNode` chain (Tone.js effects, WAM plugins, native nodes) per-track or on the master bus.
 - **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`.
 
@@ -55,9 +55,12 @@ import { NativePlayoutAdapter } from '@dawcore/transport';
 const audioContext = new AudioContext({ sampleRate: 48000 });
 const adapter = new NativePlayoutAdapter(audioContext);
 
-// Use as daw-editor's adapter factory
+// Use as daw-editor's playout adapter
 const editor = document.querySelector('daw-editor');
-editor.adapterFactory = () => new NativePlayoutAdapter(audioContext);
+editor.adapter = adapter;
+
+// Transport-specific APIs stay available on your adapter reference
+adapter.transport.setMetronomeEnabled(true);
 ```
 
 ### Metronome
@@ -156,6 +159,17 @@ transport.connectTrackOutput('vocals', reverb);
 
 // Remove effects — restores direct routing to master
 transport.disconnectTrackOutput('vocals');
+
+// Master bus effects — inserted between master gain and destination
+const compressor = audioContext.createDynamicsCompressor();
+compressor.connect(audioContext.destination);
+
+transport.connectMasterOutput(compressor);
+
+// Remove master effects — restores direct routing to destination.
+// Parallel taps on transport.masterOutputNode (analyzers, recorders)
+// are unaffected by connect/disconnect.
+transport.disconnectMasterOutput();
 ```
 
 ## API
@@ -205,7 +219,8 @@ new Transport(audioContext: AudioContext, options?: TransportOptions)
 - `setLoopSamples(enabled, startSample: Sample, endSample: Sample)` — Set loop region in samples (convenience)
 
 **Tempo & Meter:**
-- `setTempo(bpm, atTick?, options?)` / `getTempo(atTick?: Tick)` — options: `{ interpolation: 'step' | 'linear' | { type: 'curve', slope } }`
+- `setTempo(bpm, atTick?, options?)` / `getTempo(atTick?: Tick)` — options: `{ interpolation: 'step' | 'linear' | { type: 'curve', slope } }`. Returns `boolean`: a defaulted `atTick` is the single-BPM convenience path and is refused (with a warning) when the tempo map has more than one entry — pass an explicit `atTick` to modify a tempo curve.
+- `removeTempo(atTick: Tick)` — remove the tempo entry at a tick (the tick-0 entry cannot be removed)
 - `clearTempos()` — remove all tempo entries
 - `setMeter(numerator, denominator, atTick?: Tick)` / `getMeter(atTick?: Tick)`
 - `removeMeter(atTick: Tick)` / `clearMeters()`
@@ -224,12 +239,16 @@ new Transport(audioContext: AudioContext, options?: TransportOptions)
 - `isCountingIn()` — whether count-in is active
 
 **Effects:**
-- `connectTrackOutput(trackId, node)` — Insert effects chain
-- `disconnectTrackOutput(trackId)` — Remove effects chain
+- `connectTrackOutput(trackId, node)` — Insert per-track effects chain
+- `disconnectTrackOutput(trackId)` — Remove per-track effects chain
+- `connectMasterOutput(node)` — Insert master bus effects chain
+- `disconnectMasterOutput()` — Remove master bus effects chain
+- `masterOutputNode` (getter) — Master gain node, for parallel taps (analyzers, recorders) that should survive chain connect/disconnect
 
 **Events:**
 - `on(event, callback)` / `off(event, callback)`
-- Events: `play`, `pause`, `stop`, `loop`, `tempochange`, `meterchange`, `countIn`, `countInEnd`
+- Events: `play`, `pause`, `stop`, `seek`, `loop`, `tempochange`, `meterchange`, `countIn`, `countInEnd`
+- `seek` payload: `{ seconds: number }`
 - `tempochange` payload: `{ bpm: number, atTick: Tick }`
 - `meterchange` payload: `{ numerator: number, denominator: number, atTick: Tick }`
 - `countIn` payload: `{ beat: number, totalBeats: number }`
@@ -245,15 +264,27 @@ 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
+- `adapter.transport` — Direct access to the `Transport` for tempo, metronome, count-in, and effects APIs
+- `adapter.ppqn` — Tick resolution, read by the engine on construction
+- `adapter.masterOutputNode` — Master gain node for parallel taps (analyzers, recorders)
+- `adapter.init()` — Resumes a suspended AudioContext and waits for the hardware pipeline to warm up (Safari needs this before clips scheduled at time 0 play on time)
+- `setTempo(bpm, atTick?)`, `setMeter(numerator, denominator, atTick?)`, `ticksToSeconds(tick)`, `secondsToTicks(seconds)` — tempo/meter surface the engine uses for tick-based timeline math
+
+## Examples
+
+[`examples/dawcore-native/`](https://github.com/naomiaro/waveform-playlist/tree/main/examples/dawcore-native) pairs this transport with the `@dawcore/components` editor: metronome, tempo automation, mixed meter, beat-map grids, effects, and recording pages (`pnpm example:dawcore-native`).
 
 ## Architecture
 
-See [TRANSPORT.md](./TRANSPORT.md) for the full architecture guide.
+See [TRANSPORT.md](https://github.com/naomiaro/waveform-playlist/blob/main/packages/transport/TRANSPORT.md) for the full architecture guide.
 
 ## How It Works
 
-See [EDUCATIONAL.md](./EDUCATIONAL.md) for an in-depth explanation of the math and timing models behind audio transport systems.
+See [EDUCATIONAL.md](https://github.com/naomiaro/waveform-playlist/blob/main/packages/transport/EDUCATIONAL.md) for an in-depth explanation of the math and timing models behind audio transport systems.
+
+## Documentation
+
+Full guides at [naomiaro.github.io/waveform-playlist](https://naomiaro.github.io/waveform-playlist/).
 
 ## License
 

package/dist/index.d.mts

@@ -281,9 +281,22 @@ declare class MeterMap {
 
 declare class MasterNode {
     private _gainNode;
+    private _destination;
+    private _effectsInput;
     constructor(audioContext: AudioContext);
     get input(): AudioNode;
     get output(): AudioNode;
+    /** Connect the master output to its final destination (audioContext.destination) */
+    connectOutput(destination: AudioNode): void;
+    /**
+     * Insert an effects chain between the master gain and the destination.
+     * Only the destination edge is severed (targeted disconnect), so parallel
+     * taps on the master output (analyzers, recorders) keep working.
+     * The caller is responsible for routing the chain's output onward.
+     */
+    connectEffects(effectsInput: AudioNode): void;
+    /** Remove the effects chain and restore direct routing to the destination */
+    disconnectEffects(): void;
     setVolume(value: number): void;
     dispose(): void;
 }
@@ -393,6 +406,9 @@ interface TransportEvents {
     pause: () => void;
     stop: () => void;
     loop: () => void;
+    seek: (event: {
+        seconds: number;
+    }) => void;
     tempochange: (event: TempoChangeEventData) => void;
     meterchange: (event: MeterChangeEventData) => void;
     countIn: (event: CountInEventData) => void;
@@ -492,6 +508,16 @@ declare class Transport {
     /** The master output AudioNode. Connect your own nodes (analyzers, recorders, etc.)
      *  in parallel. The transport already routes this to audioContext.destination. */
     get masterOutputNode(): AudioNode;
+    /**
+     * Insert an effects chain on the master bus, between the master gain and
+     * audioContext.destination. Accepts any AudioNode chain (Tone.js effects,
+     * WAM plugins, native nodes). The caller is responsible for connecting the
+     * chain's output to audioContext.destination. Calling again replaces the
+     * previous chain. Parallel taps on `masterOutputNode` are unaffected.
+     */
+    connectMasterOutput(node: AudioNode): void;
+    /** Remove the master effects chain and restore direct routing to audioContext.destination. */
+    disconnectMasterOutput(): void;
     on<K extends TransportEventType>(event: K, cb: TransportEvents[K]): void;
     off<K extends TransportEventType>(event: K, cb: TransportEvents[K]): void;
     dispose(): void;

package/dist/index.d.ts

@@ -281,9 +281,22 @@ declare class MeterMap {
 
 declare class MasterNode {
     private _gainNode;
+    private _destination;
+    private _effectsInput;
     constructor(audioContext: AudioContext);
     get input(): AudioNode;
     get output(): AudioNode;
+    /** Connect the master output to its final destination (audioContext.destination) */
+    connectOutput(destination: AudioNode): void;
+    /**
+     * Insert an effects chain between the master gain and the destination.
+     * Only the destination edge is severed (targeted disconnect), so parallel
+     * taps on the master output (analyzers, recorders) keep working.
+     * The caller is responsible for routing the chain's output onward.
+     */
+    connectEffects(effectsInput: AudioNode): void;
+    /** Remove the effects chain and restore direct routing to the destination */
+    disconnectEffects(): void;
     setVolume(value: number): void;
     dispose(): void;
 }
@@ -393,6 +406,9 @@ interface TransportEvents {
     pause: () => void;
     stop: () => void;
     loop: () => void;
+    seek: (event: {
+        seconds: number;
+    }) => void;
     tempochange: (event: TempoChangeEventData) => void;
     meterchange: (event: MeterChangeEventData) => void;
     countIn: (event: CountInEventData) => void;
@@ -492,6 +508,16 @@ declare class Transport {
     /** The master output AudioNode. Connect your own nodes (analyzers, recorders, etc.)
      *  in parallel. The transport already routes this to audioContext.destination. */
     get masterOutputNode(): AudioNode;
+    /**
+     * Insert an effects chain on the master bus, between the master gain and
+     * audioContext.destination. Accepts any AudioNode chain (Tone.js effects,
+     * WAM plugins, native nodes). The caller is responsible for connecting the
+     * chain's output to audioContext.destination. Calling again replaces the
+     * previous chain. Parallel taps on `masterOutputNode` are unaffected.
+     */
+    connectMasterOutput(node: AudioNode): void;
+    /** Remove the master effects chain and restore direct routing to audioContext.destination. */
+    disconnectMasterOutput(): void;
     on<K extends TransportEventType>(event: K, cb: TransportEvents[K]): void;
     off<K extends TransportEventType>(event: K, cb: TransportEvents[K]): void;
     dispose(): void;

package/dist/index.js

@@ -711,6 +711,8 @@ var MeterMap = class {
 // src/audio/master-node.ts
 var MasterNode = class {
   constructor(audioContext) {
+    this._destination = null;
+    this._effectsInput = null;
     this._gainNode = audioContext.createGain();
   }
   get input() {
@@ -719,6 +721,37 @@ var MasterNode = class {
   get output() {
     return this._gainNode;
   }
+  /** Connect the master output to its final destination (audioContext.destination) */
+  connectOutput(destination) {
+    this._destination = destination;
+    this._gainNode.connect(destination);
+  }
+  /**
+   * Insert an effects chain between the master gain and the destination.
+   * Only the destination edge is severed (targeted disconnect), so parallel
+   * taps on the master output (analyzers, recorders) keep working.
+   * The caller is responsible for routing the chain's output onward.
+   */
+  connectEffects(effectsInput) {
+    if (this._effectsInput) {
+      this._gainNode.disconnect(this._effectsInput);
+    } else if (this._destination) {
+      this._gainNode.disconnect(this._destination);
+    }
+    this._gainNode.connect(effectsInput);
+    this._effectsInput = effectsInput;
+  }
+  /** Remove the effects chain and restore direct routing to the destination */
+  disconnectEffects() {
+    if (!this._effectsInput) {
+      return;
+    }
+    this._gainNode.disconnect(this._effectsInput);
+    if (this._destination) {
+      this._gainNode.connect(this._destination);
+    }
+    this._effectsInput = null;
+  }
   setVolume(value) {
     this._gainNode.gain.value = value;
   }
@@ -728,6 +761,8 @@ var MasterNode = class {
     } catch (err) {
       console.warn("[waveform-playlist] MasterNode.dispose: error disconnecting: " + String(err));
     }
+    this._destination = null;
+    this._effectsInput = null;
   }
 };
 
@@ -1378,6 +1413,7 @@ var _Transport = class _Transport {
       this._clipPlayer.onPositionJump(seekTick);
       this._timer.start();
     }
+    this._emit("seek", { seconds: time });
   }
   getCurrentTime() {
     if (this._countingIn) {
@@ -1687,6 +1723,20 @@ var _Transport = class _Transport {
   get masterOutputNode() {
     return this._masterNode.output;
   }
+  /**
+   * Insert an effects chain on the master bus, between the master gain and
+   * audioContext.destination. Accepts any AudioNode chain (Tone.js effects,
+   * WAM plugins, native nodes). The caller is responsible for connecting the
+   * chain's output to audioContext.destination. Calling again replaces the
+   * previous chain. Parallel taps on `masterOutputNode` are unaffected.
+   */
+  connectMasterOutput(node) {
+    this._masterNode.connectEffects(node);
+  }
+  /** Remove the master effects chain and restore direct routing to audioContext.destination. */
+  disconnectMasterOutput() {
+    this._masterNode.disconnectEffects();
+  }
   // --- Events ---
   on(event, cb) {
     if (!this._listeners.has(event)) {
@@ -1740,7 +1790,7 @@ var _Transport = class _Transport {
   }
   _initAudioGraph(audioContext) {
     this._masterNode = new MasterNode(audioContext);
-    this._masterNode.output.connect(audioContext.destination);
+    this._masterNode.connectOutput(audioContext.destination);
     const toAudioTime = (transportTime) => this._clock.toAudioTime(transportTime);
     this._clipPlayer = new ClipPlayer(
       audioContext,