Track

Track 对象是 Track 模式下的媒体对象，可以用来在页面上播放媒体。

info

类型 TrackInfo

标记这个 Track 的 TrackInfo, 包含 trackId、kind、tag 等信息

userId

类型 string

标记这个 Track 是来自哪个用户发布的

mediaTrack

类型 MediaStreamTrack

表示这个 Track 原生的浏览器媒体对象，一般场景不会用到

mediaElement

类型 HTMLVideoElement | HTMLAudioElement | undefined

如果调用了 Track 的 play 方法，这里可以访问到实际播放媒体的 <video> 或 <audio> 元素。如果没有 play 过或者 Track 被释放，为 undefined。

play(container)

container: HTMLElement

在传入的 container 下创建相应的 <audio> 或 <video> 元素播放媒体。详细参见播放音视频轨

返回 Promise<void>

返回值 Promise 如果结果为 reject 表示播放失败，反之表示播放成功。

如果您在还没有与用户任何交互的情况下调用了 play 方法可能会发生播放失败的情况，详情参考我们的博文：浏览器的自动播放策略的注意事项

getStats()

返回 TrackStatsReport[]

获取当前 Track 的传输状态数据，SDK 内部会每秒更新一次。TrackStatsReport 的详细格式见下：

TrackStatsReport {
  id: string,             // 该路流的唯一标识，用于大小流中区分多路流
  bitrate: number;        // 当前实时码率
  bytes: number;          // 截止目前一共发送/接收的字节数
  packets: number;        // 截止目前一共发送/接收的包数
  packetLoss: number;     // 截止目前一共的丢包数
  packetLossRate: number; // 当前的丢包率
  rtt: number;            // 网络往返延时
  timestamp: number;      // 时间戳
  width?: number;         // 该路流传输的 frameWidth
  height?: number;        // 该路流传输的 frameHeight
  frameRate: number;      // 视频实时帧率
  networkGrade: NetworkGrade;
}

NetworkGrade 表示网络质量等级枚举，含义如下：

export enum NetworkGrade {
  /**
   * 网络等级还未获取
   */
  INVALID = -1,

  /**
   * 网络优
   */
  EXCELLENT = 1,

  /**
   * 网络良
   */
  GOOD = 2,

  /**
   * 网络一般
   */
  FAIR = 3,

  /**
   * 网络较差
   */
  POOR = 4
}

该方法仅支持 Chrome 和 Firefox

release()

停止从远端或者采集设备拉取媒体数据，释放这个 Track

取消订阅会自动调用相应Track 的 release，但是取消发布不会调用，如果需要请手动调用

getCurrentFrameDataURL()

视频Track调用才会生效

截帧

返回: DataURL

当视频不存在时返回 "data:,"

setVolume(value)

音频Track调用才会生效

value: number

设置音量，目前仅对采集到的 Track 有效（订阅 Track 无效）
value 是增益值，0 代表静音，2，代表当前声音的 2 倍

getCurrentTimeDomainData()

音频Track调用才会生效

返回 Uint8Array

获取当前 2048 位的时域数据
通常用于音频可视化的数据，可以配合 requestAnimationFrame 和 canvas 实现绘制声波图

getCurrentFrequencyData()

音频Track调用才会生效

返回 Uint8Array

获取当前 2048 位的频域数据
通常用于音频可视化的数据，可以配合 requestAnimationFrame 和 canvas 实现绘制频谱图

getCurrentVolumeLevel()

音频Track调用才会生效

返回 number

获取当前实时的音量等级，返回值的范围在 0 - 1 之间，可以用于音量的可视化。

事件列表

audioBuffer

监听该回调后，SDK 会收集音频的原始 Buffer 数据，然后回调给传入的 callback 函数中。AudioBuffer 是浏览器原生的音频 Buffer 对象。

track.on("audioBuffer", audioBuffer => {
  console.log(audioBuffer);
});

audio-active-status

当 track 为 audio 时，监听 audio-active-status，实时返回当前音频轨道是否活跃。

这里的活跃是指音频轨道中存在有效的音频数据。SDK 通过实时检测音频轨道中音量是否存在正常的高低变化来判断是否活跃。处于极度安静的情况下，SDK 可能会发生误判（返回结果亦为 false）。

track.on("audio-active-status", (status) => {
  console.log(`audio-active-status: ${ status ? "active" : "passive" }`);
});

release

当 Track 调用 release 方法的时候触发，表示这个 Track 已经被释放。无论是自己手动调用还是 SDK 自动调用都会触发。

track.once("release", () => {
  console.log("track", track, "is released!");
});

ended

当 Track 由于任何原因不再向流提供数据时发生此事件，包括到达媒体输入的结束，用户撤消所需的权限，删除源设备或远程结束连接。

常见于 USB 输入设备被拔出或 Chrome 下在屏幕共享过程中用户自行取消了屏幕共享。订阅下来的 Track 不会触发此事件

track.once("ended", () => {
  console.log("track ended!");
});

当发生 ended 事件时，应当取消发布并释放该路 track，并重新采集新的 track 发布到房间。

自 SDK 2.5.1 开始，当发生 ended 事件后，SDK 会主动取消发布并释放该路 track。如果使用的是之前的版本，需要注意主动调用取消发布和释放的接口。