Local Stream Object (LocalStream)

initialize

initialize(): Promise<StreamInitializeResult>

[Function Description]

Initializes a local audio and video stream object based on the input parameter StreamConfig of createStream. Streams can be played only after being initialized.

[Request Parameters]

None

[Response Parameters]

Stream initialization result, which is of the StreamInitializeResult type.

StreamInitializeResult indicates the stream initialization result. The object is inherited from RtcError. The following methods are provided:

• To obtain the initialization results of all media types, run the following command:

  getMediaCaptureResult(): MediaCaptureResult[]

• To obtain the initialization result of a specified media type, run the following command:

  getMediaCaptureResultByType(type: MediaType): MediaCaptureResult

MediaCaptureResult is defined as:

{

• type: (mandatory) media type. The type is MediaType. The values of MediaType can be audio and video.
• track: (optional) track generated if the media type is initialized successfully. The type is MediaStreamTrack.
• error: (optional) error generated if the media type fails to be initialized. The type is RtcError.

}

If the audio/video initialization fails, the error information is returned in the result. Related error codes are 90000001 and 90100017 to 90100020. For details, see Table 1.

setAudioProfile

setAudioProfile(profile: string|RTCAudioProfile): void

[Function Description]

Sets the audio stream sampling rate, number of audio channels, and bit rate. If this API is not called, the SDK uses the default value.

[Request Parameters]

RTCAudioProfile is defined as: {

• sampleRate: (optional) sampling rate. The type is number.
• channelCount: (optional) number of audio channels. The type is number.
• bitrate: (optional) bitrate, in bit/s. The type is number.

}

[Response Parameters]

None

This method must be called before initialize.

setVideoProfile

setVideoProfile(profile: string|RTCVideoProfile,resolutionId?: string): void

[Function Description]

Sets video stream parameters, such as the resolution, frame rate, and bit rate. If this API is not called, the SDK uses the default value 360p_2. If the video stream has been published, it will be automatically published to the remote end again.

[Request Parameters]

• profile: (mandatory) The type is string or RTCVideoProfile. If the type is string, the resolution, frame rate, and bitrate are shown in Table 3. If the type is RTCVideoProfile, you need to set this parameter as required. You are advised to use a defined profile. If an invalid value is used, the default profile 360p_2 is used.

  Table 3 Resolution, frame rate, and bitrate of profile

  profile	Resolution	Frame Rate	Minimum Bitrate (kbit/s)	Maximum Bitrate (kbit/s)
  90p_1	160 x 90	15	64	110
  90p_2	120 x 90	15	64	110
  120p_1	160 x 120	15	64	120
  120p_2	120 x 120	15	64	110
  180p_1	320 x 180	15	80	320
  180p_2	240 x 180	15	80	170
  180p_3	180 x 180	15	64	130
  240p_1	320 x 240	15	100	400
  240p_2	240 x 240	15	80	320
  270p_1	480 x 270	15	160	600
  300p_1	400 x 300	15	200	500
  360p_1	640 x 360	15	200	800
  360p_2	480 x 360	15	200	700
  360p_3	360 x 360	15	150	600
  450p_1	800 x 450	15	300	950
  480p_1	640 x 480	15	250	900
  480p_2	480 x 480	15	200	800
  540p_1	960 x 540	15	400	1000
  630p_1	1120 x 630	15	450	1150
  720p_1	1280 x 720	15	500	1500
  720p_2	960 x 720	15	450	1100
  1080p_1	1920 x 1080	15	600	2000
  1080p_2	1440 x 1080	15	550	1700

• resolutionId: (optional) The type is string. In the dual-stream scenario, specify the resolution ID of the video to be set. If the resolution ID is not specified, the video with the highest resolution is selected by default.

RTCVideoProfile is defined as: {

• width: (optional) width of the resolution, in pixels. The type is number.
• height: (optional) height of the resolution, in pixels. The type is number.
• frameRate: (optional) video frame rate, in fps. The type is number.
• minBitrate: (optional) minimum video bitrate, in bit/s. The type is number.
• maxBitrate: (optional) maximum video bitrate, in bit/s. The type is number.

}

[Response Parameters]

None

• This API cannot be dynamically called for custom streams created using videoSource. It can be called only for streams collected by cameras.
• Due to the limitations of the device capture capability, system performance, and browser, the actual video resolution, frame rate, and bitrate may not match the preset value. In this case, the browser automatically adjusts the resolution to match the preset value. The actual resolution is subject to the collected resolution.
• Whether 1080p or higher resolution data can be captured depends on the device capabilities and system performance. iOS Safari does not support 1080p data capture.
• The 1080p resolution in the profile table is newly added in version 2.0.0. If the 1080p resolution needs to be captured in version 1.0, customize a profile.
• Firefox does not support custom frame rate. The default frame rate is 30 fps.
• You can customize a profile to meet your service requirements.

