@pexip/media-control 20.3.4 → 21.0.0

package/api-docs/functions/deviceChanged.mdx

@@ -0,0 +1,21 @@
+```ts
+function deviceChanged(fn): () => void;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `fn` | (`event`) => `void` |
+
+## Returns
+
+```ts
+(): void;
+```
+
+### Returns
+
+`void`

package/api-docs/functions/extractConstrainDevice.mdx

@@ -0,0 +1,14 @@
+```ts
+function extractConstrainDevice(constraints, initialParam): ConstrainNoneTuple | ConstrainDeviceTuple;
+```
+
+## Parameters
+
+| Parameter | Type | Default value |
+| ------ | ------ | ------ |
+| `constraints` | \| [`InputDeviceConstraint`](../type-aliases/InputDeviceConstraint.mdx) \| `undefined` | `undefined` |
+| `initialParam` | `"exact"` \| `"ideal"` | `'ideal'` |
+
+## Returns
+
+`ConstrainNoneTuple` \| `ConstrainDeviceTuple`

package/api-docs/functions/extractConstraintsWithKeys.mdx

@@ -0,0 +1,51 @@
+```ts
+function extractConstraintsWithKeys<T>(keys): (constraints) => Pick<Constraints, T>;
+```
+
+Extract the constraints with provided keys
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` *extends* \| `"deviceId"` \| `"groupId"` \| `"device"` \| `"videoSegmentation"` \| `"videoSegmentationModel"` \| `"denoise"` \| `"vad"` \| `"asd"` \| `"mixWithAdditionalMedia"` \| `"backgroundImageUrl"` \| `"excludeBystanders"` \| `"resizeMode"` \| `"pan"` \| `"tilt"` \| `"zoom"` \| `"contentHint"` \| `"facingMode"` \| `"echoCancellation"` \| `"autoGainControl"` \| `"noiseSuppression"` \| `ConstrainNumberKeys` |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `keys` | readonly `T`[] | The keys to be used for the extraction |
+
+## Returns
+
+an object with the provided key and the value-param tuple
+
+```ts
+(constraints): Pick<Constraints, T>;
+```
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `constraints` | \| [`InputDeviceConstraint`](../type-aliases/InputDeviceConstraint.mdx) \| `undefined` |
+
+### Returns
+
+`Pick`\<`Constraints`, `T`\>
+
+## 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');
+```

package/api-docs/functions/findCurrentAudioOutputId.mdx

@@ -0,0 +1,16 @@
+```ts
+function findCurrentAudioOutputId(audioOutput?, devices?): string;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `audioOutput?` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx) |
+| `devices?` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] |
+
+## Returns
+
+`string`

package/api-docs/functions/findCurrentVideoInputDeviceIdFromStream.mdx

@@ -0,0 +1,15 @@
+```ts
+function findCurrentVideoInputDeviceIdFromStream(stream): string | undefined;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `stream` | `MediaStream` |
+
+## Returns
+
+`string` \| `undefined`

package/api-docs/functions/findDevice.mdx

@@ -0,0 +1,33 @@
+```ts
+function findDevice(deviceToFind, useFallback): (devices) => 
+  | MediaDeviceInfoLike
+  | undefined;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type | Default value |
+| ------ | ------ | ------ |
+| `deviceToFind` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx) | `undefined` |
+| `useFallback` | `boolean` | `true` |
+
+## Returns
+
+```ts
+(devices): 
+  | MediaDeviceInfoLike
+  | undefined;
+```
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `devices` | readonly [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] |
+
+### Returns
+
+  \| [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)
+  \| `undefined`

package/api-docs/functions/findDeviceFromConstraints.mdx

@@ -0,0 +1,24 @@
+```ts
+function findDeviceFromConstraints(constraints, devices): 
+  | boolean
+  | MediaDeviceInfoLike
+  | undefined;
+```
+
+Find device from the device list with provided constraints
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `constraints` | \| [`InputDeviceConstraint`](../type-aliases/InputDeviceConstraint.mdx) \| `undefined` | The constraints to be used for the lookup |
+| `devices` | [`IndexedDevices`](../interfaces/IndexedDevices.mdx) | The devices to be used for the lookup |
+
+## Returns
+
+  \| `boolean`
+  \| [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)
+  \| `undefined`
+
+`true` means it can be any devices, `undefined` means not found,
+otherwise, the matched device will be returned

package/api-docs/functions/findDeviceWithDeviceId.mdx

