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

# 腾讯云播放器

> 通过 so.kontext:video-txplayer 把腾讯云播放器 SDK 的播放器（TXVodPlayer）交给 SDK。

SDK 会跟随你的内容播放器：观众在剧集中的位置，以及内容是否在播放。叠加广告只在内容播放时展示，观众暂停时结束；暂停广告在内容再次播放时结束。使用腾讯云播放器 SDK（`TXVodPlayer`，LiteAV）时，一次调用加上播放监听中的一行代码，就能把这些都交给 SDK。

## 添加适配器

```kotlin theme={null}
dependencies {
    implementation("so.kontext:video:0.1.0")
    implementation("so.kontext:video-txplayer:0.1.0")
}
```

* **播放器 SDK 11.0 或更高版本**（`TXVodPlayer`，包含它的任何 LiteAV 版本）。
* **不包含播放器 SDK。** 适配器使用你应用自己的播放器 SDK 和你的授权；它不会向你的构建添加任何 LiteAV 构件。
* **R8：** 适配器不需要你添加任何规则。请保留播放器 SDK 集成指南中它自己的规则（`-keep class com.tencent.** { *; }`）：没有它，经过混淆的应用会在创建播放器时中止。

## 跟随播放器

```kotlin theme={null}
import so.kontext.video.txplayer.track

ads.track(player, currentItem = { episode.id })
```

在播放器拿到该集的播放源（`startVodPlay`）之后、剧集开始时调用。SDK 弱持有播放器，并在 `ads.destroy()` 或下一次 `track` 时放开。

`currentItem` 可选：这个播放器上你的剧集（它的 id），用于一个播放器先后播放多集的情况。不提供时，播放器本身就是这一集。无论哪种方式，视频播放到结尾或循环的下一轮都算作另一次播放。

## 转交播放事件

`TXVodPlayer` 只有一个监听器，即你的（`setVodListener`），SDK 不会占用它。在你的 `onPlayEvent` 中把每个播放事件原样转交：

```kotlin theme={null}
import so.kontext.video.txplayer.KontextTXVodPlayer

player.setVodListener(object : ITXVodPlayListener {
    override fun onPlayEvent(player: TXVodPlayer, event: Int, param: Bundle?) {
        KontextTXVodPlayer.onPlayEvent(player, event)
        // … 你自己的处理
    }

    override fun onNetStatus(player: TXVodPlayer, status: Bundle?) {}
})
```

有了这些事件，SDK 会立即得知视频结束、循环的下一轮和拖动进度。没有它们时，SDK 仍会跟随播放器，读取其位置和 `isPlaying()`，并根据位置推断拖动。没有被任何 `VideoAds` 跟随的播放器的事件会被忽略，因此请转交每个播放器的每个事件。

## 在信息流中

短剧信息流通常为每一页提供自己的 `TXVodPlayer`。为每一页创建自己的 `VideoAds`，并在该页的播放器拿到播放源后跟随它：

```kotlin theme={null}
override fun onPageSelected(page: Int) {
    val item = pages[page]
    item.ads.track(item.player, currentItem = { item.episodeId })
}
```

只在当前页展示叠加广告或暂停广告。广告在屏幕上时被滑走的页面，其广告会在大约一秒内结束（`INTERRUPTED`），以便下一页的广告可以展示。预先准备并暂停的相邻页面不算播放，因此不会在其上展示叠加广告。

## 暂停与缓冲

播放器 SDK 不会为暂停发送事件。叠加广告或暂停广告在屏幕上时，SDK 每秒读取四次 `isPlaying()`，并在每次 `show` 时读取，因此叠加广告会在 `pause()` 后四分之一秒内结束。播放器卡顿加载时 `isPlaying()` 仍为 true，因此缓冲算作播放，叠加广告会保留。

## 播放速度

播放器 SDK 没有读取速度的方法。观众改变速度时（`setRate`）告诉 SDK，这样叠加广告的时长才能正确按视频秒数计算：

```kotlin theme={null}
ads.track(player, playbackSpeed = { currentRate })     // SDK 需要时读取
```

不提供时，SDK 接受最高约 4× 的播放速度，更大的跳变视为拖动进度。

## SDK 读取什么

| SDK 需要 | 从播放器 SDK 读取 |
| - | - |
| 内容的位置 | `getCurrentPlaybackTime()`，单位为秒 |
| 是否在播放 | `isPlaying()`。暂停、结束或停止不算播放；缓冲算作播放。 |
| 另一集 | 你的闭包返回另一个 `currentItem`，或视频播放结束（`PLAY_EVT_PLAY_END`）或循环的下一轮（`VOD_PLAY_EVT_LOOP_ONCE_COMPLETE`）：重新播放算作另一次播放 |
| 拖动进度 | `VOD_PLAY_EVT_SEEK_COMPLETE`，没有事件时根据位置推断 |

此后，一旦播放器播放另一集或重新播放这一集，该 `VideoAds` 的叠加广告或暂停广告会在 `show` 时抛出 `Invalidated(ContentChanged)`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.