@pexip/media-control 17.3.0 → 18.0.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 18.0.0
+
+### Minor Changes
+
+- 79d02d8: Allow triggering new GUM if the track is muted.
+- bfb8058: Add `maskCombineRatio` Constraint
+
+  - Add `maskCombineRatio` Constraint
+  - Rename bgImageUrl to backgroundImageUrl
+    https://gitlab.com/pexip/zoo/-/issues/2776
+  - Remove `flipHorizontal`
+
+### Patch Changes
+
+- Updated dependencies [bfb8058]
+  - @pexip/utils@16.11.0
+
+## 17.4.0
+
+### Minor Changes
+
+- fec1c90: Format following Prettier update
+
+### Patch Changes
+
+- Updated dependencies [4a1908a]
+- Updated dependencies [ec134d1]
+- Updated dependencies [24fe7e1]
+  - @pexip/utils@16.10.0
+
 ## 17.3.0
 
 ### Minor Changes

package/dist/baseLogger.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Log meta and message with respective log level
+ */
+export type LogMethod = (meta: unknown, message?: string) => void;
+export declare enum LogLevels {
+    trace = 10,
+    debug = 20,
+    info = 30,
+    warn = 40,
+    error = 50,
+    fatal = 60,
+    silent
+}
+export type LogLevelsString = keyof typeof LogLevels;
+export type LogMethods = {
+    [key in LogLevelsString]: LogMethod;
+};
+/**
+ * Log Level from high to low, "fatal" | "error" | "warn" | "info" | "debug" | "trace"
+ * Typically, debug and trace logs are only valid for development, and not needed in production
+ */
+export interface Logger extends LogMethods {
+    /**
+     * Adds a value to the redaction set, which makes it replaced by [REDACTED] when logged to file.
+     *
+     * @remarks
+     * The redaction set is applied globally, and only applies to the log file, not console logs.
+     *
+     * @param value - the string to redact
+     */
+    redact(value: string): void;
+}
+/**
+ * Create a logger with console API, and map fatal to error, skipping trace
+ * and silent, and there is no redaction
+ */
+export declare function createConsoleLogger(): Readonly<Logger>;

package/dist/baseLogger.js

@@ -0,0 +1,29 @@
+export var LogLevels;
+(function (LogLevels) {
+    LogLevels[LogLevels["trace"] = 10] = "trace";
+    LogLevels[LogLevels["debug"] = 20] = "debug";
+    LogLevels[LogLevels["info"] = 30] = "info";
+    LogLevels[LogLevels["warn"] = 40] = "warn";
+    LogLevels[LogLevels["error"] = 50] = "error";
+    LogLevels[LogLevels["fatal"] = 60] = "fatal";
+    // eslint-disable-next-line @typescript-eslint/prefer-literal-enum-member -- needs infinity
+    LogLevels[LogLevels["silent"] = Number.MAX_SAFE_INTEGER] = "silent";
+})(LogLevels || (LogLevels = {}));
+/**
+ * Create a logger with console API, and map fatal to error, skipping trace
+ * and silent, and there is no redaction
+ */
+export function createConsoleLogger() {
+    return Object.freeze({
+        /* eslint-disable no-console -- set logger to console */
+        fatal: (meta, message) => console.error(message, meta),
+        error: (meta, message) => console.error(message, meta),
+        warn: (meta, message) => console.warn(message, meta),
+        info: (meta, message) => console.info(message, meta),
+        debug: (meta, message) => console.debug(message, meta),
+        trace() { }, // Noop
+        silent() { }, // Noop
+        redact() { }, // Noop
+        /* eslint-enable no-console -- set logger to console */
+    });
+}

package/dist/constants.d.ts

