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

Index

Methods

addTrack

  • 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

  • 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

    Returns void

getVideoTrack

  • 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

  • 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:

    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