@dawcore/components 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/dist/index.d.mts

@@ -0,0 +1,541 @@
+import * as lit from 'lit';
+import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost } from 'lit';
+import { Peaks, Bits, FadeType, PeakData, ClipTrack } from '@waveform-playlist/core';
+import { PlaylistEngine } from '@waveform-playlist/engine';
+
+declare class DawClipElement extends LitElement {
+    src: string;
+    peaksSrc: string;
+    start: number;
+    duration: number;
+    offset: number;
+    gain: number;
+    name: string;
+    color: string;
+    fadeIn: number;
+    fadeOut: number;
+    fadeType: string;
+    readonly clipId: `${string}-${string}-${string}-${string}-${string}`;
+    createRenderRoot(): this;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-clip': DawClipElement;
+    }
+}
+
+declare class DawTrackElement extends LitElement {
+    src: string;
+    name: string;
+    volume: number;
+    pan: number;
+    muted: boolean;
+    soloed: boolean;
+    readonly trackId: `${string}-${string}-${string}-${string}-${string}`;
+    createRenderRoot(): this;
+    connectedCallback(): void;
+    private _hasRendered;
+    updated(changed: PropertyValues): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-track': DawTrackElement;
+    }
+}
+
+declare class DawWaveformElement extends LitElement {
+    private _peaks;
+    private _dirtyPixels;
+    private _drawScheduled;
+    private _rafId;
+    /** Chunk indices visible in the last draw pass — used to detect new chunks on scroll. */
+    private _drawnChunks;
+    set peaks(value: Peaks);
+    get peaks(): Peaks;
+    /**
+     * Replace the internal peaks reference without marking all dirty.
+     * Use with updatePeaks() for incremental recording updates where
+     * appendPeaks() returns a new array but only the tail changed.
+     */
+    setPeaksQuiet(value: Peaks): void;
+    get bits(): Bits;
+    length: number;
+    waveHeight: number;
+    barWidth: number;
+    barGap: number;
+    /** Visible viewport start in pixels (relative to timeline origin). */
+    visibleStart: number;
+    /** Visible viewport end in pixels (relative to timeline origin). */
+    visibleEnd: number;
+    /** This element's left offset on the timeline (for viewport intersection). */
+    originX: number;
+    static styles: lit.CSSResult;
+    private _getVisibleChunkIndices;
+    /**
+     * Mark a range of peak indices as dirty for incremental redraw.
+     * The caller must have already updated the underlying peaks array.
+     * Does NOT trigger a Lit re-render — bypasses Lit entirely.
+     */
+    updatePeaks(startIndex: number, endIndex: number): void;
+    private _markAllDirty;
+    private _scheduleDraw;
+    private _drawDirty;
+    private _drawChunk;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    render(): lit.TemplateResult<1>;
+    /** Mark peaks dirty only for chunks that weren't drawn in the previous frame. */
+    private _markNewChunksDirty;
+    updated(changedProperties: Map<string, unknown>): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-waveform': DawWaveformElement;
+    }
+}
+
+declare class DawPlayheadElement extends LitElement {
+    private _animation;
+    private _line;
+    static styles: lit.CSSResult;
+    render(): lit.TemplateResult<1>;
+    firstUpdated(): void;
+    startAnimation(getTime: () => number, sampleRate: number, samplesPerPixel: number): void;
+    stopAnimation(time: number, sampleRate: number, samplesPerPixel: number): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-playhead': DawPlayheadElement;
+    }
+}
+
+declare class DawTransportElement extends LitElement {
+    for: string;
+    get target(): HTMLElement | null;
+    createRenderRoot(): this;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-transport': DawTransportElement;
+    }
+}
+
+/**
+ * Base class for transport button elements.
+ * Finds target daw-editor via closest <daw-transport>.
+ */
+declare class DawTransportButton extends LitElement {
+    protected get target(): any;
+    static styles: lit.CSSResultGroup;
+}
+
+declare class DawPlayButtonElement extends DawTransportButton {
+    render(): lit.TemplateResult<1>;
+    private _onClick;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-play-button': DawPlayButtonElement;
+    }
+}
+
+declare class DawPauseButtonElement extends DawTransportButton {
+    render(): lit.TemplateResult<1>;
+    private _onClick;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-pause-button': DawPauseButtonElement;
+    }
+}
+
+declare class DawStopButtonElement extends DawTransportButton {
+    render(): lit.TemplateResult<1>;
+    private _onClick;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-stop-button': DawStopButtonElement;
+    }
+}
+
+interface TrackDescriptor {
+    name: string;
+    src: string;
+    volume: number;
+    pan: number;
+    muted: boolean;
+    soloed: boolean;
+    clips: ClipDescriptor[];
+}
+interface ClipDescriptor {
+    src: string;
+    start: number;
+    duration: number;
+    offset: number;
+    gain: number;
+    name: string;
+    fadeIn: number;
+    fadeOut: number;
+    fadeType: FadeType;
+}
+
+/**
+ * Peak generation pipeline: AudioBuffer → web worker → WaveformData → PeakData.
+ *
+ * Manages worker lifecycle, WaveformData caching per AudioBuffer (WeakMap),
+ * inflight dedup, and peak extraction via resample() for any zoom level
+ * coarser than the base scale.
+ *
+ * The base scale determines the finest zoom level that can be rendered without
+ * regenerating. Resampling only works to coarser (larger) scales. Set baseScale
+ * to the finest zoom level the user might need.
+ */
+
+declare class PeakPipeline {
+    private _worker;
+    private _cache;
+    private _inflight;
+    /**
+     * Generate PeakData for a clip from its AudioBuffer.
+     * Uses cached WaveformData when available; otherwise generates via worker.
+     * The worker generates at `scale` (= samplesPerPixel) for exact rendering.
+     */
+    generatePeaks(audioBuffer: AudioBuffer, samplesPerPixel: number, isMono: boolean): Promise<PeakData>;
+    /**
+     * Re-extract peaks for all clips at a new zoom level using cached WaveformData.
+     * Only works for zoom levels coarser than (or equal to) the cached base scale.
+     * Returns a new Map of clipId → PeakData. Clips without cached data or where
+     * the target scale is finer than the cached base are skipped.
+     */
+    reextractPeaks(clipBuffers: ReadonlyMap<string, AudioBuffer>, samplesPerPixel: number, isMono: boolean): Map<string, PeakData>;
+    terminate(): void;
+    private _getWaveformData;
+}
+
+declare class DawTrackControlsElement extends LitElement {
+    /** Track ID — set by the editor to link controls to a track row. */
+    trackId: string | null;
+    trackName: string;
+    volume: number;
+    pan: number;
+    muted: boolean;
+    soloed: boolean;
+    static styles: lit.CSSResult;
+    private _onVolumeInput;
+    private _onPanInput;
+    private _onMuteClick;
+    private _onSoloClick;
+    private _onRemoveClick;
+    private _dispatchControl;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-track-controls': DawTrackControlsElement;
+    }
+}
+
+interface RecordingOptions {
+    trackId?: string;
+    bits?: 8 | 16;
+    startSample?: number;
+}
+interface RecordingSession {
+    readonly trackId: string;
+    readonly stream: MediaStream;
+    readonly source: {
+        disconnect(): void;
+        connect(dest: unknown): void;
+    };
+    readonly workletNode: {
+        port: MessagePort;
+        disconnect(): void;
+    };
+    readonly chunks: Float32Array[][];
+    totalSamples: number;
+    readonly peaks: (Int8Array | Int16Array)[];
+    readonly startSample: number;
+    readonly channelCount: number;
+    readonly bits: Bits;
+    isFirstMessage: boolean;
+    /** Stored so it can be removed on stop/cleanup — not just when stream ends. */
+    readonly _onTrackEnded: (() => void) | null;
+    readonly _audioTrack: MediaStreamTrack | null;
+}
+/** Readonly view of a recording session for external consumers. */
+type ReadonlyRecordingSession = Readonly<Omit<RecordingSession, 'chunks' | 'peaks' | '_onTrackEnded' | '_audioTrack'>> & {
+    readonly chunks: ReadonlyArray<ReadonlyArray<Float32Array>>;
+    readonly peaks: ReadonlyArray<Int8Array | Int16Array>;
+};
+/** Narrow interface for the host editor. */
+interface RecordingHost extends ReactiveControllerHost {
+    readonly samplesPerPixel: number;
+    readonly effectiveSampleRate: number;
+    readonly _selectedTrackId: string | null;
+    readonly _currentTime: number;
+    readonly shadowRoot: ShadowRoot | null;
+    resolveAudioContextSampleRate(rate: number): void;
+    _addRecordedClip?(trackId: string, buf: AudioBuffer, startSample: number, durSamples: number): void;
+    dispatchEvent(event: Event): boolean;
+}
+declare class RecordingController implements ReactiveController {
+    private _host;
+    private _sessions;
+    private _workletLoaded;
+    constructor(host: RecordingHost & HTMLElement);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    get isRecording(): boolean;
+    getSession(trackId: string): ReadonlyRecordingSession | undefined;
+    startRecording(stream: MediaStream, options?: RecordingOptions): Promise<void>;
+    stopRecording(trackId?: string): void;
+    private _onWorkletMessage;
+    private _createClipFromRecording;
+    private _removeTrackEndedListener;
+    private _cleanupSession;
+}
+
+interface DawSelectionDetail {
+    start: number;
+    end: number;
+}
+interface DawSeekDetail {
+    time: number;
+}
+interface DawTrackSelectDetail {
+    trackId: string;
+}
+interface DawTrackConnectedDetail {
+    trackId: string;
+    element: DawTrackElement;
+}
+interface DawTrackIdDetail {
+    trackId: string;
+}
+interface DawTrackErrorDetail {
+    trackId: string;
+    error: unknown;
+}
+interface DawFilesLoadErrorDetail {
+    file: File;
+    error: unknown;
+}
+interface DawErrorDetail {
+    operation: string;
+    error: unknown;
+}
+interface DawTrackControlDetail {
+    trackId: string;
+    prop: string;
+    value: number | boolean;
+}
+interface DawTrackRemoveDetail {
+    trackId: string;
+}
+interface DawRecordingStartDetail {
+    trackId: string;
+    stream: MediaStream;
+}
+interface DawRecordingCompleteDetail {
+    trackId: string;
+    audioBuffer: AudioBuffer;
+    startSample: number;
+    durationSamples: number;
+}
+interface DawRecordingErrorDetail {
+    trackId: string;
+    error: unknown;
+}
+interface DawEventMap {
+    'daw-selection': CustomEvent<DawSelectionDetail>;
+    'daw-seek': CustomEvent<DawSeekDetail>;
+    'daw-track-select': CustomEvent<DawTrackSelectDetail>;
+    'daw-track-connected': CustomEvent<DawTrackConnectedDetail>;
+    'daw-track-update': CustomEvent<DawTrackIdDetail>;
+    'daw-track-ready': CustomEvent<DawTrackIdDetail>;
+    'daw-track-error': CustomEvent<DawTrackErrorDetail>;
+    'daw-files-load-error': CustomEvent<DawFilesLoadErrorDetail>;
+    'daw-play': CustomEvent<void>;
+    'daw-pause': CustomEvent<void>;
+    'daw-stop': CustomEvent<void>;
+    'daw-error': CustomEvent<DawErrorDetail>;
+    'daw-track-control': CustomEvent<DawTrackControlDetail>;
+    'daw-track-remove': CustomEvent<DawTrackRemoveDetail>;
+    'daw-recording-start': CustomEvent<DawRecordingStartDetail>;
+    'daw-recording-complete': CustomEvent<DawRecordingCompleteDetail>;
+    'daw-recording-error': CustomEvent<DawRecordingErrorDetail>;
+}
+type DawEvent<K extends keyof DawEventMap> = DawEventMap[K];
+interface LoadFilesResult {
+    loaded: string[];
+    failed: Array<{
+        file: File;
+        error: unknown;
+    }>;
+}
+
+declare class DawEditorElement extends LitElement {
+    samplesPerPixel: number;
+    waveHeight: number;
+    timescale: boolean;
+    mono: boolean;
+    barWidth: number;
+    barGap: number;
+    fileDrop: boolean;
+    /** Initial sample rate hint. Overridden by decoded audio buffer's actual rate. */
+    sampleRate: number;
+    /** Resolved sample rate — falls back to sampleRate property until first audio decode. */
+    _resolvedSampleRate: number | null;
+    _tracks: Map<string, TrackDescriptor>;
+    _engineTracks: Map<string, ClipTrack>;
+    _peaksData: Map<string, PeakData>;
+    _isPlaying: boolean;
+    private _duration;
+    _selectedTrackId: string | null;
+    _dragOver: boolean;
+    _selectionStartTime: number;
+    _selectionEndTime: number;
+    _currentTime: number;
+    _engine: PlaylistEngine | null;
+    private _enginePromise;
+    private _audioInitialized;
+    _audioCache: Map<string, Promise<AudioBuffer>>;
+    _clipBuffers: Map<string, AudioBuffer>;
+    _peakPipeline: PeakPipeline;
+    private _trackElements;
+    private _childObserver;
+    private _audioResume;
+    eagerResume?: string;
+    private _recordingController;
+    private _pointer;
+    private _viewport;
+    static styles: lit.CSSResult[];
+    get effectiveSampleRate(): number;
+    resolveAudioContextSampleRate(rate: number): void;
+    private get _totalWidth();
+    _setSelectedTrackId(trackId: string | null): void;
+    get tracks(): TrackDescriptor[];
+    get selectedTrackId(): string | null;
+    get selection(): {
+        start: number;
+        end: number;
+    } | null;
+    setSelection(start: number, end: number): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changedProperties: Map<string, unknown>): void;
+    private _onTrackConnected;
+    private _onTrackRemoved;
+    private _onTrackUpdate;
+    private static _CONTROL_PROPS;
+    private _onTrackControl;
+    private _onTrackRemoveRequest;
+    private _readTrackDescriptor;
+    private _loadTrack;
+    _fetchAndDecode(src: string): Promise<AudioBuffer>;
+    _recomputeDuration(): void;
+    _ensureEngine(): Promise<PlaylistEngine>;
+    private _buildEngine;
+    private _disposeEngine;
+    private _onDragOver;
+    private _onDragLeave;
+    private _onDrop;
+    loadFiles(files: FileList | File[]): Promise<LoadFilesResult>;
+    play(): Promise<void>;
+    pause(): void;
+    stop(): void;
+    seekTo(time: number): void;
+    recordingStream: MediaStream | null;
+    get isRecording(): boolean;
+    stopRecording(): void;
+    _addRecordedClip(trackId: string, buf: AudioBuffer, startSample: number, durSamples: number): void;
+    startRecording(stream?: MediaStream, options?: RecordingOptions): Promise<void>;
+    private _renderRecordingPreview;
+    _startPlayhead(): void;
+    _stopPlayhead(): void;
+    private _getPlayhead;
+    private _getOrderedTracks;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-editor': DawEditorElement;
+    }
+}
+
+declare class DawRulerElement extends LitElement {
+    samplesPerPixel: number;
+    sampleRate: number;
+    duration: number;
+    rulerHeight: number;
+    private _tickData;
+    static styles: lit.CSSResult;
+    willUpdate(): void;
+    render(): lit.TemplateResult<1>;
+    updated(): void;
+    private _drawTicks;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-ruler': DawRulerElement;
+    }
+}
+
+declare class DawSelectionElement extends LitElement {
+    startPx: number;
+    endPx: number;
+    static styles: lit.CSSResult;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-selection': DawSelectionElement;
+    }
+}
+
+declare class DawRecordButtonElement extends DawTransportButton {
+    private _isRecording;
+    private _targetRef;
+    private _onStart;
+    private _onComplete;
+    private _onError;
+    static styles: lit.CSSResultGroup[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _listenToTarget;
+    private _cleanupListeners;
+    render(): lit.TemplateResult<1>;
+    private _onClick;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'daw-record-button': DawRecordButtonElement;
+    }
+}
+
+declare class AudioResumeController implements ReactiveController {
+    private _host;
+    private _target;
+    private _attached;
+    private _generation;
+    /** CSS selector, or 'document'. When undefined, controller is inert. */
+    target?: string;
+    constructor(host: ReactiveControllerHost & HTMLElement);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    private _onGesture;
+    private _resolveTarget;
+    private _removeListeners;
+}
+
+/** Narrow engine contract for pointer interactions. */
+interface PointerEngineContract {
+    setSelection(start: number, end: number): void;
+    stop(): void;
+    play(time: number): void;
+    seek(time: number): void;
+    selectTrack(trackId: string | null): void;
+}
+
+export { AudioResumeController, type ClipDescriptor, DawClipElement, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawPauseButtonElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type LoadFilesResult, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type TrackDescriptor };