• 文档中心 /
• RTC 实时音视频 /
• 音视频SDK /
• Web /
• Stream /

CloudHub JSSDK

• 概览
• CloudHubRTC
• CloudHubRTCObject
• Client
• ClientEvent
• ClientLiveTranscoding
• ClientChannelMediaRelayConfig
• Stream
• StreamEvent
• DeviceManager
• 常量

Stream 的说明以及接口

• Stream 接口提供的方法用于定义音视频流对象的行为。
• 您可以通过 createStream 创建 Stream 对象。一个 Stream 对象指通话中发布的本地音视频流或订阅的远端音视频流。
• 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
  //……
});

Note：

• 当 stream 的 type 为 video 时，可能出现以下情况：
  • 音频正常、视频正常（errinfos 为 undefined）
  • 音频正常、视频失败（errinfos 为 array，携带 video_device 错误信息）
  • 音频失败、视频正常（errinfos 为 array，携带 audio_device 错误信息）
  • 音频失败、音频失败（errinfos 为 array，携带 video_device 和 audio_device 错误信息）
• 如果 init 有失败的情况，那么回调参数错误信息 errinfos 类型为 array，错误信息里面 type 有 video_device(视频设备)、audio_device(音频设备)、screen(屏幕 / 程序共享)。 例如：

[
  {
    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 字段可能出现以下值：

• “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”: 请求设备 / 屏幕共享超时。
• “SCREEN_FAIL”: 屏幕 / 程序流获取失败。
• “UNDEFINED_ERROR”: 未定义错误。

Note：

• 可以参考 浏览器 getUserMedia 接口错误类型
• 可以参考 “常量声明以及补充说明” 的浏览器 getUserMedia 接口失败的错误类型。
• Chrome 72 及以后的版本支持屏幕共享，如果需要请安装最新版 Chrome 浏览器。
• 屏幕 / 应用共享只支持 PC 端，不支持移动端。

on

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

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

// example:
stream.on('camera-access-allowed', function (evt) {
  // 该回调通知 App 已获取本地摄像头使用权限。
  console.log(''camera-access-allowed'', evt);
})

off

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

off(eventType: string, listener?: function): void

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);
  // 播放失败，一般为浏览器策略阻止。引导用户用手势触发恢复播放。
});

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：

• 对于本地流，在 createStream 时将 audio 设置为 true 才可使用该方法。
• 音频轨道默认为开启状态。如果您调用了 muteAudio，可调用本方法启用音频。

Returns boolean

setAudioOutput

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

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

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

setAudioVolume

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

setAudioVolume(volume: number): void

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);
});

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：

• 对于本地创建的流，在 createStream 时将 video 设置为 true 才可使用该方法。
• 视频轨道默认为开启状态。如果您调用了 muteVideo，可调用本方法启用视频。

Returns boolean

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

setVideoProfile

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

setVideoProfile(profile: object): object

// example:
stream.setVideoProfile({width: 320, height:240, fps:15});

Note：

• 动态修改视频属性仅支持 Chrome 63 及以上版本和 Safari 11 及以上版本。
• 在部分 iOS 设备上动态修改视频属性可能会导致视频出现黑边。
• 请避免在发布流时调用该方法。
• 开启多流模式（enableMultiStream）后，无法向上调整视频分辨率。该问题为 Chromium 已知问题。
• 如果不调用 setVideoProfile，则视频分辨率为默认的视频分辨率，视频帧率为默认的视频帧率。
• SDK 限制了帧率不能超过 30，如果想调整此限制的值，可以使用 CloudHubRTC.DEVICE_ADAPTER_CONFIG.MAX_VIDEO_FPS 进行设置，如：CloudHubRTC.DEVICE_ADAPTER_CONFIG.MAX_VIDEO_FPS = 60。

Returns object

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

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

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

Note：

• 视频能否达到 1080p 以上的分辨率取决于设备的性能，在性能配备较低的设备上有可能无法实现。如果采用 720p 分辨率而设备性能跟不上，则有可能出现帧率过低的情况。
• 随着浏览器的升级，上表中列出的浏览器的分辨率支持可能并不完整，具体支持以实际情况为准。
• 部分浏览器的某些版本可能不完全支持上表中列出的分辨率，在这种情况下建议使用主流分辨率（即上表中备注 “主流” 的分辨率）。
• Safari 浏览器不支持自定义视频帧率（默认为 30 fps）。如果您设置的视频帧率不是 30 fps，Safari 浏览器可能会修改或者拒绝您的设置。
• 由于设备和浏览器的限制，部分浏览器对设置的 Video Profile 不一定能全部适配，这种情况下浏览器会自动调整分辨率。

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);
});

Note：

• 部分统计数据可能存在延时。
• Edge 浏览器不支持。

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);

Note：

• 支持 Chrome 65+，Safari 以及最新版 Firefox 浏览器。
• 部分移动设备上该方法可能不生效。
• Firefox 不支持在不同的麦克风之间切换音频轨道。
• Safari 部分外接音频设备不支持此方法。
• 订阅端无法知悉音视频轨道被替换。

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

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

close

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

close(): void

用户

getUserId

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

getUserId(): string

Returns string

设备

switchDevice

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

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

• 移动端浏览器
• switchDevice 参数 type 不是 “audio” | “video”
• 流类型不是 “video”(即：stream.getType() !== “video”)
• stream 不是本地流
• 使用自采集属性（audioSource 和 videoSource）创建的流
• 多流模式不支持切换视频设备，即：enableMultiStream 设置为多流且 type 为 “video”

switchDevice(type: "audio" | "video", deviceId: string, onSuccess?: function, onFailure?: function): void

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

switchMobileCamera

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

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

• 非移动端浏览器
• 流类型不是 “video”(即：stream.getType() !== “video”)
• stream 不是本地流
• 使用自采集属性（audioSource 和 videoSource）创建的流

switchMobileCamera(onSuccess?: function, onFailure?: function): void

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