更新时间:2024-03-25 GMT+08:00
分享

本地流对象(LocalStream)

该对象继承自Stream对象,并有如下新增接口。

表1 LocalStream接口

接口

描述

initialize

本地流初始化。

setAudioProfile

设置音频流配置。

setVideoProfile

设置视频流配置。

setScreenProfile

设置辅流配置。

addAudioTrackCapture

流初始化后,流对象中没有音频track的,可通过该接口增加音频track采集。该接口为1.10.0版本新增。

addVideoTrackCapture

流初始化后,流对象中没有视频track的,通过该接口可增加视频track采集。该接口为1.10.0版本新增。

addResolution

对初始化后的本地流增加新的分辨率的视频。

removeResolution

对流删除视频指定分辨率的视频。

addTrack

为本地流对象添加音视频轨。

removeTrack

从本地流对象移除音视频轨。

replaceTrack

为本地流对象替换音视频轨。

switchDevice

切换媒体输入设备。

startAudioMixing

开始播放在线音频文件。

stopAudioMixing

停止播放在线音频文件。

pauseAudioMixing

暂停播放在线音频文件。

resumeAudioMixing

恢复播放在线音频文件。

getAudioMixingDuration

获取在线音频文件时长。

setAudioMixingVolume

设置在线音频音量大小。

setAudioMixingPosition

设置在线音频播放进度。

getAudioMixingCurrentPosition

获取在线音频播放进度。

bindScreenAudio2RelatedStream

绑定屏幕共享背景音至关联流对象。该接口为1.4.0版本新增。

initialize

initialize(): Promise<StreamInitializeResult>

功能说明

根据createStream入参StreamConfig,初始化本地音视频流对象。流只有初始化完成后才可以播放。

请求参数

返回参数

流初始化结果:StreamInitializeResult类型。

StreamInitializeResult表示流初始化的结果。对象继承自RtcError。提供如下方法:

  • 获取所有媒体类型的初始化结果:
    getMediaCaptureResult(): MediaCaptureResult[]
  • 获取指定媒体类型的初始化结果:
    getMediaCaptureResultByType(type: MediaType): MediaCaptureResult

MediaCaptureResult类型定义如下:

{

  • type:必选,表示媒体类型,MediaType类型,MediaType枚举值包括audio或者video。
  • track:可选,表示对应媒体类型如果初始化成功后的 track,MediaStreamTrack类型。
  • error:可选,表示对应媒体类型如果初始化失败的错误,RtcError类型。

}

如果初始化音视频采集失败,则结果中会返回对应的错误信息。错误码范围90000001,90100017~90100020,具体请参考表1

setAudioProfile

setAudioProfile(profile: string|RTCAudioProfile): void

功能说明

设置音频流采样率、声道和码率等配置。如果未调用该接口设置,则SDK设置为默认值standard。

请求参数

profile:必选,string类型或RTCAudioProfile类型。 若为string类型,则相关的采样率、声道数、码率如表2所示。 若为RTCAudioProfile类型,则需要根据实际情况进行配置,推荐使用已定义的profile,输入不合法时,默认使用standard。
表2 profile对应的采样率、声道数和码率

profile

采样率(千赫兹/KHZ)

声道数

码率(Kbps)

low

16

1

24

standard

48

1

40

high

48

1

128

RTCAudioProfile类型定义为:{

  • sampleRate:可选,number类型,采样率。
  • channelCount:可选,number类型,音轨数。
  • bitrate:可选,number类型,码率,单位为bps。

}

返回参数

该方法需要在调用initialize之前调用。

需注意码表中单位为kbps,接口传参的单位为bps,实际调用接口时需进行转换。

setVideoProfile

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

功能说明

设置视频主流配置,如分辨率、帧率和码率等。如果未调用该接口设置,则SDK设置默认值为360p_2。如果该流已经发布,则该流会自动重新发布到远端。

请求参数

  • profile:必选,string类型或RTCVideoProfile类型。 若为string类型,则相关的分辨率、帧率和码率如表3。 若为RTCVideoProfile类型,则需要根据实际情况进行配置,推荐使用已定义的“profile”。输入不合法时,默认使用360p_2。
    表3 profile 对应的分辨率、帧率和码率

    profile

    分辨率

    帧率

    最小码率(kbps)

    最大码率(kbps)

    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:可选,string类型。在双流场景下,指定要设置的分辨率Id的视频,如果不指定,默认选择最高的分辨率的视频。

RTCVideoProfile类型定义为:{

  • width:可选,number类型,分辨率的宽度,单位为像素。
  • height:可选,number类型,分辨率的高度,单位为像素。
  • frameRate:可选,number类型,视频帧率,单位为帧/秒。
  • minBitrate:可选,number类型,视频最小码率,单位为bps。
  • maxBitrate:可选,number类型,视频最大码率,单位为bps。

}

