CloudHub 文档中心
下载中心 文档中心

RTC 实时音视频


CloudHub JSSDK

Stream 的说明以及接口

基础

init

方法作用: 初始化音视频对象。 该方法初始化本地创建的音视频流对象。

init(options?:object, onCallback?: function): void

// example:
stream.init({}, function(errinfos) {
  if(errinfos){
    console.error(stream init errinfos:, errinfos);
    // handle err
  }
  console.log("local stream initialized");
  // publish the stream
  //……
});
名称类型描述
onCallbackfunction回调函数,回调函数携 errinfos 参数,类型为 array | undefined,如果 errinfos 为 undefined,则表示 init 没有失败过。如果 errinfos 为 array,表示 init 有失败的情况。

Note:

[
  {
    type: "video_device",
    errflag: "NOT_ALLOWED_ERROR",
    message: "Permission denied"
  }, {
    type: "audio_deivce",
    errflag: "NOT_ALLOWED_ERROR",
    message: "Permission denied"
  }
]

或者

[
  {
    type: "screen",
    errflag: "NOT_SUPPORT",
    message: "not support not plugin screen shareing"
  }
]

errflag 字段可能出现以下值:

Note:

on

方法作用: 进行事件绑定。 目前支持绑定的事件以及事件的作用详情请看 “Stream 事件文档”

on(eventType: string, listener: function): void

// example:
stream.on('camera-access-allowed', function (evt) {
  // 该回调通知 App 已获取本地摄像头使用权限。
  console.log(''camera-access-allowed'', evt);
})
名称类型描述
eventTypestring要绑定的事件名称
listenerfunction要绑定的事件监听器

off

方法作用: 取消事件绑定。 该方法用于移除通过 Stream.on() 绑定的事件。

off(eventType: string, listener?: function): void
名称类型描述
eventTypestring要移除的事件名称
listenerfunction要移除的事件监听器。

offAll

方法作用: 取消指定类型下的所有事件绑定。

offAll(eventType: string): void

// example:
stream.offAll("videoplayer-status-change");

音频

hasAudio

方法作用: 获取音频 flag。 该方法获取音视频流中的视频轨道,可与 replaceTrack 搭配使用。

hasAudio(): boolean

Returns: boolean

true: 该音视频流对象中包含音频资源。 false: 该音视频流对象中不包含音频资源。

getAudioTrack

方法功能:获取音轨。 此方法获取音频和视频流中的音轨,可与 replaceTrack 一起使用。

getAudioTrack(): MediaStreamTrack | void

Returns: MediaStreamTrack | void

如果音视频流中包含音频轨道,会以 MediaStreamTrack 对象返回。

playAudio

方法作用: 播放音频流。 该方法播放音频流

playAudio(options?: object, onCallback?: function): void

// example:
stream.playAudio({}, function(StreamPlayError){
  console.error(playAudio StreamPlayError, StreamPlayError);
  // 播放失败,一般为浏览器策略阻止。引导用户用手势触发恢复播放。
});
名称类型描述
optionsobject用于流播放的选项, 有如下配置:
1. muted?: boolean: 设置播放的流是否静音, 缺省为 false。muted 通常用于规避浏览器的自动播放策略。 一般情况下,播放音频 / 带声音的视频时,浏览器会要求该行为由手势触发。 如果您不希望以手势触发,也可以选择将 muted 设为 true,这样可以绕过自动播放策略,详见 处理浏览器的自动播放策略
2. volume?: number: 设置播放的音量大小,取值范围在 [0,100], 缺省为 100。
onCallbackfunction播放是否成功的回调, 回调参数携带 StreamPlayError 如果播放成功该参数为 null/undefined。 如果播放失败可以通过 StreamPlayError 了解可能的原因。 StreamPlayError: 详情查看 CloudHubRTC 数据对象文档 的 StreamPlayError 说明。

Note: 受浏览器策略影响,在 Chrome 70+ 和 Safari 浏览器上,该方法必须由用户手势触发,详见 处理浏览器的自动播放策略

unplayAudio

