Interface ILocalVideoTrack | 声网文档中心

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

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

Events

beauty-effect-overload

event_beauty_effect_overload:

sei-received

sei-received(sei: Uint8Array): void

自从

4.20.1

从 H.264 或 H.265 视频流中解析出 SEI 数据时触发，此事件会返回 SEI 数据。

Parameters
参数名	描述
`sei`Uint8Array required	Uint8Array 类型的 SEI 数据

Returns
返回类型	描述
void

video-element-visible-status

video-element-visible-status(data?: CheckVideoVisibleResult): void

自从

4.8.0

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

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

Parameters
参数名	描述
`data`CheckVideoVisibleResult optional	`<video>` 标签的可见状态信息。

Returns
返回类型	描述
void

Properties

enabled

enabled: boolean

Inherited from IBufferSourceAudioTrack.enabled

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

isPlaying

isPlaying: boolean

Inherited from IBufferSourceAudioTrack.isPlaying

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

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

muted

muted: boolean

Inherited from IBufferSourceAudioTrack.muted

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

processorDestination

processorDestination: IBaseProcessor

自从

4.10.0

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

trackMediaType

trackMediaType: "audio"|"video"

Inherited from IBufferSourceAudioTrack.trackMediaType

媒体轨道的类型：

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

Methods

clone

clone(config?: VideoEncoderConfiguration | VideoEncoderConfigurationPreset, cloneTrack?: boolean): ILocalVideoTrack

自从

4.19.0

复制当前的视频轨道对象，生成一个新的视频轨道。

在视频会议、在线教育等场景中，你可以用该方法实现同一视频流的两路显示，并为每路显示设置不同的分辨率、帧率、码率等参数。

Parameters
参数名	描述
`config`VideoEncoderConfiguration \| VideoEncoderConfigurationPreset optional	新生成视频轨道的编码配置。你可以通过 VideoEncoderConfiguration 传入 SDK 内置的编码配置；也可以通过传入一个 VideoEncoderConfigurationPreset 来自定义视频编码配置。
`cloneTrack`boolean optional	是否克隆当前轨道。默认为 `true`。

Returns
返回类型	描述
ILocalVideoTrack	新生成的视频轨道。

close

close(): void

Inherited from IBufferSourceAudioTrack.close

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

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

Returns
返回类型	描述
void

getCurrentFrameData

getCurrentFrameData(): ImageData

自从

4.1.0

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

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

Returns
返回类型	描述
ImageData	存储了 RGBA 数据的 `ImageData` 对象。该对象为浏览器原生对象，详见 ImageData。

getListeners

getListeners(event: string): Function[]

Inherited from EventEmitter.getListeners

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

Parameters
参数名	描述
`event`string required	事件名称。

Returns
返回类型	描述
Function[]

getMediaStreamTrack

getMediaStreamTrack(): MediaStreamTrack

Inherited from IBufferSourceAudioTrack.getMediaStreamTrack

获取浏览器原生的 MediaStreamTrack 对象。

Returns
返回类型	描述
MediaStreamTrack	一个 MediaStreamTrack 对象。

getRTCRtpTransceiver

getRTCRtpTransceiver(type?: StreamType): RTCRtpTransceiver | undefined

Inherited from IBufferSourceAudioTrack.getRTCRtpTransceiver

获取当前轨道的 RTCRtpTransceiver 实例。

该方法目前主要用于视频流的端到端加密（Beta）。

如果 SDK 发生断线重连，当前轨道对应的 RTCRtpTransceiver 实例可能会发生变化。你可以通过以下回调来获取新的 RTCRtpTransceiver 实例：

本地轨道：ILocalTrack.transceiver-updated

远端轨道：IRemoteTrack.transceiver-updated

Parameters
参数名	描述
`type`StreamType optional	视频流的类型。详见 StreamType。

Returns
返回类型	描述
RTCRtpTransceiver \| undefined	当前轨道的 `RTCRtpTransceiver` 实例。

getStats

getStats(): LocalVideoTrackStats

Overrides ILocalTrack.getStats

获取本地视频轨道的相关信息。

deprecated

自 v4.1.0 起废弃，请使用 AgoraRTCClient.getLocalVideoStats 和 AgoraRTCClient.getLocalAudioStats。

Returns
返回类型	描述
LocalVideoTrackStats

getTrackId

getTrackId(): string

Inherited from IBufferSourceAudioTrack.getTrackId