返回参数

  • 需注意码表中单位为kbps,接口传参的单位为bps,实际调用接口时需进行转换。
  • 自定义采集的流(使用videoSource创建的Stream)不支持动态调用此接口,仅支持摄像头采集的流调用。
  • 由于设备采集能力、系统性能以及浏览器的限制,视频分辨率,帧率,码率的实际值不一定能够完全匹配设定值,这种情况下浏览器会自动调整分辨率,尽可能匹配设定值,具体分辨率以实际采集到的分辨率为准。
  • 能否采集1080p及以上的分辨率取决于采集设备能力以及系统性能,iOS Safari不支持采集1080p。
  • 码表中的1080p分辨率为2.0.0版本新增,1.0版本如需采集1080P分辨率,请使用自定义参数的方式设置。
  • Firefox不支持自定义帧率(默认为30fps)。
  • 如果上表的Profile不符合您的要求,用户可以根据自身业务需求自定义Profile。

setScreenProfile

setScreenProfile(profile: string|RTCScreenProfile): void

功能说明

设置辅流配置,包括分辨率、帧率和码率等。如果未调用该接口设置,则SDK设置默认值为720p。

请求参数

profile:必选,string类型或RTCScreenProfile类型。若为string类型,则相关分辨率、帧率、码率如表4所示。如果为RTCScreenProfile,则需要根据实际情况进行配置,推荐使用已定义的“profile”。输入不合法时,默认使用720p。

表4 profile对应的分辨率、帧率和码率

profile

分辨率

帧率

码率(kbps)

720p

1280 x 720

15

1200

1080p

1920 x 1080

15

2000

RTCScreenProfile类型为: {

  • width:可选,number类型,分辨率的宽度,单位为像素。
  • height:可选,number类型,分辨率的高度,单位为像素。
  • frameRate:可选,number类型,视频帧率,单位为帧/秒。
  • bitrate:可选,number类型,视频码率,单位为bps。

}

返回参数

该方法需要在调用initialize之前调用。

需注意码表中单位为kbps,接口传参的单位为bps,实际调用接口时需进行转换。

addAudioTrackCapture

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

功能说明

已经初始化的本地流对象,如果未初始化音频或者音频初始化失败,可以调用该接口对本地流增加音频的track采集。若该本地流已经被发布,则该流会自动重新发布到远端。该接口为1.10.0版本新增。

请求参数

microphoneId:可选,string类型,指定采集的麦克风设备Id。如果不传,SDK采用createStream入参StreamConfig中指定的microphoneId。

返回参数

MediaStreamTrack类型。表示增加成功的track。

在通过removeTrack移除音频的track后,可以通过该接口重新添加音频的track。

addVideoTrackCapture

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

功能说明

已经初始化的本地流对象,如果未初始化视频或者视频初始化失败,可以调用该接口对本地流增加视频的track采集。若该本地流已经被发布,则该流会自动重新发布到远端。该接口为1.10.0版本新增。

请求参数

option:可选,指定采集参数。VideoCaptureOption类型。

VideoCaptureOption定义如下:{

  • cameraId:可选,string类型。指定摄像头设备Id。对于Android设备:user表示前置摄像头,environment表示后置摄像头。如果不传,SDK采用createStream入参StreamConfig中指定的cameraId和facingMode 。
  • resolutionId:可选,string类型。指定要设置的分辨率Id的视频。如果不传,SDK默认选择分辨率最高的视频。

}

返回参数

MediaStreamTrack类型。表示增加成功的track。

在通过removeTrack移除视频的track后,可以通过该接口重新添加视频的track。

addResolution

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

功能说明

为已经初始化的本地流对象添加指定分辨率的视频。若该本地流已经被发布,则该流会自动重新发布到远端。

请求参数

  • profile:必选,string类型,表示添加的分辨率视频的参数信息。RTCVideoProfile类型说明参考setVideoProfile部分的说明。
  • audio:可选,boolean类型,表示是否创建音频,true表示创建,false表示不创建。Stream中的音频对该stream中的所有的resolution是公共的。如果创建流的配置开启了音频但是没有音频track,则默认创建。

返回参数

RTCVideoProfileInfo类型。增加成功后resolution的profile信息。RTCVideoProfileInfo定义参考getStreamInfo接口定义。

如果失败,则返回StreamInitializeResult。StreamInitializeResult参考initialize接口的定义。

  • 当前对一个LocalStream最多可支持2个分辨率。
  • 当开启大小流的场景下,流的分辨率设置接口setVideoProfile使用会存在限制(两条流的分辨率大者,决定了可调整的最大分辨率上限),建议谨慎使用。

removeResolution

removeResolution(resolutionId: string): promise<void>

功能说明

对本地流对象删除视频分辨率。若该本地流已经被发布,则该流会自动重新发布到远端。

请求参数

resolutionId:必选。string类型,指定要删除的视频的分辨率Id。

返回参数

Promise<void>:返回一个Promise对象。

addTrack

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

功能说明

