@pexip/media-control

media-control is meant to extend the mediaDevices api methods such as getUserMedia, enumerateDevices and events on media streams and tracks. The final goal is to have a library that gives a stable and robust way to use these methods while guaranteeing that the developer has better control over which devices are delivered, fail, or exist.

Enumerations

• MediaDeviceFailure
• MediaDeviceKinds
• MediaEventType

Interfaces

• InputConstraintSet
• InputDevicePermission
• MediaControl
• MediaDeviceRequest
• MediaInput
• StreamTrackEventHandlers

Type Aliases

DeviceChangedChanges

Ƭ DeviceChangedChanges: Object

DeviceChange Event

devices (raw)
|--- authorized
|        |--- found
|        |--- lost
|--- unauthorized

Type declaration

Name	Type
authorized	MediaDeviceInfoLike[]
devices	MediaDeviceInfoLike[]
found	MediaDeviceInfoLike[]
lost	MediaDeviceInfoLike[]
unauthorized	MediaDeviceInfoLike[]

---

Events

Ƭ Events: { id: string ; type: Mute } | { id: string ; type: Unmute } | { id: string ; type: Ended } | { devices: MediaDeviceInfoLike[] ; type: DevicesChanged } | { authorizedDevices: MediaDeviceInfoLike[] ; devices: MediaDeviceInfoLike[] ; type: DevicesFound ; unauthorizedDevices: MediaDeviceInfoLike[] } | { authorizedDevices: MediaDeviceInfoLike[] ; devices: MediaDeviceInfoLike[] ; type: DevicesLost ; unauthorizedDevices: MediaDeviceInfoLike[] } | { authorizedDevices: MediaDeviceInfoLike[] ; devices: MediaDeviceInfoLike[] ; type: DevicesUnauthorized } | { devices: MediaDeviceInfoLike[] ; type: NoInputDevices } | { device: MediaDeviceInfoLike ; type: DeviceLost } | { error: Error ; type: Error } | { facingMode: boolean ; stream: MediaStream ; type: Stream ; video: boolean }

Event object by MediaEventType

---

FacingMode

Ƭ FacingMode: typeof FACING_MODE[number]

---

MediaDeviceInfoLike

Ƭ MediaDeviceInfoLike: Omit<MediaDeviceInfo, "toJSON"> & { settings?: MediaTrackSettings ; toJSON?: MediaDeviceInfo["toJSON"] }

A striped version of MediaDeviceInfo

---

MediaEvent

Ƭ MediaEvent: CustomEvent<Events>

Custom Media Event

---

MediaStreamTrackLike

Ƭ MediaStreamTrackLike: Pick<MediaStreamTrack, "id" | "kind" | "label" | "getSettings" | "stop">

Lesser strict type of MediaStreamTrack

---

Unsubscribe

Ƭ Unsubscribe: () => void

Type declaration

▸ (): void

Returns

void

Functions

applyConstraints

▸ applyConstraints(tracks, constraints): Promise<void>

Call applyConstraints foreach track accordingly

Parameters

Name	Type	Description
tracks	undefined | MediaStreamTrack[]	Tracks to be applied
constraints	MediaDeviceRequest	constraints to be applied

Returns

Promise<void>

---

areMultipleFacingModeSupportted

▸ areMultipleFacingModeSupportted(currentDevices, getSupportedConstraints?): 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

Parameters

Name	Type	Description
currentDevices	MediaDeviceInfoLike[]	Current list of devices available
getSupportedConstraints	() => MediaTrackSupportedConstraints	A function to get supported constraints, i.e. navigator.mediaDevices.getSupportedConstraints()

Returns

boolean

---

areTracksEnabled

▸ areTracksEnabled(stream, type): boolean

Checks that tracks with a given type are enabled in the stream

Parameters

Name	Type	Description
stream	undefined | MediaStream	MediaStream used for comparison
type	"audio" | "video"	MediaInput used for comparison

Returns

boolean

Return true when all the tracks are enabled false otherwise

---

compareDevices

▸ compareDevices(deviceInfo, key?): (anotherDeviceInfo: MediaDeviceInfoLike) => boolean

Compare 2 devices to see if they are the same by deviceId or label as a fallback

Parameters

Name	Type	Default value
deviceInfo	MediaDeviceInfoLike	undefined
key	"toJSON" | "deviceId" | "groupId" | "label"	'deviceId'

