通知
本站点除 Legacy 产品与方案外，已迁移至 声网新文档中心 ，当前页面不再维护
文档中心
全部产品
Console 官网 社区 技术支持
简体中文
search-icon

Agora Web API Reference

概览 AgoraRTC AgoraRTCClient LocalTrack RemoteTrack 错误码

LocalVideoTrack 为本地视频轨道的基础类，提供了本地视频轨道的主要功能。

你可以通过 AgoraRTC.createCustomVideoTrack 或者 AgoraRTC.createScreenVideoTrack 来获取 LocalVideoTrack。

通过摄像头采集到的本地视频轨道对象 CameraVideoTrack 继承于此接口，并在本接口的基础上提供了一些摄像头独有的功能。

Hierarchy

Index

Events

Properties

Methods

Events

video-element-visible-status-2

  • 自从
       4.8.0

    提示 HTML <video> 标签的可见状态和不可见原因。SDK 每 30 秒触发一次该事件。

    调用 localVideoTrack.play 后 SDK 会创建 HTML <video> 标签用于播放视频轨道。当 localVideoTrack.isPlaying 为 true 却看不到图像时，你可通过此事件来进行问题排查。

    Parameters

    Returns void

Properties

enabled

enabled: boolean

本地轨道当前的启用状态。

isPlaying

isPlaying: boolean

媒体轨道是否正在页面上播放。

  • true: 媒体轨道正在页面上播放。
  • false: 媒体轨道没有在页面上播放。

muted

muted: boolean

本地媒体轨道当前的静音状态。

processorDestination

processorDestination: IBaseProcessor

自从
   4.10.0

本地视频轨道上当前媒体处理链路的最终节点。

trackMediaType

trackMediaType: "audio" | "video"

媒体轨道的类型：

  • "audio": 音频轨道。
  • "video": 视频轨道。

Methods

close

  • close(): void

  • 关闭本地轨道，并释放相关采集设备。

    一旦本地轨道被关闭，就无法再次使用。如需再次使用本地轨道，需要重新创建。

    Returns void

getCurrentFrameData

  • getCurrentFrameData(): ImageData

  • 自从
       4.1.0

    获取当前渲染的视频帧数据。

    只有在播放后才能调用此方法，如果没有调用 play 则返回空数据。

    Returns ImageData

    存储了 RGBA 数据的 ImageData 对象。该对象为浏览器原生对象，详见 ImageData。

getListeners

  • getListeners(event: string): Function[]

  • 指定一个事件名，获取当前所有监听这个事件的回调函数。

    Parameters

    • event: string

      事件名称。

    Returns Function[]

getMediaStreamTrack

  • getMediaStreamTrack(): MediaStreamTrack

getStats

getTrackId

  • getTrackId(): string

getTrackLabel

  • getTrackLabel(): string

  • 获取本地轨道的来源描述。

    Returns string

    可能返回以下值：

    • 如果是通过 createMicrophoneAudioTrack 或 createCameraVideoTrack 创建的轨道，返回 MediaDeviceInfo.label 字段。
    • 如果是通过 createScreenVideoTrack 创建的轨道，返回屏幕共享的 sourceId。
    • 如果是 createCustomAudioTrack 或 createCustomVideoTrack 创建的轨道，返回 MediaStreamTrack.label 字段。

getVideoElementVisibleStatus

    • 自从
         4.8.0

    获取 HTML <video> 标签的可见状态和不可见原因。

    调用 localVideoTrack.play 后 SDK 会创建 HTML <video> 标签用于播放视频轨道。当 localVideoTrack.isPlaying 为 true 却看不到图像时，你可调用该方法进行问题排查。

    Returns CheckVideoVisibleResult | undefined

    CheckVideoVisibleResult 对象。如果该方法返回 undefined，可能为以下原因：

    • localVideoTrack.isPlaying 为 false。
    • <video> 标签不存在。
    • <video> 标签不是通过 play 方法调用产生的。

off

  • off(event: string, listener: Function): void

  • 取消一个指定事件的监听。

    Parameters

    • event: string

      指定事件的名称。

    • listener: Function

      监听事件时传入的回调函数。

    Returns void

on

  • on(event: "track-ended", listener: typeof event_track_ended): void
  • on(event: "video-element-visible-status", listener: typeof event_video_element_visible_status_2): void

once

  • once(event: string, listener: Function): void

  • 监听一个指定的事件，当事件触发时会调用传入的回调函数。

    当监听后事件第一次触发时，该监听和回调函数就会被立刻移除，也就是只监听一次指定事件。

    Parameters

    • event: string

      指定事件的名称。

    • listener: Function

      传入的回调函数。

    Returns void

pipe

  • pipe(processor: IBaseProcessor): IBaseProcessor

  • 自从
       4.10.0

    将 Processor 注入本地视频轨道。

    Parameters

    • processor: IBaseProcessor

      Processor 实例。每个插件均有对应类型的 Processor。

    Returns IBaseProcessor

    Processor 实例。

play

  • 在页面上播放本地视频轨道。

    Parameters

    • element: string | HTMLElement

      指定一个 DOM 元素，SDK 将在这个元素下创建 <video> 元素播放视频轨道，支持 2 种类型：

      • string: 指定该 DOM 元素的 ID 值。
      • HTMLElement: 直接传入一个 DOM 元素对象。
    • Optional config: VideoPlayerConfig

      设置播放参数（镜像/显示模式）。详见 VideoPlayerConfig。对于本地视频轨道，镜像模式默认开启。

    Returns void

