# Interface IRemoteVideoTrack (/zh-CN/api-reference/rtc/web/interfaces/iremotevideotrack)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

调用 [subscribe](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#subscribe) 后通过 [AgoraRTCRemoteUser.videoTrack](/zh-CN/api-reference/rtc/web/interfaces/iagorartcremoteuser#videotrack) 对象获取。

## Events [#events]

<a id="event_video_element_visible_status_2"></a>

### video-element-visible-status [#video-element-visible-status]

<ApiSignature>

video-element-visible-status(data?: [CheckVideoVisibleResult](/zh-CN/api-reference/rtc/web/globals#checkvideovisibleresult)): void

</ApiSignature>

:::info[自从]
*4.8.0*
:::

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

调用 `remoteVideoTrack.play` 后 SDK 会创建 [HTML `<video>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video) 标签用于播放视频轨道。当 `remoteVideoTrack.isPlaying` 为 `true` 却看不到图像时，你可通过此事件来进行问题排查。

<ParameterList title="Parameters">
<Parameter name="data" optional>

<ParameterType>

[CheckVideoVisibleResult](/zh-CN/api-reference/rtc/web/globals#checkvideovisibleresult)

</ParameterType>

`<video>` 标签的可见状态信息。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

## Properties [#properties]

<a id="isplaying"></a>

### isPlaying [#isplaying]

<ApiSignature>

isPlaying: boolean

</ApiSignature>

Inherited from [IBufferSourceAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack).[isPlaying](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack#isplaying)

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

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

<a id="processordestination"></a>

### processorDestination [#processordestination]

<ApiSignature>

processorDestination: IBaseProcessor

</ApiSignature>

:::info[自从]
*4.13.0*
:::

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

<a id="trackmediatype"></a>

### trackMediaType [#trackmediatype]

<ApiSignature>

trackMediaType: "audio"|"video"

</ApiSignature>

Inherited from [IBufferSourceAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack).[trackMediaType](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack#trackmediatype)

媒体轨道的类型：

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

## Methods [#methods]

<a id="getcurrentframedata"></a>

### getCurrentFrameData [#getcurrentframedata]

<ApiSignature>

getCurrentFrameData(): ImageData

</ApiSignature>

:::info[自从]
*4.1.0*
:::

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

> 只有在播放后才能调用此方法，如果没有调用 [play](/zh-CN/api-reference/rtc/web/interfaces/iremotevideotrack#play) 则返回空数据。

<ApiReturns>

<ApiReturnType>

ImageData

</ApiReturnType>

存储了 RGBA 数据的 `ImageData` 对象。该对象为浏览器原生对象，详见 [ImageData](https://developer.mozilla.org/zh-CN/docs/Web/API/ImageData)。

</ApiReturns>

<a id="getlisteners"></a>

### getListeners [#getlisteners]

<ApiSignature>

getListeners(event: string): Function[]

</ApiSignature>

Inherited from EventEmitter.getListeners

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

<ParameterList title="Parameters">
<Parameter name="event" type="string" required>

事件名称。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Function[]

</ApiReturnType>

</ApiReturns>

<a id="getmediastreamtrack"></a>

### getMediaStreamTrack [#getmediastreamtrack]

<ApiSignature>

getMediaStreamTrack(): MediaStreamTrack

</ApiSignature>

Inherited from [IBufferSourceAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack).[getMediaStreamTrack](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack#getmediastreamtrack)

获取浏览器原生的 [MediaStreamTrack](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack) 对象。

<ApiReturns>

<ApiReturnType>

MediaStreamTrack

</ApiReturnType>

一个 [MediaStreamTrack](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack) 对象。

</ApiReturns>

<a id="getrtcrtptransceiver"></a>

### getRTCRtpTransceiver [#getrtcrtptransceiver]

<ApiSignature>

getRTCRtpTransceiver(type?: [StreamType](/zh-CN/api-reference/rtc/web/enums/streamtype)): RTCRtpTransceiver | undefined

</ApiSignature>

Inherited from [IBufferSourceAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack).[getRTCRtpTransceiver](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack#getrtcrtptransceiver)

获取当前轨道的 [RTCRtpTransceiver](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpTransceiver) 实例。

该方法目前主要用于视频流的[端到端加密（Beta）](/zh-CN/realtime-media/rtc/build/security-and-auth/e2e-encryption)。

> 如果 SDK 发生断线重连，当前轨道对应的 `RTCRtpTransceiver` 实例可能会发生变化。你可以通过以下回调来获取新的 `RTCRtpTransceiver` 实例：
>
> - 本地轨道：[ILocalTrack.transceiver-updated](/zh-CN/api-reference/rtc/web/interfaces/ilocaltrack#event_transceiver_updated)
> - 远端轨道：[IRemoteTrack.transceiver-updated](/zh-CN/api-reference/rtc/web/interfaces/iremotetrack#event_transceiver_updated_2)

<ParameterList title="Parameters">
<Parameter name="type" optional>

<ParameterType>

[StreamType](/zh-CN/api-reference/rtc/web/enums/streamtype)

</ParameterType>

视频流的类型。详见 [StreamType](/zh-CN/api-reference/rtc/web/enums/streamtype)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

RTCRtpTransceiver | undefined

</ApiReturnType>

当前轨道的 `RTCRtpTransceiver` 实例。

</ApiReturns>

<a id="getstats"></a>

### getStats [#getstats]

<ApiSignature>

getStats(): [RemoteVideoTrackStats](/zh-CN/api-reference/rtc/web/interfaces/remotevideotrackstats)

</ApiSignature>

Overrides [IRemoteTrack](/zh-CN/api-reference/rtc/web/interfaces/iremotetrack).[getStats](/zh-CN/api-reference/rtc/web/interfaces/iremotetrack#getstats)

获取远端视频轨道相关信息。

**不推荐使用** 请使用 [AgoraRTCClient.getRemoteVideoStats](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#getremotevideostats) 获取远端视频轨道相关信息。

<ApiReturns>

<ApiReturnType>

[RemoteVideoTrackStats](/zh-CN/api-reference/rtc/web/interfaces/remotevideotrackstats)

</ApiReturnType>

一个 [RemoteVideoTrackStats](/zh-CN/api-reference/rtc/web/interfaces/remotevideotrackstats) 对象。

</ApiReturns>

<a id="gettrackid"></a>

### getTrackId [#gettrackid]

<ApiSignature>

getTrackId(): string

</ApiSignature>

Inherited from [IBufferSourceAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack).[getTrackId](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack#gettrackid)

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

<ApiReturns>

<ApiReturnType>

string

</ApiReturnType>

媒体轨道 ID。

</ApiReturns>

<a id="getuserid"></a>

### getUserId [#getuserid]

<ApiSignature>

getUserId(): [UID](/zh-CN/api-reference/rtc/web/globals#uid)

</ApiSignature>

Inherited from [IRemoteAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack).[getUserId](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack#getuserid)

获取发布远端轨道的远端用户 ID。

<ApiReturns>

<ApiReturnType>

[UID](/zh-CN/api-reference/rtc/web/globals#uid)

</ApiReturnType>

远端轨道对应的 `uid`。

</ApiReturns>

<a id="getvideoelementvisiblestatus"></a>

### getVideoElementVisibleStatus [#getvideoelementvisiblestatus]

<ApiSignature>

getVideoElementVisibleStatus(): [CheckVideoVisibleResult](/zh-CN/api-reference/rtc/web/globals#checkvideovisibleresult) | undefined

</ApiSignature>

:::info[自从]

*4.8.0*
:::

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

调用 `remoteVideoTrack.play` 后 SDK 会创建 [HTML `<video>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video) 标签用于播放视频轨道。当 `remoteVideoTrack.isPlaying` 为 `true` 却看不到图像时，你可调用该方法进行问题排查。

<ApiReturns>

<ApiReturnType>

[CheckVideoVisibleResult](/zh-CN/api-reference/rtc/web/globals#checkvideovisibleresult) | undefined

</ApiReturnType>

[CheckVideoVisibleResult](/zh-CN/api-reference/rtc/web/globals#checkvideovisibleresult) 对象。如果该方法返回 `undefined`，可能为以下原因：

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

</ApiReturns>

<a id="off"></a>

### off [#off]

<ApiSignature>

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

</ApiSignature>

Inherited from EventEmitter.off

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

<ParameterList title="Parameters">
<Parameter name="event" type="string" required>

指定事件的名称。

</Parameter>
<Parameter name="listener" type="Function" required>

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

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="on"></a>

### on [#on]

#### on [1/6] [#on-16]

<ApiSignature>

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

</ApiSignature>

Overrides [IRemoteAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack).[on](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack#on)

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;track-updated&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_track_updated" required>

详见 [track-updated](/zh-CN/api-reference/rtc/web/globals#event_track_updated)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [2/6] [#on-26]

<ApiSignature>

on(event: "video-state-changed", listener: typeof event_video_state_changed): void

</ApiSignature>

Overrides [IRemoteAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack).[on](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack#on)

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;video-state-changed&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_video_state_changed" required>

详见 [video-state-changed](/zh-CN/api-reference/rtc/web/interfaces/iremotetrack#event_video_state_changed)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [3/6] [#on-36]

<ApiSignature>

on(event: "first-frame-decoded", listener: typeof event_first_frame_decoded): void

</ApiSignature>

Overrides [IRemoteAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack).[on](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack#on)

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;first-frame-decoded&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_first_frame_decoded" required>

详见 [first-frame-decoded](/zh-CN/api-reference/rtc/web/interfaces/iremotetrack#event_first_frame_decoded)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [4/6] [#on-46]

<ApiSignature>

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

</ApiSignature>

Overrides [IRemoteAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack).[on](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack#on)

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;video-element-visible-status&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_video_element_visible_status_2" required>

详见 [video-element-visible-status](/zh-CN/api-reference/rtc/web/interfaces/iremotevideotrack#event_video_element_visible_status_2)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [5/6] [#on-56]

<ApiSignature>

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

</ApiSignature>

Overrides [IRemoteAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack).[on](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack#on)

添加事件监听器。

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;transceiver-updated&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_transceiver_updated_2" required>

详见 [IRemoteTrack.transceiver-updated](/zh-CN/api-reference/rtc/web/interfaces/iremotetrack#event_transceiver_updated_2)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [6/6] [#on-66]

<ApiSignature>

on(event: "sei-received", listener: typeof event_sei_received): void

</ApiSignature>

Overrides [IRemoteAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack).[on](/zh-CN/api-reference/rtc/web/interfaces/iremoteaudiotrack#on)

添加事件监听器。

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;sei-received&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_sei_received" required>

详见 [ILocalTrack.sei-received](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack#event_sei_received)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="once"></a>

### once [#once]

<ApiSignature>

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

</ApiSignature>

Inherited from EventEmitter.once

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

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

<ParameterList title="Parameters">
<Parameter name="event" type="string" required>

指定事件的名称。

</Parameter>
<Parameter name="listener" type="Function" required>

传入的回调函数。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="pipe"></a>

### pipe [#pipe]

<ApiSignature>

pipe(processor: IBaseProcessor): IBaseProcessor

</ApiSignature>

:::info[自从]
*4.13.0*
:::

将 `Processor` 注入远端视频轨道。

<ParameterList title="Parameters">
<Parameter name="processor" type="IBaseProcessor" required>

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

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

IBaseProcessor

</ApiReturnType>

`Processor` 实例。

</ApiReturns>

<a id="play"></a>

### play [#play]

<ApiSignature>

play(element: string | HTMLElement, config?: [VideoPlayerConfig](/zh-CN/api-reference/rtc/web/interfaces/videoplayerconfig)): void

</ApiSignature>

Overrides [ILocalTrack](/zh-CN/api-reference/rtc/web/interfaces/ilocaltrack).[play](/zh-CN/api-reference/rtc/web/interfaces/ilocaltrack#play)

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

<ParameterList title="Parameters">
<Parameter name="element" type="string | HTMLElement" required>

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

- `string`: 指定该 DOM 元素的 ID 值。
- `HTMLElement`: 直接传入一个 DOM 元素对象。

</Parameter>
<Parameter name="config" optional>

<ParameterType>

[VideoPlayerConfig](/zh-CN/api-reference/rtc/web/interfaces/videoplayerconfig)

</ParameterType>

设置播放参数（镜像/显示模式）。详见 [VideoPlayerConfig](/zh-CN/api-reference/rtc/web/interfaces/videoplayerconfig)。对于本地视频轨道，镜像模式默认开启。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="removealllisteners"></a>

### removeAllListeners [#removealllisteners]

<ApiSignature>

removeAllListeners(event?: string): void

</ApiSignature>

Inherited from EventEmitter.removeAllListeners

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

<ParameterList title="Parameters">
<Parameter name="event" type="string" optional>

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

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="stop"></a>

### stop [#stop]

<ApiSignature>

stop(): void

</ApiSignature>

Inherited from [IBufferSourceAudioTrack](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack).[stop](/zh-CN/api-reference/rtc/web/interfaces/ibuffersourceaudiotrack#stop)

停止播放。

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="unpipe"></a>

### unpipe [#unpipe]

<ApiSignature>

unpipe(): void

</ApiSignature>

:::info[自从]
*4.13.0*
:::

取消远端视频轨道上注入的 `Processor`。

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>