API Reference

Dev Center





Video Call

Agora.io Community





Agora Web SDK API Reference

Overview AgoraRTC Client Stream

The Stream object created by the createStream method.

A stream represents a published local or remote media stream object in a call session.

Hierarchy

Stream

Methods

addTrack

addTrack(track: MediaStreamTrack): void

Adds the Audio or Video Track

This method adds the audio or video tracks into the stream.
example
Sample Code
```
var localStream = AgoraRTC.createStream({audio: true, video: false});
localStream.addTrack(anotherStream.getVideoTrack());
```
Note:
- This method does not support Firefox and Safari.
- A Stream object can have only one audio track and one video track at most.
Parameters
- track: MediaStreamTrack
  
  The track can be retrieved from the mediaStream method.
Returns void

adjustAudioMixingVolume

adjustAudioMixingVolume(level: number): void

Adjusts Audio Mixing Volume

Parameters
- level: number
  
  The volume of the mixing audio. The value ranges between 0 and 100 (default).
Returns void

close

close(): void

CLoses the Audio/Video Stream

This method closes the video/audio stream.

After calling this method, the camera and microphone authorizations will be reset.

Returns void

disableAudio

disableAudio(): void

Disables the Audio

This method disables the audio track in the stream.

It works only when the audio flag is true in the stream.

Returns void

disableVideo

disableVideo(): void

Disables the Video

This method disables the video track in the stream.

It works only when the video flag is true in the stream.

Returns void

enableAudio

enableAudio(): void

Enables the Audio

This method enables the audio track in the stream.

It works only when the audio flag is true in the stream.

By default the audio track is enabled. If you called disableAudio, call this method to enable audio.

Returns void

enableVideo

enableVideo(): void

Enables the Video

This method enables the video track in the stream.

It works only when the video flag is true in the stream.

By default the video track is enabled. If you called disableVideo, call this method to enable video.

Returns void

getAudioLevel

getAudioLevel(): number

Retrieves the Current Audio Level

This method retrieves the current audio level.

Call setTimeout or setInterval to retrieve the local or remote audio change.
example
Sample Code
```
setInterval(function() {
  var audioLevel = stream.getAudioLevel();
  // Use audioLevel to render the UI
}, 100)
```
This method does not apply to streams that contain no audio data and may result in warnings.

Note:

Due to browser policy changes, this method must be triggered by the user's gesture on the Chrome 70+ and Safari browsers, see Autoplay Policy Changes for details.
Returns number

getAudioMixingCurrentPosition

getAudioMixingCurrentPosition(): number | void

Retrieves the Current Position of the Audio Mixing

Retrieves the playback position (ms) of the audio.

Returns number | void

Returns the current position of the audio mixing if successful.

getAudioMixingDuration

getAudioMixingDuration(): number | void

Retrieves Audio Mixing Duration

Returns number | void

Returns the audio mixing duration (ms) if successful.

getAudioTrack

getAudioTrack(): MediaStreamTrack | void

Retrieves the Audio Track

This method retrieves the audio track in the stream and can be used together with replaceTrack.

Returns MediaStreamTrack | void

If the stream contains an audio track, it will be returned in a MediaStreamTrack object.

getId

getId(): number

Retrieves the Stream ID

This method retrieves the stream ID.

example

stream.getId()

Returns number

getStats

getStats(callback: function): void

Gets Connection Statistics

This method gets the connection statistics of the stream.

Note:

It may take some time to get some of the statistics.

Parameters
- callback: function
  The callback contains the connection statistics of the stream.
  - If it is a publishing stream, then the stats is LocalStreamStats.
  - If it is a subscribing stream, then the stats is RemoteStreamStats.
  - - (stats: LocalStreamStats | RemoteStreamStats): void
    - Parameters
      - stats: LocalStreamStats | RemoteStreamStats
      Returns void
Returns void

getVideoTrack