方法作用: 停止音频流。 调用该方法停止播放 “Stream.playAudio 播放的音频流”。

unplayAudio(): void

resumeAudio

方法作用: 恢复音频流播放。

该方法一般在调用 Stream.playAudio 之后,播放失败时调用。通常播放失败是由于浏览器策略阻止导致的。 该方法需用手势触发。详见 “处理浏览器的自动播放策略”

resumeAudio(): Promise<any>

Returns Promise

muteAudio

方法作用: 禁用音频轨道。 该方法禁用音频轨道。 对于本地流,调用该方法会停止发送音频,远端会触发 Client.on(“mute-audio”) 回调。 对于远端流,调用该方法不会接收音频且会停止播放音频。

muteAudio(): boolean

Note: 对于本地流,在 createStream 时将 audio 设置为 true 才可使用该方法。

Returns: boolean

true: 禁用音频轨道成功。 false: 禁用音频轨道失败,可能的原因包括没有音频、流未初始化、音频轨道已经禁用等。

unmuteAudio

方法作用: 启用音频轨道。 该方法启用音频轨道。对本地流启用音频轨道后远端会触发 Client.on(“unmute-audio”) 回调。

unmuteAudio(): boolean

Note:

Returns boolean

setAudioOutput

方法作用: 设置音频输出。 该方法可以设置订阅流的音频输出设备,在通话时切换扬声器。在播放订阅流之前或之后都可以调用该方法。

setAudioOutput(deviceId: string, onSuccess?: function, onFailure?: function): void
名称类型描述
deviceIdstring设备 ID,可以通过 getDevices 获得,设备的 kind 属性应该为 “audiooutput”
onSuccessfunction设置成功的回调
onFailurefunction设置失败的回调

Note: 移动端浏览器不支持。

setAudioVolume

方法作用: 调节音量大小。 该方法可以调节订阅流的音量大小 (对应节点元素的 volume 属性)。

setAudioVolume(volume: number): void
名称类型描述
volumenumber音量,范围为 0(静音) 到 100(声音最大)

getAudioVolume

方法作用: 获取音量大小。 该方法可以获取订阅流的音量大小 (对应节点元素的 volume 属性)。

getAudioVolume(): number

Returns number

范围为 0(静音) 到 100(声音最大)

isAudioPlaying

方法作用: 返回音频流当前是否在播放状态。

isAudioPlaying(): boolean

Returns boolean

true:该音频流正在渲染或播放。 false:该音频流没有渲染。

isPubedAudio

方法作用: 流的发布者是否发布音频。 即:发布者如果 muteAudio 则返回 false, 否则返回 true。

isPubedAudio(): boolean

Returns boolean

true: 发布了音频 false: 不发布音频

视频

hasVideo

方法作用: 获取视频 flag。 该方法获取音视频流中的视频轨道,可与 replaceTrack 搭配使用。

hasVideo(): boolean

Returns: boolean

true: 该音视频流对象中包含视频资源。 false: 该音视频流对象中不包含视频资源。

playVideo

方法作用: 播放视频流。 该方法播放视频流

playVideo(HTMLElementID: string, options?: object, onCallback?: function): void

// example:
stream.playVideo("remote_stream_id", {fit: "contain"}, function(StreamPlayError){
    console.log("playVideo StreamPlayError", StreamPlayError);
});
名称类型描述
HTMLElementIDstring节点 ID
optionsobject用于流播放的选项, 有如下配置:
1. fit?: “cover” | “contain”: 设置视频播放时的显示模式,有 “cover” 和 “contain” 可以选择,默认为 “cover”,cover 模式和 contain 模式区别如下:
* cover 模式:优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗,可以参考 CSS 属性中 object-fit 的 cover 选项。
* contain 模式:优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边,可以参考 CSS 属性中 object-fit 的 contain 选项。
2. mirror?: boolean: 用于表示是否以镜面方式显示视频,缺省 false。
3. loader?: boolean: 用于表示未加载到视频数据时是否显示‘加载中’样式,缺省 true。
onCallbackfunction播放是否成功的回调, 回调参数携带 StreamPlayError
如果播放成功该参数为 null/undefined。
如果播放失败可以通过 StreamPlayError 了解可能的原因。
StreamPlayError: 详情查看 “CloudHubRTC 数据对象文档” 的 StreamPlayError 说明

