@pexip/media-processor 16.7.1 → 17.1.0

package/dist/main/types.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Interface for Point consist of coordinates x and y
+ *
+ * @alpha
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export type Rect = Point & Size;
+export interface Frame extends Size {
+    source: Canvas | HTMLVideoElement | HTMLImageElement;
+}
+/**
+ * Unsubscribe the subscription
+ */
+export type Unsubscribe = () => void;
+/**
+ * Same as {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioBuffer | AudioBuffer}
+ * Or the return from {@link https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getFloatFrequencyData | AnalyserNode.getFloatFrequencyData()}
+ */
+export type AudioBufferFloats = Float32Array;
+/**
+ * Same as the return from {@link https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData | AnalyserNode.getByteFrequencyData()}
+ */
+export type AudioBufferBytes = Uint8Array;
+/**
+ * Audio samples from each channel, either in float or bytes form
+ *
+ * @example
+ *
+ * ```
+ * |       |            | Sample Frame 1 | Sample Frame 2 | Sample Frame 3 |
+ * | Input | Channel L: | sample 1       | sample 2       | sample 3       |
+ * |       | Channel R: | sample 1       | sample 2       | sample 3       |
+ * ```
+ * We can get 2 `AudioSamples` from "Channel L" and "Channel R" from "Input"
+ */
+export type AudioSamples = number[] | AudioBufferFloats | AudioBufferBytes;
+/**
+ * Data structure for the audio statistics while processing
+ */
+export interface AudioStats {
+    /**
+     * Indicating the audio is silent when it is set to `true`
+     */
+    silent: boolean;
+    /**
+     * Indicating the audio is mono when it is set to `true`
+     *
+     * `undefined` means cannot-not-tell.
+     */
+    mono?: boolean;
+    /**
+     * Indicating the audio is low volume when it is set to `true`
+     */
+    lowVolume: boolean;
+    /**
+     * Indicating the audio is clipping when it is set to `true`
+     */
+    clipping: boolean;
+    /**
+     * Peak gain value
+     */
+    peak: number;
+    /**
+     * Global rms
+     */
+    rms: number;
+    /**
+     * Maximum running RMS value
+     */
+    maxRms: number;
+    /**
+     * Maximum Clip count
+     */
+    maxClipCount: number;
+    /**
+     * Value of sum squared sample used for RMS calculation
+     */
+    sumSquare: number;
+    /**
+     * Value of sum number of sample used for RMS calculation
+     */
+    sumLength: number;
+}
+/**
+ * Stats options for calculating the audio stats
+ */
+export interface StatsOptions {
+    /**
+     * Used for the analysis
+     */
+    samples: AudioSamples;
+    /**
+     * this will be used for accumulation
+     */
+    baseStats?: AudioStats;
+    /**
+     * Threshold for clipping
+     *
+     * @defaultValue
+     * `1.0` as assuming it is float value
+     */
+    clipThreshold?: number;
+    /**
+     * Threshold for silent
+     *
+     * @defaultValue
+     * 1.0 / 32767
+     */
+    silentThreshold?: number;
+}
+export interface SubscribableOptions {
+    updateFrequency?: number;
+}
+export interface WorkletMessagePortOptions<T> {
+    messageHandler: (message: T) => void;
+    errorHandler?: (event: Event) => void;
+}
+export interface AnalyzerSubscribableOptions extends SubscribableOptions, WorkletMessagePortOptions<Analyzer> {
+}
+/**
+ * A wrapper for the Denoise wasm module
+ */
+export interface Denoise {
+    vad(channel: number): number;
+    free(): void;
+    pipe(inputs: Float32Array[][], outputs: Float32Array[][]): void;
+}
+export type NodeConnectionAction = 'connect' | 'disconnect';
+export type BaseAudioNode = Pick<AudioNode, NodeConnectionAction>;
+export interface Gain extends BaseAudioNode {
+    readonly node: GainNode;
+    mute: boolean;
+}
+export interface Analyzer extends BaseAudioNode {
+    readonly node: AnalyserNode;
+    readonly frequencyBinCount: AnalyserNode['frequencyBinCount'];
+    fftSize: AnalyserNode['fftSize'];
+    minDecibels: AnalyserNode['minDecibels'];
+    maxDecibels: AnalyserNode['maxDecibels'];
+    smoothingTimeConstant: AnalyserNode['smoothingTimeConstant'];
+    /**
+     * Copies the current waveform, or time-domain, data into a Uint8Array
+     * (unsigned byte array) passed into it.
+     *
+     * If the array has fewer elements than the `AnalyserNode.fftSize`, excess
+     * elements are dropped.
+     * If it has more elements than needed, excess elements are ignored.
+     *
+     * @param buffer - Use provided buffer instead of creating a new one
+     *
+     * @remarks
+     * The bytes versions are not cheaper than the float version but provided
+     * for convenient: the byte version are computed from the float version,
+     * using simple quantization to 2^8 values
+     * ref. https://padenot.github.io/web-audio-perf/#analysernode
+     */
+    getByteTimeDomainData(buffer: Uint8Array): void;
+    /**
+     * Copies the current frequency data into a Uint8Array (unsigned byte array)
+     * passed into it.
+     *
+     * The frequency data is composed of integers on a scale from 0 to 255.
+     *
+     * @param buffer - Use provided buffer instead of creating a new one
+     *
+     * @remarks
+     * The bytes versions are not cheaper than the float version but provided
+     * for convenient: the byte version are computed from the float version,
+     * using simple quantization to 2^8 values
+     * ref. https://padenot.github.io/web-audio-perf/#analysernode
+     */
+    getByteFrequencyData(buffer: Uint8Array): void;
+    /**
+     * Copies the current waveform, or time-domain, data into Float32Array
+     * passed into it
+     *
+     * @param buffer - Use provided buffer instead of creating a new one
+     *
+     * @remarks
+     * The buffer size should be the same as `AnalyserNode.fftSize`
+     */
+    getFloatTimeDomainData(buffer: Float32Array): void;
+    /**
+     * Copies the current waveform, or time-domain, data into Float32Array
+     * passed into it
+     *
+     * @param buffer - Use provided buffer instead of creating a new one
+     *
+     * @remarks
+     * The buffer size should be the same as `AnalyserNode.frequencyBinCount`
+     */
+    getFloatFrequencyData(buffer: Float32Array): void;
+    /**
+     * Utility function to get the average volume from `getByteFrequencyData`
+     *
+     * @param options - `buffer`, use provided buffer instead of creating a new
+     * one, and `beforeAlter`, will analyze the raw data before any changes to
+     * the audio signal when it is set to `true`
+     *
+     * @remarks
+     * This is a better option when you only need to get the volume in terms of
+     * performance and complexity.
+     */
+    getAverageVolume(buffer: Float32Array): number;
+}
+export interface AudioNodeProps<T extends AudioNode, R extends BaseAudioNode> {
+    name: string;
+    node: R | undefined;
+    audioNode: T | undefined;
+    outputs: WeakSet<AudioNodeInit | AudioParam>;
+}
+export type AudioNodeParam = BaseAudioNode | AudioParam;
+export type Node = AudioNode | AudioParam;
+export type Nodes = Node[];
+export type ConnectParamBaseType = AudioParam | BaseAudioNode;
+export type ConnectInitParamBaseType = AudioParam | AudioNodeInit;
+export type ConnectParamType = ConnectParamBaseType | undefined;
+export type ConnectInitParamType = ConnectInitParamBaseType | undefined;
+type AudioNodeInputIndex = number | undefined;
+type AudioNodeOutputIndex = number | undefined;
+export type ConnectParamBase<T extends ConnectParamType | ConnectInitParamType> = [
+    T,
+    T extends undefined ? undefined : AudioNodeOutputIndex,
+    T extends undefined ? undefined : AudioNodeInputIndex
+] | T;
+export type AudioNodeConnectParam = ConnectParamBase<ConnectParamType>;
+export type AudioNodeInitConnectParam = ConnectParamBase<ConnectInitParamType>;
+export type AudioNodeInitConnection = AudioNodeInitConnectParam[];
+export type AudioNodeInitConnections = AudioNodeInitConnection[];
+export interface AudioNodeInit<T extends AudioNode = AudioNode, R extends BaseAudioNode = BaseAudioNode> extends Readonly<AudioNodeProps<T, R>> {
+    /**
+     * Internal function to create the actual AudioNode.
+     * Should ONLY be CALLED inside an AudioGraph
+     *
+     * @param context - Audio Context to use
+     * @param prevNode - The input AudioNode for connection
+     *
+     * @internal
+     */
+    create(context: AudioContext, prevNode?: AudioNode): [T, R];
+    /**
+     * Internal function to connect a signal output
+     * Should ONLY be CALLED inside an AudioGraph
+     *
+     * @param param - The init to connect
+     *
+     * @internal
+     */
+    connect(param: AudioNodeInitConnectParam | undefined): void;
+    /**
+     * Internal function to disconnect a signal output
+     * Should ONLY be CALLED inside an AudioGraph
+     *
+     * @param param - The init to disconnect
+     *
+     * @internal
+     */
+    disconnect(param: AudioNodeInitConnectParam | undefined): void;
+    /**
+     * Check if there is a connection to the provided init
+     * @param init - AudioNodeInit
+     */
+    hasConnectedTo(init: AudioNodeInit | AudioParam): boolean;
+    /**
+     * Internal function to release the node init resources
+     * Should ONLY be CALLED inside an AudioGraph
+     *
+     * @internal
+     */
+    release(): void;
+    toJSON?: () => unknown;
+}
+export type MediaStreamAudioSourceNodeInit = AudioNodeInit<MediaStreamAudioSourceNode, MediaStreamAudioSourceNode>;
+export type MediaElementAudioSourceNodeInit = AudioNodeInit<MediaElementAudioSourceNode, MediaElementAudioSourceNode>;
+export type AnalyzerNodeInit = AudioNodeInit<AnalyserNode, Analyzer>;
+export type DenoiseWorkletNodeInit = AudioNodeInit<AudioWorkletNode>;
+export type GainNodeInit = AudioNodeInit<GainNode, Gain>;
+export type MediaStreamAudioDestinationNodeInit = AudioNodeInit<MediaStreamAudioDestinationNode, MediaStreamAudioDestinationNode>;
+export type AudioDestinationNodeInit = AudioNodeInit<AudioDestinationNode, AudioDestinationNode>;
+export type DelayNodeInit = AudioNodeInit<DelayNode, DelayNode>;
+export type ChannelSplitterNodeInit = AudioNodeInit<ChannelSplitterNode, ChannelSplitterNode>;
+export interface WorkletModule {
+    moduleURL: string;
+    options?: WorkletOptions;
+}
+export interface AudioGraphOptions {
+    context?: AudioContext;
+    contextOptions?: AudioContextOptions;
+}
+type AudioGraphState = AudioContext['state'] | 'closing';
+export interface AudioGraph {
+    readonly context: AudioContext;
+    readonly inits: AudioNodeInit[];
+    readonly state: AudioGraphState;
+    connect(sequence: AudioNodeInitConnection): void;
+    disconnect(sequence: AudioNodeInitConnection): void;
+    addWorklet(moduleURL: string, options?: WorkletOptions): Promise<void>;
+    releaseInit(init: AudioNodeInit): void;
+    release(): Promise<void>;
+}
+/**
+ * We need to add the missing type def to work with AudioContextState in Safari
+ * See https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/state#resuming_interrupted_play_states_in_ios_safari
+ *
+ */
+export type UniversalAudioContextState = AudioContextState | 'interrupted';
+export type Canvas = HTMLCanvasElement | OffscreenCanvas;
+export type CanvasContext = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+/**
+ * Clock interface to get the current time with now method, @see Performance['now']
+ */
+export interface Clock {
+    now: Performance['now'];
+}
+/**
+ * Limit the rate of flow in terms of millisecond, and provided Clock
+ */
+export interface ThrottleOptions {
+    throttleMs?: number;
+    clock?: Clock;
+}
+export type IsVoice<T> = (data: T) => boolean;
+export type AsyncCallback = () => Promise<void>;
+export type Callback<R, T extends unknown[]> = (...params: T) => R;
+export interface Runner<P extends unknown[]> {
+    start(...params: P): Promise<void>;
+    stop(): void;
+    frameRate: number;
+}
+export type RunnerCreator<P extends unknown[], R> = (callback: Callback<R, P>, frameRate: number) => Runner<P>;
+export interface Transform<I, O> extends Transformer<I, O> {
+    init(): Promise<void>;
+    destroy(): Promise<void>;
+}
+export {};