getVideoTrack(): MediaStreamTrack | void

Retrieves the Video Track

This method retrieves the video track in the stream and can be used together with replaceTrack.

Returns MediaStreamTrack | void

If the stream contains a video track, it will be returned in a MediaStreamTrack object.

hasAudio

hasAudio(): boolean

Retrieves the Audio Flag

This method retrieves the audio flag.

Returns boolean
- true: The stream contains audio data.
- false: The stream does not contain audio data.

hasVideo

hasVideo(): boolean

Retrieves the Video Flag

This method retrieves the video flag.

Returns boolean
- true: The stream contains video data.
- false: The stream does not contain video data.

init

init(onSuccess: function, onFailure: function): void

Initializes the Stream Object

This method initializes the stream object.

If this method fails, the returned callback will show the error message, for example: {type: "error", msg: "MEDIA_OPTION_INVALID"}.

The error messages include：
- MEDIA_OPTION_INVALID: The camera is occupied or the resolution is not supported (on browsers in early versions).
- DEVICES_NOT_FOUND: No device is found.
- NOT_SUPPORTED: The browser does not support using camera and microphone.
- PERMISSION_DENIED: The device is disabled by the browser or the user has denied permission of using the device.
- CONSTRAINT_NOT_SATISFIED: The settings are illegal (on browsers in early versions).
- UNDEFINED: Undefined error.
example
Sample Code
```
init(function() {
    console.log("local stream initialized");
    // publish the stream
    //……
}, function(err) {
    console.error("local stream init failed ", err);
    //error handling
});
```
Parameters
- onSuccess: function
  
  The callback when the method succeeds.
  - - (): void
    - Returns void
- onFailure: function
  
  The callback when the method fails.
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

on

on(event: "accessAllowed", callback: function): void
on(event: "accessDenied", callback: function): void
on(event: "stopScreenSharing", callback: function): void

This callback notifies the application that the user has given access to the camera and microphone.

Parameters
- event: "accessAllowed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the user has denied access to the camera and microphone.

Parameters
- event: "accessDenied"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that screen-sharing has stopped.

Parameters
- event: "stopScreenSharing"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void

pauseAudioMixing

pauseAudioMixing(): void

Pauses Audio Mixing

Returns void

play

play(HTMLElementID: string, option: object): void

Plays the Audio/Video Stream

This method plays the video or audio stream.

Note:

Due to browser policy changes, this method must be triggered by the user's gesture on the Chrome 70+ and Safari browsers, see Autoplay Policy Changes for details.
example
Sample Code
```
stream.play("agora_remote", {fit: 'contain'}); // stream will be played in the element with the ID agora_remote
```
Parameters
- HTMLElementID: string
  
  Represents the HTML element ID.
- option: object
  
  Options for playing the stream.
  - fit: string
    Video display mode:
    - 'cover': Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents. Refer to the cover option of object-fit in CSS.
    - 'contain': Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio will be filled with black. Refer to the contain option of object-fit in CSS.
    For local streams, by default the cover mode is used for video playing and the contain mode is used for screen sharing; for remote streams, by default the cover mode is used.
Returns void

removeTrack

removeTrack(track: MediaStreamTrack): void

Removes the Audio or Video Track

This method removes the audio or video tracks from the stream.

Note:
- If you need to change both the audio and video tracks, Agora recommends using the replaceTrack method instead.
- This method does not support Firefox and Safari.
example
Sample Code
```
var localStream = AgoraRTC.createStream({audio: true, video: true});
localStream.removeTrack(localStream.getAudioTrack());
```
Parameters
- track: MediaStreamTrack
  
  The track can be retrieved from the mediaStream method.
Returns void

replaceTrack

replaceTrack(MediaStreamTrack: MediaStreamTrack, onSuccess: function, onFailure: function): void

Replaces the Audio/Video Track

This method replaces the audio or video MediaStreamTrack in the local stream.