unplayVideo

方法作用: 停止视频流。 调用该方法停止播放 “Stream.playVideo 播放的视频流”。

unplayVideo(): void

resumeVideo

方法作用: 恢复音频流播放。 该方法一般在调用 Stream.playVideo 之后,播放失败时调用。

resumeVideo(): Promise<any>

Returns Promise

muteVideo

方法作用: 禁用视频轨道。 对于本地流,调用该方法会停止发送视频,远端会触发 Client.on(“mute-video”) 回调。 对于远端流,调用该方法不会接收视频且会停止播放视频。

muteVideo(): boolean

Note: 对于本地创建的流,在 createStream 时将 video 设置为 true 才可使用该方法。

Returns: boolean

true: 禁用视频轨道成功。 false: 禁用视频轨道失败,可能的原因包括没有视频、流未初始化、视频轨道已经禁用等。

unmuteVideo

方法作用: 启用视频轨道。 该方法启用视频轨道。对本地流启用视频轨道后远端会触发 Client.on(“unmute-video”) 回调

unmuteVideo(): boolean

Note:

Returns boolean

true: 启用视频轨道成功。 false: 启用视频轨道失败,可能的原因包括没有视频、流未初始化、视频轨道已经启用等。

setVideoProfile

方法作用: 设置视频属性。 该方法设置本地流的视频属性。 只对流类型为 video 有效 (即:stream.getType() === “video”)。

setVideoProfile(profile: object): object

// example:
stream.setVideoProfile({width: 320, height:240, fps:15});
名称类型描述
profileobject视频属性,有以下属性:
* width?:number 视频宽度,缺省为默认的视频宽度。
* height?:number 视频高度,缺省为默认的视频高度。
* fps?:number 视频帧率,缺省为默认的视频帧率。

Note:

Returns object

返回实际设置的视频属性,如:{width: 320, height:240, fps:15}。

** 视频分辨率参考表格 **

分辨率(宽 × 高)帧率(fps)ChromeFirefoxSafari备注
80 × 4510
80 × 4810
80 × 6010
176 × 14410
200 × 15010
120 × 12015
160 × 12015主流
180 × 18015
240 × 18015
320 × 18015主流
240 × 24015
320 × 24010
320 × 24015主流
424 × 24015
360 × 36015
360 × 36030
480 × 36015
480 × 36030
640 × 36015主流
640 × 36024
640 × 36030
480 × 48015
480 × 48030
640 × 48010
640 × 48015主流
640 × 48030
848 × 48015
848 × 48030
960 × 72015
960 × 72030
1280 × 72015主流
1280 × 72030
1920 × 108015
1920 × 108030主流

表格更多内容详见 视频分辨率表格

Note:

getAttributes

方法作用: 获取流的自定义属性

/**获取流的自定义属性
  * @returns {
    mute_audio: string;
    sourceid: string;
    type: string
    videofps: number
    videoheight: number
    videowidth: number
  }
*/
stream.getAttributes();

getVideoProfile

方法作用: 获取本地流的视频属性。 只对流类型为 video 有效 (即:stream.getType() === “video”)。

getVideoProfile(): object

// example:
stream.getVideoProfile();

Returns object

有设置视频属性,返回设置成功的视频属性,否则返回默认的视频属性,如:{width: 320, height:240, fps:15}

getType

方法作用: 获取该流的类型。 该方法返回当前流的类型。

getType(): string

Note: 目前的类型有 “video” 、“media” 、“screen”、“file”

Returns string

getSourceID

方法作用: 获取该流的 sourceID。 该方法返回当前流的 sourceID。

getSourceID(): string

Returns string

getAudioLevel

