@pexip/media-control 20.3.4 → 21.0.0

package/api-docs/type-aliases/CursorCaptureConstraint.mdx

@@ -0,0 +1,10 @@
+```ts
+type CursorCaptureConstraint = ExtractObjectValueTypes<typeof CURSOR_CAPTURE_CONSTRAINT>;
+```
+
+The `CursorCaptureConstraint` enumerates the conditions under which the
+cursor is captured.
+
+## See
+
+[https://w3c.github.io/mediacapture-screen-share/#cursorcaptureconstraint](https://w3c.github.io/mediacapture-screen-share/#cursorcaptureconstraint)

package/api-docs/type-aliases/DeviceChangedChanges.mdx

@@ -0,0 +1,19 @@
+```ts
+type DeviceChangedChanges = object;
+```
+
+**`Beta`**
+
+DeviceChange Event
+
+```
+devices (raw)
+```
+
+## Properties
+
+| Property | Type |
+| ------ | ------ |
+| <a id="found"></a> `found` | [`MediaDeviceInfoLike`](MediaDeviceInfoLike.mdx)[] |
+| <a id="lost"></a> `lost` | [`MediaDeviceInfoLike`](MediaDeviceInfoLike.mdx)[] |
+| <a id="devices"></a> `devices` | [`MediaDeviceInfoLike`](MediaDeviceInfoLike.mdx)[] |

package/api-docs/type-aliases/DisplayCaptureSurfaceType.mdx

@@ -0,0 +1,10 @@
+```ts
+type DisplayCaptureSurfaceType = ExtractObjectValueTypes<typeof DISPLAY_CAPTURE_SURFACE_TYPE>;
+```
+
+The `DisplayCaptureSurfaceType` enumeration describes the different types of
+display surface
+
+## See
+
+[https://w3c.github.io/mediacapture-screen-share/#displaycapturesurfacetype](https://w3c.github.io/mediacapture-screen-share/#displaycapturesurfacetype)

package/api-docs/type-aliases/Events.mdx

@@ -0,0 +1,51 @@
+```ts
+type Events = 
+  | {
+  id: string;
+  type: Mute;
+}
+  | {
+  id: string;
+  type: Unmute;
+}
+  | {
+  id: string;
+  type: Ended;
+}
+  | {
+  devices: MediaDeviceInfoLike[];
+  type: DevicesChanged;
+}
+  | {
+  devices: MediaDeviceInfoLike[];
+  devicesFound: MediaDeviceInfoLike[];
+  type: DevicesFound;
+}
+  | {
+  devices: MediaDeviceInfoLike[];
+  devicesLost: MediaDeviceInfoLike[];
+  type: DevicesLost;
+}
+  | {
+  devices: MediaDeviceInfoLike[];
+  type: NoInputDevices;
+}
+  | {
+  device: MediaDeviceInfoLike;
+  type: DeviceLost;
+}
+  | {
+  error: Error;
+  type: Error;
+}
+  | {
+  facingMode: boolean;
+  stream: MediaStream;
+  type: Stream;
+  video: boolean;
+};
+```
+
+**`Beta`**
+
+Event object by MediaEventType

package/api-docs/type-aliases/FacingMode.mdx

@@ -0,0 +1,3 @@
+```ts
+type FacingMode = typeof FACING_MODE[number];
+```

package/api-docs/type-aliases/IncludeExcludeConstraint.mdx

@@ -0,0 +1,3 @@
+```ts
+type IncludeExcludeConstraint = ExtractObjectValueTypes<typeof INCLUDE_EXCLUDE_CONSTRAINT>;
+```

package/api-docs/type-aliases/InputDeviceConstraint.mdx

@@ -0,0 +1,6 @@
+```ts
+type InputDeviceConstraint = 
+  | DeviceConstraint
+  | InputConstraintSet
+  | boolean;
+```

package/api-docs/type-aliases/MediaDeviceInfoLike.mdx

@@ -0,0 +1,13 @@
+```ts
+type MediaDeviceInfoLike = Omit<MediaDeviceInfo, "toJSON"> & object;
+```
+
+**`Beta`**
+
+A striped version of MediaDeviceInfo
+
+## Type Declaration
+
+| Name | Type |
+| ------ | ------ |
+| `toJSON?` | `MediaDeviceInfo`\[`"toJSON"`\] |

package/api-docs/type-aliases/MediaEvent.mdx

@@ -0,0 +1,7 @@
+```ts
+type MediaEvent = CustomEvent<Events>;
+```
+
+**`Beta`**
+
+Custom Media Event

package/api-docs/type-aliases/MediaStreamTrackLike.mdx

@@ -0,0 +1,7 @@
+```ts
+type MediaStreamTrackLike = Pick<MediaStreamTrack, "id" | "kind" | "label" | "getSettings" | "stop">;
+```
+
+**`Beta`**
+
+Lesser strict type of `MediaStreamTrack`

package/api-docs/type-aliases/Unsubscribe.mdx

@@ -0,0 +1,7 @@
+```ts
+type Unsubscribe = () => void;
+```
+
+## Returns
+
+`void`

package/api-docs/variables/CURSOR_CAPTURE_CONSTRAINT.mdx

@@ -0,0 +1,18 @@
+```ts
+const CURSOR_CAPTURE_CONSTRAINT: object;
+```
+
+The `CursorCaptureConstraint` enumerates the conditions under which the
+cursor is captured.
+
+## Type Declaration
+
+| Name | Type | Default value |
+| ------ | ------ | ------ |
+| <a id="never"></a> `Never` | `"never"` | `'never'` |
+| <a id="always"></a> `Always` | `"always"` | `'always'` |
+| <a id="motion"></a> `Motion` | `"motion"` | `'motion'` |
+
+## See
+
+[https://w3c.github.io/mediacapture-screen-share/#cursorcaptureconstraint](https://w3c.github.io/mediacapture-screen-share/#cursorcaptureconstraint)

package/api-docs/variables/DEVICE_ID_SEPARATOR.mdx

@@ -0,0 +1,3 @@
+```ts
+const DEVICE_ID_SEPARATOR: ":" = ':';
+```

package/api-docs/variables/DISPLAY_CAPTURE_SURFACE_TYPE.mdx

@@ -0,0 +1,18 @@
+```ts
+const DISPLAY_CAPTURE_SURFACE_TYPE: object;
+```
+
+The `DisplayCaptureSurfaceType` enumeration describes the different types of
+display surface
+
+## Type Declaration
+
+| Name | Type | Default value |
+| ------ | ------ | ------ |
+| <a id="monitor"></a> `Monitor` | `"monitor"` | `'monitor'` |
+| <a id="window"></a> `Window` | `"window"` | `'window'` |
+| <a id="browser"></a> `Browser` | `"browser"` | `'browser'` |
+
+## See
+
+[https://w3c.github.io/mediacapture-screen-share/#displaycapturesurfacetype](https://w3c.github.io/mediacapture-screen-share/#displaycapturesurfacetype)

package/api-docs/variables/INCLUDE_EXCLUDE_CONSTRAINT.mdx

@@ -0,0 +1,10 @@
+```ts
+const INCLUDE_EXCLUDE_CONSTRAINT: object;
+```
+
+## Type Declaration
+
+| Name | Type | Default value |
+| ------ | ------ | ------ |
+| <a id="include"></a> `Include` | `"include"` | `'include'` |
+| <a id="exclude"></a> `Exclude` | `"exclude"` | `'exclude'` |

package/api-docs/variables/findAudioInputDevices.mdx

@@ -0,0 +1,19 @@
+```ts
+const findAudioInputDevices: (devices) => MediaDeviceInfoLike[];
+```
+
+**`Beta`**
+
+Find in the list of devices only the audio input ones
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] | A list of media devices from `navigator.mediaDevices.enumerateDevices()`. Will be used for search target |
+
+## Returns
+
+[`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[]
+
+List of devices that are audio inputs

package/api-docs/variables/findAudioOutputDevices.mdx

@@ -0,0 +1,19 @@
+```ts
+const findAudioOutputDevices: (devices) => MediaDeviceInfoLike[];
+```
+
+**`Beta`**
+
+Find in the list of devices only the audio output ones
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] | A list of media devices from `navigator.mediaDevices.enumerateDevices()`. Will be used for search target |
+
+## Returns
+
+[`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[]
+
+List of devices that are audio outputs

package/api-docs/variables/findVideoInputDevices.mdx

@@ -0,0 +1,19 @@
+```ts
+const findVideoInputDevices: (devices) => MediaDeviceInfoLike[];
+```
+
+**`Beta`**
+
+Find in the list of devices only the video input ones
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `devices` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[] | A list of media devices from `navigator.mediaDevices.enumerateDevices()`. Will be used for search target |
+
+## Returns
+
+[`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx)[]
+
+List of devices that are video inputs

package/api-docs/variables/getUserMedia.mdx

@@ -0,0 +1,21 @@
+```ts
+getUserMedia: (__namedParameters) => Promise<MediaStream>;
+```
+
+Get MediaStream with provided [input constraints](../interfaces/MediaDeviceRequest.mdx)
+
+**`Beta`**
+
+Get MediaStream with MediaDeviceRequest
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `__namedParameters` | [`MediaDeviceRequest`](../interfaces/MediaDeviceRequest.mdx) |
+
+## Returns
+
+`Promise`\<`MediaStream`\>
+
+MediaStream

package/api-docs/variables/isAudioInput.mdx

@@ -0,0 +1,13 @@
+```ts
+const isAudioInput: (device) => boolean;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `device` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx) |
+
+## Returns
+
+`boolean`

package/api-docs/variables/isAudioOutput.mdx

@@ -0,0 +1,13 @@
+```ts
+const isAudioOutput: (device) => boolean;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `device` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx) |
+
+## Returns
+
+`boolean`

package/api-docs/variables/isVideoInput.mdx

@@ -0,0 +1,13 @@
+```ts
+const isVideoInput: (device) => boolean;
+```
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `device` | [`MediaDeviceInfoLike`](../type-aliases/MediaDeviceInfoLike.mdx) |
+
+## Returns
+
+`boolean`

package/api-docs/variables/setDefaultConstraints.mdx

@@ -0,0 +1,17 @@
+```ts
+setDefaultConstraints: (newConstraints) => void;
+```
+
+Set default media stream constraints
+
+A [MediaStreamConstraints](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamConstraints) object specifying the types of media to request, along with any requirements for each type.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `newConstraints` | `MediaStreamConstraints` |
+
+## Returns
+
+`void`

package/api-docs/variables/subscribe.mdx

@@ -0,0 +1,25 @@
+```ts
+subscribe: (listener) => () => void;
+```
+
+Subscribe media events
+
+**`Beta`**
+
+Subscription media events
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `listener` | (`event`) => `void` |
+
+## Returns
+
+```ts
+(): void;
+```
+
+### Returns
+
+`void`

package/dist/devices.js

@@ -372,6 +372,9 @@ export const resolveInputDevice = (tracksOrDevice, findInput) => {
     return undefined;
 };
 export const isStreamingRequestingDevice = (request, trackOrDevice, devices) => {
+    if (request === false) {
+        return false;
+    }
     if (request === undefined) {
         return true;
     }

package/dist/typeGuards.d.ts

@@ -21,11 +21,11 @@ export declare const EXTENDED_CONSTRAIN_STRING_KEYS: readonly ["videoSegmentatio
 export type ExtendedConstrainStringKeys = (typeof EXTENDED_CONSTRAIN_STRING_KEYS)[number];
 export type ConstrainStringKeys = (typeof CONSTRAIN_STRING_KEYS)[number];
 export declare const CONSTRAIN_U_LONG_KEYS: readonly ["width", "height", "sampleRate", "sampleSize", "channelCount"];
-export declare const EXTENDED_CONSTRAIN_U_LONG_KEYS: readonly ["backgroundBlurAmount", "edgeBlurAmount"];
+export declare const EXTENDED_CONSTRAIN_U_LONG_KEYS: readonly ["backgroundBlurAmount", "edgeBlurAmount", "morphErodeRadiusPx", "morphPass", "morphDilateRadiusPx", "lightWrapBlurAmount", "downSampleFactor"];
 export type ExtendedConstrainULongKeys = (typeof EXTENDED_CONSTRAIN_U_LONG_KEYS)[number];
 export type ConstrainULongKeys = (typeof CONSTRAIN_U_LONG_KEYS)[number];
 export declare const CONSTRAIN_DOUBLE_KEYS: readonly ["aspectRatio", "frameRate", "latency"];
-export declare const EXTENDED_CONSTRAIN_DOUBLE_KEYS: readonly ["foregroundThreshold", "maskCombineRatio"];
+export declare const EXTENDED_CONSTRAIN_DOUBLE_KEYS: readonly ["foregroundThreshold", "backgroundThreshold", "sigmaSpace", "sigmaRangeLo", "sigmaRangeHi", "maskCombineRatio", "personCenterX", "personCenterY", "lightWrapIntensity", "lightWrapTightness", "lightWrapEdgeBand"];
 export type ExtendedConstrainDoubleKeys = (typeof EXTENDED_CONSTRAIN_DOUBLE_KEYS)[number];
 export type ConstrainDoubleKeys = (typeof CONSTRAIN_DOUBLE_KEYS)[number];
 export declare const CONSTRAIN_BOOLEAN_KEYS: readonly ["echoCancellation", "autoGainControl", "noiseSuppression", "pan", "tilt", "zoom"];
@@ -33,7 +33,7 @@ export declare const CONSTRAIN_BOOLEAN_KEYS: readonly ["echoCancellation", "auto
  * Extends boolean constraint keys for our own implementation of the media
  * feature
  */
-export declare const EXTENDED_CONSTRAIN_BOOLEAN_KEYS: readonly ["vad", "asd", "mixWithAdditionalMedia", "denoise"];
+export declare const EXTENDED_CONSTRAIN_BOOLEAN_KEYS: readonly ["vad", "asd", "mixWithAdditionalMedia", "denoise", "excludeBystanders"];
 export type ExtendedConstrainBooleanKeys = (typeof EXTENDED_CONSTRAIN_BOOLEAN_KEYS)[number];
 export type ConstrainBooleanKeys = (typeof CONSTRAIN_BOOLEAN_KEYS)[number];
 /**

package/dist/typeGuards.js

@@ -39,6 +39,11 @@ export const CONSTRAIN_U_LONG_KEYS = [
 export const EXTENDED_CONSTRAIN_U_LONG_KEYS = [
     'backgroundBlurAmount',
     'edgeBlurAmount',
+    'morphErodeRadiusPx',
+    'morphPass',
+    'morphDilateRadiusPx',
+    'lightWrapBlurAmount',
+    'downSampleFactor',
 ];
 export const CONSTRAIN_DOUBLE_KEYS = [
     'aspectRatio',
@@ -47,7 +52,16 @@ export const CONSTRAIN_DOUBLE_KEYS = [
 ];
 export const EXTENDED_CONSTRAIN_DOUBLE_KEYS = [
     'foregroundThreshold',
+    'backgroundThreshold',
+    'sigmaSpace',
+    'sigmaRangeLo',
+    'sigmaRangeHi',
     'maskCombineRatio',
+    'personCenterX',
+    'personCenterY',
+    'lightWrapIntensity',
+    'lightWrapTightness',
+    'lightWrapEdgeBand',
 ];
 export const CONSTRAIN_BOOLEAN_KEYS = [
     'echoCancellation',
@@ -70,6 +84,8 @@ export const EXTENDED_CONSTRAIN_BOOLEAN_KEYS = [
     'mixWithAdditionalMedia',
     // Noise Suppression using our own impl
     'denoise',
+    // Bystander removal
+    'excludeBystanders',
 ];
 /**
  * The keys from the `MediaTrackConstraintSet`

package/dist/types.d.ts

@@ -107,9 +107,93 @@ export interface InputConstraintSet extends MediaTrackConstraints {
      */
     backgroundImageUrl?: ConstrainDOMString;
     /**
-     * The ratio to be used for smoothing segmentation mask
+     * The ratio to be used for smoothing segmentation mask.
+     * How much uncertainty enables temporal blend, [0,1].
+     * Higher = more frame-to-frame blending, more stability but more trailing ghosts.
+     * Typical: 0.6–0.85.
      */
     maskCombineRatio?: ConstrainDouble;
+    /**
+     * [0,1] Lower mask confidence: all mask pixels <= this are considered definite background.
+     * Adjust to make mask edges tighter or more permissive for background inclusion.
+     * Example: 0.3 ("mask < 0.3 = sure background").
+     */
+    backgroundThreshold?: ConstrainDouble;
+    /**
+     * Bilateral filter: sigma in pixel space for mask edge snapping.
+     * Controls the neighborhood/pixel distance—higher is larger window (5–10 typical).
+     */
+    sigmaSpace?: ConstrainDouble;
+    /**
+     * Bilateral filter: minimum sigma in color/luma (for mask interiors), [0,1].
+     * Controls how little color difference is needed to cross-mask regions away from edge.
+     * Lower = sharper edge preservation in mask interiors.
+     * Example: 0.2
+     */
+    sigmaRangeLo?: ConstrainDouble;
+    /**
+     * Bilateral filter: maximum sigma in color/luma (for mask uncertain zones), [0,1].
+     * Controls how much color similarity is required at uncertain/edge mask locations.
+     * Higher = more mask smoothing at edges.
+     * Example: 0.8
+     */
+    sigmaRangeHi?: ConstrainDouble;
+    /**
+     * Whether to exclude bystanders/connected people from the output mask.
+     * The main person instance (closest to personCenter OR largest blob) is kept in
+     * the output mask.
+     * All other bystanders/connected people are suppressed (bystander removal).
+     */
+    excludeBystanders?: ConstrainBoolean;
+    /**
+     * Person center: normalized in [0,1] image coordinates for main subject selection.
+     * Used by the CCL/bias filter to select the main person blob.
+     */
+    personCenterX?: ConstrainDouble;
+    /**
+     * Person center: normalized in [0,1] image coordinates for main subject selection.
+     * Used by the CCL/bias filter to select the main person blob.
+     */
+    personCenterY?: ConstrainDouble;
+    /**
+     * Morphological erosion: radius in pixels [1,12]. Sets kernel size for bridge-breaking.
+     * Larger values break thicker bridges but may erode fine details.
+     */
+    morphErodeRadiusPx?: ConstrainULong;
+    /**
+     * Morphological pass: number of separable passes [1,10].
+     * More passes increase the effective span.
+     */
+    morphPass?: ConstrainULong;
+    /**
+     * Geodesic dilation: radius in pixels [1,12]. Must match erosion for good reconstruction.
+     */
+    morphDilateRadiusPx?: ConstrainULong;
+    /**
+     * [0,1] Light wrap amount (halo intensity) at mask edge.
+     * Wraps blurred background color just outside the subject edge onto the subject boundary for realism.
+     */
+    lightWrapIntensity?: ConstrainDouble;
+    /**
+     * [0.5,4.0] Controls power/tightness of the wrap band falloff. Higher = tighter/narrower wrap.
+     */
+    lightWrapTightness?: ConstrainDouble;
+    /**
+     * Width of the wrap band (feather size, in normalized mask units) between the backgroundThreshold
+     * and foregroundThreshold in [0.0, (foregroundThreshold - backgroundThreshold) / 2]
+     * Higher = wider soft halo.
+     */
+    lightWrapEdgeBand?: ConstrainDouble;
+    /**
+     * Blur amount used for background color in the wrap band (units=blur passes).
+     */
+    lightWrapBlurAmount?: ConstrainULong;
+    /**
+     * Downsampling factor for mask/blurring, must be [2,4].
+     * 2 = half resolution, 4 = quarter resolution for faster filtering.
+     * Use for performance tuning vs. quality.
+     */
+    downSampleFactor?: ConstrainULong;
     /**
      * Image Url that is being used for video overlay effects
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pexip/media-control",
-  "version": "20.3.4",
-  "homepage": "https://gitlab.com/pexip/zoo",
+  "version": "21.0.0",
+  "homepage": "https://developer.pexip.com",
   "bugs": "https://gitlab.com/pexip/zoo/issues",
   "repository": {
     "type": "git",
@@ -27,27 +27,32 @@
       "import": "./dist/*.js"
     }
   },
+  "directories": {
+    "doc": "api-docs"
+  },
   "files": [
-    "dist"
+    "dist",
+    "api-docs"
   ],
   "scripts": {
     "build": "pexip-bundler build",
     "build:sourcemap": "pexip-bundler build --sourcemap",
-    "clean": "rm -rf dist",
+    "clean": "rm -rf dist api-docs",
     "dev": "pexip-bundler dev",
-    "prepack": "yarn clean && yarn build",
+    "prepack": "yarn clean && yarn build && yarn docs",
     "test": "jest",
     "check-format": "prettier --ignore-path=../../.prettierignore --check .",
     "format": "prettier --ignore-path=../../.prettierignore --write .",
     "lint": "yarn run -T biome lint",
-    "typecheck": "yarn tsc --noEmit -p tsconfig.build.json"
+    "typecheck": "yarn tsc --noEmit -p tsconfig.build.json",
+    "docs": "typedoc"
   },
   "dependencies": {
-    "@pexip/utils": "17.1.2"
+    "@pexip/utils": "17.2.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.2.0",
-    "@pexip/bundler": "18.1.2",
+    "@pexip/bundler": "18.2.0",
     "@swc/core": "^1.10.12",
     "@swc/jest": "^0.2.39",
     "@types/uuid": "^8.3.0",
@@ -55,6 +60,8 @@
     "jest": "^29.5.12",
     "jest-junit": "^16.0.0",
     "prettier": "^3.2.5",
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "~5.7.3",
     "uuid": "^11.0.0"
   },