@pexip/media-processor 16.7.1 → 17.1.0

package/dist/main/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A library for media analysis using Web APIs.
+ *
+ * @packageDocumentation
+ */
+export * from './audio';
+export * from './video';
+export * from './visual';
+export * from './types';
+export * from './math';
+export * from './process';
+export * from './typeGuards';
+export { createAsyncCallbackLoop } from './utils';
+export * from './benchUtils';
+export declare const urls: {
+    denoise: () => URL;
+};

package/dist/main/index.js

@@ -0,0 +1,17 @@
+/**
+ * A library for media analysis using Web APIs.
+ *
+ * @packageDocumentation
+ */
+export * from './audio';
+export * from './video';
+export * from './visual';
+export * from './types';
+export * from './math';
+export * from './process';
+export * from './typeGuards';
+export { createAsyncCallbackLoop } from './utils';
+export * from './benchUtils';
+export const urls = {
+    denoise: () => new URL('../worklets/denoise.worklet.js', import.meta.url),
+};

package/dist/main/math.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Sum an array of numbers
+ *
+ * @param nums - An array of numbers
+ */
+export declare const sum: (nums: number[]) => number;
+/**
+ * Average an array of numbers
+ *
+ * @param nums - An array of numbers
+ */
+export declare const avg: (nums: number[]) => number;
+/**
+ * pow function from Math in functional form `number -> number -> number`
+ *
+ * @param exponent - The exponent used for the expression
+ * @param base - The base value to be powered
+ *
+ * @returns Math.pow(base, exponent)
+ */
+export declare const pow: (exponent: number) => (base: number) => number;
+/**
+ * Calculate the Root Mean Square from provided numbers
+ *
+ * @param nums - An array of numbers
+ */
+export declare const rms: (nums: number[]) => number;
+/**
+ * Round the floating point number away from zero, which is different from
+ * `Math.round`
+ *
+ * @param num - The number to round
+ *
+ * @example
+ *
+ * ```typescript
+ * round(0.5) // 1
+ * round(-0.5) // -1
+ * ```
+ */
+export declare const round: (num: number) => number;

package/dist/main/math.js

@@ -0,0 +1,57 @@
+/**
+ * Sum an array of numbers
+ *
+ * @param nums - An array of numbers
+ */
+export const sum = (nums) => nums.reduce((accm, num) => accm + num, 0);
+/**
+ * Average an array of numbers
+ *
+ * @param nums - An array of numbers
+ */
+export const avg = (nums) => {
+    if (nums.length === 0) {
+        return 0;
+    }
+    if (nums.length === 1) {
+        return nums[0] ?? 0;
+    }
+    return sum(nums) / nums.length;
+};
+/**
+ * pow function from Math in functional form `number -> number -> number`
+ *
+ * @param exponent - The exponent used for the expression
+ * @param base - The base value to be powered
+ *
+ * @returns Math.pow(base, exponent)
+ */
+export const pow = (exponent) => (base) => Math.pow(base, exponent);
+/**
+ * Calculate the Root Mean Square from provided numbers
+ *
+ * @param nums - An array of numbers
+ */
+export const rms = (nums) => {
+    if (!nums || !Array.isArray(nums) || !nums.length) {
+        return 0;
+    }
+    if (nums.length === 1 && nums[0] !== undefined) {
+        return Math.abs(nums[0]);
+    }
+    return Math.sqrt(sum(nums.map(pow(2))) / nums.length);
+};
+/**
+ * Round the floating point number away from zero, which is different from
+ * `Math.round`
+ *
+ * @param num - The number to round
+ *
+ * @example
+ *
+ * ```typescript
+ * round(0.5) // 1
+ * round(-0.5) // -1
+ * ```
+ */
+export const round = (num) => num ? Math.round(num) : -Math.round(-num);

package/dist/main/path.d.ts

