@dawcore/components 0.0.23 → 0.0.24

package/dist/index.d.ts

@@ -46,6 +46,87 @@ declare global {
     }
 }
 
+/** Range/display metadata for one effect parameter. */
+interface EffectParamDef {
+    min: number;
+    max: number;
+    step?: number;
+    /** 's', 'ms', 'Hz', 'dB', '%' … */
+    unit?: string;
+}
+/**
+ * A live, wired effect. `input`/`output` are the chain attachment points
+ * (the same node for single-node effects). `applyParams` updates AudioParams
+ * in place — the chain never rebuilds for parameter changes.
+ */
+interface EffectInstance {
+    input: AudioNode;
+    output: AudioNode;
+    applyParams: (params: Record<string, number>) => void;
+    dispose?: () => void;
+    /** Serializable snapshot of plugin-internal state (WAM getState). */
+    getState?: () => Promise<unknown>;
+    /** Builds the plugin's own GUI element (WAM createGui). GUI lifecycle is
+     *  independent of audio — hiding/destroying a GUI never stops processing. */
+    createGui?: () => Promise<HTMLElement>;
+    /** Releases a GUI element previously built by `createGui` (WAM destroyGui). */
+    destroyGui?: (gui: HTMLElement) => void;
+    /** Parameter metadata for the generic fallback panel (WAM getParameterInfo). */
+    getParameterInfo?: () => Promise<unknown>;
+}
+/** A registered effect type. `create` must work on any BaseAudioContext so
+ *  the same definitions serve offline rendering. */
+interface EffectDefinition {
+    label: string;
+    category: string;
+    defaults: Record<string, number>;
+    params: Record<string, EffectParamDef>;
+    /** Name of the wet/dry param, when the effect has one. Bypass zeroes it
+     *  (storing the original); effects without one are bypassed by
+     *  disconnection. */
+    wetParam?: string;
+    create: (audioContext: BaseAudioContext, params: Record<string, number>) => EffectInstance;
+}
+/** Public, serializable view of one chain entry. */
+interface EffectState {
+    id: string;
+    kind: string;
+    type: string;
+    params: Record<string, number>;
+    bypassed: boolean;
+    url?: string;
+    /** Present on Faust entries: the DSP source this effect was compiled from. */
+    source?: {
+        faust: string;
+    };
+    label?: string;
+    error?: string;
+}
+/** Persisted form of a chain — see README for the consumer contract. */
+type SerializedEffectEntry = {
+    kind: 'native';
+    type: string;
+    params: Record<string, number>;
+    bypassed: boolean;
+} | {
+    kind: 'wam';
+    /** Module URL for url-loaded plugins. Absent for Faust entries. */
+    url?: string;
+    bypassed: boolean;
+    state?: unknown;
+    /** Faust DSP source — restore recompiles in-browser via @dawcore/faust
+     *  instead of fetching a URL. */
+    faustDsp?: string;
+    /** Name the Faust entry was compiled under (restores the same label). */
+    faustName?: string;
+};
+/** Result of creating an effect via the registry. */
+interface CreatedEffect {
+    instance: EffectInstance;
+    params: Record<string, number>;
+    wetParam?: string;
+}
+
 declare class DawTrackElement extends LitElement {
     src: string;
     name: string;
@@ -59,6 +140,35 @@ declare class DawTrackElement extends LitElement {
     spectrogramConfig: SpectrogramConfig | null;
     readonly trackId: `${string}-${string}-${string}-${string}-${string}`;
     createRenderRoot(): this;
+    addEffect(type: string, params?: Record<string, number>): string;
+    /** Load a WAM plugin (via the optional @dawcore/wam peer) into this track's chain. */
+    addWamPlugin(url: string, initialState?: unknown): Promise<string>;
+    /**
+     * Compile Faust DSP source in the browser (via the optional @dawcore/faust
+     * peer) and add the resulting WAM to this track's chain. Compile errors
+     * keep their Faust line/column diagnostics and leave the chain untouched.
+     */
+    addFaustEffect(dspCode: string, options?: {
+        name?: string;
+    }): Promise<string>;
+    /** Snapshot this track's chain in its persisted form (see dawcore README). */
+    getEffectsState(): Promise<SerializedEffectEntry[]>;
+    /** Replace this track's chain with a persisted snapshot. */
+    setEffectsState(entries: SerializedEffectEntry[]): Promise<void>;
+    /**
+     * Open (lazily creating) the GUI for one of this track's effects into a
+     * consumer-provided container. Closing hides without interrupting audio;
+     * the element is cached for reopen. See <daw-editor>.openEffectGui.
+     */
+    openEffectGui(effectId: string, container: HTMLElement): Promise<HTMLElement>;
+    /** Hide an effect's GUI (cached for reopen — never destroys). */
+    closeEffectGui(effectId: string): void;
+    removeEffect(effectId: string): void;
+    setEffectParams(effectId: string, params: Record<string, number>): void;
+    setEffectBypassed(effectId: string, bypassed: boolean): void;
+    moveEffect(effectId: string, newIndex: number): void;
+    get effects(): EffectState[];
+    private _effectsEditor;
     connectedCallback(): void;
     private _hasRendered;
     updated(changed: PropertyValues): void;
@@ -826,6 +936,45 @@ interface DawSpectrogramErrorDetail {
     generation: number;
     error: Error;
 }
+interface DawEffectAddDetail {
+    effectId: string;
+    kind: string;
+    type: string;
+    params: Record<string, number>;
+    index: number;
+    /** Plugin source URL (kind 'wam', url-loaded). */
+    url?: string;
+    /** Faust DSP source (kind 'wam', compiled in-browser via @dawcore/faust). */
+    source?: {
+        faust: string;
+    };
+}
+interface DawEffectRemoveDetail {
+    effectId: string;
+}
+interface DawEffectChangeDetail {
+    effectId: string;
+    params: Record<string, number>;
+}
+interface DawEffectBypassDetail {
+    effectId: string;
+    bypassed: boolean;
+}
+interface DawEffectReorderDetail {
+    effectId: string;
+    fromIndex: number;
+    toIndex: number;
+}
+interface DawEffectErrorDetail {
+    effectId: string;
+    /** Plugin source URL (absent for Faust entries, which have no URL). */
+    url?: string;
+    /** Faust DSP source of the failed entry, when applicable. */
+    source?: {
+        faust: string;
+    };
+    message: string;
+}
 interface DawEventMap {
     'daw-selection': CustomEvent<DawSelectionDetail>;
     'daw-seek': CustomEvent<DawSeekDetail>;
@@ -855,6 +1004,12 @@ interface DawEventMap {
     'daw-clip-split': CustomEvent<DawClipSplitDetail>;
     'daw-spectrogram-ready': CustomEvent<DawSpectrogramReadyDetail>;
     'daw-spectrogram-error': CustomEvent<DawSpectrogramErrorDetail>;
+    'daw-effect-add': CustomEvent<DawEffectAddDetail>;
+    'daw-effect-remove': CustomEvent<DawEffectRemoveDetail>;
+    'daw-effect-change': CustomEvent<DawEffectChangeDetail>;
+    'daw-effect-bypass': CustomEvent<DawEffectBypassDetail>;
+    'daw-effect-reorder': CustomEvent<DawEffectReorderDetail>;
+    'daw-effect-error': CustomEvent<DawEffectErrorDetail>;
 }
 type DawEvent<K extends keyof DawEventMap> = DawEventMap[K];
 interface LoadFilesResult {
@@ -887,6 +1042,42 @@ interface MidiLoaderHost {
     querySelectorAll(selector: string): NodeListOf<Element>;
 }
 
+interface ExportOptions {
+    /** Default: the host's sample rate. */
+    sampleRate?: number;
+    /** Window start in seconds. Default: 0. */
+    startTime?: number;
+    /** Window length in seconds. Default: host duration minus startTime. */
+    duration?: number;
+    /** Default: 2 (stereo). */
+    channels?: 1 | 2;
+}
+interface ExportClip {
+    startSample: number;
+    durationSamples: number;
+    offsetSamples: number;
+    sampleRate: number;
+    gain?: number;
+    audioBuffer?: AudioBuffer;
+}
+interface ExportTrack {
+    id: string;
+    volume: number;
+    pan: number;
+    muted: boolean;
+    soloed: boolean;
+    clips: ExportClip[];
+}
+/** What the editor provides to the export pipeline. */
+interface ExportAudioHost {
+    effectiveSampleRate: number;
+    /** Natural session duration in seconds. */
+    duration: number;
+    tracks: ExportTrack[];
+    getMasterEffectsState(): Promise<SerializedEffectEntry[]>;
+    getTrackEffectsState(trackId: string): Promise<SerializedEffectEntry[]>;
+}
+
 declare class DawEditorElement extends LitElement implements MidiLoaderHost {
     get samplesPerPixel(): number;
     set samplesPerPixel(value: number);
@@ -989,6 +1180,57 @@ declare class DawEditorElement extends LitElement implements MidiLoaderHost {
     set adapter(value: PlayoutAdapter | null);
     get adapter(): PlayoutAdapter | null;
     private _externalAdapter;
+    private _effectsManager;
+    private get _effects();
+    /** Master effects chain — inserted between the master bus and the destination. */
+    addEffect(type: string, params?: Record<string, number>): string;
+    removeEffect(effectId: string): void;
+    setEffectParams(effectId: string, params: Record<string, number>): void;
+    setEffectBypassed(effectId: string, bypassed: boolean): void;
+    moveEffect(effectId: string, newIndex: number): void;
+    get effects(): EffectState[];
+    /** Load a WAM plugin (via the optional @dawcore/wam peer) into the master chain. */
+    addWamPlugin(url: string, initialState?: unknown): Promise<string>;
+    /**
+     * Compile Faust DSP source in the browser (via the optional @dawcore/faust
+     * peer) and add the resulting WAM to the master chain. Compile errors keep
+     * their Faust line/column diagnostics and leave the chain untouched.
+     */
+    addFaustEffect(dspCode: string, options?: {
+        name?: string;
+    }): Promise<string>;
+    /**
+     * Open (lazily creating) the GUI for a master-chain effect into a
+     * consumer-provided container. WAM plugins mount their own GUI; plugins
+     * without one — and native effects — get the generic parameter panel from
+     * @dawcore/wam. The element is cached: closeEffectGui hides it without
+     * interrupting audio, reopening remounts the same element.
+     */
+    openEffectGui(effectId: string, container: HTMLElement): Promise<HTMLElement>;
+    /** Hide a master-chain effect's GUI (cached for reopen — never destroys). */
+    closeEffectGui(effectId: string): void;
+    /** Snapshot the master chain in its persisted form (see dawcore README). */
+    getEffectsState(): Promise<SerializedEffectEntry[]>;
+    /** Replace the master chain with a persisted snapshot. */
+    setEffectsState(entries: SerializedEffectEntry[]): Promise<void>;
+    /**
+     * Render the session offline through all effect chains (per-track +
+     * master), including WAM plugins (re-instantiated on the offline context
+     * with their live state). Returns the rendered AudioBuffer.
+     */
+    exportAudio(options?: ExportOptions): Promise<AudioBuffer>;
+    /** Internal — <daw-track> effects API delegates here (dawcore-internal contract). */
+    _trackAddEffect(trackId: string, target: EventTarget, type: string, params?: Record<string, number>): string;
+    _trackEffectOp(trackId: string, target: EventTarget, op: 'remove' | 'setParams' | 'setBypassed' | 'move', effectId: string, arg?: any): void;
+    _trackEffects(trackId: string): EffectState[];
+    _trackAddWamPlugin(trackId: string, target: EventTarget, url: string, initialState?: unknown): Promise<string>;
+    _trackAddFaustEffect(trackId: string, target: EventTarget, dspCode: string, options?: {
+        name?: string;
+    }): Promise<string>;
+    _trackOpenEffectGui(trackId: string, target: EventTarget, effectId: string, container: HTMLElement): Promise<HTMLElement>;
+    _trackCloseEffectGui(_trackId: string, effectId: string): void;
+    _trackGetEffectsState(trackId: string): Promise<SerializedEffectEntry[]>;
+    _trackSetEffectsState(trackId: string, target: EventTarget, entries: SerializedEffectEntry[]): Promise<void>;
     get audioContext(): AudioContext;
     _engine: PlaylistEngine | null;
     private _warnedMissingTicksToSeconds;
@@ -1496,4 +1738,9 @@ interface SplitHost {
  */
 declare function splitAtPlayhead(host: SplitHost): boolean;
 
-export { AudioResumeController, type ClipConfig, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, type DawClipConnectedDetail, DawClipElement, type DawClipErrorDetail, type DawClipIdDetail, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, type DawClipUpdateDetail, DawEditorElement, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawGridElement, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPianoRollElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawSpectrogramElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type DomClipDescriptor, type DropClipDescriptor, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, SpectrogramController, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackConfig, type TrackDescriptor, type TrackRenderMode, type UndoShortcutMap, type WaveformSegment, isDomClip, splitAtPlayhead };
+declare function registerEffect(type: string, definition: EffectDefinition): void;
+/** A copy — mutating the returned map does not affect the registry. */
+declare function getEffectDefinitions(): Map<string, EffectDefinition>;
+declare function createEffectInstance(type: string, audioContext: BaseAudioContext, params?: Record<string, number>): CreatedEffect;
+
+export { AudioResumeController, type ClipConfig, type ClipDescriptor, type ClipEngineContract, ClipPointerHandler, type ClipPointerHost, type DawClipConnectedDetail, DawClipElement, type DawClipErrorDetail, type DawClipIdDetail, type DawClipMoveDetail, type DawClipSplitDetail, type DawClipTrimDetail, type DawClipUpdateDetail, DawEditorElement, type DawEffectAddDetail, type DawEffectBypassDetail, type DawEffectChangeDetail, type DawEffectErrorDetail, type DawEffectRemoveDetail, type DawEffectReorderDetail, type DawErrorDetail, type DawEvent, type DawEventMap, type DawFilesLoadErrorDetail, DawGridElement, DawKeyboardShortcutsElement, DawPauseButtonElement, DawPianoRollElement, DawPlayButtonElement, DawPlayheadElement, DawRecordButtonElement, type DawRecordingCompleteDetail, type DawRecordingErrorDetail, type DawRecordingStartDetail, DawRulerElement, type DawSeekDetail, type DawSelectionDetail, DawSelectionElement, DawSpectrogramElement, DawStopButtonElement, type DawTrackConnectedDetail, type DawTrackControlDetail, DawTrackControlsElement, DawTrackElement, type DawTrackErrorDetail, type DawTrackIdDetail, type DawTrackRemoveDetail, type DawTrackSelectDetail, DawTransportButton, DawTransportElement, DawWaveformElement, type DomClipDescriptor, type DropClipDescriptor, type EffectDefinition, type EffectInstance, type EffectParamDef, type EffectState, type ExportAudioHost, type ExportOptions, type KeyBinding, type LoadFilesResult, type PlaybackShortcutMap, type PointerEngineContract, RecordingController, type RecordingOptions, type RecordingSession, type SerializedEffectEntry, SpectrogramController, type SplitEngineContract, type SplitHost, type SplittingShortcutMap, type TrackConfig, type TrackDescriptor, type TrackRenderMode, type UndoShortcutMap, type WaveformSegment, createEffectInstance, getEffectDefinitions, isDomClip, registerEffect, splitAtPlayhead };