Returns

fn

▸ (anotherDeviceInfo): boolean

Parameters

Name	Type
anotherDeviceInfo	MediaDeviceInfoLike

Returns

boolean

---

createStreamTrackEventSubscriptions

▸ createStreamTrackEventSubscriptions(track, handlers): Unsubscribe

Create a MediaStreamTrack's native events subscription

See

https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack#events

Parameters

Name	Type	Description
track	MediaStreamTrack	The track used for the subscription
handlers	StreamTrackEventHandlers	An object contains the event handlers

Returns

Unsubscribe

---

createTrackDevicesChanges

▸ createTrackDevicesChanges(prevDevices?): (devices: MediaDeviceInfoLike[]) => { authorized: MediaDeviceInfoLike[] ; devices: MediaDeviceInfoLike[] = uniqueDevices; found: MediaDeviceInfoLike[] ; lost: MediaDeviceInfoLike[] ; unauthorized: MediaDeviceInfoLike[] }

Parameters

Name	Type	Default value
prevDevices	MediaDeviceInfoLike[]	[]

Returns

fn

▸ (devices): Object

Parameters

Name	Type
devices	MediaDeviceInfoLike[]

Returns

Object

Name	Type
authorized	MediaDeviceInfoLike[]
devices	MediaDeviceInfoLike[]
found	MediaDeviceInfoLike[]
lost	MediaDeviceInfoLike[]
unauthorized	MediaDeviceInfoLike[]

---

deviceChanged

▸ deviceChanged(fn): () => void

Unified interface for subscribing DeviceChangedChanges Event

Parameters

Name	Type
fn	(event: DeviceChangedChanges) => void

Returns

fn

▸ (): void

Returns

void

---

extractConstraintsWithKeys

▸ extractConstraintsWithKeys<T>(keys): (constraints: undefined | InputDeviceConstraint) => Pick<Constraints, T>

Extract the constraints with provided keys

Example

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');

Type parameters

Name	Type
T	extends "deviceId" | "groupId" | "device" | "videoSegmentation" | "videoSegmentationModel" | "denoise" | "vad" | "asd" | "mixWithAdditionalMedia" | "flipHorizontal" | "bgImageUrl" | "resizeMode" | "facingMode" | "echoCancellation" | "autoGainControl" | "noiseSuppression" | ConstrainNumberKeys

Parameters

Name	Type	Description
keys	T[]	The keys to be used for the extraction

Returns

fn

an object with the provided key and the value-param tuple

▸ (constraints): Pick<Constraints, T>

Parameters

Name	Type
constraints	undefined | InputDeviceConstraint

Returns

Pick<Constraints, T>

---

findAudioInputDevices

▸ findAudioInputDevices(devices): MediaDeviceInfoLike[]

Find in the list of devices only the audio input ones

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target

Returns

MediaDeviceInfoLike[]

List of devices that are audio inputs

---

findAudioOutputDevices

▸ findAudioOutputDevices(devices): MediaDeviceInfoLike[]

Find in the list of devices only the audio output ones

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target

Returns

MediaDeviceInfoLike[]

List of devices that are audio outputs

---

findCurrentAudioOutputId

▸ findCurrentAudioOutputId(audioOutput?, devices?): string

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.

Parameters

Name	Type	Description
audioOutput?	MediaDeviceInfoLike	Audio output as MediaDeviceInfo
devices?	MediaDeviceInfoLike[]	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target

Returns

string

Audio output id or empty string if couldn't find it.

---

findCurrentVideoInputDeviceIdFromStream

▸ findCurrentVideoInputDeviceIdFromStream(stream): undefined | string

Find videoinput device id in the stream

Parameters

Name	Type	Description
stream	MediaStream	Media stream to do the lookup

Returns

undefined | string

A object may contains the devices

---

findDevice

▸ findDevice(deviceToFind, useFallback?): (devices: readonly MediaDeviceInfoLike[]) => undefined | MediaDeviceInfoLike

Lookup the the device from devices list

Remarks

When we cannot find the device by deviceId, we compare the label as last resort, and return the first one.

Parameters

Name	Type	Default value	Description
deviceToFind	MediaDeviceInfoLike	undefined	Provide a device info to be used for the searching
useFallback	boolean	true	Whether to use label as a fallback when there is no match from using deviceId

Returns

