腾讯云 RTC SDK - RemoteStream

远端音视频流，通过监听 Client.on('stream-added') 事件获得。

一个远端用户可发送至多两个远端流对象，其中一个远端流对象包含一路音频和一路主路视频，另一个远端流对象仅仅包含一路辅路视频。
这两种远端流对象的类型可通过 getType() 来识别。

远端流的生命周期在事件 Client.on('stream-added') 到事件 Client.on('stream-removed') 之间，在这两个事件之间，远端流可能会通过 Client.on('stream-updated') 进行更新，比如远端用户通过 addTrack() 或 removeTrack() 增加或删除 track 后本地就会收到此通知。

Example

// 远端流生命周期内的操作示例
// 通过监听‘stream-added’事件获得远端流对象
const client = TRTC.createClient({ sdkAppId, userId, userSig, mode: 'live'});
client.on('stream-added', event => {
  const remoteStream = event.stream;
  const remoteUserId = remoteStream.getUserId();
  console.log('received a remoteStream ID: ' + remoteStream.getId() + ' from user: ' + remoteUserId);
  // 若需要观看该远端流，则需要订阅它
  client.subscribe(remoteStream);
  // 若不需要观看该远端流，请取消订阅它，否则SDK会接收远端流数据。
  // client.unsubscribe(remoteStream);
});
// 监听‘stream-removed’事件
client.on('stream-removed', event => {
  const remoteStream = event.stream;
  console.log('remoteStream ID: ' + remoteStream.getId() + ' has been removed');
  // 停止播放并删除相应<video>标签
});
// 监听‘stream-updated’事件
client.on('stream-updated', event => {
  const remoteStream = event.stream;
  console.log('remoteStream ID: ' + remoteStream.getId() + ' was updated hasAudio: '
              + remoteStream.hasAudio() + ' hasVideo: ' + remoteStream.hasVideo());
});
// 监听‘stream-subscribed’事件
client.on('stream-subscribed', event => {
  const remoteStream = event.stream;
  // 远端流订阅成功，在HTML页面中创建一个<video>标签，假设该标签ID为‘remote-video-view’
  // 播放该远端流
  remoteStream.play('remote-video-view');
});

Extends

Stream

Methods

getType() → {string}

获取远端流类型

Note:

Native 端的屏幕分享流是以推辅流的形式实现的。
Web 端在 v4.15.0 版本支持以辅流形式推屏幕分享流。
参考：Web 端屏幕分享实现方案

Returns:

远端流类型

'main' 主音视频流。通常是摄像头和麦克风流。
'auxiliary' 辅助视频流，通常是一个屏幕分享流。

Type: string

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

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

NOTE

由于浏览器自动播放策略的影响，调用该接口可能会返回 PLAY_NOT_ALLOWED 错误，此时需要引导用户通过手势操作调用 resume() 恢复音视频播放。

Inherited From:

Stream#play

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 元素中创建音视频标签来播放音视频流。
注意：

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

options

object

播放选项

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 页面中删除。

Inherited From:

Stream#stop

(async) resume() → {Promise}

恢复播放音视频
NOTE

在某些版本的浏览器，如果您移动了 play() 指定的 div 容器会导致音视频播放器进入 ‘PAUSED’ 状态，您需要调用该接口恢复播放。
由于浏览器自动播放策略的限制，在 play() 返回 PLAY_NOT_ALLOWED 错误后，需要引导用户通过与页面交互并调用该接口恢复播放，例如点击播放。

Inherited From:

Stream#resume

Example

stream.on('player-state-changed', event => {
  if (event.state === 'PAUSED') {
    // resume audio/video playback
    stream.resume();
  }
});

Throws:

RtcError

Returns:

Type: Promise

muteAudio() → {boolean}

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

本地流LocalStream调用该方法会停止发送音频，远端会触发 Client.on('mute-audio') 事件。
远端流RemoteStream调用该方法会停止解码播放音频，但是仍然接收音频数据，若您不想接收视频数据，请使用 Client.unsubscribe 取消订阅，或者 Client.subscribe 只订阅视频。

Inherited From:

Stream#muteAudio

Returns:

true 禁用音频轨道成功。
false 禁用音频轨道失败，因为没有音频轨道。

Type: boolean

muteVideo() → {boolean}

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

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

Inherited From:

Stream#muteVideo

Returns:

true 禁用视频轨道成功
false 禁用视频轨道失败，因为没有视频轨道。

Type: boolean

unmuteAudio() → {boolean}

启用音频轨道

存在音频轨道的情况下，本地流LocalStream在调用 muteAudio() 后，用该方法重新启用音频，这时远端会触发 Client.on('unmute-audio') 事件。
远端流RemoteStream在调用 muteAudio() 后，用该方法恢复解码播放音频。

Inherited From:

Stream#unmuteAudio

Returns:

true 启用音频轨道成功。
false 没有音频轨道，启用失败。

Type: boolean

unmuteVideo() → {boolean}

启用视频轨道

存在视频轨道的情况下，本地流LocalStream在调用 muteVideo() 后，用该方法重新启用视频轨道，这时远端会触发 Client.on('unmute-video') 事件。
远端流RemoteStream在调用 muteVideo() 后，用该方法恢复解码播放视频。

Inherited From:

Stream#unmuteVideo

Returns:

true 启用视频轨道成功。
false 没有视频轨道，启用失败。

Type: boolean

getId() → {string}

获取 Stream 唯一标识ID

Inherited From:

Stream#getId

Returns:

Id 流唯一标识

Type: string

getUserId() → {string}

获取该流所属的用户ID

Inherited From:

Stream#getUserId

Returns:

userId 用户ID

Type: string

(async) setAudioOutput(deviceId)

设置声音输出设备

移动端不支持设置扬声器。

Inherited From:

Stream#setAudioOutput

Parameters:

Name	Type	Description
`deviceId`	string	设备标识，通过 TRTC.getSpeakers() 获取。

setAudioVolume(volume)

设置播放音量大小

Inherited From:

Stream#setAudioVolume

Parameters:

Name	Type	Description
`volume`	double	音量大小，取值在 0.0 (静音) 到 1.0 (最大音量) 之间。

getAudioLevel() → {number}

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

Inherited From:

Stream#getAudioLevel

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') 事件做进一步处理。

Inherited From:

Stream#hasAudio

Returns:

Type: boolean

hasVideo() → {boolean}

是否包含视频轨道

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

Inherited From:

Stream#hasVideo

Returns:

Type: boolean

getAudioTrack() → (nullable) {MediaStreamTrack}

获取音频轨道

Overrides:

Stream#getAudioTrack

Returns:

音频轨道

Type: MediaStreamTrack

getVideoTrack() → (nullable) {MediaStreamTrack}

获取视频轨道

Overrides:

Stream#getVideoTrack

Returns:

视频轨道

Type: MediaStreamTrack

getVideoFrame() → (nullable) {String}

获取当前视频帧
NOTE

该方法需要在 play() 后调用，并且 Stream 中有视频流才有效

Inherited From:

Stream#getVideoFrame

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

Inherited From:

Stream#on

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 事件

Inherited From:

Stream#off

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	上下文对象

RemoteStream

new RemoteStream()

Example

Extends

Methods

getType() → {string}

Returns:

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

Example

Parameters:

Properties

Throws:

Returns:

stop()

(async) resume() → {Promise}

Example

Throws:

Returns:

muteAudio() → {boolean}

Returns:

muteVideo() → {boolean}

Returns:

unmuteAudio() → {boolean}

Returns:

unmuteVideo() → {boolean}

Returns:

getId() → {string}

Returns:

getUserId() → {string}

Returns:

(async) setAudioOutput(deviceId)

Parameters:

setAudioVolume(volume)

Parameters:

getAudioLevel() → {number}

Example

Returns:

hasAudio() → {boolean}

Returns:

hasVideo() → {boolean}

Returns:

getAudioTrack() → (nullable) {MediaStreamTrack}

Returns:

getVideoTrack() → (nullable) {MediaStreamTrack}

Returns:

getVideoFrame() → (nullable) {String}

Example

Returns:

on(eventName, handler, context)

Example

Parameters:

off(eventName, handler, context)

Example

Parameters: