updateInputSettings()
updateInputSettings({inputSettings})
Updates settings applied to local media inputs during a Daily call. Returns a Promise
that resolves with the resulting inputSettings
object. The Promise does not resolve until settings are updated.
A call resulting in a change to input settings will also trigger an 'input-settings-updated'
event.
{inputSettings}
Input settings are passed as an object with video
and/or audio
as a key. Both video
and audio
take an object with optional fields, settings
and processor
. The settings
object should either be a MediaTrackConstraints
object or a custom object, providing a custom track to be used in lieu of Daily getting the track. The processor
takes an object specifying the type
of processor and an optional config
for further processor specifications. See below for more details on each.
When updating input settings, only the media devices and top-level setting(s) (settings
or processor
) that you specify will be updated. i.e. If you call updateInputSettings({video: {...}})
, audio
will be unaffected. Similarly, if you only specify video.processor
, the video's constraints will remain unchanged. However, at the level of settings
or processor
, you must specify all the settings you want applied. These settings are not merged with existing settings. i.e. If you currently have sampleRate
set for audio and you want to additionally turn off echoCancellation
, you must include sampleRate
in the new settings
object.
Audio / Video settings
Providing custom constraints
For both video
and audio
objects, settings
takes either a MediaTrackConstraints
object or an object specifying a customTrack
. When specifying constraints, be sure to specify ALL constraints you want to apply. What you provide will be applied as-is and will not be merged with existing constraints.
If you want to change just the deviceId
, without affecting the other constraints, setInputDevicesAsync()
does just that. It is a helper method that wraps updating the input setting and merges the deviceId
with existing constraints.
For most use cases, we do not recommend overriding constraints. Track constraints are implemented inconsistently across browsers. Daily has sorted through these, using reasonable defaults to accommodate these differences along with other browser-specific issues. When providing constraints via input settings, you override these defaults. If our defaults do not match your needs, be sure to refer to the MediaTrackConstraints
documentation for more information on what constraints are available on which platforms and test across platforms to ensure they behave as intended.
Providing a custom track
For custom tracks, simply provide an object that looks like {customTrack: track}
, where track
is a MediaStreamTrack
object.
Providing a custom track means that you are responsible for managing the lifecycle of that track. Daily will not stop the track for you and will not handle any state changes on the track.
When a custom track is provided, any existing constraints will be cleared. These are not meant to be used together. To unset a custom track and let Daily take control back over track handling, simply call updateInputSettings()
with new or empty settings.
Video processor
For video
objects, type
has the following allowed values: "none"
, "background-image"
, "background-blur"
and "face-detection"
. Changing type
to "none"
turns off the video processor.
Video processors are currently only supported on desktop browsers.
Also, only one video processor
type
can be applied at a time. For example, changingtype
toface-detection
turns off thebackground-image
andbackground-blur
video processors.
Setting type
to "background-blur"
obscures the local participant's background.
If "background-blur"
is enabled, then an additional strength
value can be passed to config
. The strength
value is a float greater than 0 and less than or equal to 1, with 1 being the default and strongest blur.
Setting type
to "background-image"
will replace the participant's background with the image passed in the config
property. The nested source
property should be set to either an HTTP or data URI. Supported file extensions are .jpg
, .jpeg
, and .png
.
Example 1: Set your background-image
using a hosted file:
Example 2: Set your background-image
using Data URI, supplied by an ArrayBuffer
. Note that there are many ways to provide an ArrayBuffer, this example shows how to use the FileReader API:
Setting type
to "face-detection"
doesn't apply any changes to the participant's background. However, it starts the identification
of the number of people in view at a given time and triggers the face-counts-updated
event when the face count has been updated.
Audio processor
For audio
objects, type
has two allowed values: "none"
and "noise-cancellation"
. If "noise-cancellation"
is set, changing type
to "none"
turns off the audio processor.
"noise-cancellation"
is supported on the following browsers:
Desktop:
- Safari (version 17.4.1 and newer)
- Firefox
- Chromium-based browsers (e.g. Chrome, Edge, Brave)
Mobile:
- iOS Safari (version 17.4.1 and newer)
Setting type
to "noise-cancellation"
reduces background noise on the microphone input.
Error handling
If any invalid fields are provided or the wrong types are used, an error will be thrown immediately. If an error occurs in the process of applying the provided settings or processors, a nonfatal-error
of type input-settings
will be emitted with deatils about what specifically went wrong.
Settings errors
If the constraints provided result in a getUserMedia()
error, a camera-error
will also be emitted and the input will likely be muted (There are scenarios where if the device was already on and only a minor constraint was being applied, the device can remain on). When a constraints error occurs, the settings are reset to defaults so that they do not repeatedly cause issues. Note: If the device is off or has not been initialized at the time of the update, the issue will not be detected until the device is turned on and only the camera-error
event will be emitted. The settings will still be cleared and an input-settings-updated
event will be emitted with the cleared settings.
Processor errors
If an error occurs after the settings have been applied and the processor has started, a nonfatal-error
of type video-processor-error
or audio-processor-error
will be emitted. The processor will be turned off and the processor settings will be cleared. An input-settings-updated
event will also be emitted with the cleared settings. For video processor failures, the video will be turned off to ensure the user is not broadcasting unintended content.
;