After the local stream is published, you can use this method to switch the cameras, or switch between the microphone and the music player.

The new track can be retrieved by getUserMedia, MediaElement.captureStream or other methods.

The replaced track will be stopped.

Note:
- Supports Chrome 65+, Safari, and latest Firefox.
- Firefox does not support switching audio tracks between different microphones. You can replace the audio track from the microphone with an audio file, or vice versa.
- Replacing audio tracks from external audio devices may not be fully supported on Safari.
- The subscriber will not be notified if the track gets replaced.
- Agora recommends you use switchDevice to switch the media input devices.
example
Sample Code
```
// Suppose we have a localStream1
localStream2 = AgoraRTC.createStream({video: true, cameraId: "XXX"});
localStream2.setVideoProfile('<same as localStream1>')
localStream2.init(function(){
    var newVideoTrack = localStream2.getVideoTrack();
    localStream1.replaceTrack(newVideoTrack);
});
```
Parameters
- MediaStreamTrack: MediaStreamTrack
  
  The new track.
- onSuccess: function
  
  The callback when the method succeeds.
  - - (): void
    - Returns void
- onFailure: function
  
  The callback when the method fails.
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

resumeAudioMixing

resumeAudioMixing(): void

Resumes Audio Mixing

Returns void

setAudioMixingPosition

setAudioMixingPosition(position: number): void

Sets the Audio Mixing Position

Sets the playback position of the audio mixing file to a different start position (by default plays from the beginning).

Parameters
- position: number
  
  The time (ms) to start playing the audio mixing file.
Returns void

setAudioOutput

setAudioOutput(deviceId: string, onSuccess: function, onFailure: function): void

Sets the Audio Output

This method sets the audio output device for the remote stream. You can use it to switch between the microphone and the speakerphone.

It can be called either before or after the remote stream is played.

Note:

Only Chrome 49+ supports this function.

Parameters
- deviceId: string
  
  The device ID can be retrieved from getDevices, whose kind should be "audiooutput".
- onSuccess: function
  - - (): void
    - Returns void
- onFailure: function
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

setAudioProfile

setAudioProfile(profile: "speech_standard" | "music_standard" | "standard_stereo" | "high_quality" | "high_quality_stereo"): void

Sets the Audio Profile

This method sets the audio profile.

It is optional and works only when called before Stream.init. The default value is "music_standard".

Note:

Due to the limitations of browsers, some browsers may not be fully compatible with the audio profile you set.
- Firefox does not support setting the audio encoding rate.
- Safari does not support stereo audio.
- The latest version of Google Chrome does not support playing stereo audio, but supports sending a stereo audio stream.
Parameters
- profile: "speech_standard" | "music_standard" | "standard_stereo" | "high_quality" | "high_quality_stereo"
  The audio profile has the following options：
  - "speech_standard": Sample rate 32 kHz, mono, encoding rate 24 Kbps.
  - "music_standard": Sample rate 48 kHz, mono, encoding rate 40 Kbps.
  - "standard_stereo": Sample rate 48 kHz, stereo, encoding rate 64 Kbps.
  - "high_quality": Sample rate 48 kHz, mono, encoding rate 128 Kbps.
  - "high_quality_stereo": Sample rate 48 kHz, stereo, encoding rate 192 Kbps.
Returns void

setAudioVolume

setAudioVolume(volume: number): void

Sets the Volume

This method set the volume for the remote stream.

It can be called either before or after the remote stream is played.

Parameters
- volume: number
  
  Ranges from 0 (muted) to 100 (loudest).
Returns void

setScreenProfile

setScreenProfile(profile: string): void

Sets the Screen Profile

This method sets the profile of the screen in screen-sharing.

Parameters

profile: string

The screen profile. See the following table for details.

Screen Profile Definition

Screen Profile	Resolution	Frame Rate
480p_1	640 × 480	5
480p_2	640 × 480	30
720p_1	1280 × 720	5
720p_2	1280 × 720	30
1080p_1	1920 × 1080	5
1080p_2	1920 × 1080	30

