@dawcore/components 0.0.5 → 0.0.7

package/README.md

@@ -0,0 +1,170 @@
+# @dawcore/components
+
+Framework-agnostic Web Components for multi-track audio editing. Drop `<daw-editor>` into any HTML page — no React, no build step required.
+
+## Features
+
+- **Pure Web Components** — Works with vanilla HTML, React, Vue, Svelte, or any framework
+- **Declarative tracks** — `<daw-track>` and `<daw-clip>` elements define your timeline in HTML
+- **Canvas waveforms** — Chunked rendering with virtual scrolling for large timelines
+- **Drag interactions** — Move clips, trim boundaries, split at playhead
+- **Keyboard shortcuts** — Play/pause, split, undo/redo via `<daw-keyboard-shortcuts>`
+- **File drop** — Drag audio files onto the editor to add tracks
+- **Recording** — Live mic recording with waveform preview (optional)
+- **Pre-computed peaks** — Instant waveform rendering from `.dat` files before audio decodes
+- **CSS theming** — Dark mode by default, fully customizable via CSS custom properties
+- **Native Web Audio** — Uses `@dawcore/transport` for playback scheduling. No Tone.js dependency.
+
+## Installation
+
+```bash
+npm install @dawcore/components
+```
+
+Peer dependencies:
+```bash
+npm install @waveform-playlist/core @waveform-playlist/engine @dawcore/transport
+```
+
+Optional (for recording):
+```bash
+npm install @waveform-playlist/recording @waveform-playlist/worklets
+```
+
+## Quick Start
+
+```html
+<script type="module">
+  import '@dawcore/components';
+</script>
+
+<daw-editor id="editor" samples-per-pixel="1024" wave-height="100" timescale>
+  <daw-track src="/audio/drums.opus" name="Drums"></daw-track>
+  <daw-track src="/audio/bass.opus" name="Bass"></daw-track>
+  <daw-track src="/audio/synth.opus" name="Synth"></daw-track>
+</daw-editor>
+
+<daw-transport for="editor">
+  <daw-play-button></daw-play-button>
+  <daw-pause-button></daw-pause-button>
+  <daw-stop-button></daw-stop-button>
+</daw-transport>
+```
+
+That's it. The editor loads audio, generates waveforms, and handles playback.
+
+## Multi-Clip Timeline
+
+For multiple clips per track with independent positioning:
+
+```html
+<daw-editor id="editor" samples-per-pixel="1024" wave-height="80"
+            timescale clip-headers interactive-clips>
+  <daw-keyboard-shortcuts playback splitting undo></daw-keyboard-shortcuts>
+
+  <daw-track name="Drums">
+    <daw-clip src="/audio/drums.opus" start="0" duration="8"></daw-clip>
+    <daw-clip src="/audio/drums.opus" start="12" duration="8" offset="8"></daw-clip>
+  </daw-track>
+
+  <daw-track name="Bass">
+    <daw-clip src="/audio/bass.opus" start="0" duration="20"></daw-clip>
+  </daw-track>
+</daw-editor>
+```
+
+## Pre-Computed Peaks
+
+For instant waveform rendering before audio finishes decoding:
+
+```html
+<daw-track name="Drums">
+  <daw-clip src="/audio/drums.opus"
+            peaks-src="/audio/drums.dat"
+            start="0" duration="8"></daw-clip>
+</daw-track>
+```
+
+The `.dat` file renders the waveform immediately. Audio decodes in the background for playback.
+
+## CSS Theming
+
+Style with CSS custom properties on `<daw-editor>` or any ancestor:
+
+```css
+daw-editor {
+  --daw-wave-color: #c49a6c;
+  --daw-playhead-color: #d08070;
+  --daw-background: #1a1a2e;
+  --daw-track-background: #16213e;
+  --daw-ruler-color: #c49a6c;
+  --daw-ruler-background: #0f0f1a;
+  --daw-selection-color: rgba(99, 199, 95, 0.3);
+  --daw-controls-background: #1a1a2e;
+  --daw-controls-text: #e0d4c8;
+  --daw-clip-header-background: rgba(0, 0, 0, 0.4);
+  --daw-clip-header-text: #e0d4c8;
+  --daw-controls-width: 180px;
+  --daw-min-height: 200px;
+}
+```
+
+## Recording
+
+```html
+<daw-editor id="editor" samples-per-pixel="1024" wave-height="100">
+  <daw-track name="Recording"></daw-track>
+</daw-editor>
+
+<daw-transport for="editor">
+  <daw-play-button></daw-play-button>
+  <daw-pause-button></daw-pause-button>
+  <daw-stop-button></daw-stop-button>
+  <daw-record-button></daw-record-button>
+</daw-transport>
+
+<script type="module">
+  const editor = document.getElementById('editor');
+  // Consumer provides the mic stream
+  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+  editor.recordingStream = stream;
+</script>
+```
+
+## Events
+
+Listen for editor events on the `<daw-editor>` element:
+
+```javascript
+const editor = document.getElementById('editor');
+
+editor.addEventListener('daw-play', () => console.log('playing'));
+editor.addEventListener('daw-pause', () => console.log('paused'));
+editor.addEventListener('daw-stop', () => console.log('stopped'));
+editor.addEventListener('daw-seek', (e) => console.log('seek:', e.detail.time));
+editor.addEventListener('daw-selection', (e) => console.log('selection:', e.detail));
+editor.addEventListener('daw-track-select', (e) => console.log('track:', e.detail.trackId));
+editor.addEventListener('daw-clip-move', (e) => console.log('move:', e.detail));
+editor.addEventListener('daw-clip-trim', (e) => console.log('trim:', e.detail));
+editor.addEventListener('daw-clip-split', (e) => console.log('split:', e.detail));
+editor.addEventListener('daw-track-error', (e) => console.error('error:', e.detail));
+```
+
+## Custom AudioContext
+
+By default, `<daw-editor>` creates its own `AudioContext` using the `sample-rate` attribute. To provide your own:
+
+```javascript
+const editor = document.getElementById('editor');
+editor.audioContext = new AudioContext({ sampleRate: 48000, latencyHint: 0 });
+```
+
+Set this before tracks load. The provided context is used for decoding, playback, and recording.
+
+## API
+
+See [COMPONENTS.md](./COMPONENTS.md) for the full element and attribute reference.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -278,6 +278,8 @@ declare global {
 interface RecordingOptions {
     trackId?: string;
     bits?: 8 | 16;
+    /** Fallback channel count when stream doesn't report one via getSettings(). Must be 1 or 2. */
+    channelCount?: 1 | 2;
     startSample?: number;
     /** Start playback during recording so user hears existing tracks. */
     overdub?: boolean;
@@ -300,7 +302,7 @@ interface RecordingSession {
     readonly channelCount: number;
     readonly bits: Bits;
     isFirstMessage: boolean;
-    /** Latency samples to skip in live preview (outputLatency + lookAhead). */
+    /** Latency samples to skip in live preview (outputLatency only). */
     readonly latencySamples: number;
     readonly wasOverdub: boolean;
     /** Stored so it can be removed on stop/cleanup — not just when stream ends. */
@@ -315,6 +317,7 @@ type ReadonlyRecordingSession = Readonly<Omit<RecordingSession, 'chunks' | 'peak
 };
 /** Narrow interface for the host editor. */
 interface RecordingHost extends ReactiveControllerHost {
+    readonly audioContext: AudioContext;
     readonly samplesPerPixel: number;
     readonly effectiveSampleRate: number;
     readonly _selectedTrackId: string | null;
@@ -329,7 +332,7 @@ interface RecordingHost extends ReactiveControllerHost {
 declare class RecordingController implements ReactiveController {
     private _host;
     private _sessions;
-    private _workletLoaded;
+    private _workletLoadedCtx;
     constructor(host: RecordingHost & HTMLElement);
     hostConnected(): void;
     hostDisconnected(): void;
@@ -562,6 +565,12 @@ declare class DawEditorElement extends LitElement {
     _selectionStartTime: number;
     _selectionEndTime: number;
     _currentTime: number;
+    /** Consumer-provided AudioContext. When set, used for decode, playback, and recording. */
+    private _externalAudioContext;
+    private _ownedAudioContext;
+    /** Set an AudioContext to use for all audio operations. Must be set before tracks load. */
+    set audioContext(ctx: AudioContext | null);
+    get audioContext(): AudioContext;
     _engine: PlaylistEngine | null;
     private _enginePromise;
     _audioCache: Map<string, Promise<AudioBuffer>>;
@@ -612,13 +621,6 @@ declare class DawEditorElement extends LitElement {
     private _onTrackRemoveRequest;
     private _readTrackDescriptor;
     private _loadTrack;
-    private _contextConfigurePromise;
-    /**
-     * Ensure the global AudioContext is configured with the editor's sample-rate hint
-     * before the first audio operation. Idempotent — concurrent callers await the
-     * same promise so no one proceeds to getGlobalAudioContext() before configuration.
-     */
-    private _ensureContextConfigured;
     _fetchAndDecode(src: string): Promise<AudioBuffer>;
     private _fetchPeaks;
     _recomputeDuration(): void;
@@ -769,6 +771,10 @@ declare global {
     }
 }
 
+interface AudioResumeHost extends ReactiveControllerHost, HTMLElement {
+    /** Returns the AudioContext to resume on user gesture */
+    readonly audioContext: AudioContext;
+}
 declare class AudioResumeController implements ReactiveController {
     private _host;
     private _target;
@@ -776,7 +782,7 @@ declare class AudioResumeController implements ReactiveController {
     private _generation;
     /** CSS selector, or 'document'. When undefined, controller is inert. */
     target?: string;
-    constructor(host: ReactiveControllerHost & HTMLElement);
+    constructor(host: AudioResumeHost);
     hostConnected(): void;
     hostDisconnected(): void;
     private _onGesture;

package/dist/index.d.ts

@@ -278,6 +278,8 @@ declare global {
 interface RecordingOptions {
     trackId?: string;
     bits?: 8 | 16;
+    /** Fallback channel count when stream doesn't report one via getSettings(). Must be 1 or 2. */
+    channelCount?: 1 | 2;
     startSample?: number;
     /** Start playback during recording so user hears existing tracks. */
     overdub?: boolean;
@@ -300,7 +302,7 @@ interface RecordingSession {
     readonly channelCount: number;
     readonly bits: Bits;
     isFirstMessage: boolean;
-    /** Latency samples to skip in live preview (outputLatency + lookAhead). */
+    /** Latency samples to skip in live preview (outputLatency only). */
     readonly latencySamples: number;
     readonly wasOverdub: boolean;
     /** Stored so it can be removed on stop/cleanup — not just when stream ends. */
@@ -315,6 +317,7 @@ type ReadonlyRecordingSession = Readonly<Omit<RecordingSession, 'chunks' | 'peak
 };
 /** Narrow interface for the host editor. */
 interface RecordingHost extends ReactiveControllerHost {
+    readonly audioContext: AudioContext;
     readonly samplesPerPixel: number;
     readonly effectiveSampleRate: number;
     readonly _selectedTrackId: string | null;
@@ -329,7 +332,7 @@ interface RecordingHost extends ReactiveControllerHost {
 declare class RecordingController implements ReactiveController {
     private _host;
     private _sessions;
-    private _workletLoaded;
+    private _workletLoadedCtx;
     constructor(host: RecordingHost & HTMLElement);
     hostConnected(): void;
     hostDisconnected(): void;
@@ -562,6 +565,12 @@ declare class DawEditorElement extends LitElement {
     _selectionStartTime: number;
     _selectionEndTime: number;
     _currentTime: number;
+    /** Consumer-provided AudioContext. When set, used for decode, playback, and recording. */
+    private _externalAudioContext;
+    private _ownedAudioContext;
+    /** Set an AudioContext to use for all audio operations. Must be set before tracks load. */
+    set audioContext(ctx: AudioContext | null);
+    get audioContext(): AudioContext;
     _engine: PlaylistEngine | null;
     private _enginePromise;
     _audioCache: Map<string, Promise<AudioBuffer>>;
@@ -612,13 +621,6 @@ declare class DawEditorElement extends LitElement {
     private _onTrackRemoveRequest;
     private _readTrackDescriptor;
     private _loadTrack;
-    private _contextConfigurePromise;
-    /**
-     * Ensure the global AudioContext is configured with the editor's sample-rate hint
-     * before the first audio operation. Idempotent — concurrent callers await the
-     * same promise so no one proceeds to getGlobalAudioContext() before configuration.
-     */
-    private _ensureContextConfigured;
     _fetchAndDecode(src: string): Promise<AudioBuffer>;
     private _fetchPeaks;
     _recomputeDuration(): void;
@@ -769,6 +771,10 @@ declare global {
     }
 }
 
+interface AudioResumeHost extends ReactiveControllerHost, HTMLElement {
+    /** Returns the AudioContext to resume on user gesture */
+    readonly audioContext: AudioContext;
+}
 declare class AudioResumeController implements ReactiveController {
     private _host;
     private _target;
@@ -776,7 +782,7 @@ declare class AudioResumeController implements ReactiveController {
     private _generation;
     /** CSS selector, or 'document'. When undefined, controller is inert. */
     target?: string;
-    constructor(host: ReactiveControllerHost & HTMLElement);
+    constructor(host: AudioResumeHost);
     hostConnected(): void;
     hostDisconnected(): void;
     private _onGesture;

package/dist/index.js

@@ -1668,18 +1668,22 @@ var ViewportController = class {
 };
 
 // src/controllers/audio-resume-controller.ts
-var import_playout = require("@waveform-playlist/playout");
 var AudioResumeController = class {
   constructor(host) {
     this._target = null;
     this._attached = false;
     this._generation = 0;
     this._onGesture = (e) => {
-      (0, import_playout.resumeGlobalAudioContext)().catch((err) => {
-        console.warn(
-          "[dawcore] AudioResumeController: eager resume failed, will retry on play: " + String(err)
-        );
-      });
+      const ctx = this._host.audioContext;
+      if (ctx.state === "closed") {
+        console.warn("[dawcore] AudioResumeController: AudioContext is closed, cannot resume.");
+      } else if (ctx.state === "suspended") {
+        ctx.resume().catch((err) => {
+          console.warn(
+            "[dawcore] AudioResumeController: eager resume failed, will retry on play: " + String(err)
+          );
+        });
+      }
       const otherType = e.type === "pointerdown" ? "keydown" : "pointerdown";
       this._target?.removeEventListener(otherType, this._onGesture, {
         capture: true
@@ -1747,13 +1751,12 @@ var AudioResumeController = class {
 };
 
 // src/controllers/recording-controller.ts
-var import_playout2 = require("@waveform-playlist/playout");
 var import_worklets = require("@waveform-playlist/worklets");
 var import_recording = require("@waveform-playlist/recording");
 var RecordingController = class {
   constructor(host) {
     this._sessions = /* @__PURE__ */ new Map();
-    this._workletLoaded = false;
+    this._workletLoadedCtx = null;
     this._host = host;
     host.addController(this);
   }
@@ -1763,6 +1766,7 @@ var RecordingController = class {
     for (const trackId of [...this._sessions.keys()]) {
       this._cleanupSession(trackId);
     }
+    this._workletLoadedCtx = null;
   }
   get isRecording() {
     return this._sessions.size > 0;
@@ -1781,21 +1785,25 @@ var RecordingController = class {
       return;
     }
     const bits = options.bits ?? 16;
-    const context = (0, import_playout2.getGlobalContext)();
-    const rawCtx = context.rawContext;
-    this._host.resolveAudioContextSampleRate(rawCtx.sampleRate);
     try {
-      if (!this._workletLoaded) {
+      const rawCtx = this._host.audioContext;
+      this._host.resolveAudioContextSampleRate(rawCtx.sampleRate);
+      if (!this._workletLoadedCtx || this._workletLoadedCtx !== rawCtx) {
         await rawCtx.audioWorklet.addModule(import_worklets.recordingProcessorUrl);
-        this._workletLoaded = true;
+        this._workletLoadedCtx = rawCtx;
       }
-      const channelCount = stream.getAudioTracks()[0]?.getSettings()?.channelCount ?? 1;
+      const detectedChannelCount = stream.getAudioTracks()[0]?.getSettings()?.channelCount;
+      if (detectedChannelCount === void 0 && options.channelCount !== void 0) {
+        console.warn(
+          "[dawcore] Could not detect stream channel count, using fallback: " + options.channelCount
+        );
+      }
+      const channelCount = detectedChannelCount ?? options.channelCount ?? 1;
       const startSample = options.startSample ?? Math.floor(this._host._currentTime * this._host.effectiveSampleRate);
       const outputLatency = rawCtx.outputLatency ?? 0;
-      const lookAhead = context.lookAhead ?? 0;
-      const latencySamples = Math.floor((outputLatency + lookAhead) * rawCtx.sampleRate);
-      const source = context.createMediaStreamSource(stream);
-      const workletNode = context.createAudioWorkletNode("recording-processor", {
+      const latencySamples = Math.floor(outputLatency * rawCtx.sampleRate);
+      const source = rawCtx.createMediaStreamSource(stream);
+      const workletNode = new AudioWorkletNode(rawCtx, "recording-processor", {
         channelCount,
         channelCountMode: "explicit"
       });
@@ -1896,8 +1904,7 @@ var RecordingController = class {
       );
       return;
     }
-    const context = (0, import_playout2.getGlobalContext)();
-    const stopCtx = context.rawContext;
+    const stopCtx = this._host.audioContext;
     const channelData = session.chunks.map((chunkArr) => (0, import_recording.concatenateAudioData)(chunkArr));
     const audioBuffer = (0, import_recording.createAudioBuffer)(
       stopCtx,
@@ -2869,6 +2876,9 @@ var DawEditorElement = class extends import_lit12.LitElement {
     this._selectionStartTime = 0;
     this._selectionEndTime = 0;
     this._currentTime = 0;
+    /** Consumer-provided AudioContext. When set, used for decode, playback, and recording. */
+    this._externalAudioContext = null;
+    this._ownedAudioContext = null;
     this._engine = null;
     this._enginePromise = null;
     this._audioCache = /* @__PURE__ */ new Map();
@@ -2963,7 +2973,6 @@ var DawEditorElement = class extends import_lit12.LitElement {
         this._onTrackRemoved(trackId);
       }
     };
-    this._contextConfigurePromise = null;
     // --- File Drop ---
     this._onDragOver = (e) => {
       if (!this.fileDrop) return;
@@ -3015,6 +3024,31 @@ var DawEditorElement = class extends import_lit12.LitElement {
     this._samplesPerPixel = clamped;
     this.requestUpdate("samplesPerPixel", old);
   }
+  /** Set an AudioContext to use for all audio operations. Must be set before tracks load. */
+  set audioContext(ctx) {
+    if (ctx && ctx.state === "closed") {
+      console.warn("[dawcore] Provided AudioContext is already closed. Ignoring.");
+      return;
+    }
+    if (this._engine) {
+      console.warn(
+        "[dawcore] audioContext set after engine is built. The engine will continue using the previous context."
+      );
+    }
+    this._externalAudioContext = ctx;
+  }
+  get audioContext() {
+    if (this._externalAudioContext) return this._externalAudioContext;
+    if (!this._ownedAudioContext) {
+      this._ownedAudioContext = new AudioContext({ sampleRate: this.sampleRate });
+      if (this._ownedAudioContext.sampleRate !== this.sampleRate) {
+        console.warn(
+          "[dawcore] Requested sampleRate " + this.sampleRate + " but AudioContext is running at " + this._ownedAudioContext.sampleRate
+        );
+      }
+    }
+    return this._ownedAudioContext;
+  }
   get _clipHandler() {
     return this.interactiveClips ? this._clipPointer : null;
   }
@@ -3115,12 +3149,17 @@ var DawEditorElement = class extends import_lit12.LitElement {
     this._clipOffsets.clear();
     this._peakPipeline.terminate();
     this._minSamplesPerPixel = 0;
-    this._contextConfigurePromise = null;
     try {
       this._disposeEngine();
     } catch (err) {
       console.warn("[dawcore] Error disposing engine: " + String(err));
     }
+    if (this._ownedAudioContext) {
+      this._ownedAudioContext.close().catch((err) => {
+        console.warn("[dawcore] Error closing AudioContext: " + String(err));
+      });
+      this._ownedAudioContext = null;
+    }
   }
   willUpdate(changedProperties) {
     if (changedProperties.has("eagerResume")) {
@@ -3225,9 +3264,7 @@ var DawEditorElement = class extends import_lit12.LitElement {
         if (waveformDataPromise) {
           try {
             const wd = await waveformDataPromise;
-            await this._ensureContextConfigured();
-            const { getGlobalAudioContext } = await import("@waveform-playlist/playout");
-            const contextRate = getGlobalAudioContext().sampleRate;
+            const contextRate = this.audioContext.sampleRate;
             if (wd.sample_rate === contextRate) {
               waveformData = wd;
             } else {
@@ -3359,30 +3396,6 @@ var DawEditorElement = class extends import_lit12.LitElement {
       );
     }
   }
-  /**
-   * Ensure the global AudioContext is configured with the editor's sample-rate hint
-   * before the first audio operation. Idempotent — concurrent callers await the
-   * same promise so no one proceeds to getGlobalAudioContext() before configuration.
-   */
-  _ensureContextConfigured() {
-    if (!this._contextConfigurePromise) {
-      this._contextConfigurePromise = (async () => {
-        const { configureGlobalContext } = await import("@waveform-playlist/playout");
-        const actualRate = configureGlobalContext({
-          sampleRate: this.sampleRate
-        });
-        if (actualRate !== this.sampleRate) {
-          console.warn(
-            "[dawcore] Requested sampleRate " + this.sampleRate + " but AudioContext is running at " + actualRate
-          );
-        }
-      })().catch((err) => {
-        this._contextConfigurePromise = null;
-        throw err;
-      });
-    }
-    return this._contextConfigurePromise;
-  }
   async _fetchAndDecode(src) {
     if (this._audioCache.has(src)) {
       return this._audioCache.get(src);
@@ -3395,9 +3408,7 @@ var DawEditorElement = class extends import_lit12.LitElement {
         );
       }
       const arrayBuffer = await response.arrayBuffer();
-      await this._ensureContextConfigured();
-      const { getGlobalAudioContext } = await import("@waveform-playlist/playout");
-      return getGlobalAudioContext().decodeAudioData(arrayBuffer);
+      return this.audioContext.decodeAudioData(arrayBuffer);
     })();
     this._audioCache.set(src, promise);
     try {
@@ -3438,11 +3449,11 @@ var DawEditorElement = class extends import_lit12.LitElement {
     return this._enginePromise;
   }
   async _buildEngine() {
-    const [{ PlaylistEngine }, { createToneAdapter }] = await Promise.all([
+    const [{ PlaylistEngine }, { NativePlayoutAdapter }] = await Promise.all([
       import("@waveform-playlist/engine"),
-      import("@waveform-playlist/playout")
+      import("@dawcore/transport")
     ]);
-    const adapter = createToneAdapter();
+    const adapter = new NativePlayoutAdapter(this.audioContext);
     const engine = new PlaylistEngine({
       adapter,
       sampleRate: this.effectiveSampleRate,