@pexip/media-control 17.2.0 → 17.4.0

package/dist/devices.d.ts

@@ -0,0 +1,416 @@
+import type { MediaDeviceInfoLike, MediaInput, MediaDeviceRequest, InputDeviceConstraint, InputConstraintSet, InputDevicePermission, FacingMode } from './types';
+import { MediaDeviceKinds } from './types';
+/**
+ * DeviceChange Event
+ *
+ * ```
+ * devices (raw)
+ * |--- authorized
+ * |        |--- found
+ * |        |--- lost
+ * |--- unauthorized
+ * ```
+ *
+ * @beta
+ */
+export type DeviceChangedChanges = {
+    authorized: MediaDeviceInfoLike[];
+    unauthorized: MediaDeviceInfoLike[];
+    found: MediaDeviceInfoLike[];
+    lost: MediaDeviceInfoLike[];
+    devices: MediaDeviceInfoLike[];
+};
+interface ToKeyOptions {
+    id: string;
+    kind: string;
+    label: string;
+}
+/**
+ * Convert provided info to key for Map
+ *
+ * @beta
+ */
+export declare const toKey: ({ id, kind, label }: ToKeyOptions) => string;
+/**
+ * Future proofing: in case we want to alter the values or type returned
+ * by {@link https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices | enumerateDevices}
+ *
+ * @returns
+ * a list of currently available {@link https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo | devices}
+ *
+ * @example
+ * ```javascript
+ * import {getDevices} from "media-control";
+ *
+ * const devices = await getDevices();
+ * // return MediaDeviceInfo[]
+ * ```
+ *
+ * @beta
+ */
+export declare const getDevices: () => Promise<MediaDeviceInfo[]>;
+export declare const toDeviceKey: (device: MediaDeviceInfoLike) => string;
+export declare const toDeviceTuple: (device: MediaDeviceInfoLike) => readonly [string, MediaDeviceInfoLike];
+export declare const toDevicesMap: (devices: MediaDeviceInfoLike[]) => Map<string, MediaDeviceInfoLike>;
+export declare const toUniqueDevices: (devices: MediaDeviceInfoLike[]) => MediaDeviceInfoLike[];
+export declare const createTrackDevicesChanges: (prevDevices?: MediaDeviceInfoLike[]) => (devices: MediaDeviceInfoLike[]) => {
+    unauthorized: MediaDeviceInfoLike[];
+    authorized: MediaDeviceInfoLike[];
+    found: MediaDeviceInfoLike[];
+    lost: MediaDeviceInfoLike[];
+    devices: MediaDeviceInfoLike[];
+};
+/**
+ * Unified interface for subscribing {@link DeviceChangedChanges} Event
+ *
+ * @beta
+ */
+export declare const deviceChanged: (fn: (event: DeviceChangedChanges) => void) => () => void;
+export declare const extractDeviceInfo: (track: MediaStreamTrack) => {
+    kind: MediaDeviceKinds;
+    deviceId: string;
+    groupId: string;
+    label: string;
+    settings: {
+        aspectRatio?: number | undefined;
+        autoGainControl?: boolean | undefined;
+        channelCount?: number | undefined;
+        displaySurface?: string | undefined;
+        echoCancellation?: boolean | undefined;
+        facingMode?: string | undefined;
+        frameRate?: number | undefined;
+        height?: number | undefined;
+        noiseSuppression?: boolean | undefined;
+        sampleRate?: number | undefined;
+        sampleSize?: number | undefined;
+        width?: number | undefined;
+        latency?: number | undefined;
+    };
+};
+/**
+ * Convert `MediaStreamTrack` to `MediaDeviceInfoLike`
+ *
+ * @beta
+ */
+export declare const toMediaDeviceInfoLike: (track: MediaStreamTrack) => MediaDeviceInfoLike | undefined;
+/**
+ * Compare the provide the MediaStreamTrack and MediaDeviceInfo to see if they
+ * are the same with best efforts
+ *
+ * @param track - `MediaStreamTrack` used for the comparison
+ * @param device - `MediaDeviceInfo` used for the comparison
+ *
+ * @returns `true` if they are the same else `false`
+ *
+ * @remarks
+ * Old browser may not have `deviceId` from getSettings()
+ * https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackSettings
+ * The `label` attribute will then be used for the comparison instead of the
+ * `deviceId`
+ *
+ * @beta
+ */
+export declare const compareMediaDeviceToMediaTrack: (track: Pick<MediaStreamTrack, 'kind' | 'getSettings' | 'label'>) => (device: MediaDeviceInfoLike) => boolean;
+export declare const toMediaDeviceInfo: (info: MediaDeviceInfoLike) => {
+    deviceId: string;
+    groupId: string;
+    kind: MediaDeviceKind;
+    label: string;
+};
+/**
+ * Find the MediaDeviceInfo from provided MediaDeviceInfo[] by comparing with
+ * provided MediaStreamTrack
+ *
+ * @param devices - A device list used for the searching
+ * @param track - A track for the searching criteria
+ *
+ * @returns `MediaDeviceInfo` if found, otherwise `undefined`
+ *
+ * @beta
+ */
+export declare const findMediaInputFromMediaStreamTrack: (devices: MediaDeviceInfoLike[]) => (track?: MediaStreamTrack | undefined) => MediaDeviceInfoLike | undefined;
+/**
+ * Find media input from media stream
+ *
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ * @param stream - A media stream used for the search criteria
+ *
+ * @returns A object may contains the devices
+ *
+ * @beta
+ */
+export declare const findMediaInputFromStream: (devices: MediaDeviceInfoLike[]) => (stream: MediaStream | undefined) => MediaInput;
+export declare const compareDeviceConstraintAndTrackDevice: (device: MediaDeviceInfoLike | undefined) => (constraint: InputConstraintSet['device']) => boolean;
+export declare const isRequestedResolution: (request: InputDeviceConstraint | undefined, response: MediaDeviceInfoLike | undefined) => boolean;
+export declare const isRequestedInputDevice: (request: InputDeviceConstraint | undefined, response: MediaDeviceInfoLike | undefined) => boolean;
+/**
+ * Compare request and the input to see if the request has been fulfilled
+ */
+export declare const isRequestedInputTrack: (request: InputDeviceConstraint | undefined, current: MediaStreamTrack | MediaDeviceInfoLike | undefined) => boolean;
+export declare const hasRequestingDevice: (request: InputDeviceConstraint | undefined, kind: MediaDeviceKind, currentDevices: MediaDeviceInfoLike[]) => boolean;
+/**
+ * Decide if we should send a new gUM request based on the inputs
+ *
+ * @param request - Requesting input device constraint
+ * @param tracks - The current media stream tracks
+ * @param currentDevices - The current list of device of the same kind of the
+ * request
+ *
+ * @returns `true` means the request should be conducted, otherwise `false`.
+ */
+export declare const shouldRequestDevice: (request: InputDeviceConstraint | undefined, tracks: MediaStreamTrack[], currentDevices: MediaDeviceInfoLike[]) => boolean;
+export declare const resolveInputDevice: (tracksOrDevice: MediaDeviceInfoLike | MediaStreamTrack[] | undefined, findInput: ReturnType<typeof findMediaInputFromMediaStreamTrack>) => MediaDeviceInfo | MediaDeviceInfoLike | MediaStreamTrack | undefined;
+export declare const isStreamingRequestedDevicesBase: (request: MediaDeviceRequest, tracksOrDevices: {
+    audio?: MediaDeviceInfoLike | MediaStreamTrack[];
+    video?: MediaDeviceInfoLike | MediaStreamTrack[];
+}, devices: MediaDeviceInfoLike[]) => {
+    audio: boolean;
+    video: boolean;
+};
+/**
+ * Check if provided request has already been fulfilled
+ *
+ * @param request - A media request constraints
+ * @param stream - Current media stream
+ *
+ * @returns
+ * audio - The stream is using the same device as requested if `true`
+ * video - The stream is using the same device as requested if `true`
+ */
+export declare const isStreamingRequestedDevices: (request: MediaDeviceRequest, stream: MediaStream | undefined, devices: MediaDeviceInfoLike[]) => {
+    audio: boolean;
+    video: boolean;
+};
+/**
+ * Find in the list of devices which has permissions granted
+ *
+ * From MDN:
+ * For security reasons,the label field is always blank unless an active media stream
+ * exists or the user has granted persistent permission for media device access.
+ *
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ *
+ * @returns List of devices that has permission granted
+ *
+ * @beta
+ */
+export declare const findPermissionGrantedDevices: (devices: MediaDeviceInfoLike[]) => MediaDeviceInfoLike[];
+/**
+ * Use provided devices to guess the permission state. When there is no active
+ * stream and there is no device with label, 'prompt' will be returned
+ * otherwise, 'denied'.
+ *
+ * @param devices - The current devices
+ * @param anyActiveStream - Has ever got an active stream to help the fallback to
+ * guess the state more accurately
+ */
+export declare const toPermissionState: (devices: MediaDeviceInfoLike[], anyActiveStream?: boolean) => PermissionState;
+/**
+ * A wrapper for `navigator.permissions.query` with fallback to use
+ * `navigator.mediaDevices.enumerateDevices` to guess the `PermissionState`
+ *
+ * @param anyActiveStream - Has ever got an active stream to help the fallback to
+ * guess the state more accurately
+ */
+export declare const getInputDevicePermissionState: (anyActiveStream?: boolean) => Promise<InputDevicePermission>;
+/**
+ * Find current audio output id to be used to set as sinkId
+ *
+ * If you set the stale deviceId to setSink it will throw exception.
+ * So we want to check if audio output id still exist.
+ *
+ * @param audioOutput - Audio output as `MediaDeviceInfo`
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ *
+ * @returns Audio output id or empty string if couldn't find it.
+ *
+ * @beta
+ */
+export declare const findCurrentAudioOutputId: (audioOutput?: MediaDeviceInfoLike, devices?: MediaDeviceInfoLike[]) => string;
+/**
+ * Find videoinput device id in the stream
+ *
+ * @param stream - Media stream to do the lookup
+ *
+ * @returns A object may contains the devices
+ *
+ * @beta
+ */
+export declare const findCurrentVideoInputDeviceIdFromStream: (stream: MediaStream) => string | undefined;
+/**
+ * Finds device with given deviceId
+ *
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ * @param deviceId - id that represents desired device
+ *
+ * @returns device with given deviceId
+ *
+ * @beta
+ */
+export declare const findDeviceWithDeviceId: (devices: MediaDeviceInfoLike[], deviceId: string) => MediaDeviceInfoLike | undefined;
+/**
+ * Find in the list of devices with given MediaDeviceKind
+ *
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ * @param kind - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ *
+ * @returns List of devices that have required MediaDeviceKind
+ *
+ * @beta
+ */
+export declare const findDevicesByKind: (kind: MediaDeviceKind) => (devices: MediaDeviceInfoLike[]) => MediaDeviceInfoLike[];
+/**
+ * Find in the list of devices only the audio input ones
+ *
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ *
+ * @returns List of devices that are audio inputs
+ *
+ * @beta
+ */
+export declare const findAudioInputDevices: (devices: MediaDeviceInfoLike[]) => MediaDeviceInfoLike[];
+/**
+ * Find in the list of devices only the video input ones
+ *
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ *
+ * @returns List of devices that are video inputs
+ *
+ * @beta
+ */
+export declare const findVideoInputDevices: (devices: MediaDeviceInfoLike[]) => MediaDeviceInfoLike[];
+/**
+ * Find in the list of devices only the audio output ones
+ *
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ *
+ * @returns List of devices that are audio outputs
+ *
+ * @beta
+ */
+export declare const findAudioOutputDevices: (devices: MediaDeviceInfoLike[]) => MediaDeviceInfoLike[];
+/**
+ * Set `MediaStreamTrack['enabled']` according to `mute` param for the provided `stream`
+ *
+ * @param stream - Media stream
+ * @param mute - disable or enable the audio stream
+ * @param mediaType - Can either be 'audio', 'video' or 'all'
+ * @defaultValue
+ * 'all'
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/enabled
+ *
+ * @beta
+ */
+export declare const muteStreamTrack: (stream?: MediaStream) => (mute: boolean, mediaType?: 'audio' | 'video' | 'all') => void;
+/**
+ * Stops all tracks in the given stream
+ *
+ * Immediately after calling stop(), the readyState property is set to `ended`.
+ * Note that the `ended` event will not be fired in this situation
+ * https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/stop#description
+ *
+ * @param stream - `MediaStream` which we mutate
+ * @param onStopped - callback to be called when the track is stopped
+ */
+export declare const stopMediaStream: (stream: MediaStream | undefined, onStopped?: ((track: MediaStreamTrack) => void) | undefined) => void;
+/**
+ * Checks that tracks with a given type are enabled in the stream
+ *
+ * @param stream - `MediaStream` used for comparison
+ * @param type - `MediaInput` used for comparison
+ *
+ * @returns Return true when all the tracks are enabled false otherwise
+ *
+ * @beta
+ */
+export declare const areTracksEnabled: (stream: MediaStream | undefined, type: 'audio' | 'video') => boolean;
+/**
+ * Check if list contains media inputs
+ *
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ *
+ * @returns True when some media inputs false otherwise
+ *
+ * @beta
+ */
+export declare const hasAudioOrVideoInputs: (devices: MediaDeviceInfoLike[]) => boolean;
+/**
+ * Check if list contains audio inputs
+ *
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ *
+ * @returns True when some audio inputs false otherwise
+ *
+ * @beta
+ */
+export declare const hasAudioInputs: (devices: MediaDeviceInfoLike[]) => boolean;
+/**
+ * Check if list contains video inputs
+ *
+ * @param devices - A list of media devices from
+ * `navigator.mediaDevices.enumerateDevices()`. Will be used for search target
+ *
+ * @returns True when some video inputs false otherwise
+ *
+ * @beta
+ */
+export declare const hasVideoInputs: (devices: MediaDeviceInfoLike[]) => boolean;
+/**
+ * Check if provided devices have any granted input device
+ *
+ * @param devices - The devices to check
+ */
+export declare const hasAnyGrantedInput: (devices: MediaDeviceInfoLike[]) => boolean;
+/**
+ * Check if provided devices have any video and audio inputs
+ *
+ * @param devices - The devices to lookup
+ * @param grantedOnly - When it is `true`, the device label is also taken into
+ * consideration
+ * @defaultValue `false`
+ *
+ * @returns A tuple of `[anyAudioInput, anyVideoInput]`, e.g. `[true, false]`
+ * means there is audio input but no video input
+ */
+export declare const hasAnyInputs: (devices: MediaDeviceInfoLike[], grantedOnly?: boolean) => [boolean, boolean];
+/**
+ * An utility function to check the input device has been changed
+ *
+ * @param oldInput - The previous input device
+ * @param newInput - The current input device
+ */
+export declare const hasChangedInput: (oldInput: MediaDeviceInfoLike | undefined, newInput: MediaDeviceInfoLike | undefined) => boolean;
+/**
+ * An utility function to check if facing mode is supported by interpreting the
+ * device label and the API `getSupportedConstraints`
+ *
+ * @remarks
+ * Only support snooping the label for English
+ *
+ * @param currentDevices - Current list of devices available
+ * @param getSupportedConstraints - A function to get supported constraints,
+ * i.e. `navigator.mediaDevices.getSupportedConstraints()`
+ * @param tracks - Current video input track
+ */
+export declare const areMultipleFacingModeSupported: (currentDevices: MediaDeviceInfoLike[], getSupportedConstraints?: () => MediaTrackSupportedConstraints) => boolean;
+/**
+ * Interpret the current facing mode from the provided track, and try to get the
+ * mode from settings, or use the label to guess the facing mode when facingMode
+ * is not supported from settings
+ *
+ * @param currentTrack - The current video input track
+ */
+export declare const interpretCurrentFacingMode: (currentTrack: MediaStreamTrack | undefined) => FacingMode | undefined;
+export {};