Stream

Stream

Stream 音视频流，一个 Stream 中最多只能同时包含一个音频 track 和一个视频 track。
Stream 类是本地流 LocalStream 和远端流 RemoteStream 的基类，它包含本地流和远端流通用的方法。

Methods

(async) play(elementId, optionsopt) → {Promise}

播放该音视频流
该方法会自动创建 <audio> 和 <video> 标签并在指定的标签上播放音频和视频，同时该标签会被添加到页面中名为 elementId 的 div 容器。
换句说，Stream 内部会自动创建相应的音频播放器和视频播放器来播放相应的音频和视频。

NOTE

  • 由于浏览器自动播放策略的影响，调用该接口可能会返回 PLAY_NOT_ALLOWED 错误， 此时需要引导用户通过手势操作调用 resume() 恢复音视频播放。
Example
// v4.8.4 以下版本, 请使用以下方式捕捉并处理 0x4043 错误
stream.play('remote').then(() => {
  // autoplay success
}).catch((error) => {
  const errorCode = error.getCode();
  if (errorCode === 0x4043) {
    // PLAY_NOT_ALLOWED,引导用户手势操作并调用 stream.resume 恢复音视频播放
    // stream.resume()
  }
});
// v4.8.4 及其以上版本, 强烈建议使用 stream 监听 error 的方式捕捉并处理 0x4043 错误
stream.play('remote').catch(error => {});
stream.on('error', error => {
  const errorCode = error.getCode();
  if (errorCode === 0x4043) {
    // PLAY_NOT_ALLOWED,引导用户手势操作并调用 stream.resume 恢复音视频播放
    // stream.resume()
  }
})
Parameters:
Name Type Attributes Description
elementId string | HTMLDivElement

在 DOM 中的某个 <div> 标签 ID 或者 HTMLDivElement 对象，该方法会在指定的 elementId 元素中创建音视频标签来播放音视频流。
注意：

  1. 当传入 string 类型的 elementId 时，需要确保 elementId 在 DOM 中，否则调用接口会报错。
  2. 业务侧可自行调整该 DOM 元素的 css 宽高来控制 video 标签显示的宽高。
options object <optional>

播放选项

Properties
Name Type Description
objectFit string

视频画面显示模式，参考 CSS object-fit 属性

  • contain 优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致，在保持长宽比的前提下，将视频进行缩放后填满视窗，缩放后的视频四周会有一圈黑边。
  • cover 优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。
  • fill 保证视窗被填满的同时保证视频内容全部显示，但是不保证视频尺寸比例不变。视频的宽高会被拉伸至和视窗尺寸一致。(该选项值自 v4.12.1 开始支持)

    播放视频流默认使用 cover 模式; 播放屏幕共享流默认使用 contain 模式。
muted boolean

是否需要 mute 声音。

  • 对于本地流，muted 默认为 true，防止播放从麦克风采集的声音。
mirror boolean

是否开启视频镜像预览。(该选项自 v4.12.1 开始支持)
注意

  • 对于本地音视频流，默认开启镜像预览。建议在使用前置摄像头时开启镜像，使用后置摄像头时关闭镜像。
  • 对于远端音视频流，默认关闭镜像预览。
  • 对于屏幕分享流，不支持开启镜像预览。
  • 该参数只对本地预览有效，推流是没有镜像效果的。
Throws:
RtcError
Returns:
Type
Promise

stop()

停止播放音视频流
该方法还会将由 play() 创建的音视频标签从 HTML 页面中删除。

(async) resume() → {Promise}

恢复播放音视频
NOTE

  • 在某些版本的浏览器，如果您移动了 play() 指定的 div 容器会导致音视频播放器进入 ‘PAUSED’ 状态，您需要调用该接口恢复播放。
  • 由于浏览器自动播放策略的限制，在 play() 返回 PLAY_NOT_ALLOWED 错误后，需要引导用户通过与页面交互并调用该接口恢复播放，例如点击播放。
Example
stream.on('player-state-changed', event => {
  if (event.state === 'PAUSED') {
    // resume audio/video playback
    stream.resume();
  }
});
Throws:
RtcError
Returns:
Type
Promise

close()

关闭音视频流
使用场景：

  • 本地流LocalStream调用该方法会停止播放及停止采集。因此若您想停止采集摄像头及麦克风，可以调用该方法。
  • 远端流RemoteStream一般无需调用该方法。该方法会停止播放并关闭音视频 track。若您不想继续订阅远端流，请使用 Client.unsubscribe。

muteAudio() → {boolean}

禁用音频轨道，且保留音频轨道，通常用于本地流临时静音。

  • 本地流LocalStream调用该方法会停止发送音频，远端会触发 Client.on('mute-audio') 事件。
  • 远端流RemoteStream调用该方法会停止解码播放音频，但是仍然接收音频数据，若您不想接收视频数据，请使用 Client.unsubscribe 取消订阅，或者 Client.subscribe 只订阅视频。
