> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stmlink.com/llms.txt
> Use this file to discover all available pages before exploring further.

# media-tracks

> Web SRTC 音视频 SDK media-tracks 接口参考

### 继承关系

```typescript theme={null}
BaseTrack
├── LocalAudioTrack           ← 本地音频基类（自定义音频流）
│   ├── LocalMicTrack         ← 麦克风流
│   └── LocalScreenAudioTrack ← 屏幕共享附带的系统音频流
├── LocalVideoTrack           ← 本地视频基类（自定义视频流）
│   ├── LocalCameraTrack      ← 摄像头流
│   └── LocalScreenTrack      ← 屏幕共享视频流
├── RemoteAudioTrack          ← 远端单路音频流
│   └── RemoteAudioMixTrack   ← 远端全频道混音流
└── RemoteVideoTrack          ← 远端视频流
```

***

## BaseTrack

所有轨道的基类，提供轨道元信息访问。

#### id

```typescript theme={null}
get id(): string
```

轨道 ID，在频道内唯一标识该轨道。

#### kind

```typescript theme={null}
get kind(): TrackKind
```

轨道类型：`'audio'` 或 `'video'`。

#### desc

```typescript theme={null}
get desc(): string
```

轨道描述，由发布时指定，例如 `'camera_big'`、`'screen'`。

#### getInfo

获取完整轨道信息，例如分辨率、码率、采样率等。

```typescript theme={null}
getInfo(): TrackInfo
```