@@ -0,0 +1,43 @@
+type ExtractObjectValueTypes<T extends object> = T[keyof T];
+/**
+ * The `DisplayCaptureSurfaceType` enumeration describes the different types of
+ * display surface
+ *
+ * @see {@link https://w3c.github.io/mediacapture-screen-share/#displaycapturesurfacetype}
+ */
+export declare const DISPLAY_CAPTURE_SURFACE_TYPE: {
+    readonly Monitor: "monitor";
+    readonly Window: "window";
+    readonly Browser: "browser";
+};
+/**
+ * The `DisplayCaptureSurfaceType` enumeration describes the different types of
+ * display surface
+ *
+ * @see {@link https://w3c.github.io/mediacapture-screen-share/#displaycapturesurfacetype}
+ */
+export type DisplayCaptureSurfaceType = ExtractObjectValueTypes<typeof DISPLAY_CAPTURE_SURFACE_TYPE>;
+/**
+ * The `CursorCaptureConstraint` enumerates the conditions under which the
+ * cursor is captured.
+ *
+ * @see {@link https://w3c.github.io/mediacapture-screen-share/#cursorcaptureconstraint}
+ */
+export declare const CURSOR_CAPTURE_CONSTRAINT: {
+    readonly Never: "never";
+    readonly Always: "always";
+    readonly Motion: "motion";
+};
+/**
+ * The `CursorCaptureConstraint` enumerates the conditions under which the
+ * cursor is captured.
+ *
+ * @see {@link https://w3c.github.io/mediacapture-screen-share/#cursorcaptureconstraint}
+ */
+export type CursorCaptureConstraint = ExtractObjectValueTypes<typeof CURSOR_CAPTURE_CONSTRAINT>;
+export declare const INCLUDE_EXCLUDE_CONSTRAINT: {
+    readonly Include: "include";
+    readonly Exclude: "exclude";
+};
+export type IncludeExcludeConstraint = ExtractObjectValueTypes<typeof INCLUDE_EXCLUDE_CONSTRAINT>;
+export {};

package/dist/constants.js

@@ -0,0 +1,26 @@
+/**
+ * The `DisplayCaptureSurfaceType` enumeration describes the different types of
+ * display surface
+ *
+ * @see {@link https://w3c.github.io/mediacapture-screen-share/#displaycapturesurfacetype}
+ */
+export const DISPLAY_CAPTURE_SURFACE_TYPE = {
+    Monitor: 'monitor',
+    Window: 'window',
+    Browser: 'browser',
+};
+/**
+ * The `CursorCaptureConstraint` enumerates the conditions under which the
+ * cursor is captured.
+ *
+ * @see {@link https://w3c.github.io/mediacapture-screen-share/#cursorcaptureconstraint}
+ */
+export const CURSOR_CAPTURE_CONSTRAINT = {
+    Never: 'never',
+    Always: 'always',
+    Motion: 'motion',
+};
+export const INCLUDE_EXCLUDE_CONSTRAINT = {
+    Include: 'include',
+    Exclude: 'exclude',
+};

package/dist/constraints.d.ts