为初始化后的本地流对象添加音视频轨。若该本地流已经被发布,则该流会自动重新发布到远端。

请求参数

  • track:必选,MediaStreamTrack类型。指定要添加的track。
  • resolutionId:可选,string类型。在双流主流场景下,指定分辨率Id的视频,如果不指定,默认选择分辨率最高的视频增加 track。

返回参数

Promise<void>:返回一个Promise对象。

  • 如果分辨率的视频track已经存在,则不能重复添加。
  • 如果需要更新旁路推流等操作,需要等待异步操作完成

removeTrack

removeTrack(track: MediaStreamTrack): promise<void>

功能说明

从本地流对象移除音视频轨。若该本地流已经被发布,则该流会自动重新发布到远端。

请求参数

track:必选,MediaStreamTrack类型。指定要移除的track。

返回参数

Promise<void>:返回一个Promise对象。

  • 如果麦克风对应的音频track都移除,则SDK不会再访问该麦克风。
  • 如果摄像头对应的视频track都移除,则SDK不会再访问该摄像头。
  • 如果需要更新旁路推流等操作,需要等待异步操作完成

replaceTrack

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

功能说明

为初始化后的本地流对象替换音视频轨。若该本地流已经被发布,则该流会自动重新发布到远端。

请求参数

  • track:必选,MediaStreamTrack类型。
  • type:必选,string类型,"audio" | "video"。
  • resolutionId:可选,string类型。type为video的时候有效。指定要替换的分辨率Id的视频,如果不指定,默认选择分辨率最高的视频。

返回参数

Promise<void>:返回一个Promise对象。

switchDevice

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

功能说明

切换媒体输入设备。若该本地流已经被发布,则会自动更新发布到远端的音视频流。

请求参数
  • deviceType:必选,string类型,"audio" | "video"。
  • deviceId:必选,string类型, 输入设备的设备ID。

返回参数

Promise<void>:返回一个Promise对象。

startAudioMixing

startAudioMixing(option: AudioMixOption): Promise<void>

功能说明

开始播放在线音频文件。

请求参数

option:必选,音频文件播放参数。参数类型为AudioMixOption。

AudioMixOption定义为:{

  • filePath:必选,string类型,表示在线音频文件的下载路径。支持音频格式包括MP3、AAC以及浏览器支持的其他音频格式。
  • startTime:可选,number类型,表示音频文件开始播放的时间点,默认值为0。
  • replace:可选,boolean类型,如果为true表示要用音频文件替换本地音频流,默认值为false。
  • loop:可选,boolean类型,如果为true表示需要无限循环播放,默认值为false。
  • repeatCount:可选,number类型,循环播放次数。如果为0,表示不重复播放,默认值为0。

}

返回参数

Promise<void>:返回一个Promise对象。

  • loop设置为true时,repeatCount需要设置为0。
  • 混音功能相关接口仅在publish接口调用成功后方可调用。

stopAudioMixing

stopAudioMixing(): Promise<void>

功能说明

停止播放在线音频文件。

请求参数

返回参数

Promise<void>:返回一个Promise对象。

pauseAudioMixing

pauseAudioMixing(): void

功能说明

暂停播放在线音频文件。

请求参数

返回参数

resumeAudioMixing

resumeAudioMixing(): void

功能说明

恢复播放在线音频文件。

请求参数

返回参数

getAudioMixingDuration

getAudioMixingDuration(): number

功能说明

获取在线音频文件时长。单位为毫秒。

请求参数

返回参数

number类型,音频文件时长。

setAudioMixingVolume

setAudioMixingVolume(level: number): void

功能说明

设置在线音频音量大小。

请求参数

level:必选,number类型,表示音量大小。

返回参数

setAudioMixingPosition

setAudioMixingPosition(position: number): void

功能说明

设置在线音频播放进度。

请求参数

position:必选,number类型,表示进度,取值不能大于音频实际时长。单位为毫秒。

返回参数

getAudioMixingCurrentPosition

getAudioMixingCurrentPosition(): number

功能说明

获取在线音频播放进度。

请求参数

返回参数

number类型,当前音频播放进度。单位为毫秒。

bindScreenAudio2RelatedStream

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

功能说明

绑定屏幕共享背景音至关联流对象。

请求参数

  • bindStream:必选,LocalStream类型, 创建并初始化成功的本地主流对象。
  • muteMainStreamAudio:可选,boolean类型, 主流音频是否静音,默认值为false。true表示主流音频静音,false表示主流音频不静音。

返回参数

  • 该接口仅由通过HRTC.createStream创建的辅流对象调用。
  • 屏幕共享背景音需要借助主流的音频通道发送,若想要订阅共享背景音,至少需要订阅主流音频。
  • 弹出的共享选择窗口,需要勾选左下角的共享音频复选框,否则屏幕共享背景音将无法共享。
  • 该功能仅支持Windows平台Chrome浏览器74及以上版本。

相关文档