@waveform-playlist/playout 5.0.0-alpha.0

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,224 @@
+import { Gain, ToneAudioNode, Volume, BaseContext, Context } from 'tone';
+import { Fade, Track } from '@waveform-playlist/core';
+
+type TrackEffectsFunction = (graphEnd: Gain, masterGainNode: ToneAudioNode, isOffline: boolean) => void | (() => void);
+interface ClipInfo {
+    buffer: AudioBuffer;
+    startTime: number;
+    duration: number;
+    offset: number;
+    fadeIn?: Fade;
+    fadeOut?: Fade;
+    gain: number;
+}
+interface ToneTrackOptions {
+    buffer?: AudioBuffer;
+    clips?: ClipInfo[];
+    track: Track;
+    effects?: TrackEffectsFunction;
+    destination?: ToneAudioNode;
+}
+declare class ToneTrack {
+    private clips;
+    private volumeNode;
+    private panNode;
+    private muteGain;
+    private track;
+    private effectsCleanup?;
+    private onStopCallback?;
+    private activePlayers;
+    constructor(options: ToneTrackOptions);
+    /**
+     * Schedule fade envelopes for a clip at the given start time
+     */
+    private scheduleFades;
+    private gainToDb;
+    setVolume(gain: number): void;
+    setPan(pan: number): void;
+    setMute(muted: boolean): void;
+    setSolo(soloed: boolean): void;
+    play(when?: number, offset?: number, duration?: number): void;
+    pause(): void;
+    stop(when?: number): void;
+    dispose(): void;
+    get id(): string;
+    get duration(): number;
+    get buffer(): AudioBuffer;
+    get isPlaying(): boolean;
+    get muted(): boolean;
+    get startTime(): number;
+    setOnStopCallback(callback: () => void): void;
+}
+
+type EffectsFunction = (masterGainNode: Volume, destination: ToneAudioNode, isOffline: boolean) => void | (() => void);
+interface TonePlayoutOptions {
+    tracks?: ToneTrack[];
+    masterGain?: number;
+    effects?: EffectsFunction;
+}
+declare class TonePlayout {
+    private tracks;
+    private masterVolume;
+    private isInitialized;
+    private soloedTracks;
+    private manualMuteState;
+    private effectsCleanup?;
+    private onPlaybackCompleteCallback?;
+    private activeTracks;
+    private playbackSessionId;
+    constructor(options?: TonePlayoutOptions);
+    private gainToDb;
+    init(): Promise<void>;
+    addTrack(trackOptions: ToneTrackOptions): ToneTrack;
+    removeTrack(trackId: string): void;
+    getTrack(trackId: string): ToneTrack | undefined;
+    play(when?: number, offset?: number, duration?: number): void;
+    pause(): void;
+    stop(): void;
+    setMasterGain(gain: number): void;
+    setSolo(trackId: string, soloed: boolean): void;
+    private updateSoloMuting;
+    setMute(trackId: string, muted: boolean): void;
+    getCurrentTime(): number;
+    seekTo(time: number): void;
+    dispose(): void;
+    get context(): BaseContext;
+    get sampleRate(): number;
+    setOnPlaybackComplete(callback: () => void): void;
+}
+
+/**
+ * Global AudioContext Manager
+ *
+ * Provides a single AudioContext shared across the entire application.
+ * This context is used by Tone.js for playback and by all recording/monitoring hooks.
+ *
+ * Uses Tone.js's Context class which wraps standardized-audio-context for
+ * cross-browser compatibility (fixes Firefox AudioListener issues).
+ */
+
+/**
+ * Get the global Tone.js Context
+ * This is the main context for cross-browser audio operations.
+ * Use context.createAudioWorkletNode(), context.createMediaStreamSource(), etc.
+ * @returns The Tone.js Context instance
+ */
+declare function getGlobalContext(): Context;
+/**
+ * Get or create the global AudioContext
+ * Uses Tone.js Context for cross-browser compatibility
+ * @returns The global AudioContext instance (rawContext from Tone.Context)
+ */
+declare function getGlobalAudioContext(): AudioContext;
+/**
+ * @deprecated Use getGlobalContext() instead
+ * Get the Tone.js Context's rawContext typed as IAudioContext
+ * @returns The rawContext cast as IAudioContext
+ */
+declare function getGlobalToneContext(): Context;
+/**
+ * Resume the global AudioContext if it's suspended
+ * Should be called in response to a user gesture (e.g., button click)
+ * @returns Promise that resolves when context is running
+ */
+declare function resumeGlobalAudioContext(): Promise<void>;
+/**
+ * Get the current state of the global AudioContext
+ * @returns The AudioContext state ('suspended', 'running', or 'closed')
+ */
+declare function getGlobalAudioContextState(): AudioContextState;
+/**
+ * Close the global AudioContext
+ * Should only be called when the application is shutting down
+ */
+declare function closeGlobalAudioContext(): Promise<void>;
+
+/**
+ * MediaStreamSource Manager
+ *
+ * Manages MediaStreamAudioSourceNode instances to ensure only one source
+ * is created per MediaStream per AudioContext.
+ *
+ * Web Audio API constraint: You can only create one MediaStreamAudioSourceNode
+ * per MediaStream per AudioContext. Multiple attempts will fail or disconnect
+ * previous sources.
+ *
+ * This manager ensures a single source is shared across multiple consumers
+ * (e.g., AnalyserNode for VU meter, AudioWorkletNode for recording).
+ *
+ * NOTE: With Tone.js Context, you can also use context.createMediaStreamSource()
+ * directly, which handles cross-browser compatibility internally.
+ */
+/**
+ * Get or create a MediaStreamAudioSourceNode for the given stream
+ *
+ * @param stream - The MediaStream to create a source for
+ * @returns MediaStreamAudioSourceNode that can be connected to multiple nodes
+ *
+ * @example
+ * ```typescript
+ * const source = getMediaStreamSource(stream);
+ *
+ * // Multiple consumers can connect to the same source
+ * source.connect(analyserNode);  // For VU meter
+ * source.connect(workletNode);   // For recording
+ * ```
+ */
+declare function getMediaStreamSource(stream: MediaStream): MediaStreamAudioSourceNode;
+/**
+ * Manually release a MediaStreamSource
+ *
+ * Normally you don't need to call this - cleanup happens automatically
+ * when the stream ends. Only call this if you need to force cleanup.
+ *
+ * @param stream - The MediaStream to release the source for
+ */
+declare function releaseMediaStreamSource(stream: MediaStream): void;
+/**
+ * Check if a MediaStreamSource exists for the given stream
+ *
+ * @param stream - The MediaStream to check
+ * @returns true if a source exists for this stream
+ */
+declare function hasMediaStreamSource(stream: MediaStream): boolean;
+
+/**
+ * Fade utilities for Web Audio API
+ *
+ * Applies fade in/out envelopes to AudioParam (typically gain)
+ * using various curve types.
+ */
+type FadeType = 'linear' | 'logarithmic' | 'exponential' | 'sCurve';
+/**
+ * Simple fade configuration - just duration and type
+ */
+interface FadeConfig {
+    /** Duration of the fade in seconds */
+    duration: number;
+    /** Type of fade curve (default: 'linear') */
+    type?: FadeType;
+}
+/**
+ * Apply a fade in to an AudioParam
+ *
+ * @param param - The AudioParam to apply the fade to (usually gain)
+ * @param startTime - When the fade starts (in seconds, AudioContext time)
+ * @param duration - Duration of the fade in seconds
+ * @param type - Type of fade curve
+ * @param startValue - Starting value (default: 0)
+ * @param endValue - Ending value (default: 1)
+ */
+declare function applyFadeIn(param: AudioParam, startTime: number, duration: number, type?: FadeType, startValue?: number, endValue?: number): void;
+/**
+ * Apply a fade out to an AudioParam
+ *
+ * @param param - The AudioParam to apply the fade to (usually gain)
+ * @param startTime - When the fade starts (in seconds, AudioContext time)
+ * @param duration - Duration of the fade in seconds
+ * @param type - Type of fade curve
+ * @param startValue - Starting value (default: 1)
+ * @param endValue - Ending value (default: 0)
+ */
+declare function applyFadeOut(param: AudioParam, startTime: number, duration: number, type?: FadeType, startValue?: number, endValue?: number): void;
+
+export { type EffectsFunction, type FadeConfig, type FadeType, TonePlayout, type TonePlayoutOptions, ToneTrack, type ToneTrackOptions, type TrackEffectsFunction, applyFadeIn, applyFadeOut, closeGlobalAudioContext, getGlobalAudioContext, getGlobalAudioContextState, getGlobalContext, getGlobalToneContext, getMediaStreamSource, hasMediaStreamSource, releaseMediaStreamSource, resumeGlobalAudioContext };

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+import { Gain, ToneAudioNode, Volume, BaseContext, Context } from 'tone';
+import { Fade, Track } from '@waveform-playlist/core';
+
+type TrackEffectsFunction = (graphEnd: Gain, masterGainNode: ToneAudioNode, isOffline: boolean) => void | (() => void);
+interface ClipInfo {
+    buffer: AudioBuffer;
+    startTime: number;
+    duration: number;
+    offset: number;
+    fadeIn?: Fade;
+    fadeOut?: Fade;
+    gain: number;
+}
+interface ToneTrackOptions {
+    buffer?: AudioBuffer;
+    clips?: ClipInfo[];
+    track: Track;
+    effects?: TrackEffectsFunction;
+    destination?: ToneAudioNode;
+}
+declare class ToneTrack {
+    private clips;
+    private volumeNode;
+    private panNode;
+    private muteGain;
+    private track;
+    private effectsCleanup?;
+    private onStopCallback?;
+    private activePlayers;
+    constructor(options: ToneTrackOptions);
+    /**
+     * Schedule fade envelopes for a clip at the given start time
+     */
+    private scheduleFades;
+    private gainToDb;
+    setVolume(gain: number): void;
+    setPan(pan: number): void;
+    setMute(muted: boolean): void;
+    setSolo(soloed: boolean): void;
+    play(when?: number, offset?: number, duration?: number): void;
+    pause(): void;
+    stop(when?: number): void;
+    dispose(): void;
+    get id(): string;
+    get duration(): number;
+    get buffer(): AudioBuffer;
+    get isPlaying(): boolean;
+    get muted(): boolean;
+    get startTime(): number;
+    setOnStopCallback(callback: () => void): void;
+}
+
+type EffectsFunction = (masterGainNode: Volume, destination: ToneAudioNode, isOffline: boolean) => void | (() => void);
+interface TonePlayoutOptions {
+    tracks?: ToneTrack[];
+    masterGain?: number;
+    effects?: EffectsFunction;
+}
+declare class TonePlayout {
+    private tracks;
+    private masterVolume;
+    private isInitialized;
+    private soloedTracks;
+    private manualMuteState;
+    private effectsCleanup?;
+    private onPlaybackCompleteCallback?;
+    private activeTracks;
+    private playbackSessionId;
+    constructor(options?: TonePlayoutOptions);
+    private gainToDb;
+    init(): Promise<void>;
+    addTrack(trackOptions: ToneTrackOptions): ToneTrack;
+    removeTrack(trackId: string): void;
+    getTrack(trackId: string): ToneTrack | undefined;
+    play(when?: number, offset?: number, duration?: number): void;
+    pause(): void;
+    stop(): void;
+    setMasterGain(gain: number): void;
+    setSolo(trackId: string, soloed: boolean): void;
+    private updateSoloMuting;
+    setMute(trackId: string, muted: boolean): void;
+    getCurrentTime(): number;
+    seekTo(time: number): void;
+    dispose(): void;
+    get context(): BaseContext;
+    get sampleRate(): number;
+    setOnPlaybackComplete(callback: () => void): void;
+}
+
+/**
+ * Global AudioContext Manager
+ *
+ * Provides a single AudioContext shared across the entire application.
+ * This context is used by Tone.js for playback and by all recording/monitoring hooks.
+ *
+ * Uses Tone.js's Context class which wraps standardized-audio-context for
+ * cross-browser compatibility (fixes Firefox AudioListener issues).
+ */
+
+/**
+ * Get the global Tone.js Context
+ * This is the main context for cross-browser audio operations.
+ * Use context.createAudioWorkletNode(), context.createMediaStreamSource(), etc.
+ * @returns The Tone.js Context instance
+ */
+declare function getGlobalContext(): Context;
+/**
+ * Get or create the global AudioContext
+ * Uses Tone.js Context for cross-browser compatibility
+ * @returns The global AudioContext instance (rawContext from Tone.Context)
+ */
+declare function getGlobalAudioContext(): AudioContext;
+/**
+ * @deprecated Use getGlobalContext() instead
+ * Get the Tone.js Context's rawContext typed as IAudioContext
+ * @returns The rawContext cast as IAudioContext
+ */
+declare function getGlobalToneContext(): Context;
+/**
+ * Resume the global AudioContext if it's suspended
+ * Should be called in response to a user gesture (e.g., button click)
+ * @returns Promise that resolves when context is running
+ */
+declare function resumeGlobalAudioContext(): Promise<void>;
+/**
+ * Get the current state of the global AudioContext
+ * @returns The AudioContext state ('suspended', 'running', or 'closed')
+ */
+declare function getGlobalAudioContextState(): AudioContextState;
+/**
+ * Close the global AudioContext
+ * Should only be called when the application is shutting down
+ */
+declare function closeGlobalAudioContext(): Promise<void>;
+
+/**
+ * MediaStreamSource Manager
+ *
+ * Manages MediaStreamAudioSourceNode instances to ensure only one source
+ * is created per MediaStream per AudioContext.
+ *
+ * Web Audio API constraint: You can only create one MediaStreamAudioSourceNode
+ * per MediaStream per AudioContext. Multiple attempts will fail or disconnect
+ * previous sources.
+ *
+ * This manager ensures a single source is shared across multiple consumers
+ * (e.g., AnalyserNode for VU meter, AudioWorkletNode for recording).
+ *
+ * NOTE: With Tone.js Context, you can also use context.createMediaStreamSource()
+ * directly, which handles cross-browser compatibility internally.
+ */
+/**
+ * Get or create a MediaStreamAudioSourceNode for the given stream
+ *
+ * @param stream - The MediaStream to create a source for
+ * @returns MediaStreamAudioSourceNode that can be connected to multiple nodes
+ *
+ * @example
+ * ```typescript
+ * const source = getMediaStreamSource(stream);
+ *
+ * // Multiple consumers can connect to the same source
+ * source.connect(analyserNode);  // For VU meter
+ * source.connect(workletNode);   // For recording
+ * ```
+ */
+declare function getMediaStreamSource(stream: MediaStream): MediaStreamAudioSourceNode;
+/**
+ * Manually release a MediaStreamSource
+ *
+ * Normally you don't need to call this - cleanup happens automatically
+ * when the stream ends. Only call this if you need to force cleanup.
+ *
+ * @param stream - The MediaStream to release the source for
+ */
+declare function releaseMediaStreamSource(stream: MediaStream): void;
+/**
+ * Check if a MediaStreamSource exists for the given stream
+ *
+ * @param stream - The MediaStream to check
+ * @returns true if a source exists for this stream
+ */
+declare function hasMediaStreamSource(stream: MediaStream): boolean;
+
+/**
+ * Fade utilities for Web Audio API
+ *
+ * Applies fade in/out envelopes to AudioParam (typically gain)
+ * using various curve types.
+ */
+type FadeType = 'linear' | 'logarithmic' | 'exponential' | 'sCurve';
+/**
+ * Simple fade configuration - just duration and type
+ */
+interface FadeConfig {
+    /** Duration of the fade in seconds */
+    duration: number;
+    /** Type of fade curve (default: 'linear') */
+    type?: FadeType;
+}
+/**
+ * Apply a fade in to an AudioParam
+ *
+ * @param param - The AudioParam to apply the fade to (usually gain)
+ * @param startTime - When the fade starts (in seconds, AudioContext time)
+ * @param duration - Duration of the fade in seconds
+ * @param type - Type of fade curve
+ * @param startValue - Starting value (default: 0)
+ * @param endValue - Ending value (default: 1)
+ */
+declare function applyFadeIn(param: AudioParam, startTime: number, duration: number, type?: FadeType, startValue?: number, endValue?: number): void;
+/**
+ * Apply a fade out to an AudioParam
+ *
+ * @param param - The AudioParam to apply the fade to (usually gain)
+ * @param startTime - When the fade starts (in seconds, AudioContext time)
+ * @param duration - Duration of the fade in seconds
+ * @param type - Type of fade curve
+ * @param startValue - Starting value (default: 1)
+ * @param endValue - Ending value (default: 0)
+ */
+declare function applyFadeOut(param: AudioParam, startTime: number, duration: number, type?: FadeType, startValue?: number, endValue?: number): void;
+
+export { type EffectsFunction, type FadeConfig, type FadeType, TonePlayout, type TonePlayoutOptions, ToneTrack, type ToneTrackOptions, type TrackEffectsFunction, applyFadeIn, applyFadeOut, closeGlobalAudioContext, getGlobalAudioContext, getGlobalAudioContextState, getGlobalContext, getGlobalToneContext, getMediaStreamSource, hasMediaStreamSource, releaseMediaStreamSource, resumeGlobalAudioContext };