setScreenProfile

setScreenProfile(profile: string|RTCScreenProfile): void

[Function Description]

Sets presentation stream parameters, such as the resolution, frame rate, and bit rate. If this API is not called, the SDK uses the default value 720p.

[Request Parameters]

profile: (mandatory) The type is string or RTCScreenProfile. If the type is string, the resolution, frame rate, and bitrate are shown in Table 4. If the type is RTCScreenProfile, you need to set this parameter as required. You are advised to use a defined profile. If an invalid value is used, the default profile 720p is used.

RTCScreenProfile is defined as: {

• width: (optional) width of the resolution, in pixels. The type is number.
• height: (optional) height of the resolution, in pixels. The type is number.
• frameRate: (optional) video frame rate, in fps. The type is number.
• bitrate: (optional) bitrate, in bit/s. The type is number.

}

[Response Parameters]

None

This method must be called before initialize.

addAudioTrackCapture

addAudioTrackCapture(microphoneId?: string): promise<MediaStreamTrack>

[Function Description]

Adds audio track capture to an initialized local stream object if the audio is not initialized or the audio fails to be initialized. If the local stream has been published, it will be automatically published to the remote end again. This API is added in version 1.10.0.

[Request Parameters]

microphoneId: (optional) ID of the microphone to be captured. The type is string. If this parameter is not passed, the SDK uses microphoneId specified in the input parameter StreamConfig of createStream.

[Response Parameters]

The type is MediaStreamTrack. It indicates the track that is successfully added.

After removing an audio track by calling the removeTrack AP, you can call this API to add the audio track again.

addVideoTrackCapture

addVideoTrackCapture(option?: VideoCaptureOption): promise<MediaStreamTrack>

[Function Description]

Adds video track capture to an initialized local stream object if the video is not initialized or the video fails to be initialized. If the local stream has been published, it will be automatically published to the remote end again. This API is added in version 1.10.0.

[Request Parameters]

option: (optional) capture parameters. The type is VideoCaptureOption.

VideoCaptureOption is defined as: {

• cameraId: (optional) The type is string. It specifies the ID of a camera. For Android devices, user indicates the front-facing camera, and environment indicates the rear-facing camera. If this parameter is not passed, the SDK uses cameraId and facingMode specified in the input parameter StreamConfig of createStream.
• resolutionId: (optional) The type is string. It specifies the resolution ID of the video to be configured. If this parameter is not passed, the video with the highest resolution is selected by default.

}

[Response Parameters]

The type is MediaStreamTrack. It indicates the track that is successfully added.

After removing a video track by calling the removeTrack API, you can call this API to add the video track again.

addResolution

addResolution(profile: string|RTCVideoProfile,audio?: boolean): promise<RTCVideoProfileInfo>

[Function Description]

Adds a video with a specific resolution to an initialized local stream object. If the local stream has been published, it will be automatically published to the remote end again.

[Request Parameters]

• profile: (mandatory) parameter information about the video resolution to be added. The type is string. For details about the RTCVideoProfile description, see setVideoProfile.
• audio: (optional) whether to create the audio. The type is Boolean. The value true indicates yes and the value false indicates no. The audio in a stream is common to all resolutions in the stream. If the audio is enabled but no audio track is configured, the audio is created by default.

[Response Parameters]

The type is RTCVideoProfileInfo. It indicates the profile information of the resolution of the video that is added successfully. For details about the definition of RTCVideoProfileInfo, see getStreamInfo.

If the operation fails, StreamInitializeResult is returned. For details about the definition of StreamInitializeResult, see initialize.

• Currently, a local stream supports a maximum of two resolutions.
• When the high- and low-quality streams are enabled, there are restrictions on the setVideoProfile API for setting stream resolution. The maximum resolution allowed is subject to the stream of higher resolution. Exercise caution when using this API.

removeResolution

removeResolution(resolutionId: string): promise<void>

[Function Description]

Removes the video resolution of a local stream object. If the local stream has been published, it will be automatically published to the remote end again.

[Request Parameters]

resolutionId: (mandatory) ID of the video resolution to be removed. The type is string.

[Response Parameters]

Promise<void>: returns a Promise object.

addTrack

addTrack(track: MediaStreamTrack,resolutionId?: string ): promise<void>

[Function Description]

Adds audio and video tracks to an initialized local stream object. If the local stream has been published, it will be automatically published to the remote end again.

[Request Parameters]

• track: (mandatory) track to be added. The type is MediaStreamTrack.
• resolutionId: (optional) The type is string. In the dual video stream scenario, specify the resolution ID. If the resolution ID is not specified, the video with the highest resolution is selected by default.

[Response Parameters]

Promise<void>: returns a Promise object.

If a video track with the same resolution already exists, the video track cannot be added again.

removeTrack