fn

▸ (devices): undefined | MediaDeviceInfoLike

Parameters

Name	Type
devices	readonly MediaDeviceInfoLike[]

Returns

undefined | MediaDeviceInfoLike

---

findDeviceFromConstraints

▸ findDeviceFromConstraints(constraints, devices): undefined | boolean | MediaDeviceInfoLike

Find device from the device list with provided constraints

Parameters

Name	Type	Description
constraints	undefined | InputDeviceConstraint	The constraints to be used for the lookup
devices	MediaDeviceInfoLike[]	The devices to be used for the lookup

Returns

undefined | boolean | MediaDeviceInfoLike

true means it can be any devices, undefined means not found, otherwise, the matched device will be returned

---

findDeviceWithDeviceId

▸ findDeviceWithDeviceId(devices, deviceId): undefined | MediaDeviceInfoLike

Finds device with given deviceId

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target
deviceId	string	id that represents desired device

Returns

undefined | MediaDeviceInfoLike

device with given deviceId

---

findDevicesByKind

▸ findDevicesByKind(kind): (devices: MediaDeviceInfoLike[]) => MediaDeviceInfoLike[]

Find in the list of devices with given MediaDeviceKind

Parameters

Name	Type	Description
kind	MediaDeviceKind	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target

Returns

fn

List of devices that have required MediaDeviceKind

▸ (devices): MediaDeviceInfoLike[]

Parameters

Name	Type
devices	MediaDeviceInfoLike[]

Returns

MediaDeviceInfoLike[]

---

findMediaInputFromMediaStreamTrack

▸ findMediaInputFromMediaStreamTrack(devices): (track?: MediaStreamTrack) => undefined | MediaDeviceInfoLike

Find the MediaDeviceInfo from provided MediaDeviceInfo[] by comparing with provided MediaStreamTrack

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	A device list used for the searching

Returns

fn

MediaDeviceInfo if found, otherwise undefined

▸ (track?): undefined | MediaDeviceInfoLike

Parameters

Name	Type
track?	MediaStreamTrack

Returns

undefined | MediaDeviceInfoLike

---

findMediaInputFromStream

▸ findMediaInputFromStream(devices): (stream: undefined | MediaStream) => MediaInput

Find media input from media stream

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target

Returns

fn

A object may contains the devices

▸ (stream): MediaInput

Parameters

Name	Type
stream	undefined | MediaStream

Returns

MediaInput

---

findPermissionGrantedDevices

▸ findPermissionGrantedDevices(devices): MediaDeviceInfoLike[]

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.

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target

Returns

MediaDeviceInfoLike[]

List of devices that has permission granted

---

findVideoInputDevices

▸ findVideoInputDevices(devices): MediaDeviceInfoLike[]

Find in the list of devices only the video input ones

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target

Returns

MediaDeviceInfoLike[]

List of devices that are video inputs

---

getDevices

▸ getDevices(): Promise<MediaDeviceInfo[]>

Future proofing: in case we want to alter the values or type returned by enumerateDevices

Example

import {getDevices} from "media-control";

const devices = await getDevices();
// return MediaDeviceInfo[]

Returns

Promise<MediaDeviceInfo[]>

a list of currently available devices

---

getFacingModeFromConstraintString

▸ getFacingModeFromConstraintString(constraint): undefined | "user" | "environment" | "left" | "right"

Parameters

Name	Type
constraint	string

Returns

undefined | "user" | "environment" | "left" | "right"

---

getInputDevicePermissionState

▸ getInputDevicePermissionState(anyActiveStream?): Promise<InputDevicePermission>

A wrapper for navigator.permissions.query with fallback to use navigator.mediaDevices.enumerateDevices to guess the PermissionState

Parameters

Name	Type	Default value	Description
anyActiveStream	boolean	false	Has ever got an active stream to help the fallback to guess the state more accurately

Returns

Promise<InputDevicePermission>

---

getUserMedia

▸ getUserMedia(«destructured»): Promise<MediaStream>

Get MediaStream with provided input constraints

Parameters

Name	Type
«destructured»	MediaDeviceRequest

Returns

Promise<MediaStream>

---

getValueFromConstrainNumber

▸ getValueFromConstrainNumber(constraint): number

Parameters

Name	Type
constraint	ConstrainNumber

Returns

number

---

hasAnyGrantedInput