获取由 SDK 生成的对于媒体轨道来说的唯一 ID。

Returns
返回类型	描述
string	媒体轨道 ID。

getTrackLabel

getTrackLabel(): string

Inherited from IBufferSourceAudioTrack.getTrackLabel

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

Returns
返回类型	描述
string	可能返回以下值：如果是通过 `createMicrophoneAudioTrack` 或 `createCameraVideoTrack` 创建的轨道，返回 MediaDeviceInfo.label 字段。如果是通过 `createScreenVideoTrack` 创建的轨道，返回屏幕共享的 `sourceId`。如果是 `createCustomAudioTrack` 或 `createCustomVideoTrack` 创建的轨道，返回 MediaStreamTrack.label 字段。

getVideoElementVisibleStatus

getVideoElementVisibleStatus(): CheckVideoVisibleResult | undefined

自从

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

Inherited from EventEmitter.off

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

Parameters
参数名	描述
`event`string required	指定事件的名称。
`listener`Function required	监听事件时传入的回调函数。

Returns
返回类型	描述
void

on

on [1/4]

on(event: "track-updated", listener: typeof event_track_updated): void

Overrides ILocalAudioTrack.on

Parameters
参数名	描述
`event`"track-updated" required	事件名称。
`listener`typeof event_track_updated required	详见 track-updated。

Returns
返回类型	描述
void

on [2/4]

on(event: "track-ended", listener: typeof event_track_ended): void

Overrides ILocalAudioTrack.on

Parameters
参数名	描述
`event`"track-ended" required	事件名称。
`listener`typeof event_track_ended required	详见 track-ended。

Returns
返回类型	描述
void

on [3/4]

on(event: "video-element-visible-status", listener: typeof event_video_element_visible_status): void

Overrides ILocalAudioTrack.on

Parameters
参数名	描述
`event`"video-element-visible-status" required	事件名称。
`listener`typeof event_video_element_visible_status required	详见 video-element-visible-status。

Returns
返回类型	描述
void

on [4/4]

on(event: "transceiver-updated", listener: typeof event_transceiver_updated): void

Overrides ILocalAudioTrack.on

添加事件监听器。

Parameters
参数名	描述
`event`"transceiver-updated" required	事件名称。
`listener`typeof event_transceiver_updated required	详见 ILocalTrack.transceiver-updated。

Returns
返回类型	描述
void

once

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

Inherited from EventEmitter.once

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

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

Parameters
参数名	描述
`event`string required	指定事件的名称。
`listener`Function required	传入的回调函数。

Returns
返回类型	描述
void

pipe

pipe(processor: IBaseProcessor): IBaseProcessor

自从

4.10.0

将 Processor 注入本地视频轨道。

Parameters
参数名	描述
`processor`IBaseProcessor required	`Processor` 实例。每个插件均有对应类型的 `Processor`。

Returns
返回类型	描述
IBaseProcessor	`Processor` 实例。

play

play(element: string | HTMLElement, config?: VideoPlayerConfig): void

Overrides ILocalTrack.play

在页面上播放远端视频轨道。

Parameters
参数名	描述
`element`string \| HTMLElement required	指定一个 DOM 元素，SDK 将在这个元素下创建 `<video>` 元素播放视频轨道，支持 2 种类型： `string`: 指定该 DOM 元素的 ID 值。 `HTMLElement`: 直接传入一个 DOM 元素对象。
`config`VideoPlayerConfig optional	设置播放参数（镜像/显示模式）。详见 VideoPlayerConfig。对于本地视频轨道，镜像模式默认开启。

Returns
返回类型	描述
void

removeAllListeners

removeAllListeners(event?: string): void

Inherited from EventEmitter.removeAllListeners

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

Parameters
参数名	描述
`event`string optional	指定事件的名称，如果没有指定事件，则取消所有事件的所有监听。

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 方法。

示例代码

JavaScript

// 原有的本地视频轨道
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 required	新的视频轨道。需要传入一个 MediaStreamTrack 对象。
`stopOldTrack`boolean required	是否停止原有的视频轨道：停止原有的视频轨道。保留原有的视频轨道。

Returns
返回类型	描述
Promise<void>

sendSeiData

sendSeiData(sei: Uint8Array): void

在 H.264 视频流中添加 SEI 数据。

Parameters
参数名	描述
`sei`Uint8Array required	SEI 数据。

Returns
返回类型	描述
void

setEnabled

setEnabled(enabled: boolean): Promise<void>