@@ -0,0 +1,19 @@
+```ts
+function findDeviceWithDeviceId(devices, deviceId): 
+  | MediaDeviceInfoLike
+  | undefined;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] |
+| `deviceId` | `string` |
+
+## Returns
+
+  \| [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)
+  \| `undefined`

package/api-docs/functions/findDevicesByKind.mdx

@@ -0,0 +1,27 @@
+```ts
+function findDevicesByKind(kind): (devices) => MediaDeviceInfoLike[];
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `kind` | `MediaDeviceKind` |
+
+## Returns
+
+```ts
+(devices): MediaDeviceInfoLike[];
+```
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] |
+
+### Returns
+
+[`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[]

package/api-docs/functions/findMediaInputFromMediaStreamTrack.mdx

@@ -0,0 +1,32 @@
+```ts
+function findMediaInputFromMediaStreamTrack(devices): (track?) => 
+  | MediaDeviceInfoLike
+  | undefined;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `devices` | [`IndexedDevices`](../interfaces/IndexedDevices.mdx) |
+
+## Returns
+
+```ts
+(track?): 
+  | MediaDeviceInfoLike
+  | undefined;
+```
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `track?` | `MediaStreamTrack` |
+
+### Returns
+
+  \| [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)
+  \| `undefined`

package/api-docs/functions/findMediaInputFromStream.mdx

@@ -0,0 +1,27 @@
+```ts
+function findMediaInputFromStream(devices): (stream) => MediaInput;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `devices` | [`IndexedDevices`](../interfaces/IndexedDevices.mdx) |
+
+## Returns
+
+```ts
+(stream): MediaInput;
+```
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `stream` | `MediaStream` \| `undefined` |
+
+### Returns
+
+[`MediaInput`](../interfaces/MediaInput.mdx)

package/api-docs/functions/findPermissionGrantedDevices.mdx

@@ -0,0 +1,15 @@
+```ts
+function findPermissionGrantedDevices(devices): MediaDeviceInfoLike[];
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] |
+
+## Returns
+
+[`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[]

package/api-docs/functions/getDeviceId.mdx

@@ -0,0 +1,17 @@
+```ts
+function getDeviceId(device, separator): string;
+```
+
+Create a device ID from provided `device`.
+The device ID here is in the format of `deviceId:kind`, be default.
+
+## Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `device` | `Pick`\<[`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx), `"deviceId"` \| `"kind"`\> | `undefined` | The device to create the ID from |
+| `separator` | `string` | `DEVICE_ID_SEPARATOR` | The separator to use to join the device ID |
+
+## Returns
+
+`string`

package/api-docs/functions/getDevices.mdx

@@ -0,0 +1,9 @@
+```ts
+function getDevices(): Promise<MediaDeviceInfo[]>;
+```
+
+**`Beta`**
+
+## Returns
+
+`Promise`\<`MediaDeviceInfo`[]\>

package/api-docs/functions/getFacingModeFromConstraintString.mdx

@@ -0,0 +1,13 @@
+```ts
+function getFacingModeFromConstraintString(constraint): "user" | "environment" | "left" | "right" | undefined;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `constraint` | `string` |
+
+## Returns
+
+`"user"` \| `"environment"` \| `"left"` \| `"right"` \| `undefined`

package/api-docs/functions/getInputDevicePermissionState.mdx

@@ -0,0 +1,21 @@
+```ts
+function getInputDevicePermissionState(
+   anyActiveAudioTrack, 
+   anyActiveVideoTrack, 
+getDevices): Promise<InputDevicePermission>;
+```
+
+A wrapper for `navigator.permissions.query` with fallback to use
+`navigator.mediaDevices.enumerateDevices` to guess the `PermissionState`
+
+## Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `anyActiveAudioTrack` | `boolean` | `false` | Has ever got an active audio to help the fallback to guess the state more accurately |
+| `anyActiveVideoTrack` | `boolean` | `false` | Has ever got an active video to help the fallback to guess the state more accurately |
+| `getDevices` | () => `Promise`\<`MediaDeviceInfo`[]\> | `...` | A function to get the list of devices, e.g. navigator.mediaDevices.enumerateDevices |
+
+## Returns
+
+`Promise`\<[`InputDevicePermission`](../interfaces/InputDevicePermission.mdx)\>

package/api-docs/functions/getValueFromConstrainNumber.mdx

@@ -0,0 +1,13 @@
+```ts
+function getValueFromConstrainNumber(constraint): number;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `constraint` | `ConstrainNumber` |
+
+## Returns
+
+`number`

package/api-docs/functions/hasAnyGrantedInput.mdx

@@ -0,0 +1,15 @@
+```ts
+function hasAnyGrantedInput(devices): boolean;
+```
+
+Check if provided devices have any granted input device
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] | The devices to check |
+
+## Returns
+
+`boolean`

package/api-docs/functions/hasAnyInputs.mdx

@@ -0,0 +1,23 @@
+```ts
+function hasAnyInputs(devices, grantedOnly): [boolean, boolean];
+```
+
+Check if provided devices have any video and audio inputs
+
+## Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] | `undefined` | The devices to lookup |
+| `grantedOnly` | `boolean` | `false` | When it is `true`, the device label is also taken into consideration |
+
+## Returns
+
+\[`boolean`, `boolean`\]
+
+A tuple of `[anyAudioInput, anyVideoInput]`, e.g. `[true, false]`
+means there is audio input but no video input
+
+## Default Value
+
+`false`

package/api-docs/functions/hasAudioInputs.mdx