Returns:
  • true 禁用音频轨道成功。
  • false 禁用音频轨道失败，因为没有音频轨道。
Type
boolean

muteVideo() → {boolean}

禁用视频轨道，且保留视频轨道，通常用于本地流临时禁画。

  • 本地流LocalStream调用该方法会停止发送视频，远端会触发 Client.on('mute-video') 事件。
    如果视频是从摄像头采集，此时摄像头灯仍然是亮着的。若想完全禁用视频轨道(即关闭摄像头)，
    可以使用 removeTrack() 删除视频轨道然后调用 MediaStreamTrack.stop() 关闭视频轨道（关闭摄像头）。
  • 远端流RemoteStream调用该方法会停止解码播放视频，但是仍然接收视频数据，若您不想接收视频数据，请使用 Client.unsubscribe 取消订阅，或者 Client.subscribe 只订阅音频。
Returns:
  • true 禁用视频轨道成功
  • false 禁用视频轨道失败，因为没有视频轨道。
Type
boolean

unmuteAudio() → {boolean}

启用音频轨道

  • 存在音频轨道的情况下，本地流LocalStream在调用 muteAudio() 后，用该方法重新启用音频，这时远端会触发 Client.on('unmute-audio') 事件。
  • 远端流RemoteStream在调用 muteAudio() 后，用该方法恢复解码播放音频。
Returns:
  • true 启用音频轨道成功。
  • false 没有音频轨道，启用失败。
Type
boolean

unmuteVideo() → {boolean}

启用视频轨道

  • 存在视频轨道的情况下，本地流LocalStream在调用 muteVideo() 后，用该方法重新启用视频轨道，这时远端会触发 Client.on('unmute-video') 事件。
  • 远端流RemoteStream在调用 muteVideo() 后，用该方法恢复解码播放视频。
Returns:
  • true 启用视频轨道成功。
  • false 没有视频轨道，启用失败。
Type
boolean

getId() → {string}

获取 Stream 唯一标识ID

Returns:

Id 流唯一标识

Type
string

getUserId() → {string}

获取该流所属的用户ID

Returns:

userId 用户ID

Type
string

(async) setAudioOutput(deviceId)

设置声音输出设备

  • 移动端不支持设置扬声器。
Parameters:
Name Type Description
deviceId string

设备标识，通过 TRTC.getSpeakers() 获取。

setAudioVolume(volume)

设置播放音量大小

Parameters:
Name Type Description
volume double

音量大小，取值在 0.0 (静音) 到 1.0 (最大音量) 之间。

getAudioLevel() → {number}

获取当前音量大小
只有当本地流或远端流中有音频数据才有效，在获取音量前需要先 播放 该音视频流。

Example
setInterval(() => {
  const level = stream.getAudioLevel();
  if (level >= 0.1) {
    console.log(`user ${stream.getUserId()} is speaking`);
  }
}, 200);
Returns:

audioLevel 音量大小

  • 返回值在(0.0, 1.0)之间，通常认为值大于0.1为用户正在说话。
Type
number

hasAudio() → {boolean}

是否包含音频轨道

  • 如果需要获取 Stream mute 状态，需要监听 Client.on('mute-audio') 事件做进一步处理。
Returns:
Type
boolean

hasVideo() → {boolean}

是否包含视频轨道

  • 如果需要获取 Stream mute 状态，需要监听 Client.on('mute-video') 事件做进一步处理。
Returns:
Type
boolean

getAudioTrack() → (nullable) {MediaStreamTrack}

获取音频轨道

Returns:

音频轨道

Type
MediaStreamTrack

getVideoTrack() → (nullable) {MediaStreamTrack}

获取视频轨道

Returns:

视频轨道

Type
MediaStreamTrack

getVideoFrame() → (nullable) {String}

获取当前视频帧
NOTE

  • 该方法需要在 play() 后调用，并且 Stream 中有视频流才有效
Example
// 截取当前视频帧
const frame = stream.getVideoFrame();
if (frame) {
  const img = document.createElement('img');
  img.src = frame;
}
Returns:

'image/png' 类型的 dataURL

Type
String

on(eventName, handler, context)

监听 Stream 事件
详细事件列表请参见：StreamEvent

Example
function onPlayerStateChange(event) {
   console.log(`${event.type} player is ${event.state}`);
}
stream.on('player-state-changed', onPlayerStateChange);
Parameters:
Name Type Description
eventName string

事件名称
handler function

事件处理方法
context object

上下文对象

off(eventName, handler, context)

取消监听 Stream 事件

Example
function onPlayerStateChange(event) {
   console.log(`${event.type} player is ${event.state}`);
}
stream.on('player-state-changed', onPlayerStateChange);
stream.off('player-state-changed', onPlayerStateChange);
Parameters:
Name Type Description
eventName string

事件名称，传入通配符 '*' 会解除所有事件绑定。
handler function

事件处理方法
context object

上下文对象