Inherited from IBufferSourceAudioTrack.setEnabled

自从

4.0.0

启用/禁用该轨道。

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

禁用轨道不会触发 LocalTrack.on("track-ended") 事件。

如果该轨道已发布，禁用轨道后，远端会触发 user-unpublished 事件。重新启用后，远端会触发 user-published 事件。

setEnabled 和 setMuted 不能同时调用。

Parameters
参数名	描述
`enabled`boolean required	是否启用该轨道: `true`: 启用该轨道。 `false`: 禁用该轨道。

Returns
返回类型	描述
Promise<void>

setEncoderConfiguration

setEncoderConfiguration(config: VideoEncoderConfiguration | VideoEncoderConfigurationPreset): Promise<void>

设置视频的编码参数，包括分辨率、帧率、码率。

Parameters
参数名	描述
`config`VideoEncoderConfiguration \| VideoEncoderConfigurationPreset required	你可以传入 SDK 预设的视频编码配置 VideoEncoderConfigurationPreset，也可以传入自定义的 VideoEncoderConfiguration 对象。

Returns
返回类型	描述
Promise<void>

setMuted

setMuted(muted: boolean): Promise<void>

Inherited from IBufferSourceAudioTrack.setMuted

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

自从

4.0.0

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

与 setEnabled 相比，调用该方法响应速度更快且不影响视频采集状态，详见 setEnabled 和 setMuted 有什么区别？。

setEnabled 和 setMuted 不能同时调用。

Parameters
参数名	描述
`muted`boolean required	是否发送该轨道的媒体数据: `true`: 暂停发送该轨道的媒体数据。 `false`: 恢复发送该轨道的媒体数据。

Returns
返回类型	描述
Promise<void>

setOptimizationMode

setOptimizationMode(mode: OptimizationMode): Promise<void>

自从

4.2.0

设置视频传输优化模式。

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

注意事项

该方法只支持 Chrome 浏览器。

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

Returns
返回类型	描述
Promise<void>

stop

stop(): void

Inherited from IBufferSourceAudioTrack.stop

停止播放。

Returns
返回类型	描述
void

unpipe

unpipe(): void

自从

4.10.0

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

Returns
返回类型	描述
void

EventsCopy Anchor Link

beauty-effect-overloadCopy Anchor Link

sei-receivedCopy Anchor Link

video-element-visible-statusCopy Anchor Link

PropertiesCopy Anchor Link

enabledCopy Anchor Link

isPlayingCopy Anchor Link

mutedCopy Anchor Link

processorDestinationCopy Anchor Link

trackMediaTypeCopy Anchor Link

MethodsCopy Anchor Link

cloneCopy Anchor Link

closeCopy Anchor Link

getCurrentFrameDataCopy Anchor Link

getListenersCopy Anchor Link

getMediaStreamTrackCopy Anchor Link

getRTCRtpTransceiverCopy Anchor Link

getStatsCopy Anchor Link

deprecatedCopy Anchor Link

getTrackIdCopy Anchor Link

getTrackLabelCopy Anchor Link

getVideoElementVisibleStatusCopy Anchor Link

offCopy Anchor Link

onCopy Anchor Link

on [1/4]Copy Anchor Link

on [2/4]Copy Anchor Link

on [3/4]Copy Anchor Link

on [4/4]Copy Anchor Link

onceCopy Anchor Link

pipeCopy Anchor Link

playCopy Anchor Link

removeAllListenersCopy Anchor Link

replaceTrackCopy Anchor Link

sendSeiDataCopy Anchor Link

setEnabledCopy Anchor Link

setEncoderConfigurationCopy Anchor Link

setMutedCopy Anchor Link

setOptimizationModeCopy Anchor Link

stopCopy Anchor Link

unpipeCopy Anchor Link

咨询电话

咨询电话

Events

beauty-effect-overload

sei-received

video-element-visible-status

Properties

enabled

isPlaying

muted

processorDestination

trackMediaType

Methods

clone

close

getCurrentFrameData

getListeners

getMediaStreamTrack

getRTCRtpTransceiver

getStats

deprecated

getTrackId

getTrackLabel

getVideoElementVisibleStatus

off

on

on [1/4]

on [2/4]

on [3/4]

on [4/4]

once

pipe

play

removeAllListeners

replaceTrack

sendSeiData

setEnabled

setEncoderConfiguration

setMuted

setOptimizationMode

stop

unpipe