@@ -0,0 +1,174 @@
+import type { FacingMode, InputConstraintSet, InputDeviceConstraint, MediaConstraintRequirement, MediaDeviceInfoLike, MediaDeviceRequest, NormalizedConstraintDeviceParameters } from './types';
+import type { ConstrainBooleanKeys, ConstrainDoubleKeys, ConstrainParamKeys, ConstrainRangeParamKeys, ConstrainStringKeys, ConstrainULongKeys, ExtendedConstrainBooleanKeys, ExtendedConstrainDoubleKeys, ExtendedConstrainStringKeys, ExtendedConstrainULongKeys } from './typeGuards';
+/**
+ * Check if provided constraint is an `exact` device constraint
+ */
+export declare const isExactDeviceConstraint: (constraint: InputDeviceConstraint | undefined) => boolean;
+/**
+ * Use navigator.mediaDevices.getSupportedConstraints to remove constraints not supported by agent.
+ * Creates a copy of MediaStreamConstraints with only supported properties.
+ */
+export declare const removeUnsupportedConstraints: (constraints: MediaStreamConstraints) => MediaStreamConstraints;
+/**
+ * Merge base constraints with provided base constraints and another constraints
+ */
+export declare const mergeConstraints: (baseConstraints: InputConstraintSet | boolean | undefined) => (constraints: InputDeviceConstraint | undefined) => InputConstraintSet | boolean;
+/**
+ * Normalize Device
+ * Convert any valid `MediaDeviceInfoLike` into `MediaDeviceInfoLike[]`
+ *
+ * Check test cases for the details
+ */
+export declare const normalizeDevice: (device: InputConstraintSet['device']) => MediaDeviceInfo[] | undefined;
+/**
+ * Normalize Device Constraint
+ * Convert Device Constraints into a form of `ConstraintDeviceParameters`
+ * e.g.
+ * `{ideal?: MediaDeviceInfoLike[], exact?: MediaDeviceInfoLike[]}`
+ *
+ * Check test cases for the details
+ *
+ * @returns
+ * `undefined` if nothing is meaningful for the constraint, otherwise,
+ * a normalized form of `ConstraintDeviceParameters`
+ */
+export declare const normalizeDeviceConstraint: (constraints: InputConstraintSet['device']) => NormalizedConstraintDeviceParameters | undefined;
+/**
+ * Convert `InputConstraintSet['device']` into
+ * `MediaTrackConstraintSet['deviceId']` in a normalized form
+ */
+export declare const toDeviceIdConstraintSet: (constraint: InputConstraintSet['device']) => MediaTrackConstraints['deviceId'];
+export declare const toArray: <T>(t: T | T[]) => T[];
+export type ConstrainNoneTuple = [undefined, 'ideal'];
+export declare const NONE: ConstrainNoneTuple;
+export type ConstrainStringTuple = [string[], ConstrainParamKeys];
+export declare const extractConstrainString: (key: ConstrainStringKeys | ExtendedConstrainStringKeys) => (constraints: InputConstraintSet) => ConstrainStringTuple | ConstrainNoneTuple;
+export type ConstrainBooleanTuple = [boolean, ConstrainParamKeys];
+export declare const extractConstrainBoolean: (key: ConstrainBooleanKeys | ExtendedConstrainBooleanKeys) => (constraints: InputConstraintSet) => ConstrainBooleanTuple | ConstrainNoneTuple;
+export type ConstrainNumber = number | Partial<Record<ConstrainRangeParamKeys, number>>;
+export type ConstrainNumberTuple = [
+    ConstrainNumber,
+    ConstrainParamKeys | 'min-max'
+];
+export declare const extractConstrainNumber: (key: ConstrainULongKeys | ConstrainDoubleKeys | ExtendedConstrainULongKeys | ExtendedConstrainDoubleKeys) => (constraints: InputConstraintSet) => ConstrainNumberTuple | ConstrainNoneTuple;
+export type ConstrainDeviceTuple = [MediaDeviceInfoLike[], ConstrainParamKeys];
+export declare const extractConstrainDevice: (constraints: InputDeviceConstraint | undefined) => ConstrainDeviceTuple | ConstrainNoneTuple;
+/**
+ * Compare float point number a and b to see if they are closed to be considered
+ * as having the same value
+ *
+ * @param a - Floating point number a
+ * @param b - Floating point number b
+ * @param numDigits - The number of digits to check after the decimal point @defaultValue 5 digits
+ */
+export declare const closedTo: (a: number, b: number, numDigits?: number) => boolean;
+/**
+ * Check if provided num is between min (inclusive) and max (inclusive)
+ *
+ * @param min - Lower boundary of the checking
+ * @param num - The number used for the checking
+ * @param max - Upper boundary of the checking
+ */
+export declare const between: (min: number | undefined, num: number, max: number | undefined) => boolean;
+export declare const getValueFromConstrainNumber: (constraint: ConstrainNumber) => number;
+export declare const getFacingModeFromConstraintString: (constraint: string) => FacingMode | undefined;
+/**
+ * Compare the provided constraint and num and see if the num satisfy the
+ * constraint
+ *
+ * @param constraint - The constraint to be used
+ * @param num - The num to be used to check
+ *
+ * @returns `true` means satisfy otherwise `false`
+ */
+export declare const satisfyConstrainNumber: (constraint: ConstrainNumber | undefined, num: number | undefined) => boolean;
+/**
+ * Resolve *constraints* and mediaTrackConstraints by checking the type and
+ * try to return the best possible from mediaTrackConstraints.
+ *
+ * @internal
+ */
+export declare const resolveMediaDeviceConstraints: (constraints?: InputDeviceConstraint, base?: MediaTrackConstraints | boolean) => MediaTrackConstraints | boolean;
+/**
+ * @remarks
+ * Constraint multiple (exact) devices is not supported
+ *
+ * @internal
+ */
+export declare const getMediaConstraints: ({ audio, video, defaultConstraints, }: MediaConstraintRequirement) => MediaStreamConstraints;
+/**
+ * Call applyConstraints foreach track accordingly
+ *
+ * @param tracks - Tracks to be applied
+ * @param constraints - constraints to be applied
+ */
+export declare const applyConstraints: (tracks: MediaStreamTrack[] | undefined, constraints: MediaDeviceRequest) => Promise<void>;
+export declare const findDeviceFrom: (devicesToFind: MediaDeviceInfoLike[], deviceList: MediaDeviceInfoLike[]) => MediaDeviceInfoLike[] | undefined;
+export declare const findDeviceFromDeviceConstraints: (device: InputConstraintSet['device'], devices: MediaDeviceInfoLike[]) => MediaDeviceInfoLike[] | undefined;
+export declare const relaxDevice: (device: InputConstraintSet['device'], devices: MediaDeviceInfoLike[]) => MediaDeviceInfoLike[] | undefined;
+export declare const resolveOnlyDevice: (devices: MediaDeviceInfoLike[]) => true | MediaDeviceInfoLike | undefined;
+type ConstrainNumberKeys = ConstrainULongKeys | ConstrainDoubleKeys | ExtendedConstrainDoubleKeys | ExtendedConstrainULongKeys;
+type ConstrainTuples = ConstrainDeviceTuple | ConstrainNumberTuple | ConstrainStringTuple | ConstrainBooleanTuple | ConstrainNoneTuple;
+type ExtractConstraintFn<R extends ConstrainTuples> = (constraints: InputDeviceConstraint | undefined) => R;
+export declare function extractConstraints<T extends 'device'>(key: T): ExtractConstraintFn<ConstrainDeviceTuple>;
+export declare function extractConstraints<T extends ConstrainStringKeys | ExtendedConstrainStringKeys>(key: T): ExtractConstraintFn<ConstrainStringTuple>;
+export declare function extractConstraints<T extends ConstrainNumberKeys>(key: T): ExtractConstraintFn<ConstrainNumberTuple>;
+export declare function extractConstraints<T extends ConstrainBooleanKeys | ExtendedConstrainBooleanKeys>(key: T): ExtractConstraintFn<ConstrainBooleanTuple>;
+type ConstrainStrings = Record<ConstrainStringKeys | ExtendedConstrainStringKeys, ConstrainStringTuple | ConstrainNoneTuple>;
+type ConstrainNumbers = Record<ConstrainNumberKeys, ConstrainNumberTuple | ConstrainNoneTuple>;
+type ConstrainBooleans = Record<ConstrainBooleanKeys | ExtendedConstrainBooleanKeys, ConstrainBooleanTuple | ConstrainNoneTuple>;
+type ConstrainDevices = Record<'device', ConstrainDeviceTuple | ConstrainNoneTuple>;
+type Constraints = ConstrainStrings & ConstrainNumbers & ConstrainBooleans & ConstrainDevices;
+/**
+ * Extract the constraints with provided keys
+ *
+ * @param keys - The keys to be used for the extraction
+ * @param constraints - The constraints to be used for the extraction
+ *
+ * @returns an object with the provided key and the value-param tuple
+ *
+ * @example
+ *
+ * ```typescript
+ * const device = {deviceId: 'xxxx', label: 'abc', kind: 'audioinput'};
+ * const constraints = { device, noiseSuppression: true };
+ * const extract = extractConstraintsWithKeys(['device', 'noiseSuppression']);
+ * const {
+ *   device: [devices, deviceParam],
+ *   noiseSuppression: [noiseSuppression, noiseSuppressionParam],
+ * } = extract(constraints);
+ * expect(devices).toEqual([device]);
+ * expect(deviceParam).toEqual('ideal');
+ * expect(noiseSuppression).toEqual(true);
+ * expect(noiseSuppressionParam).toEqual('ideal');
+ * ```
+ */
+export declare const extractConstraintsWithKeys: <T extends "deviceId" | "groupId" | "device" | "videoSegmentation" | "videoSegmentationModel" | "denoise" | "vad" | "asd" | "mixWithAdditionalMedia" | "backgroundImageUrl" | "resizeMode" | "pan" | "tilt" | "zoom" | "contentHint" | "facingMode" | "echoCancellation" | "autoGainControl" | "noiseSuppression" | ConstrainNumberKeys>(keys: readonly T[]) => (constraints: InputDeviceConstraint | undefined) => Pick<Constraints, T>;
+/**
+ * Extract deviceId from constraints
+ */
+export declare const extractDeviceId: (constraints: InputConstraintSet) => ConstrainStringTuple | ConstrainNoneTuple;
+/**
+ * Find device from the device list with provided constraints
+ *
+ * @param constraints - The constraints to be used for the lookup
+ * @param devices - The devices to be used for the lookup
+ *
+ * @returns `true` means it can be any devices, `undefined` means not found,
+ * otherwise, the matched device will be returned
+ */
+export declare const findDeviceFromConstraints: (constraints: InputDeviceConstraint | undefined, devices: MediaDeviceInfoLike[]) => boolean | MediaDeviceInfoLike | undefined;
+/**
+ * Relax input constraints to enable looking up the device by `deviceId` as well
+ * as `label` as a fallback as a best effort to get a similar device when
+ * possible.
+ *
+ * @param input - The input constraints to be relaxed
+ * @param devices - The current device list
+ */
+export declare const relaxInputConstraint: (input: InputDeviceConstraint | undefined, devices: MediaDeviceInfoLike[]) => InputDeviceConstraint | undefined;
+export declare const getConstraintsHandlers: () => {
+    getDefaultConstraints: () => MediaStreamConstraints;
+    setDefaultConstraints: (newConstraints: MediaStreamConstraints) => void;
+};
+export {};