**返回值：** `TrackInfo`，详见 [类型定义](/zh/rtc/web/types#trackinfo)

#### getUid

获取轨道所属用户的 UID。

```typescript theme={null}
getUid(): string
```

#### getMediaStreamTrack

获取底层 `MediaStreamTrack`，可用于 Web Audio API、自定义后处理等场景。

```typescript theme={null}
getMediaStreamTrack(): MediaStreamTrack | undefined
```

***

## LocalAudioTrack

本地音频轨道基类，也用于自定义音频流，例如 `srtc.createLocalCustomAudioTrack(...)` 的返回值。

继承自 `BaseTrack`。

#### startPlay

播放音频，可用于本地监听。

```typescript theme={null}
startPlay(opt?: AudioOutputOptions): Promise<void>
```

| 参数    | 类型                   |  必填 | 说明            |
| ----- | -------------------- | :-: | ------------- |
| `opt` | `AudioOutputOptions` |  否  | 播放配置，可指定扬声器设备 |

#### stopPlay

停止播放，释放对播放设备的占用。

```typescript theme={null}
stopPlay(): void
```

#### getVolume

获取当前音频输入音量，范围 `0 ~ 100`。

```typescript theme={null}
getVolume(): number
```

#### isPlaying

当前是否正在播放。

```typescript theme={null}
isPlaying(): boolean
```

#### setProcessor

挂载音频处理器（如 RNN 降噪、变声）。需先 `startCapture` 采集到轨道后调用；传入数组时按顺序串联。已发布的轨道也可挂载，SDK 会免重协商地切换；切换设备后处理器会自动重挂。详见[音视频处理器](/zh/rtc/web/advanced/audio-processor)。

```typescript theme={null}
setProcessor(processor: TrackProcessor | TrackProcessor[]): Promise<void>
```

| 参数          | 类型                                   |  必填 | 说明                 |
| ----------- | ------------------------------------ | :-: | ------------------ |
| `processor` | `TrackProcessor \| TrackProcessor[]` |  是  | 处理器实例，或按顺序串联的处理器数组 |

#### removeProcessor

卸载已挂载的处理器，还原为原始采集轨道并释放处理器资源。

```typescript theme={null}
removeProcessor(): Promise<void>
```

***

## LocalMicTrack

本地麦克风轨道，继承自 `LocalAudioTrack`，通过 `srtc.createLocalMicTrack` 创建。

#### startCapture

开始采集，会向用户请求麦克风权限。

```typescript theme={null}
startCapture(opt?: Partial<MicCaptureOptions>): Promise<void>
```

| 参数    | 类型                           |  必填 | 说明                  |
| ----- | ---------------------------- | :-: | ------------------- |
| `opt` | `Partial<MicCaptureOptions>` |  否  | 采集配置，可指定设备 ID、回声消除等 |

#### stopCapture

停止采集，释放麦克风设备。

```typescript theme={null}
stopCapture(): void
```

#### changeDeviceId

热切换麦克风设备。

```typescript theme={null}
changeDeviceId(deviceId: string): Promise<void>
```

| 参数         | 类型       |  必填 | 说明                                        |
| ---------- | -------- | :-: | ----------------------------------------- |
| `deviceId` | `string` |  是  | 目标设备 ID，可通过 `getDevices('audioinput')` 获取 |

***

## LocalScreenAudioTrack

屏幕共享附带的系统音频轨道，继承自 `LocalAudioTrack`。

这个类通常不直接手动创建，而是通过 `LocalScreenTrack.getAudioTrack()` 获取。

#### stopCapture

停止系统音频采集。

```typescript theme={null}
stopCapture(): void
```

> 其余播放相关方法继承自 `LocalAudioTrack`，例如 `startPlay()`、`stopPlay()`、`isPlaying()`。

***

## LocalVideoTrack

本地视频轨道基类，也用于自定义视频流，例如 `srtc.createLocalCustomVideoTrack(...)` 的返回值。

继承自 `BaseTrack`。

#### addPlayView

将视频渲染到指定 HTML 容器元素。

```typescript theme={null}
addPlayView(container: HTMLElement): void
```

#### hasPlayView

判断是否已有渲染容器。

```typescript theme={null}
hasPlayView(): boolean
```

#### removePlayView

移除指定渲染容器。

```typescript theme={null}
removePlayView(container: HTMLElement): void
```

#### removeAllPlayViews

移除所有渲染容器。

```typescript theme={null}
removeAllPlayViews(): void
```

#### enterPictureInPicture

让指定容器对应的视频进入画中画模式。

```typescript theme={null}
enterPictureInPicture(container: HTMLElement, options?: PipOptions): Promise<PipHandle>
```

| 参数          | 类型            |  必填 | 说明                                         |
| ----------- | ------------- | :-: | ------------------------------------------ |
| `container` | `HTMLElement` |  是  | 已通过 `addPlayView` 绑定的视频容器                  |
| `options`   | `PipOptions`  |  否  | 画中画配置，可指定窗口尺寸、是否优先使用 Document PiP、是否隐藏原始视图 |

> 默认优先使用 Document PiP。若浏览器不支持，会自动降级到传统 `video.requestPictureInPicture()`。

#### exitPictureInPicture

退出指定容器的画中画模式。

```typescript theme={null}
exitPictureInPicture(container: HTMLElement): Promise<void>
```

#### isPictureInPicture

判断指定容器是否处于画中画模式。

```typescript theme={null}
isPictureInPicture(container: HTMLElement): boolean
```

#### popOutToWindow

将指定容器对应的视频弹出到独立浏览器窗口。

```typescript theme={null}
popOutToWindow(container: HTMLElement, options?: PopOutOptions): PopOutHandle
```

| 参数          | 类型              |  必填 | 说明                        |
| ----------- | --------------- | :-: | ------------------------- |
| `container` | `HTMLElement`   |  是  | 已通过 `addPlayView` 绑定的视频容器 |
| `options`   | `PopOutOptions` |  否  | 弹窗配置，可指定窗口尺寸、标题、是否隐藏原始视图  |

#### closePopOutWindow

关闭指定容器对应的弹出窗口。

```typescript theme={null}
closePopOutWindow(container: HTMLElement): void
```

#### isPopOut

判断指定容器是否已经弹出到独立窗口。

```typescript theme={null}
isPopOut(container: HTMLElement): boolean
```

#### getSimulcastTrack

基于给定的联播发布参数创建或获取一个联播子轨道。

```typescript theme={null}
getSimulcastTrack(opt: VideoPublishOptions, owidth?: number, oheight?: number): LocalVideoTrack
```

| 参数        | 类型                    |  必填 | 说明                     |
| --------- | --------------------- | :-: | ---------------------- |
| `opt`     | `VideoPublishOptions` |  是  | 联播子轨道的发布参数，`desc` 不能为空 |
| `owidth`  | `number`              |  否  | 原始视频宽度，用于计算编码缩放比例      |
| `oheight` | `number`              |  否  | 原始视频高度，用于计算编码缩放比例      |

#### setProcessor

挂载视频处理器（如美颜、虚化背景）。需先 `startCapture` 采集到轨道后调用；传入数组时按顺序串联。已发布的轨道也可挂载，SDK 会免重协商地切换；切换设备后处理器会自动重挂。详见[音视频处理器](/zh/rtc/web/advanced/audio-processor)。

```typescript theme={null}
setProcessor(processor: TrackProcessor | TrackProcessor[]): Promise<void>
```

| 参数          | 类型                                   |  必填 | 说明                 |
| ----------- | ------------------------------------ | :-: | ------------------ |
| `processor` | `TrackProcessor \| TrackProcessor[]` |  是  | 处理器实例，或按顺序串联的处理器数组 |

#### removeProcessor

卸载已挂载的处理器，还原为原始采集轨道并释放处理器资源。

```typescript theme={null}
removeProcessor(): Promise<void>
```

> 对于 `LocalCameraTrack`、`LocalScreenTrack` 和 `RemoteVideoTrack`，以上 PiP / 弹窗方法均可使用。
>
> 当 `options.hideOriginView` 为 `true`（默认值）时：
>
> * `Document PiP` 和 `弹出窗口` 会隐藏主页面中的原始播放视图，避免双重渲染
> * 传统 `video PiP` 仍依赖原始 `video` 元素，因此不会隐藏原始视图

***

## LocalCameraTrack

本地摄像头视频轨道，继承自 `LocalVideoTrack`，通过 `srtc.createLocalCameraTrack` 创建。

#### startCapture

开始采集，会向用户请求摄像头权限。

```typescript theme={null}
startCapture(opt?: Partial<CameraCaptureOptions>): Promise<void>
```

| 参数    | 类型                              |  必填 | 说明                   |
| ----- | ------------------------------- | :-: | -------------------- |
| `opt` | `Partial<CameraCaptureOptions>` |  否  | 采集配置，可指定设备 ID、分辨率、帧率 |

#### stopCapture

停止采集，释放摄像头设备。

```typescript theme={null}
stopCapture(): void
```

#### changeDeviceId

热切换摄像头设备。

```typescript theme={null}
changeDeviceId(deviceId: string): Promise<void>
```

#### switchFacingMode

在前置/后置摄像头之间切换，仅移动端生效。

```typescript theme={null}
switchFacingMode(): Promise<void>
```

#### setMirror

设置本地预览镜像开关。前置摄像头默认开启镜像（如同照镜子），可在此调整；后置摄像头不支持镜像，调用无任何反应。

镜像只影响本地预览的渲染（含画中画、弹出窗口），**不会改变推流数据与远端看到的画面**。切换前后置摄像头会自动重新计算镜像状态，并保留用户对前置摄像头的开关偏好。

```typescript theme={null}
setMirror(enabled: boolean): void
```

| 参数        | 类型        |  必填 | 说明     |
| --------- | --------- | :-: | ------ |
| `enabled` | `boolean` |  是  | 是否开启镜像 |

#### isMirrored

返回当前是否处于镜像状态（前置摄像头且镜像开关开启）。后置摄像头恒为 `false`，可用于 UI 回显当前镜像状态。

```typescript theme={null}
isMirrored(): boolean
```

#### isFrontFacing

判断当前是否为前置摄像头。采集时显式指定的 `facingMode` 最可靠；未指定时按前置处理。

```typescript theme={null}
isFrontFacing(): boolean
```

***

## LocalScreenTrack

本地屏幕共享视频轨道，继承自 `LocalVideoTrack`，通过 `srtc.createLocalScreenTrack` 创建。

#### startCapture

开始屏幕采集，浏览器会弹出屏幕选择窗口。

```typescript theme={null}
startCapture(opt?: Partial<ScreenCaptureOptions>): Promise<void>
```

| 参数    | 类型                              |  必填 | 说明                             |
| ----- | ------------------------------- | :-: | ------------------------------ |
| `opt` | `Partial<ScreenCaptureOptions>` |  否  | 采集配置，可指定分辨率、帧率、`contentHint` 等 |

#### stopCapture

停止屏幕采集。

```typescript theme={null}
stopCapture(): void
```

#### getAudioTrack

获取同时采集的系统音频轨道。仅当 `createLocalScreenTrack` 传入了 `audioPreset` 且浏览器支持时有效。

```typescript theme={null}
getAudioTrack(): LocalScreenAudioTrack | undefined
```

> 详细用法见 [屏幕共享 - 同时采集系统音频](/zh/rtc/web/advanced/screen-sharing#同时采集系统音频)

***

## RemoteAudioTrack

远端单路音频轨道，通过 `srtc.subscribeRemoteAudioTrack` 订阅。

继承自 `BaseTrack`。

#### startPlay

播放远端音频。

```typescript theme={null}
startPlay(opt?: AudioOutputOptions): Promise<void>
```

| 参数    | 类型                   |  必填 | 说明       |
| ----- | -------------------- | :-: | -------- |
| `opt` | `AudioOutputOptions` |  否  | 可指定扬声器设备 |

#### stopPlay

停止播放，释放对播放设备的占用。

```typescript theme={null}
stopPlay(): void
```

#### isPlaying

当前是否正在播放。

```typescript theme={null}
isPlaying(): boolean
```

***

## RemoteAudioMixTrack

远端全频道混音流，继承自 `RemoteAudioTrack`，通过 `srtc.subscribeRemoteAudioMixTrack` 订阅。

大多数场景下只需要订阅这一路混音流，而无需订阅每个用户的单独音频流。

#### getFilterUids

获取当前从混音中排除的用户 ID 列表。

```typescript theme={null}
getFilterUids(): string[]
```

> 播放相关方法继承自 `RemoteAudioTrack`，例如 `startPlay()`、`stopPlay()`、`isPlaying()`。

***

## RemoteVideoTrack

远端视频轨道，通过 `srtc.subscribeRemoteVideoTrack` 订阅。

继承自 `BaseTrack`。

#### setJitterBufferTarget

设置接收端抗抖动缓冲的目标延迟，单位 ms。

```typescript theme={null}
setJitterBufferTarget(ms?: number): void
```

参数说明：

| 参数   | 类型       |  必填 | 说明                                                                                |
| ---- | -------- | :-: | --------------------------------------------------------------------------------- |
| `ms` | `number` |  否  | 目标延迟。`0` 表示低延迟优先，`200` 到 `500` 这类较大值更偏向平滑播放；不传或传 `undefined` 表示清除设置，回到浏览器默认自适应策略。 |

> 该能力依赖浏览器 WebRTC 接收端实现。Chrome / Edge 会优先使用 `jitterBufferTarget`，并兼容旧的 `playoutDelayHint`；Firefox / Safari 不支持时会静默忽略。

#### getJitterBufferTarget

获取当前设置的接收端抗抖动缓冲目标延迟。

```typescript theme={null}
getJitterBufferTarget(): number | undefined
```

返回值为当前业务设置的目标延迟，单位 ms；返回 `undefined` 表示未设置，使用浏览器默认自适应策略。

#### addPlayView

将远端视频渲染到指定 HTML 容器元素。

```typescript theme={null}
addPlayView(container: HTMLElement): void
```

#### hasPlayView

判断是否已有渲染容器。

```typescript theme={null}
hasPlayView(): boolean
```

#### removePlayView

移除指定渲染容器。

```typescript theme={null}
removePlayView(container: HTMLElement): void
```

#### removeAllPlayViews

移除所有渲染容器。

```typescript theme={null}
removeAllPlayViews(): void
```

#### enterPictureInPicture

让指定容器对应的远端视频进入画中画模式。

```typescript theme={null}
enterPictureInPicture(container: HTMLElement, options?: PipOptions): Promise<PipHandle>
```

#### exitPictureInPicture

退出指定容器的画中画模式。

```typescript theme={null}
exitPictureInPicture(container: HTMLElement): Promise<void>
```

#### isPictureInPicture

判断指定容器是否处于画中画模式。

```typescript theme={null}
isPictureInPicture(container: HTMLElement): boolean
```

#### popOutToWindow

将远端视频弹出到独立窗口。

```typescript theme={null}
popOutToWindow(container: HTMLElement, options?: PopOutOptions): PopOutHandle
```

#### closePopOutWindow

关闭指定容器对应的弹出窗口。

```typescript theme={null}
closePopOutWindow(container: HTMLElement): void
```

#### isPopOut

判断指定容器是否已经弹出到独立窗口。

```typescript theme={null}
isPopOut(container: HTMLElement): boolean
```