Occurs when the autoplay of an audio track fails.
The autoplay failure is caused by browsers' autoplay blocking, which does not affect video tracks.
In the Agora Web SDK, once the user has interacted with the webpage, the autoplay blocking is removed. You can deal with the issue in either of the following ways:
onAudioAutoplayFailed
callback, ensure that the user has interacted with the webpage before RemoteAudioTrack.play
or LocalAudioTrack.play
is called.RemoteAudioTrack.play
or LocalAudioTrack.play
, you can display a button and instruct the user to click it in the onAudioAutoplayFailed
callback.As long as the browser blocks autoplay, autoplay with sound is impossible before user interaction. As the number of visits on a webpage increases, the browser adds it to the autoplay whitelist, but this information is not accessible by JavaScript.
The following example demonstrates how to display a button for the user to click when autoplay fails.
If multiple audio tracks call
play()
, theonAudioAutoplayFailed
is triggered multiple times. The example uses theisAudioAutoplayFailed
object to avoid repeatedly creating buttons.
let isAudioAutoplayFailed = false;
AgoraRTC.onAudioAutoplayFailed = () => {
if (isAudioAutoplayFailed) return;
isAudioAutoplayFailed = true;
const btn = document.createElement("button");
btn.innerText = "Click me to resume the audio playback";
btn.onClick = () => {
isAudioAutoplayFailed = false;
btn.remove();
};
document.body.append(btn);
};
Occurs when a video capture device is added or removed.
AgoraRTC.onCameraChanged = (info) => {
console.log("camera changed!", info.state, info.device);
};
Parameters
Occurs when an audio sampling device is added or removed.
AgoraRTC.onMicrophoneChanged = (info) => {
console.log("microphone changed!", info.state, info.device);
};
Parameters
Since
4.1.0
Occurs when an audio playback device is added or removed.
AgoraRTC.onPlaybackDeviceChanged = (info) => {
console.log("speaker changed!", info.state, info.device);
};
Parameters
The version of the Agora Web SDK.
Since
4.2.0
Sets the region for connection.
This advanced feature applies to scenarios that have regional restrictions.
By default, the SDK connects to nearby Agora servers. After specifying the region, the SDK connects to the Agora servers within that region.
Note: The SDK supports specifying only one region.
Creates a local client object for managing a call.
This is usually the first step of using the Agora Web SDK.
The configurations for the client object, including channel profile and codec. The default codec is vp8
and default channel profile is rtc
. See ClientConfig for details.
Creates an audio track from an audio file or AudioBuffer object.
This method works with both the local and online audio files, supporting the following formats:
Configurations such as the file path, caching strategies, and encoder configuration.
Unlike other audio track objects, this audio track object adds the methods for audio playback control, such as playing, pausing, seeking and playback status querying.
Creates a video track from the video captured by a camera.
Configurations for the captured video, such as the capture device and the encoder configuration.
Creates a customized audio track.
This method creates a customized audio track from a MediaStreamTrack object.
Configurations for the customized audio track.
Creates a customized video track.
This method creates a customized video track from a MediaStreamTrack object.
Configurations for the customized video track. See CustomVideoTrackInitConfig.
You can set the sending bitrate for a customized video track by config. Other video encoder configurations are not supported.
Creates an audio track from the audio sampled by a microphone.
Configurations for the sampled audio, such as the capture device and the encoder configuration. See MicrophoneAudioTrackInitConfig.
Creates a video track for screen sharing.
Configurations for the screen-sharing video, such as encoder configuration and capture configuration.
Whether to share the audio of the screen sharing input source when sharing the screen.
enable
: Share the audio.disable
: (Default) Do not share the audio.auto
: Share the audio, dependent on whether the browser supports this function.Note:
- This function is only supported on Chrome 74 or later on Windows and macOS platforms.
- On Windows, this function allows you to share the audio when sharing the entire screen and sharing Chrome tabs, but not when sharing the application window. On macOS, this function allows you to share the audio only when sharing Chrome tabs.
- For the audio sharing to take effect, the end user must check Share audio in the pop-up window when sharing the screen.
withAudio
is enable
, then this method returns a list containing a video track for screen sharing and an audio track. If the end user does not check Share audio, the SDK throws an error.withAudio
is disable
, then this method returns a video track for screen sharing.withAudio
is auto
, then the SDK attempts to share the audio on browsers supporting this function.Creates a video track for screen sharing.
Configurations for the screen-sharing video, such as encoder configuration and capture configuration.
Whether to share the audio of the screen sharing input source when sharing the screen.
enable
: Share the audio.disable
: (Default) Do not share the audio.auto
: Share the audio, dependent on whether the browser supports this function.Note:
- This function is only supported on Chrome 74 or later on Windows and macOS platforms.
- On Windows, this function allows you to share the audio when sharing the entire screen and sharing Chrome tabs, but not when sharing the application window. On macOS, this function allows you to share the audio only when sharing Chrome tabs.
- For the audio sharing to take effect, the end user must check Share audio in the pop-up window when sharing the screen.
withAudio
is enable
, then this method returns a list containing a video track for screen sharing and an audio track. If the end user does not check Share audio, the SDK throws an error.withAudio
is disable
, then this method returns a video track for screen sharing.withAudio
is auto
, then the SDK attempts to share the audio on browsers supporting this function.Creates a video track for screen sharing.
Configurations for the screen-sharing video, such as encoder configuration and capture configuration.
Whether to share the audio of the screen sharing input source when sharing the screen.
enable
: Share the audio.disable
: (Default) Do not share the audio.auto
: Share the audio, dependent on whether the browser supports this function.Note:
- This function is only supported on Chrome 74 or later on Windows and macOS platforms.
- On Windows, this function allows you to share the audio when sharing the entire screen and sharing Chrome tabs, but not when sharing the application window. On macOS, this function allows you to share the audio only when sharing Chrome tabs.
- For the audio sharing to take effect, the end user must check Share audio in the pop-up window when sharing the screen.
withAudio
is enable
, then this method returns a list containing a video track for screen sharing and an audio track. If the end user does not check Share audio, the SDK throws an error.withAudio
is disable
, then this method returns a video track for screen sharing.withAudio
is auto
, then the SDK attempts to share the audio on browsers supporting this function.Disables log upload.
The log-upload function is disabled by default. If you have called enableLogUpload, then call this method when you need to stop uploading the log.
Enables log upload.
Call this method to enable log upload to Agora’s server.
The log-upload function is disabled by default. To enable this function, you must call this method before calling all the other methods.
If a user fails to join the channel, the log information (for that user) is unavailable on Agora's server.
Sets the output log level of the SDK.
Choose a level to see the logs preceding that level. The log level follows the sequence of NONE, ERROR, WARNING, INFO, and DEBUG.
For example, if you set the log level as AgoraRTC.Logger.setLogLevel(1);
, then you can see logs in levels INFO, ERROR, and WARNING.
The output log level.
Enumerates the video capture devices available, such as cameras.
If this method call succeeds, the SDK returns a list of video input devices in an array of MediaDeviceInfo objects.
Calling this method turns on the camera shortly for the device permission request. On browsers including Chrome 81 or later, Firefox, and Safari, the SDK cannot get accurate device information without permission for the media device.
Whether to skip the permission check. If you set this parameter as true
, the SDK does not trigger the request for media device permission. In this case, the retrieved media device information may be inaccurate.
true
: Skip the permission check.false
: (Default) Do not skip the permission check.Enumerates the media input and output devices available, such as microphones, cameras, and headsets.
If this method call succeeds, the SDK returns a list of media devices in an array of MediaDeviceInfo objects.
Calling this method turns on the camera and microphone shortly for the device permission request. On browsers including Chrome 81 or later, Firefox, and Safari, the SDK cannot get accurate device information without permission for the media device.
getDevices().then(devices => {
console.log("first device id", devices[0].deviceId);
}).catch(e => {
console.log("get devices error!", e);
});
Whether to skip the permission check. If you set this parameter as true
, the SDK does not trigger the request for media device permission. In this case, the retrieved media device information may be inaccurate.
true
: Skip the permission check.false
: (Default) Do not skip the permission check.Gets the sources for screen-sharing through Electron.
If this method call succeeds, the SDK returns a list of screen sources in an array of ElectronDesktopCapturerSource objects.
The type of screen sources (window/application/screen) to get. See ScreenSourceType. If it is left empty, this method gets all the available sources.
Enumerates the audio sampling devices available, such as microphones.
If this method call succeeds, the SDK returns a list of audio input devices in an array of MediaDeviceInfo objects.
Calling this method turns on the microphone shortly for the device permission request. On browsers including Chrome 81 or later, Firefox, and Safari, the SDK cannot get accurate device information without permission for the media device.
Whether to skip the permission check. If you set this parameter as true
, the SDK does not trigger the request for media device permission. In this case, the retrieved media device information may be inaccurate.
true
: Skip the permission check.false
: (Default) Do not skip the permission check.Since
4.1.0
Enumerates the audio playback devices available, such as speakers.
If this method call succeeds, the SDK returns a list of audio playback devices in an array of MediaDeviceInfo objects.
Calling this method turns on the microphone briefly for the device permission request. On browsers including Chrome 81 or later, Firefox, and Safari, the SDK cannot get accurate device information without permission for the media device.
Whether to skip the permission check. If you set this parameter as true
, the SDK does not trigger the request for media device permission. In this case, the retrieved media device information may be inaccurate.
true
: Skip the permission check.false
: (Default) Do not skip the permission check.Check whether an audio track is active.
The SDK determines whether an audio track is active by checking whether the volume changes during the specified time frame.
Agora recommends calling this method before starting a call to check the availability of the audio sampling device. You can pass the audio track from the audio sampled by a microphone as a parameter in this method to check whether the microphone works.
Notes:
- The check may fail in a quiet environment. Agora suggests you instruct the end user to speak or make some noise when calling this method.
- If an audio track is muted, this method returns
false
.- Do not call this method frequently as the check may affect web performance.
const audioTrack = await AgoraRTC.createMicrophoneAudioTrack({ microphoneId });
AgoraRTC.checkAudioTrackIsActive(audioTrack).then(result => {
console.log(`${ microphoneLabel } is ${ result ? "available" : "unavailable" }`);
}).catch(e => {
console.log("check audio track error!", e);
});
The local or remote audio track to be checked.
The time frame (ms) for checking. The default value is 5,000 ms.
Whether the volume in the specified audio track changes during the specified time frame:
true
: The volume changes. For the microphone audio track, it means the audio sampling device works.false
: The volume does not change. Possible reasons:Checks the compatibility of the current browser.
Use this method before calling createClient to check if the SDK is compatible with the web browser.
true
: The SDK is compatible with the current web browser.false
: The SDK is incompatible with the current web browser.Checks whether a video track is active.
The SDK determines whether a video track is active by checking for image changes during the specified time frame.
Agora recommends calling this method before starting a call to check the availability of the video capture device. You can pass the camera video track as a parameter in this method to check whether the camera works.
Notes:
- If a video track is muted, this method returns
false
.- Do not call this method frequently as the check may affect web performance.
const videoTrack = await AgoraRTC.createCameraVideoTrack({ cameraId });
AgoraRTC.checkVideoTrackIsActive(videoTrack).then(result => {
console.log(`${ cameraLabel } is ${ result ? "available" : "unavailable" }`);
}).catch(e => {
console.log("check video track error!", e);
});
The local or remote video track to be checked.
The time frame (ms) for checking. The default value is 5,000 ms.
Whether the image in the specified video track changes during the specified time frame:
true
: The image changes. For the camera video track, it means the video capture device works.false
: The image does not change. Possible reasons:Creates an object for configuring the media stream relay.
Creates an audio track and a video track.
Creates an audio track from the audio sampled by a microphone and a video track from the video captured by a camera.
Calling this method differs from calling createMicrophoneAudioTrack and createCameraVideoTrack separately:
- This method call requires access to the microphone and the camera at the same time. In this case, users only need to do authorization once.
- Calling createMicrophoneAudioTrack and createCameraVideoTrack requires access to the microphone and the camera separately. In this case, users need to do authorization twice.
Configurations for the sampled audio, such as the capture device and the encoder configurations.
Configurations for the captured video, such as the capture device and the encoder configurations.
Gets the codecs that the browser supports.
This method gets a list of the codecs supported by the SDK and the web browser. The Agora Web SDK supports video codecs VP8 and H.264, and audio codec OPUS.
Note:
- The method works with all major browsers. It gets an empty list if it does not recognize the browser or the browser does not support WebRTC.
- The returned codec list is based on the SDP used by the web browser and for reference only.
- Some Android phones claim to support H.264 but have problems in communicating with other platforms using this codec, in which case we recommend VP8 instead.
AgoraRTC.getSupportedCodec().then(result => {
console.log(`Supported video codec: ${result.video.join(",")});
console.log(`Supported audio codec: ${result.audio.join(",")});
});
A Promise
object. In the .then(function(result){})
callback, result
has the following properties:
video
: array, the supported video codecs. The array may include "H264"
and "VP8"
, or be empty.audio
: array, the supported audio codecs. The array may include "OPUS"
, or be empty.
The entry point of the Agora Web SDK.