package/dist/main/types.js

@@ -0,0 +1 @@
+export {};

package/dist/main/utils.d.ts

@@ -0,0 +1,173 @@
+import type { Clock, Callback } from './types';
+export declare const hasCreateGain: (context: BaseAudioContext) => boolean;
+export declare const hasAudioWorkletNode: () => boolean;
+export declare const hasAudioWorklet: () => boolean;
+export declare const stopStreamTracks: (stream?: MediaStream) => void | undefined;
+/**
+ * A function to create `MediaStreamAudioSourceNode` using constructor or factory
+ * function depends on the browser supports
+ *
+ * @param context - @see {@link AudioContext}
+ * @param options - @see {@link MediaStreamAudioSourceOptions}
+ *
+ * @internal
+ */
+export declare const createMediaStreamAudioSourceNode: (context: AudioContext, options: MediaStreamAudioSourceOptions) => MediaStreamAudioSourceNode;
+/**
+ * A function to create `MediaStreamAudioSourceNode` using constructor or factory
+ * function depends on the browser supports
+ *
+ * @param context - @see {@link AudioContext}
+ * @param options - @see {@link MediaStreamAudioSourceOptions}
+ *
+ * @internal
+ */
+export declare const createMediaElementSourceNode: (context: AudioContext, options: MediaElementAudioSourceOptions) => MediaElementAudioSourceNode;
+/**
+ * A function to create `AnalyserNode` using constructor or factory
+ * function depends on the browser supports
+ *
+ * @param audioContext - @see {@link AudioContext}
+ * @param options - @see {@link AnalyserOptions}
+ *
+ * @internal
+ */
+export declare const createAnalyserNode: (audioContext: BaseAudioContext, options?: AnalyserOptions) => AnalyserNode;
+/**
+ * A function to create `GainNode` using constructor or factory
+ * function depends on the browser supports
+ *
+ * @param context - @see {@link AudioContext}
+ * @param options - @see {@link GainOptions}
+ *
+ * @internal
+ */
+export declare const createGainNode: (context: BaseAudioContext, options?: GainOptions) => GainNode;
+/**
+ * A function to clone the Audio Track
+ *
+ * @param stream - Stream to be cloned
+ *
+ * @internal
+ */
+export declare const createMediaStreamAudioClone: (stream: MediaStream) => MediaStream;
+/**
+ * A function to create `MediaStreamAudioDestinationNode` using constructor or
+ * factory function depends on the browser supports
+ *
+ * @param context - @see {@link AudioContext}
+ * @param options - @see {@link AudioNodeOptions}
+ *
+ * @internal
+ */
+export declare const createMediaStreamAudioDestinationNode: (context: AudioContext, options?: AudioNodeOptions) => MediaStreamAudioDestinationNode;
+/**
+ * A function to create `DelayNode` using constructor or
+ * factory function depends on the browser supports
+ *
+ * @param context - @see {@link AudioContext}
+ * @param options - @see {@link DelayOptions}
+ *
+ * @internal
+ */
+export declare const createDelayNode: (context: AudioContext, options?: DelayOptions) => DelayNode;
+/**
+ * A function to create `ChannelSplitterNode` using constructor or
+ * factory function depends on the browser supports
+ *
+ * @param context - @see {@link AudioContext}
+ * @param options - @see {@link ChannelSplitterOptions}
+ *
+ * @internal
+ */
+export declare const createChannelSplitterNode: (context: AudioContext, options?: ChannelSplitterOptions) => ChannelSplitterNode;
+/**
+ * A function to create `ChannelMergerNode` using constructor or
+ * factory function depends on the browser supports
+ *
+ * @param context - @see {@link AudioContext}
+ * @param options - @see {@link ChannelSplitterOptions}
+ *
+ * @internal
+ */
+export declare const createChannelMergerNode: (context: AudioContext, options?: ChannelMergerOptions) => ChannelMergerNode;
+/**
+ * Map mute value to gain value
+ *
+ * ```
+ * `true` -> 0
+ * `false` -> 1
+ * ```
+ */
+export declare const muteToGain: (mute: boolean) => number;
+/**
+ * Calculate the timeout based on the provided data and returns a timeout in
+ * milliseconds with compensation added
+ *
+ * @param targetTime - The target timeout after the compensation
+ * @param startTime - The start time of the last execution
+ * @param endTime - The end time of the last execution
+ */
+export declare const calculateNextTimeout: (targetTime: number, startTime: number, endTime: number) => number;
+type Timeouts = Pick<WindowOrWorkerGlobalScope, 'setTimeout' | 'clearTimeout'>;
+/**
+ * @param delayInMS - Delay in terms of milliseconds
+ * @param params - The parameters to be passed to the provided callback
+ */
+type DelayCallback<P extends unknown[], R> = (delayInMS: number, ...params: P) => Promise<void | R>;
+/**
+ * Cancel the delay created by the @see {@link createDelayedCallback}, when it
+ * is invoked the ongoing delay will be resolved immediately
+ */
+type CancelDelay = () => void;
+/**
+ * Convert a callback to an async callback with delay added
+ *
+ * @param callback - The callback to be delayed
+ * @param options - The options to inject dependences
+ *
+ * @example
+ *
+ * ```typescript
+ * const getRandom = () => Math.random();
+ * const [delayGetRandom, cancelDelayGetRandom] = createDelayedCallback(getRandom);
+ *
+ * // Delay 500 ms to get the random number
+ * const random = await delayGetRandom(500);
+ * ```
+ */
+export declare const createDelayedCallback: <R, P extends unknown[]>(callback: Callback<R, P>, { setTimeout, clearTimeout, }?: Partial<Timeouts>) => [DelayCallback<P, R>, CancelDelay];
+type AsyncCallbackLoopOptions = Timeouts & Pick<Performance, 'now'> & {
+    frameRate: number;
+};
+/**
+ * Create an async callback loop to be called recursively with delay based on
+ * the `frameRate`
+ *
+ * @param callback - The callback to be invoked
+ * @param frameRate - The rate to be expected to invoke the `callback`
+ */
+export declare const createAsyncCallbackLoop: <P extends unknown[], R extends Promise<unknown>>(callback: Callback<R, P>, frameRate: number, { setTimeout, clearTimeout, now, }?: Partial<AsyncCallbackLoopOptions>) => {
+    start: (...params: P) => Promise<void>;
+    stop: () => void;
+    frameRate: number;
+};
+export declare const DEFAULT_THROTTLE_MS = 3000;
+/**
+ * A function to limit the provided callback being called too frequently, and
+ * assuming the function is called repeatably, and NOT for general purpose.
+ *
+ * @param callback - the callback to be called under the specified time
+ * @param throttleMs - the specified time for throttling
+ * @param clock - how to get the current time
+ */
+export declare const throttleProcess: <P extends unknown[]>(callback: Callback<void, P>, throttleMs?: number, clock?: Clock) => (...params: P) => void;
+type Unsubscribe = () => void;
+/**
+ * Subscribe visibilitychange event
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilitychange_event}
+ *
+ * @param callback - A callback to be called with `document.hidden` when the event is trigger
+ */
+export declare const subscribeVisibilityChangeEvent: (callback: (hidden: boolean) => Promise<void>) => Unsubscribe;
+export {};