▸ hasAnyGrantedInput(devices): boolean

Check if provided devices have any granted input device

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	The devices to check

Returns

boolean

---

hasAnyInputs

▸ hasAnyInputs(devices, grantedOnly?): [boolean, boolean]

Check if provided devices have any video and audio inputs

Default Value

false

Parameters

Name	Type	Default value	Description
devices	MediaDeviceInfoLike[]	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

---

hasAudioInputs

▸ hasAudioInputs(devices): boolean

Check if list contains audio inputs

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target

Returns

boolean

True when some audio inputs false otherwise

---

hasAudioOrVideoInputs

▸ hasAudioOrVideoInputs(devices): boolean

Check if list contains media inputs

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target

Returns

boolean

True when some media inputs false otherwise

---

hasChangedInput

▸ hasChangedInput(oldInput, newInput): boolean

An utility function to check the input device has been changed

Parameters

Name	Type	Description
oldInput	undefined | MediaDeviceInfoLike	The previous input device
newInput	undefined | MediaDeviceInfoLike	The current input device

Returns

boolean

---

hasRequestingDevice

▸ hasRequestingDevice(request, kind, currentDevices): boolean

Parameters

Name	Type
request	undefined | InputDeviceConstraint
kind	MediaDeviceKind
currentDevices	MediaDeviceInfoLike[]

Returns

boolean

---

hasVideoInputs

▸ hasVideoInputs(devices): boolean

Check if list contains video inputs

Parameters

Name	Type	Description
devices	MediaDeviceInfoLike[]	A list of media devices from navigator.mediaDevices.enumerateDevices(). Will be used for search target

Returns

boolean

True when some video inputs false otherwise

---

interpretCurrentFacingMode

▸ interpretCurrentFacingMode(currentTrack): undefined | "user" | "environment" | "left" | "right"

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

Name	Type	Description
currentTrack	undefined | MediaStreamTrack	The current video input track

Returns

undefined | "user" | "environment" | "left" | "right"

---

isAudioInput

▸ isAudioInput(device): boolean

Parameters

Name	Type
device	MediaDeviceInfoLike

Returns

boolean

---

isAudioOutput

▸ isAudioOutput(device): boolean

Parameters

Name	Type
device	MediaDeviceInfoLike

Returns

boolean

---

isDeviceGranted

▸ isDeviceGranted(device): boolean

Check if provided device is a permission-granted device by inspecting the device label

See

https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo/label#value

Parameters

Name	Type	Description
device	MediaDeviceInfoLike	The device to check

Returns

boolean

---

isExactDeviceConstraint

▸ isExactDeviceConstraint(constraint): boolean

Check if provided constraint is an exact device constraint

Parameters

Name	Type
constraint	undefined | InputDeviceConstraint

Returns

boolean

---

isFacingMode

▸ isFacingMode(s): s is "user" | "environment" | "left" | "right"

Parameters

Name	Type
s	unknown

Returns

s is "user" | "environment" | "left" | "right"

---

isMediaDeviceInfo

▸ isMediaDeviceInfo(t): t is MediaDeviceInfo

Check if provided is MediaDeviceInfo

Parameters

Name	Type
t	unknown

Returns

t is MediaDeviceInfo

---

isMediaDeviceInfoArray

▸ isMediaDeviceInfoArray(t): t is MediaDeviceInfo[]

Parameters

Name	Type
t	unknown

Returns

t is MediaDeviceInfo[]

---

isMediaStreamTrack

▸ isMediaStreamTrack(m): m is MediaStreamTrack

Check if provided is MediaStreamTrack

Parameters

Name	Type
m	unknown

Returns

m is MediaStreamTrack

---

isRequestedInputDevice

▸ isRequestedInputDevice(request, response): boolean

Parameters

Name	Type
request	undefined | InputDeviceConstraint
response	undefined | MediaDeviceInfoLike

Returns

boolean

---

isRequestedInputTrack

▸ isRequestedInputTrack(request, current): boolean

Compare request and the input to see if the request has been fulfilled

Parameters

Name	Type
request	undefined | InputDeviceConstraint
current	undefined | MediaDeviceInfoLike | MediaStreamTrack

Returns

boolean

---

isRequestedResolution

▸ isRequestedResolution(request, response): boolean

Parameters

Name	Type
request	undefined | InputDeviceConstraint
response	undefined | MediaDeviceInfoLike