Note:

Due to limitations of some devices and browsers, the resolution you set may fail to take effect and get adjusted by the browser. In this case, billings will be calculated based on the actual resolution.

Returns void

setVideoProfile

setVideoProfile(profile: string): void

Sets the Video Profile

This method sets the video profile.

It is optional and works only when called before Stream.init. The default value is "480p_1".

example: setVideoProfile("480p");

Parameters

profile: string

The video profile. See the following table for its definition and supported profiles in different scenarios.

Video Profile Definition

Video profile	Resolution	Frame rate (fps)	Bitrate (Kbps)	Chrome	Firefox/Opera	Safari
120p	160 × 120	15	65	✓
120p_1	160 × 120	15	65	✓
120p_3	120 × 120	15	50	✓
180p	320 × 180	15	140	✓
180p_1	320 × 180	15	140	✓
180p_3	180 × 180	15	100	✓
180p_4	240 × 180	15	120	✓
240p	320 × 240	15	200	✓
240p_1	320 × 240	15	200	✓
240p_3	240 × 240	15	140	✓
240p_4	424 × 240	15	220	✓
360p	640 × 360	15	400	✓
360p_1	640 × 360	15	400	✓
360p_3	360 × 360	15	260	✓
360p_4	640 × 360	30	600	✓
360p_6	360 × 360	30	400	✓
360p_7	480 × 360	15	320	✓
360p_8	480 × 360	30	490	✓
360p_9	640 × 360	15	800	✓
360p_10	640 × 360	24	800	✓
360p_11	640 × 360	24	1000	✓
480p	640 × 480	15	500	✓	✓	✓
480p_1	640 × 480	15	500	✓	✓	✓
480p_2	648 × 480	30	1000	✓	✓	✓
480p_3	480 × 480	15	400	✓	✓	✓
480p_4	640 × 480	30	750	✓	✓	✓
480p_6	480 × 480	30	600	✓	✓	✓
480p_8	848 × 480	15	610	✓	✓	✓
480p_9	848 × 480	30	930	✓	✓	✓
480p_10	640 × 480	10	400	✓	✓	✓
720p	1280 × 720	15	1130	✓	✓	✓
720p_1	1280 × 720	15	1130	✓	✓	✓
720p_2	1280 × 720	15	2080	✓	✓	✓
720p_3	1280 × 720	30	1710	✓	✓	✓
720p_5	960 × 720	15	910	✓	✓	✓
720p_6	960 × 720	30	1380	✓	✓	✓
1080p	1920 × 1080	15	2080	✓		✓
1080p_1	1920 × 1080	15	2080	✓		✓
1080p_2	1920 × 1080	30	3000	✓		✓
1080p_3	1920 × 1080	30	3150	✓		✓
1080p_5	1920 × 1080	60	4780	✓		✓
1440p	2560 × 1440	30	4850	✓		✓
1440p_1	2560 × 1440	30	4850	✓		✓
1440p_2	2560 × 1440	60	7350	✓		✓
4K	3840 × 2160	30	8910	✓		✓
4K_1	3840 × 2160	30	8910	✓		✓
4K_3	3840 × 2160	60	13500	✓		✓

Note:

Whether 1080 resolution or above can be supported depends on the device. If the device cannot support 1080p, the actual frame rate is lower than the one listed in the table. Agora optimizes the video on low-end devices.
The Safari browser does not support modifying the video frame rate (30 fps by default). If you set a frame rate other than 30 fps on Safari, the browser may change or reject your setting.
Due to limitations of some devices and browsers, the resolution you set may fail to take effect and get adjusted by the browser. In this case, billings are calculated based on the actual resolution.

Returns void

startAudioMixing

startAudioMixing(options: object, callback: function): void

Starts Audio Mixing

