RemoteStream

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

Methods

getType() → {string}

获取远端流类型

主要用于判断一个远端流是主音视频流还是辅路视频流,辅路视频流通常是一个屏幕分享流。

Returns:

远端流类型

  • 'main' 主音视频流
  • ‘auxiliary’ 辅助视频流,通常是一个屏幕分享流
Type
string

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

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

NOTE

  • 由于浏览器自动播放策略的影响,调用该接口可能会返回 PLAY_NOT_ALLOWED 错误, 此时需要引导用户通过手势操作调用 resume() 恢复音视频播放。
Inherited From:
Example
stream.play('remote').then(() => {
  // autoplay success
}).catch((e) => {
  const errorCode = e.getCode();
  if (errorCode === 0x4043) {
    // PLAY_NOT_ALLOWED,引导用户手势操作恢复音视频播放
    // stream.resume()
  }
});
Parameters:
Name Type Attributes Description
elementId string | HTMLDivElement

HTML <div> 标签 ID 或者 HTMLDivElement 对象,该方法内部自动创建的音视频标签将被添加到该容器中。

options object <optional>

播放选项

Properties
Name Type Description
objectFit string

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

  • 'contain' 优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。
  • 'cover' 优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。

    对于本地流,播放视频流默认使用 cover 模式,屏幕共享默认使用 contain 模式。
muted boolean

是否需要 mute 声音,对于本地流通常需要 mute 声音以防止播放从麦克风采集回来的声音。

Throws:
Returns:
Type
Promise

stop()

停止播放音视频流

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

Inherited From:

(async) resume() → {Promise}

恢复播放音视频
NOTE

  • 在某些版本浏览器上移动传入 play() 的 div 容器可能会导致音视频播放器进入 ‘PAUSED’ 状态,此时 需要调用该接口恢复播放。
  • 由于浏览器自动播放策略的限制,在 play() 返回 PLAY_NOT_ALLOWED 错误后需要引导用户通过手势 调用该接口恢复播放。
Inherited From:
Example
stream.on('player-state-changed', event => {
  if (event.state === 'PAUSED') {
    // resume audio/video playback
    stream.resume();
  }
});
Throws:
Returns:
Type
Promise

close()

关闭音视频流

对于本地流,该方法会关闭摄像头并释放摄像头和麦克风访问权限。

Inherited From:

muteAudio() → {boolean}

禁用音频轨道

  • 对于本地流,调用该方法会停止发送音频,远端会触发 Client.on('mute-audio') 事件。
  • 对于远端流,调用该方法会停止播放音频,但是仍然接收音频数据。
Inherited From:
Returns:
  • true 禁用音频轨道成功。
  • false 禁用音频轨道失败,因为没有音频轨道。
Type
boolean

muteVideo() → {boolean}

禁用视频轨道

  • 对于本地流,调用该方法会停止发送视频,远端会触发 Client.on('mute-video') 事件。
    如果视频是从摄像头采集,此时摄像头灯仍然是亮着的。若想完全禁用视频轨道(即关闭摄像头),
    可以使用 removeTrack() 删除视频轨道然后调用 MediaStreamTrack.stop() 关闭视频轨道(关闭摄像头)。
  • 对于远端流,调用该方法会停止播放视频,但是仍然接收视频数据.
Inherited From:
Returns:
  • true 禁用视频轨道成功
  • false 禁用视频轨道失败,因为没有视频轨道。
Type
boolean

unmuteAudio() → {boolean}

启用音频轨道

对于本地流,调用该方法会触发远端 Client.on('unmute-audio') 事件。

音频轨道默认是开启的,若你调用 muteAudio() 后可用该方法重新启用音频。

Inherited From:
Returns:
  • true 启用音频轨道成功。
  • false 没有音频轨道,启用失败。
Type
boolean

unmuteVideo() → {boolean}

启用视频轨道

对于本地流,调用该方法会触发远端 Client.on('unmute-video') 事件。

视频轨道默认是开启的,若你调用 muteVideo() 后可用该方法重新启用视频。

Inherited From:
Returns:
  • true 启用视频轨道成功。
  • false 没有视频轨道,启用失败。
Type
boolean

getId() → {string}

获取 Stream 唯一标识ID

Inherited From:
Returns:

Id 流唯一标识

Type
string

getUserId() → {string}

获取该流所属的用户ID

Inherited From:
Returns:

userId 用户ID

Type
string

(async) setAudioOutput(deviceId)

设置声音输出设备

Inherited From:
Parameters:
Name Type Description
deviceId string

设备标识,通过 getSpeakers() 获取。

setAudioVolume(volume)

设置播放音量大小

Inherited From:
Parameters:
Name Type Description
volume double

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

getAudioLevel() → {number}

获取当前音量大小
只有当本地流或远端流中有音频数据才有效。

Inherited From:
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}

是否包含音频轨道

Inherited From:
Returns:
Type
boolean

hasVideo() → {boolean}

是否包含视频轨道

Inherited From:
Returns:
Type
boolean

getAudioTrack() → (nullable) {MediaStreamTrack}

获取音频轨道

Inherited From:
Returns:

音频轨道

Type
MediaStreamTrack

getVideoTrack() → (nullable) {MediaStreamTrack}

获取视频轨道

Inherited From:
Returns:

视频轨道

Type
MediaStreamTrack

getVideoFrame() → (nullable) {String}

获取当前视频帧
NOTE

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

'image/png' 类型的 dataURL

Type
String

on(eventName, handler)

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

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

事件名称

handler function

事件处理方法