@dawcore/transport 0.0.4 → 0.0.5

package/README.md

@@ -7,7 +7,8 @@ Native Web Audio transport for multi-track audio scheduling, looping, tempo, and
 - **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.
+- **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).
 - **Type-safe coordinates** — Branded `Tick` and `Sample` types prevent accidentally passing seconds where ticks or samples are expected. Zero runtime cost.
@@ -71,9 +72,31 @@ const transport = new Transport(audioContext, {
   denominator: 4,
 });
 
+// Default click sounds are built in — just enable and play
 transport.setMetronomeEnabled(true);
-transport.setMetronomeClickSounds(accentBuffer, normalBuffer);
 transport.play();
+
+// Override with custom click sounds
+transport.setMetronomeClickSounds(accentBuffer, normalBuffer);
+```
+
+### Count-In
+
+```typescript
+transport.setCountIn(true);
+transport.setCountInBars(1);           // 1–8 bars, default 1
+transport.setCountInMode('always');    // 'always' | 'recording-only' (default)
+
+// Beat-by-beat events for UI countdown
+transport.on('countIn', ({ beat, totalBeats }) => {
+  console.log(beat + ' / ' + totalBeats);  // "1 / 4", "2 / 4", ...
+});
+
+transport.on('countInEnd', () => {
+  console.log('Playback starting');
+});
+
+transport.play();  // Plays count-in clicks, then starts playback
 ```
 
 ### Mixed Meter
@@ -155,6 +178,8 @@ new Transport(audioContext: AudioContext, options?: TransportOptions)
 | `numerator` | `4` | Beats per bar (time signature numerator) |
 | `denominator` | `4` | Beat unit (time signature denominator) |
 | `schedulerLookahead` | `0.2` | How far ahead to schedule (seconds) |
+| `accentFrequency` | `1000` | Default accent click frequency (Hz) |
+| `normalFrequency` | `800` | Default normal click frequency (Hz) |
 
 **Playback:**
 - `play(startTime?, endTime?)` — Start or resume playback
@@ -192,7 +217,14 @@ new Transport(audioContext: AudioContext, options?: TransportOptions)
 
 **Metronome:**
 - `setMetronomeEnabled(enabled)`
-- `setMetronomeClickSounds(accent, normal)`
+- `setMetronomeClickSounds(accent, normal)` — overrides default synthesized sounds
+
+**Count-In:**
+- `setCountIn(enabled)` — enable/disable count-in
+- `setCountInBars(bars)` — number of bars (1–8, default 1)
+- `setCountInMode(mode)` — `'recording-only'` (default) or `'always'`
+- `setRecording(recording)` — consumer signals recording state (for `'recording-only'` mode)
+- `isCountingIn()` — whether count-in is active
 
 **Effects:**
 - `connectTrackOutput(trackId, node)` — Insert effects chain
@@ -200,7 +232,10 @@ new Transport(audioContext: AudioContext, options?: TransportOptions)
 
 **Events:**
 - `on(event, callback)` / `off(event, callback)`
-- Events: `play`, `pause`, `stop`, `loop`, `tempochange`
+- Events: `play`, `pause`, `stop`, `loop`, `tempochange`, `meterchange`, `countIn`, `countInEnd`
+- `tempochange` payload: `{ bpm: number, atTick: Tick }`
+- `meterchange` payload: `{ numerator: number, denominator: number, atTick: Tick }`
+- `countIn` payload: `{ beat: number, totalBeats: number }`
 
 **Cleanup:**
 - `dispose()` — Stop playback, disconnect all nodes, remove listeners
@@ -219,6 +254,10 @@ Implements `PlayoutAdapter` from `@waveform-playlist/engine`. All methods delega
 
 See [TRANSPORT.md](./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.
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -40,6 +40,10 @@ interface TransportOptions {
     denominator?: number;
     /** How far ahead to schedule audio, in seconds. Default: 0.2 */
     schedulerLookahead?: number;
+    /** Accent click frequency in Hz. Default: 1000 */
+    accentFrequency?: number;
+    /** Normal click frequency in Hz. Default: 800 */
+    normalFrequency?: number;
 }
 /** Public return type for getMeter() */
 interface MeterSignature {
@@ -84,6 +88,33 @@ interface TransportPosition {
      *  Not branded Tick — a remainder within a beat, not an absolute position. */
     subTick: number;
 }
+/** Count-in mode: 'always' plays count-in on every play(), 'recording-only' only when recording. */
+type CountInMode = 'always' | 'recording-only';
+/** Payload emitted with the 'countIn' transport event.
+ *  Example: beat=1, totalBeats=4 means "first of four beats". */
+interface CountInEventData {
+    /** Current beat number (1-indexed) */
+    beat: number;
+    /** Total number of beats in the count-in */
+    totalBeats: number;
+}
+/** Payload emitted with the 'tempochange' transport event. */
+interface TempoChangeEventData {
+    /** The new BPM value */
+    bpm: number;
+    /** Tick position where the tempo was set */
+    atTick: Tick;
+}
+/** Payload emitted with the 'meterchange' transport event.
+ *  After removeMeter/clearMeters, reflects the resulting meter at that position. */
+interface MeterChangeEventData {
+    /** Time signature numerator */
+    numerator: number;
+    /** Time signature denominator */
+    denominator: number;
+    /** Tick position where the meter was set or removed */
+    atTick: Tick;
+}
 
 declare class Clock {
     private _audioContext;
@@ -329,13 +360,29 @@ declare class MetronomePlayer implements SchedulerListener<MetronomeEvent> {
     silence(): void;
 }
 
+interface CountInEvent extends SchedulerEvent {
+    isAccent: boolean;
+    buffer: AudioBuffer;
+    beat: number;
+    totalBeats: number;
+}
+
+interface ClickSoundOptions {
+    /** Frequency for accent click (beat 1). Default: 1000 Hz */
+    accentFrequency?: number;
+    /** Frequency for normal click (other beats). Default: 800 Hz */
+    normalFrequency?: number;
+}
+
 interface TransportEvents {
     play: () => void;
     pause: () => void;
     stop: () => void;
     loop: () => void;
-    tempochange: () => void;
-    meterchange: () => void;
+    tempochange: (event: TempoChangeEventData) => void;
+    meterchange: (event: MeterChangeEventData) => void;
+    countIn: (event: CountInEventData) => void;
+    countInEnd: () => void;
 }
 type TransportEventType = keyof TransportEvents;
 declare class Transport {
@@ -359,6 +406,19 @@ declare class Transport {
     private _loopStartTick;
     private _loopStartSeconds;
     private _listeners;
+    private _countInEnabled;
+    private _countInBars;
+    private _countInMode;
+    private _recording;
+    private _countingIn;
+    private _countInStartPosition;
+    private _countInDuration;
+    private _countInPlayer;
+    private _countInScheduler;
+    private _accentBuffer;
+    private _normalBuffer;
+    private _schedulerLookahead;
+    private _ppqn;
     constructor(audioContext: AudioContext, options?: TransportOptions);
     get audioContext(): AudioContext;
     play(startTime?: number, endTime?: number): void;
@@ -397,6 +457,13 @@ declare class Transport {
     tickToTime(tick: Tick): number;
     setMetronomeEnabled(enabled: boolean): void;
     setMetronomeClickSounds(accent: AudioBuffer, normal: AudioBuffer): void;
+    static readonly MIN_COUNT_IN_BARS = 1;
+    static readonly MAX_COUNT_IN_BARS = 8;
+    setCountIn(enabled: boolean): void;
+    setCountInBars(bars: number): void;
+    setCountInMode(mode: CountInMode): void;
+    setRecording(recording: boolean): void;
+    isCountingIn(): boolean;
     connectTrackOutput(trackId: string, node: AudioNode): void;
     disconnectTrackOutput(trackId: string): void;
     on<K extends TransportEventType>(event: K, cb: TransportEvents[K]): void;
@@ -404,6 +471,11 @@ declare class Transport {
     dispose(): void;
     private static _validateOptions;
     private _initAudioGraph;
+    private _initCountIn;
+    private _shouldCountIn;
+    private _startCountIn;
+    private _finishCountIn;
+    private _cancelCountIn;
     private _silenceAll;
     private _applyMuteState;
     private _emit;
@@ -431,7 +503,12 @@ declare class NativePlayoutAdapter implements PlayoutAdapter {
     setTrackSolo(trackId: string, soloed: boolean): void;
     setTrackPan(trackId: string, pan: number): void;
     setLoop(enabled: boolean, start: number, end: number): void;
+    setCountIn(enabled: boolean): void;
+    setCountInBars(bars: number): void;
+    setCountInMode(mode: CountInMode): void;
+    setRecording(recording: boolean): void;
+    isCountingIn(): boolean;
     dispose(): void;
 }
 
-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 SetTempoOptions, type TempoEntry, type TempoInterpolation, TempoMap, type Tick, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };
+export { type ClickSoundOptions, type ClipEvent, ClipPlayer, Clock, type CountInEvent, type CountInEventData, type CountInMode, MasterNode, type MeterChangeEventData, type MeterEntry, MeterMap, type MeterSignature, type MetronomeEvent, MetronomePlayer, NativePlayoutAdapter, type Sample, SampleTimeline, Scheduler, type SchedulerEvent, type SchedulerListener, type SchedulerOptions, type SetTempoOptions, type TempoChangeEventData, type TempoEntry, type TempoInterpolation, TempoMap, type Tick, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };

package/dist/index.d.ts

@@ -40,6 +40,10 @@ interface TransportOptions {
     denominator?: number;
     /** How far ahead to schedule audio, in seconds. Default: 0.2 */
     schedulerLookahead?: number;
+    /** Accent click frequency in Hz. Default: 1000 */
+    accentFrequency?: number;
+    /** Normal click frequency in Hz. Default: 800 */
+    normalFrequency?: number;
 }
 /** Public return type for getMeter() */
 interface MeterSignature {
@@ -84,6 +88,33 @@ interface TransportPosition {
      *  Not branded Tick — a remainder within a beat, not an absolute position. */
     subTick: number;
 }
+/** Count-in mode: 'always' plays count-in on every play(), 'recording-only' only when recording. */
+type CountInMode = 'always' | 'recording-only';
+/** Payload emitted with the 'countIn' transport event.
+ *  Example: beat=1, totalBeats=4 means "first of four beats". */
+interface CountInEventData {
+    /** Current beat number (1-indexed) */
+    beat: number;
+    /** Total number of beats in the count-in */
+    totalBeats: number;
+}
+/** Payload emitted with the 'tempochange' transport event. */
+interface TempoChangeEventData {
+    /** The new BPM value */
+    bpm: number;
+    /** Tick position where the tempo was set */
+    atTick: Tick;
+}
+/** Payload emitted with the 'meterchange' transport event.
+ *  After removeMeter/clearMeters, reflects the resulting meter at that position. */
+interface MeterChangeEventData {
+    /** Time signature numerator */
+    numerator: number;
+    /** Time signature denominator */
+    denominator: number;
+    /** Tick position where the meter was set or removed */
+    atTick: Tick;
+}
 
 declare class Clock {
     private _audioContext;
@@ -329,13 +360,29 @@ declare class MetronomePlayer implements SchedulerListener<MetronomeEvent> {
     silence(): void;
 }
 
+interface CountInEvent extends SchedulerEvent {
+    isAccent: boolean;
+    buffer: AudioBuffer;
+    beat: number;
+    totalBeats: number;
+}
+
+interface ClickSoundOptions {
+    /** Frequency for accent click (beat 1). Default: 1000 Hz */
+    accentFrequency?: number;
+    /** Frequency for normal click (other beats). Default: 800 Hz */
+    normalFrequency?: number;
+}
+
 interface TransportEvents {
     play: () => void;
     pause: () => void;
     stop: () => void;
     loop: () => void;
-    tempochange: () => void;
-    meterchange: () => void;
+    tempochange: (event: TempoChangeEventData) => void;
+    meterchange: (event: MeterChangeEventData) => void;
+    countIn: (event: CountInEventData) => void;
+    countInEnd: () => void;
 }
 type TransportEventType = keyof TransportEvents;
 declare class Transport {
@@ -359,6 +406,19 @@ declare class Transport {
     private _loopStartTick;
     private _loopStartSeconds;
     private _listeners;
+    private _countInEnabled;
+    private _countInBars;
+    private _countInMode;
+    private _recording;
+    private _countingIn;
+    private _countInStartPosition;
+    private _countInDuration;
+    private _countInPlayer;
+    private _countInScheduler;
+    private _accentBuffer;
+    private _normalBuffer;
+    private _schedulerLookahead;
+    private _ppqn;
     constructor(audioContext: AudioContext, options?: TransportOptions);
     get audioContext(): AudioContext;
     play(startTime?: number, endTime?: number): void;
@@ -397,6 +457,13 @@ declare class Transport {
     tickToTime(tick: Tick): number;
     setMetronomeEnabled(enabled: boolean): void;
     setMetronomeClickSounds(accent: AudioBuffer, normal: AudioBuffer): void;
+    static readonly MIN_COUNT_IN_BARS = 1;
+    static readonly MAX_COUNT_IN_BARS = 8;
+    setCountIn(enabled: boolean): void;
+    setCountInBars(bars: number): void;
+    setCountInMode(mode: CountInMode): void;
+    setRecording(recording: boolean): void;
+    isCountingIn(): boolean;
     connectTrackOutput(trackId: string, node: AudioNode): void;
     disconnectTrackOutput(trackId: string): void;
     on<K extends TransportEventType>(event: K, cb: TransportEvents[K]): void;
@@ -404,6 +471,11 @@ declare class Transport {
     dispose(): void;
     private static _validateOptions;
     private _initAudioGraph;
+    private _initCountIn;
+    private _shouldCountIn;
+    private _startCountIn;
+    private _finishCountIn;
+    private _cancelCountIn;
     private _silenceAll;
     private _applyMuteState;
     private _emit;
@@ -431,7 +503,12 @@ declare class NativePlayoutAdapter implements PlayoutAdapter {
     setTrackSolo(trackId: string, soloed: boolean): void;
     setTrackPan(trackId: string, pan: number): void;
     setLoop(enabled: boolean, start: number, end: number): void;
+    setCountIn(enabled: boolean): void;
+    setCountInBars(bars: number): void;
+    setCountInMode(mode: CountInMode): void;
+    setRecording(recording: boolean): void;
+    isCountingIn(): boolean;
     dispose(): void;
 }
 
-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 SetTempoOptions, type TempoEntry, type TempoInterpolation, TempoMap, type Tick, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };
+export { type ClickSoundOptions, type ClipEvent, ClipPlayer, Clock, type CountInEvent, type CountInEventData, type CountInMode, MasterNode, type MeterChangeEventData, type MeterEntry, MeterMap, type MeterSignature, type MetronomeEvent, MetronomePlayer, NativePlayoutAdapter, type Sample, SampleTimeline, Scheduler, type SchedulerEvent, type SchedulerListener, type SchedulerOptions, type SetTempoOptions, type TempoChangeEventData, type TempoEntry, type TempoInterpolation, TempoMap, type Tick, Timer, TrackNode, Transport, type TransportEvents, type TransportOptions, type TransportPosition };