@@ -0,0 +1,102 @@
+/**
+ * SVG path command functions
+ *
+ * https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d
+ */
+import type { Point } from './types';
+/**
+ * Coordinates string
+ *
+ * @example
+ *
+ * ```
+ * 30,90
+ * ```
+ */
+export declare function toCoordinateString(p?: Point): string;
+/**
+ * MoveTo Path Command
+ *
+ * @example
+ *
+ * ```
+ * M 10,20
+ * ```
+ */
+export declare function moveTo(p?: Point): string;
+/**
+ * Line to Path Command
+ *
+ * @example
+ *
+ * ```
+ * L 10,20
+ * ```
+ */
+export declare function lineTo(p: Point): string;
+/**
+ * Draw a horizontal line from the current point to the end point, which is
+ * specified by the x parameter and the current point's y coordinate.
+ *
+ * @example
+ *
+ * ```
+ * H 10
+ * ```
+ */
+export declare function horizontalLineTo(x: number): string;
+/**
+ * Draw a vertical line from the current point to the end point, which is
+ * specified by the y parameter and the current point's x coordinate.
+ *
+ * @example
+ *
+ * ```
+ * V 10
+ * ```
+ */
+export declare function verticalLineTo(y: number): string;
+/**
+ * Cubic Bezier Curve parameters
+ *
+ * scp: start control point
+ * ecp: end control point
+ * ep: end point
+ */
+interface CubicCurveParams {
+    scp: Point;
+    ecp: Point;
+    ep: Point;
+}
+/**
+ * Cubic Bezier Curve Path Command
+ *
+ * @example
+ *
+ * ```
+ * C 30,90 25,10 50,10
+ * ```
+ */
+export declare function cubicCurveTo({ scp, ecp, ep }: CubicCurveParams): string;
+/**
+ * Smooth Cubic Bezier Curve Path Command
+ *
+ * @example
+ *
+ * ```
+ * S 25,10 50,10
+ * ```
+ */
+export declare function smoothCubicCurveTo({ ecp, ep, }: Pick<CubicCurveParams, 'ecp' | 'ep'>): string;
+/**
+ *  Close the current subpath by connecting the last point of the path with its
+ *  initial point.
+ *
+ * @example
+ *
+ * ```
+ * Z
+ * ```
+ */
+export declare function closePath(): string;
+export {};

package/dist/main/path.js

@@ -0,0 +1,103 @@
+/**
+ * Coordinates string
+ *
+ * @example
+ *
+ * ```
+ * 30,90
+ * ```
+ */
+export function toCoordinateString(p) {
+    return p ? [p.x, p.y].join(',') : '';
+}
+/**
+ * MoveTo Path Command
+ *
+ * @example
+ *
+ * ```
+ * M 10,20
+ * ```
+ */
+export function moveTo(p) {
+    return p ? ['M', toCoordinateString(p)].join(' ') : '';
+}
+/**
+ * Line to Path Command
+ *
+ * @example
+ *
+ * ```
+ * L 10,20
+ * ```
+ */
+export function lineTo(p) {
+    return p ? ['L', toCoordinateString(p)].join(' ') : '';
+}
+/**
+ * Draw a horizontal line from the current point to the end point, which is
+ * specified by the x parameter and the current point's y coordinate.
+ *
+ * @example
+ *
+ * ```
+ * H 10
+ * ```
+ */
+export function horizontalLineTo(x) {
+    return `H ${x}`;
+}
+/**
+ * Draw a vertical line from the current point to the end point, which is
+ * specified by the y parameter and the current point's x coordinate.
+ *
+ * @example
+ *
+ * ```
+ * V 10
+ * ```
+ */
+export function verticalLineTo(y) {
+    return `V ${y}`;
+}
+/**
+ * Cubic Bezier Curve Path Command
+ *
+ * @example
+ *
+ * ```
+ * C 30,90 25,10 50,10
+ * ```
+ */
+export function cubicCurveTo({ scp, ecp, ep }) {
+    return scp && ecp && ep
+        ? ['C', ...[scp, ecp, ep].map(toCoordinateString)].join(' ')
+        : '';
+}
+/**
+ * Smooth Cubic Bezier Curve Path Command
+ *
+ * @example
+ *
+ * ```
+ * S 25,10 50,10
+ * ```
+ */
+export function smoothCubicCurveTo({ ecp, ep, }) {
+    return ecp && ep
+        ? ['S', ...[ecp, ep].map(toCoordinateString)].join(' ')
+        : '';
+}
+/**
+ *  Close the current subpath by connecting the last point of the path with its
+ *  initial point.
+ *
+ * @example
+ *
+ * ```
+ * Z
+ * ```
+ */
+export function closePath() {
+    return 'Z';
+}

package/dist/main/process.d.ts