@@ -0,0 +1,15 @@
+```ts
+function hasAudioInputs(devices): boolean;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] |
+
+## Returns
+
+`boolean`

package/api-docs/functions/hasAudioOrVideoInputs.mdx

@@ -0,0 +1,15 @@
+```ts
+function hasAudioOrVideoInputs(devices): boolean;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] |
+
+## Returns
+
+`boolean`

package/api-docs/functions/hasChangedInput.mdx

@@ -0,0 +1,16 @@
+```ts
+function hasChangedInput(oldInput, newInput): boolean;
+```
+
+An utility function to check the input device has been changed
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `oldInput` | \| [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx) \| `undefined` | The previous input device |
+| `newInput` | \| [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx) \| `undefined` | The current input device |
+
+## Returns
+
+`boolean`

package/api-docs/functions/hasRequestingDevice.mdx

@@ -0,0 +1,20 @@
+```ts
+function hasRequestingDevice(
+   request, 
+   kind, 
+   currentDevices): boolean;
+```
+
+Check if there is a requesting device with respecting to the current devices
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | \| [`InputDeviceConstraint`](../type-aliases/InputDeviceConstraint.mdx) \| `undefined` | Requesting input device constraint |
+| `kind` | `MediaDeviceKind` | The kind of the device |
+| `currentDevices` | [`IndexedDevices`](../interfaces/IndexedDevices.mdx) | The current indexed devices |
+
+## Returns
+
+`boolean`

package/api-docs/functions/hasVideoInputs.mdx

@@ -0,0 +1,15 @@
+```ts
+function hasVideoInputs(devices): boolean;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] |
+
+## Returns
+
+`boolean`

package/api-docs/functions/interpretCurrentFacingMode.mdx

@@ -0,0 +1,17 @@
+```ts
+function interpretCurrentFacingMode(currentTrack): "user" | "environment" | "left" | "right" | undefined;
+```
+
+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
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `currentTrack` | `MediaStreamTrack` \| `undefined` | The current video input track |
+
+## Returns
+
+`"user"` \| `"environment"` \| `"left"` \| `"right"` \| `undefined`

package/api-docs/functions/isDeviceGranted.mdx

@@ -0,0 +1,20 @@
+```ts
+function isDeviceGranted(device): boolean;
+```
+
+Check if provided device is a permission-granted device by inspecting the
+device label
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `device` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx) | The device to check |
+
+## Returns
+
+`boolean`
+
+## See
+
+[https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo/label#value](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo/label#value)

package/api-docs/functions/isExactDeviceConstraint.mdx

@@ -0,0 +1,15 @@
+```ts
+function isExactDeviceConstraint(constraint): boolean;
+```
+
+Check if provided constraint is an `exact` device constraint
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `constraint` | \| [`InputDeviceConstraint`](../type-aliases/InputDeviceConstraint.mdx) \| `undefined` |
+
+## Returns
+
+`boolean`

package/api-docs/functions/isFacingMode.mdx

@@ -0,0 +1,13 @@
+```ts
+function isFacingMode(s): s is "user" | "environment" | "left" | "right";
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `s` | `unknown` |
+
+## Returns
+
+s is "user" \| "environment" \| "left" \| "right"

package/api-docs/functions/isIndexedDevices.mdx

@@ -0,0 +1,13 @@
+```ts
+function isIndexedDevices(t): t is IndexedDevices;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `t` | `unknown` |
+
+## Returns
+
+`t is IndexedDevices`

package/api-docs/functions/isInputConstraintSet.mdx

@@ -0,0 +1,13 @@
+```ts
+function isInputConstraintSet(t): t is InputConstraintSet;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `t` | `unknown` |
+
+## Returns
+
+`t is InputConstraintSet`

package/api-docs/functions/isMediaDeviceInfo.mdx

@@ -0,0 +1,15 @@
+```ts
+function isMediaDeviceInfo(t): t is MediaDeviceInfo;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `t` | `unknown` |
+
+## Returns
+
+`t is MediaDeviceInfo`

package/api-docs/functions/isMediaDeviceInfoArray.mdx

@@ -0,0 +1,13 @@
+```ts
+function isMediaDeviceInfoArray(t): t is MediaDeviceInfo[];
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `t` | `unknown` |
+
+## Returns
+
+`t is MediaDeviceInfo[]`

package/api-docs/functions/isMediaStreamTrack.mdx

@@ -0,0 +1,15 @@
+```ts
+function isMediaStreamTrack(m): m is MediaStreamTrack;
+```
+
+**`Beta`**
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `m` | `unknown` |
+
+## Returns
+
+`m is MediaStreamTrack`

package/api-docs/functions/isRequestedInputDevice.mdx

@@ -0,0 +1,14 @@
+```ts
+function isRequestedInputDevice(request, response): boolean;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `request` | \| [`InputDeviceConstraint`](../type-aliases/InputDeviceConstraint.mdx) \| `undefined` |
+| `response` | \| [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx) \| `MediaDeviceTrackInfo` \| `undefined` |
+
+## Returns
+
+`boolean`