方法作用: 获取当前音量。 该方法获取的是当前时刻的音量。如果您想表示本地或远端音量的变化,我们建议您使用 setTimeout 或者 setInterval 方法实时获取。

getAudioLevel(): number | void

// example:
setInterval(function() {
  var audioLevel = stream.getAudioLevel();
  // Use audioLevel to render the UI
}, 100)

Note: safari 11/12.0 不支持。

Returns: number | void 获取的音量值,取值范围 [0,100]。

getId

方法作用: 获取音视频流 ID。 该方法可以获取音视频流 ID。

getId(): string

// example:
stream.getId();

Note: 流 ID 是根据 uid、type、sourceID 生成的,流 ID 格式为:uid:type:sourceID

Returns: string

getStats

方法作用: 获取连接数据。 该方法获取音视频流的连接数据。

getStats(onCallback: function): void

// example:
localStream.getStats((errinfo, stats) => {
  console.log("Local Stream stats:", stats, errinfo);
});
remoteStream.getStats((errinfo, stats) => {
  console.log("Remote Stream stats:", stats, errinfo);
});
名称类型描述
onCallbackfunction回调包含音视频流的连接统计数据,回调参数携带 errinfo 和 stats。 如果 errinfo 不为 undefined,则表示获取数据失败,否则 errinfo 为 undefined,stats 为 LocalStreamStats/RemoteStreamStats。 如果是发布的流,统计数据为 LocalStreamStats。 如果是订阅的流,统计数据为 RemoteStreamStats。 LocalStreamStats: 详情查看 “CloudHubRTC 数据对象文档” 的 LocalStreamStats 说明 RemoteStreamStats: 详情查看 “CloudHubRTC 数据对象文档” 的 RemoteStreamStats 说明

Note:

getVideoTrack

方法作用: 获取视频轨道。 该方法获取音视频流中的视频轨道,可与 replaceTrack 搭配使用。

getVideoTrack(): MediaStreamTrack | void

Returns: MediaStreamTrack | void

如果音视频流中包含视频轨道,会以 MediaStreamTrack 对象返回。

replaceTrack

方法作用: 替换音视频轨道。 该方法可以替换本地音视频流中的音视频轨道。 本地流发布后,可以通过该方法切换摄像头或者切换麦克风等。 新的音视频轨道可以通过 DeviceManager 的 getVideoTrack/getAudioTrack 等方法获取。 被替换的音视频轨道会被强制停止。

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

// example:
stream.replaceTrack(newVideoTrack);
名称类型描述
mediaStreamTrackMediaStreamTrack新的音视频轨道。 MediaStreamTrack: 详情查看 “CloudHubRTC 数据对象文档” 的 MediaStreamTrack 说明
onSuccessfunction方法调用成功的回调
onFailurefunction方法调用失败的回调,失败的参数携带格式如:{errflag: “NOT_ALLOWED_ERROR”, message: “Permission denied”}。
errflag 字段可能出现以下值:
* “INVALID_TRACK”: 新传入的 MediaStreamTrack 对象无法识别,请检查传入对象。
* “MEDIASTREAM_TRACK_NOT_FOUND”: 找不到替换对象,比如在纯音频流上尝试替换一个视频的 Track。
* “NO_STREAM_FOUND”: 找不到本地流对象,无法替换。
* “NOT_SUPPORT”: 浏览器不支持替换。
* “UNDEFINED_ERROR”: 未定义错误。

Note:

isVideoPlaying

方法作用: 返回视频流当前是否在播放状态。 调用该方法停止播放 “Stream.playVideo 播放的视频流”。

isVideoPlaying(): boolean

Returns boolean

true: 该视频流正在渲染或播放。 false: 该视频流没有渲染。

true: 启用音频轨道成功。 false: 启用音频轨道失败,可能的原因包括没有音频、流未初始化、音频轨道已经启用等。

isRemote

方法作用: 是否是远端流。

isRemote(): boolean

Returns boolean

true: 远端流。 false: 本地流。

isPubedVideo

方法作用: 流的发布者是否发布视频。 即:发布者如果 muteVideo 则返回 false, 否则返回 true。