@@ -0,0 +1,239 @@
+import type { Queue } from '@pexip/utils';
+import type { StatsOptions, AudioSamples, AudioStats, Rect, Clock, IsVoice, ThrottleOptions } from './types';
+/**
+ * Default silent threshold
+ * At least one LSB 16-bit data (compare is on absolute value).
+ */
+export declare const SILENT_THRESHOLD: number;
+/**
+ * Default mono detection threshold
+ * Data must be identical within one LSB 16-bit to be identified as mono.
+ */
+export declare const MONO_THRESHOLD: number;
+/**
+ * Default low volume detection threshold
+ */
+export declare const LOW_VOLUME_THRESHOLD = -60;
+/**
+ * Default clipping detection threshold
+ */
+export declare const CLIP_THRESHOLD = 0.98;
+/**
+ * Default Voice probability threshold
+ */
+export declare const VOICE_PROBABILITY_THRESHOLD = 0.3;
+/**
+ * Default clipping count threshold
+ * Number of consecutive clipThreshold level samples that indicate clipping.
+ */
+export declare const CLIP_COUNT_THRESHOLD = 6;
+/**
+ * AudioStats builder
+ *
+ * @param stats - overwrite the default attributes
+ * @param options - `silentThreshold`, `lowVolumeThreshold` and
+ * `clipCountThreshold`
+ */
+export declare const createAudioStats: (stats?: Partial<AudioStats>, { silentThreshold, lowVolumeThreshold, clipCountThreshold, }?: {
+    silentThreshold?: number | undefined;
+    lowVolumeThreshold?: number | undefined;
+    clipCountThreshold?: number | undefined;
+}) => AudioStats;
+/**
+ * Convert a byte to float, according to web audio spec
+ *
+ * Floating point audio sample number is defined as: non-interleaved IEEE754
+ * 32-bit linear PCM with a nominal range between -1 and +1, that is, 32bits
+ * floating point buffer, with each samples between -1.0 and 1.0
+ * https://developer.mozilla.org/en-US/docs/Web/API/AudioBuffer
+ *
+ * Byte samples are represented as follows:
+ * 128 is silence, 0 is negative max, 256 is positive max
+ *
+ * @param value - The byte value to convert to float
+ *
+ * @remarks
+ * Ref. https://www.w3.org/TR/webaudio/#dom-analysernode-getbytetimedomaindata
+ */
+export declare const fromByteToFloat: (value: number) => number;
+/**
+ * Convert a float to byte, according to web audio spec
+ *
+ * Floating point audio sample number is defined as: non-interleaved IEEE754
+ * 32-bit linear PCM with a nominal range between -1 and +1, that is, 32bits
+ * floating point buffer, with each samples between -1.0 and 1.0
+ * https://developer.mozilla.org/en-US/docs/Web/API/AudioBuffer
+ *
+ * Byte samples are represented as follows:
+ * 128 is silence, 0 is negative max, 256 is positive max
+ *
+ * @param value - The float value to convert to byte
+ *
+ * @remarks
+ * Ref. https://www.w3.org/TR/webaudio/#dom-analysernode-getbytetimedomaindata
+ */
+export declare const fromFloatToByte: (value: number) => number;
+/**
+ * Copy data from Uint8Array buffer to Float32Array buffer with byte to float conversion
+ *
+ * @param bytes - The source Byte buffer
+ * @param floats - The destination buffer
+ */
+export declare const copyByteBufferToFloatBuffer: (bytes: Uint8Array, floats: Float32Array) => void;
+/**
+ * Convert a floating point gain value into a dB representation without any
+ * reference, dBFS, https://en.wikipedia.org/wiki/DBFS
+ *
+ * See https://www.w3.org/TR/webaudio#conversion-to-db
+ *
+ * @param amplitude - Expected a value in (0, 1]
+ */
+export declare const toDecibel: (gain: number) => number;
+/**
+ * Calculate the averaged volume using Root Mean Square, assuming the data is in
+ * float form
+ *
+ * @param data - Audio Frequency data
+ *
+ * @alpha
+ */
+export declare const processAverageVolume: (data: number[]) => number;
+/**
+ * Simple silent detection to only check the first and last bit from the sample
+ *
+ * @param samples - Audio sample data, this could be in a form of floating number
+ * of a byte number as long as the `threshold` value is given accordingly.
+ * @param threshold - Silent threshold
+ *
+ * @defaultValue
+ * `1.0 / 32767` assuming the sample is float value
+ *
+ * @returns
+ * `true` when it is silent
+ */
+export declare const isSilent: (samples: AudioSamples, threshold?: number) => boolean;
+/**
+ * Check if the provided gain above the low volume threshold, which is
+ * considered as low volume.
+ *
+ * @param gain - Floating point representation of the gain number
+ *
+ * @returns
+ * `true` if the `gain` is lower than the threshold
+ */
+export declare const isLowVolume: (gain: number, threshold?: number) => boolean;
+/**
+ * Check if there is clipping
+ *
+ * @param clipCount - Number of consecutive clip
+ *
+ * @returns
+ * `true` if the `clipCount` is above the threshold, aka clipping
+ */
+export declare const isClipping: (clipCount: number, threshold?: number) => boolean;
+/**
+ * Check if provided channels are mono or stereo
+ *
+ * @param channels - Audio channels and assuming the inputs are in floating
+ * point form
+ * @param threshold - Mono detection threshold, default to floating point form
+ *
+ * @defaultValue
+ * `1.0 / 32767`
+ *
+ * @returns
+ * `true` if they are mono, otherwise stereo
+ */
+export declare const isMono: (channels: AudioSamples[], threshold?: number) => boolean;
+/**
+ * Calculate the audio stats, expected the samples are in float form
+ *
+ * @param options - See StatsOptions
+ *
+ * @remarks
+ * http://www.rossbencina.com/code/real-time-audio-programming-101-time-waits-for-nothing
+ */
+export declare const getAudioStats: ({ samples, baseStats, clipThreshold, }: StatsOptions) => AudioStats;
+/**
+ * VAD options
+ */
+interface VAOptions {
+    /**
+     * the RMS threshold used to compare with the input RMS
+     */
+    volumeThreshold?: number;
+    /**
+     * The threshold for a voice pulse in terms of time, in millisecond
+     */
+    VADTimeThreshold?: number;
+    /**
+     * The clock, can be used for testing
+     *
+     * @defaultValue
+     * `performance`
+     */
+    clock?: Clock;
+}
+/**
+ * A Naive Voice activity detection
+ *
+ * @param options - See `VAOptions`
+ *
+ * @returns `(volume: number) => boolean`, `true` if there is voice
+ */
+export declare const isVoiceActivity: ({ volumeThreshold, VADTimeThreshold, clock, }?: VAOptions) => (volume: number) => boolean;
+/**
+ * Compare the provided width and height to see if they are the same
+ *
+ * @param widthA - The width of A
+ * @param heightA - The height of A
+ * @param widthB - The width of B
+ * @param heightB - The height of B
+ */
+export declare const isEqualSize: (widthA: number, heightA: number, widthB: number, heightB: number) => boolean;
+/**
+ * Convert the source size to destination size when necessary based on the
+ * height
+ *
+ * @param sw - Source width
+ * @param sh - Source height
+ * @param dw - destination width
+ * @param dh - destination height
+ */
+export declare const fitDestinationSize: (sw: number, sh: number, dw: number, dh: number) => Rect;
+/**
+ * A function to check provided time series data is considered as voice activity
+ *
+ * @param options - @see VAOptions
+ */
+export declare const createVoiceDetectorFromTimeData: (options?: VAOptions) => IsVoice<number[]>;
+/**
+ * A function to check the provided probability is considered as voice activity
+ *
+ * @param voiceThreshold - A threshold of the probability to be considered as
+ * voice activity
+ */
+export declare const createVoiceDetectorFromProbability: (voiceThreshold?: number) => IsVoice<number>;
+/**
+ * Create a voice detector based on provided params
+ *
+ * @param onDetected - When there is voice activity, this callback will be called
+ * @param shouldDetect - When return `true`, voice activity will function, otherwise, not function
+ * @param options - @see ThrottleOptions
+ */
+export declare const createVADetector: (onDetected: () => void, shouldDetect: () => boolean, options?: ThrottleOptions) => <T>(isVoice: IsVoice<T>) => (data: T) => void;
+/**
+ * Create a function to process the AudioStats and check if silent
+ * `onSignalDetected` callback is called under 2 situations:
+ *
+ * ```
+ * Logic
+ * lastCheck | silent | should call onSignalDetected
+ * 0         | 0      | 0
+ * 0         | 1      | 1
+ * 1         | 0      | 1
+ * 1         | 1      | 0
+ * ```
+ */
+export declare const createAudioSignalDetector: (shouldDetect: () => boolean, onDetected: (silent: boolean) => void) => (buffer: Queue<number[]>, threshold?: number) => (samples: number[]) => void;
+export {};