removeTrack(track: MediaStreamTrack): promise<void>

[Function Description]

Removes audio and video tracks from a local stream object. If the local stream has been published, it will be automatically published to the remote end again.

[Request Parameters]

track: (mandatory) track to be removed. The type is MediaStreamTrack.

[Response Parameters]

Promise<void>: returns a Promise object.

• If all audio tracks of a microphone are removed, the SDK will not access the microphone.
• If all video tracks of a camera are removed, the SDK will not access the camera.

replaceTrack

replaceTrack(track: MediaStreamTrack, type: "audio" | "video",resolutionId?: string): promise<void>

[Function Description]

Replaces audio and video tracks for an initialized local stream object. If the local stream has been published, it will be automatically published to the remote end again.

[Request Parameters]

• track: (mandatory) The type is MediaStreamTrack.
• type: (mandatory) audio or video. The type is string.
• resolutionId: (optional) The type is string. This parameter is valid when type is set to video. Specify the resolution ID of the video to be replaced. If the resolution ID is not specified, the video with the highest resolution is selected by default.

[Response Parameters]

Promise<void>: returns a Promise object.

switchDevice

switchDevice(deviceType: "audio" | "video", deviceId: string): Promise<void>

[Function Description]

Switches the media input device. If the local stream has been published, it will be automatically published to the remote end again.

[Response Parameters]

Promise<void>: returns a Promise object.

startAudioMixing

startAudioMixing(option: AudioMixOption): Promise<void>

[Function Description]

Plays an online audio file.

[Request Parameters]

option: (mandatory) audio file playback parameters. The type is AudioMixOption.

AudioMixOption is defined as: {

• filePath: (mandatory) path for downloading an online audio file. The type is string. The supported audio formats include MP3, AAC, and other audio formats supported by the browser.
• startTime: (optional) time when the audio file starts to be played. The type is number. The default value is 0.
• replace: (optional) The type is Boolean. true indicates that the local audio stream is replaced with the audio file. The default value is false.
• loop: (optional) The type is Boolean. true indicates that infinite loop playback is required. The default value is false.
• repeatCount: (optional) number of playback times. The type is number. 0 indicates that repetition is disabled. The default value is 0.

}

[Response Parameters]

Promise<void>: returns a Promise object.

• When loop is set to true, repeatCount must be set to 0.
• The audio mixing APIs can be called only after the publish API is called successfully.

stopAudioMixing

stopAudioMixing(): Promise<void>

[Function Description]

Stops playing an online audio file.

[Request Parameters]

None

[Response Parameters]

Promise<void>: returns a Promise object.

pauseAudioMixing

pauseAudioMixing(): void

[Function Description]

Pauses the playback of an online audio file.

[Request Parameters]

None

[Response Parameters]

None

resumeAudioMixing

resumeAudioMixing(): void

[Function Description]

Resumes the playback of an online audio file.

[Request Parameters]

None

[Response Parameters]

None

getAudioMixingDuration

getAudioMixingDuration(): number

[Function Description]

Obtains the duration of an online audio file. The unit is millisecond.

[Request Parameters]

None

[Response Parameters]

Duration of an audio file. The type is number.

setAudioMixingVolume

setAudioMixingVolume(level: number): void

[Function Description]

Sets the volume of online audio.

[Request Parameters]

level: (mandatory) volume level. The type is number.

[Response Parameters]

None

setAudioMixingPosition

setAudioMixingPosition(position: number): void

[Function Description]

Sets the playback progress of online audio.

[Request Parameters]

position: (mandatory) progress. The value cannot be greater than the actual audio duration. The type is number. The unit is millisecond.

[Response Parameters]

None

getAudioMixingCurrentPosition

getAudioMixingCurrentPosition(): number

[Function Description]

Obtains the playback progress of online audio.

[Request Parameters]

None

[Response Parameters]

Current audio playback progress. The type is number. The unit is millisecond.

bindScreenAudio2RelatedStream

bindScreenAudio2RelatedStream(bindStream: LocalStream, muteMainStreamAudio?: boolean): void

[Function Description]

Binds the screen sharing background audio to the related stream object.

[Request Parameters]

• bindStream: (mandatory) local video stream object that is successfully created and initialized. The type is LocalStream.
• muteMainStreamAudio: (optional) whether to mute the video stream. The type is Boolean. The default value is false. true indicates muted; false indicates unmuted.

[Response Parameters]

None

• This API can be called only by the presentation stream object created using HRTC.createStream.
• The screen sharing background audio needs to be sent through the audio channel of the video stream. If you want to subscribe to the sharing background audio, you need to subscribe to the video stream audio at least.
• In the screen sharing dialog box that is displayed, select the check box for audio sharing in the lower left corner. Otherwise, the background audio cannot be shared.
• This function applies only to Chrome 74 and later versions on Windows.