removeAllListeners

  • removeAllListeners(event?: undefined | string): void

  • 指定一个事件，取消其所有的监听。

    Parameters

    • Optional event: undefined | string

      指定事件的名称，如果没有指定事件，则取消所有事件的所有监听。

    Returns void

replaceTrack

  • replaceTrack(track: MediaStreamTrack, stopOldTrack: boolean): Promise<void>

  • 自从
       4.17.0

    替换本地视频轨道。

    该方法在本地视频流发布前或发布后都可以调用：

    • 在发流前调用，新的视频轨道会在本地播放。
    • 在发流后调用，远端会接收到新的视频轨道。

    新的视频轨道可以通过 ILocalVideoTrack.getMediaStreamTrack 或者 mediaStream.getVideoTracks 方法获取。你可以选择是否停止被替换的视频轨道。

    注意事项：

    • 支持 Chrome 65+，Safari 以及最新版 Firefox 浏览器。
    • 部分移动设备上该方法可能不生效。
    • 建议在相同类型、相同编码配置的视频轨道之间进行替换，原因如下：
      • 如果视频轨道类型不同，例如用 ScreenVideoTrack 对象替换 CameraVideoTrack 对象，由于 CameraVideoTrack 默认开启镜像（详见 VideoPlayerConfig.mirror），会导致画面发生镜像翻转。
      • 如果编码配置（encoderConfig）不同，可能导致实际发送的分辨率或帧率不准。
    • 订阅端无法知悉视频轨道被替换。
    • 如果需要切换媒体输入设备，推荐使用 ICameraVideoTrack.setDevice 方法。

    示例代码

    // 原有的本地视频轨道
const localVideoTrack = await AgoraRTC.createCameraVideoTrack();
// 获取新的视频轨道（方式一）
const newTrack = localVideoTrack.getMediaStreamTrack();
// 获取新的视频轨道（方式二）
const newTrack = await navigator.mediaDevices.getUserMedia({audio: true, video: true}).then(mediaStream => mediaStream.getVideoTracks()[0]);
// 替换本地视频轨道，并且停止原有的视频轨道
await localVideoTrack.replaceTrack(newTrack, true);

    Parameters

    • track: MediaStreamTrack

      新的视频轨道。需要传入一个 MediaStreamTrack 对象。

    • stopOldTrack: boolean

      是否停止原有的视频轨道：

      • 停止原有的视频轨道。
      • 保留原有的视频轨道。

    Returns Promise<void>

setEnabled

  • setEnabled(enabled: boolean): Promise<void>

  • 自从
       4.0.0

    启用/禁用该轨道。

    轨道禁用后，播放和发布都将被停止。

    Parameters

    • enabled: boolean

      是否启用该轨道:

      • true: 启用该轨道。
      • false: 禁用该轨道。

    Returns Promise<void>

setEncoderConfiguration

setMuted

  • setMuted(muted: boolean): Promise<void>

  • 发送或暂停发送该轨道的媒体数据。

    自从
       4.6.0

    如果该轨道已发布，调用 setMuted(true) 后，远端会触发 user-unpublished 事件。再调用 setMuted(false) 后，远端会触发 user-published 事件。

    Parameters

    • muted: boolean

      是否发送该轨道的媒体数据:

      • true: 暂停发送该轨道的媒体数据。
      • false: 恢复发送该轨道的媒体数据。

    Returns Promise<void>

setOptimizationMode

  • setOptimizationMode(mode: "balanced" | "motion" | "detail"): Promise<void>

  • 自从
       4.2.0

    设置视频传输优化模式。

    你可以在视频通话、视频直播或屏幕共享过程中调用此方法动态调整视频的传输优化模式。例如你想要把屏幕共享内容从演示文稿切换为视频时，你可以将传输优化模式从 "detail" 切换为 "motion"，确保视频画面在网络波动时不会出现卡顿。

    注意事项：该方法只支持 Chrome 浏览器。

    Parameters

    • mode: "balanced" | "motion" | "detail"

      视频传输优化模式：

      • "balanced": 使用默认的传输优化模式：
        • 对于屏幕共享视频流，SDK 默认的优化策略为清晰优先。
        • 对于其他视频流，SDK 默认的优化策略为兼顾清晰和流畅，弱网条件下，帧率和分辨率都会被调整。
      • "detail": 清晰优先。
        • SDK 会自动根据你的采集分辨率和帧率设定一个最小码率。即使遭遇网络波动，发送码率也不会低于这个值，从而确保清晰的视频画面。
        • 大部分情况下，SDK 不会降低发送分辨率，但是可能会降低帧率。
      • "motion": 流畅优先。
        • SDK 不会启用最小码率策略。遭遇网络波动时，发送端会降低码率来确保接收端的视频画面不会出现中断和卡顿。
        • 大部分情况下，SDK 不会降低帧率，但是可能会降低发送分辨率。

    Returns Promise<void>

stop

  • stop(): void

unpipe

  • unpipe(): void

  • 自从
       4.10.0

    取消本地视频轨道上注入的 Processor。

    Returns void