Returns

boolean

---

isStreamingRequestedDevices

▸ isStreamingRequestedDevices(request, stream, devices): Object

Check if provided request has already been fulfilled

Parameters

Name	Type	Description
request	MediaDeviceRequest	A media request constraints
stream	undefined | MediaStream	Current media stream
devices	MediaDeviceInfoLike[]	-

Returns

Object

audio - The stream is using the same device as requested if true video - The stream is using the same device as requested if true

Name	Type
audio	boolean
video	boolean

---

isStreamingRequestedDevicesBase

▸ isStreamingRequestedDevicesBase(request, tracksOrDevices, devices): Object

Parameters

Name	Type
request	MediaDeviceRequest
tracksOrDevices	Object
tracksOrDevices.audio?	MediaDeviceInfoLike | MediaStreamTrack[]
tracksOrDevices.video?	MediaDeviceInfoLike | MediaStreamTrack[]
devices	MediaDeviceInfoLike[]

Returns

Object

Name	Type
audio	boolean
video	boolean

---

isVideoInput

▸ isVideoInput(device): boolean

Parameters

Name	Type
device	MediaDeviceInfoLike

Returns

boolean

---

mergeConstraints

▸ mergeConstraints(baseConstraints): (constraints: undefined | InputDeviceConstraint) => boolean | InputConstraintSet

Merge base constraints with provided base constraints and another constraints

Parameters

Name	Type
baseConstraints	undefined | boolean | InputConstraintSet

Returns

fn

▸ (constraints): boolean | InputConstraintSet

Parameters

Name	Type
constraints	undefined | InputDeviceConstraint

Returns

boolean | InputConstraintSet

---

muteStreamTrack

▸ muteStreamTrack(stream?): (mute: boolean, mediaType: "audio" | "video" | "all") => void

Set MediaStreamTrack['enabled'] according to mute param for the provided stream

Default Value

'all'

See

https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/enabled

Parameters

Name	Type	Description
stream?	MediaStream	Media stream

Returns

fn

▸ (mute, mediaType?): void

Parameters

Name	Type	Default value
mute	boolean	undefined
mediaType	"audio" | "video" | "all"	'all'

Returns

void

---

relaxInputConstraint

▸ relaxInputConstraint(input, devices): undefined | InputDeviceConstraint

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.

Parameters

Name	Type	Description
input	undefined | InputDeviceConstraint	The input constraints to be relaxed
devices	MediaDeviceInfoLike[]	The current device list

Returns

undefined | InputDeviceConstraint

---

setDefaultConstraints

▸ setDefaultConstraints(newConstraints): void

Set default media stream constraints

A MediaStreamConstraints object specifying the types of media to request, along with any requirements for each type.

Parameters

Name	Type
newConstraints	MediaStreamConstraints

Returns

void

---

setLogger

▸ setLogger(newLogger): void

Parameters

Name	Type
newLogger	Logger

Returns

void

---

shouldRequestDevice

▸ shouldRequestDevice(request, tracks, currentDevices): boolean

Decide if we should send a new gUM request based on the inputs

Parameters

Name	Type	Description
request	undefined | InputDeviceConstraint	Requesting input device constraint
tracks	MediaStreamTrack[]	The current media stream tracks
currentDevices	MediaDeviceInfoLike[]	The current list of device of the same kind of the request

Returns

boolean

true means the request should be conducted, otherwise false.

---

stopMediaStream

▸ stopMediaStream(stream, onStopped?): 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

Parameters

Name	Type	Description
stream	undefined | MediaStream	MediaStream which we mutate
onStopped?	(track: MediaStreamTrack) => void	callback to be called when the track is stopped

Returns

void

---

subscribe

▸ subscribe(listener): () => void

Subscribe media events

Parameters

Name	Type
listener	(event: MediaEvent) => void

Returns

fn

▸ (): void

Returns

void

---

toKey

▸ toKey(«destructured»): string

Convert provided info to key for Map

Parameters

Name	Type
«destructured»	ToKeyOptions

Returns

string

---

toMediaDeviceInfoLike

▸ toMediaDeviceInfoLike(track): undefined | MediaDeviceInfoLike

Convert MediaStreamTrack to MediaDeviceInfoLike

Parameters

Name	Type
track	MediaStreamTrack

Returns

undefined | MediaDeviceInfoLike