isPubedVideo(): boolean

Returns boolean

true: 发布了视频 false: 不发布视频

setMirror

setMirror(isMirror:boolean): void

方法作用: 设置是否使用镜像。

名称类型描述
isMirrorboolean是否使用镜像,true 表示使用,false 表示不使用。

close

方法作用: 关闭音视频流。 该方法关闭视频流或音频流。调用该方法会取消摄像头和麦克风的访问权限。

close(): void

用户

getUserId

方法作用: 获取该流的用户 id。 该方法返回当前流的用户 id。

getUserId(): string

Returns string

设备

switchDevice

方法作用: 切换输入设备。 该方法可以切换本地流的媒体输入设备: 音频输入设备,如麦克风 视频输入设备,如摄像头 已经发布的流,切换后不用重新发流。

下列情况无法使用本方法:

switchDevice(type: "audio" | "video", deviceId: string, onSuccess?: function, onFailure?: function): void
名称类型描述
typestring设备的类型,有如下值:
* “audio”: 音频输入设备 < br/>* “video”: 视频输入设备
deviceIdstring设备的 ID, 可以通过 getDevices 方法获取。
onSuccessfunction切换成功的回调。
onFailurefunction切换失败的回调,失败的参数携带格式如: {errflag: "NOT_ALLOWED_ERROR", message: "Permission denied"}。 errflag 字段可能出现以下值:
* “NOT_SUPPORT”: 浏览器不支持。
* “INVALID_ARG”: 无效的参数。
* “NOT_ALLOWED_ERROR”: 用户拒绝授予对应的摄像头或麦克风权限。
* “NOT_READABL_EERROR”: 摄像头或麦克风被占用。
* “ABORT_ERROR”: 设备中止错误。
* “NOT_FOUND_ERROR”: 没有找到设备。
* “OVER_CONSTRAINED_ERROR”: 配置的约束无法满足要求错误。
* “SECURITY_ERROR”: 安全错误, 网页使用设备媒体被禁止。这个机制是否开启或者关闭取决于单个用户的偏好设置。
* “TYPE_ERROR”: 设备约束都设置为 false 了。
* “REQ_TIMEOUT”: 请求设备超时。
* “UNDEFINED_ERROR”: 未定义错误。
1. 可以参考 浏览器 getUserMedia 接口错误类型
2. 可以参考 “常量声明以及补充说明” 的浏览器 getUserMedia 接口失败的错误类型。

Note: 移动端浏览器不支持。

switchMobileCamera

方法作用: 切换移动端前后摄像头。 已经发布的流,切换后不用重新发流。

下列情况无法使用本方法:

switchMobileCamera(onSuccess?: function, onFailure?: function): void
名称类型描述
onSuccessfunction切换成功的回调。
onFailurefunction切换失败的回调,失败的参数携带格式如:{errflag: “NOT_ALLOWED_ERROR”, message: “Permission denied”}。 errflag 字段可能出现以下值:
* “NOT_SUPPORT”: 浏览器不支持。
* “INVALID_ARG”: 无效的参数。
* “NOT_ALLOWED_ERROR”: 用户拒绝授予对应的摄像头或麦克风权限。
* “NOT_READABL_EERROR”: 摄像头或麦克风被占用。
* “ABORT_ERROR”: 设备中止错误。
* “NOT_FOUND_ERROR”: 没有找到设备。
* “OVER_CONSTRAINED_ERROR”: 配置的约束无法满足要求错误。
* “SECURITY_ERROR”: 安全错误, 网页使用设备媒体被禁止。这个机制是否开启或者关闭取决于单个用户的偏好设置。
* “TYPE_ERROR”: 设备约束都设置为 false 了。
* “REQ_TIMEOUT”: 请求设备超时。
* “UNDEFINED_ERROR”: 未定义错误。
**Note:**
1. 可以参考 浏览器 getUserMedia 接口错误类型
2. 可以参考 “常量声明以及补充说明” 的浏览器 getUserMedia 接口失败的错误类型。

Note: 非移动端浏览器不支持。