This method mixes the specified online audio file with the audio stream from the microphone; or, it replaces the microphone’s audio stream with the specified online audio file. You can specify the number of playback loops and play time duration.

Note:
- This method supports the following browsers:
  - Safari 12+
  - Chrome 65+
  - Latest Firefox
- Call this method when you are in a channel, otherwise, it may cause issues.
- Due to browser policy changes, this method must be triggered by the user's gesture on the Chrome 70+ and Safari browsers, see Autoplay Policy Changes for details.
Parameters
- options: object
  
  Audio mixing settings.
  - Optional cycle?: number
    
    Number of playback loops (only supports Chrome 65+), a positive integer.
  - filePath: string
    
    Path of the online audio file to mix. Supported audio formats: mp3, aac, and other audio formats depending on the browser.
  - Optional loop?: boolean
    Whether the audio mixing file loops infinitely.
    - true: The audio mixing file loops infinitely. Do not use this option if cycle is specified.
    - false: Disables the infinite loops.
  - playTime: number
    
    Sets the playback position (ms) of the audio mixing file. If you need to play the file from the beginning, set this paramter to 0.
  - Optional replace?: boolean
    Whether the online audio file replaces the local audio stream.
    - true: The content of the online audio file replaces the audio stream from the microphone.
    - false: The online audio file is mixed with the audio stream from the microphone.
    Note:
    
    Safari does not support this parameter.
- callback: function
  The callback of this method:
  - null: The method succeeds.
  - err: The method fails.
  - - (err: string | null): void
    - Parameters
      - err: string | null
      Returns void
Returns void

stop

stop(): void

Stops the Audio/Video Stream

Call this method to stop playing the stream set by Stream.play.

Returns void

stopAudioMixing

stopAudioMixing(): void

Stops Audio Mixing

Returns void

switchDevice

switchDevice(type: string, deviceId: string, onSuccess: function, onFailure: function): void

Switches the Media Input Device

This method switches between the media input devices:
- Audio input devices, such as microphones.
- Video input devices, such as cameras.
If you call this method after publish, there is no need to re-publish the stream after switching the device.

Note:

This method does not support the following scenarios:
- Dual-stream mode is enabled by enableDualStream.
- The remote stream.
- The stream is created by defining the audioSource and videoSource properties.
- The Firefox browser.
Parameters
- type: string
  
  Type of the device: "audio" or "video".
- deviceId: string
  
  Device ID, which can be retrieved from getDevices.
- onSuccess: function
  
  The callback when the method succeeds.
  - - (): void
    - Returns void
- onFailure: function
  
  The callback when the method fails.
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

Hierarchy

Index

Methods

Methods

addTrack

Parameters

track: MediaStreamTrack

Returns void

adjustAudioMixingVolume

Parameters

level: number

Returns void

close

Returns void

disableAudio

Returns void

disableVideo

Returns void

enableAudio

Returns void

enableVideo

Returns void

getAudioLevel

Returns number

getAudioMixingCurrentPosition

Returns number | void

getAudioMixingDuration

Returns number | void

getAudioTrack

Returns MediaStreamTrack | void

getId

Returns number

getStats

Parameters

callback: function

Parameters

stats: LocalStreamStats | RemoteStreamStats

Returns void

Returns void

getVideoTrack

Returns MediaStreamTrack | void

hasAudio

Returns boolean

hasVideo

Returns boolean

init

Parameters

onSuccess: function

Returns void

onFailure: function

Parameters

err: any

Returns void

Returns void

on

Parameters

event: "accessAllowed"

callback: function

Parameters

evt: any

Returns void

Returns void

Parameters

event: "accessDenied"

callback: function

Parameters

evt: any

Returns void

Returns void

Parameters

event: "stopScreenSharing"

callback: function

Parameters

evt: any

Returns void

Returns void

pauseAudioMixing

Returns void

play

Parameters

event: "accessAllowed"

event: "accessDenied"