KtvSdk 4.0 版本更新与接入指南

1. 版本概述

KtvSdk 4.0 在 3.0 的基础上进行了架构升级，融合了 UiSdk。

支持灵活打包：可选择 不带 UI 界面 的纯 SDK 包或 带 UI 界面 的 SDK 包（目前仅针对特定厂商提供， SDK 接入方仍建议使用不带 UI 的 SDK 包）。

新增多项核心业务能力。

2. 新增功能

2.1 PK / 合唱

支持 PK 与合唱功能。

📄 接入文档：点击查看详情

2.2 动效歌词

新增高阶动效歌词展示能力。

📄 接入文档：点击查看详情

2.3 定制录制时长

SDK 4.0 取消了必须唱完一整首才能获取打分的限制，支持在演唱满足条件时获取打分结果及录音文件信息。

📄 接入文档：点击查看详情

2.4 公播歌单段落起播

支持公播歌单直接从副歌（高潮）段落开始播放。

使用方式：

接入方需在构建播放请求时主动设置起播参数：

2.5 智能降码流

智能降码流用于优化在线歌曲在弱网环境下的起播和播放体验。功能默认关闭，降级只影响当前歌曲；降级实际生效后，SDK 会通过 onAutoBitrateChanged 通知接入方。

📄 接入文档：智能降码流接入指南

2.6 臻品 / DTS 音质（4.1.09 新增）

SDK 新增臻品和 DTS 伴奏音质，沿用现有音质配置、资源预加载和播放流程。

音质	SDK 常量	音质值
普通	`SongInfoModel.AUDIO_QUALITY_NORMAL`	`1`
HQ	`SongInfoModel.AUDIO_QUALITY_HQ`	`3`
臻品	`SongInfoModel.AUDIO_QUALITY_PREMIUM`	`19`
DTS	`SongInfoModel.AUDIO_QUALITY_DTS`	`20`

当前臻品和 DTS 音质仅作用于伴奏资源。处于原唱或智能伴唱状态时，可保留接入方维护的音质选择状态，但需要切换到伴奏后才能体验对应音质。

2.6.1 判断歌曲支持的音质

调用 preloadForPlay() 成功后，SDK 会将后台最新返回的音质列表写入回调中的 SongInfoObject，接入方可通过 getSupportAudioQualities() 获取：

返回值示例为 [1, 3, 19, 20]；列表为空表示本次未获得可展示的音质能力。接入方如果提供音质切换入口，应只展示列表中包含的音质。

如果接入方的搜索业务或者其他 openApi接口已经获得 support_audio_qualities，可以据此提前展示音质入口；播放资源准备完成后，应以 preloadForPlay() 成功回调返回的列表为准。

2.6.2 请求臻品或 DTS 音质

在调用 preloadForPlay() 前，通过现有配置接口设置目标音质：

播放中切换音质时，也沿用现有方案：更新 KtvPlayerConfig 的音质配置后，重新执行当前歌曲的 preloadForPlay() 和 play() 流程。SDK 不新增单独的显式音质切换 API。

2.6.3 不支持目标音质时的处理

请求臻品或 DTS 音质时，如果当前歌曲不支持该音质，后台会自动返回普通音质资源，不会返回错误。接入方应以 preloadForPlay() 成功回调中 event.songInfoObject.accQuality 的值作为本次实际播放音质。

该降级只作用于本次资源结果，不会永久修改接入方选择的音质配置。若接入方未主动修改配置，下次播放仍会按照当前配置请求臻品或 DTS 音质。

2.6.4 会员权益阻断

用户没有会员权益或可用体验次数时，后台返回错误码 50029。SDK 会将其映射为：

该场景沿用现有 HQ、1080P 等权益阻断的处理方式。接入方通过 AppRequestProvider 接收播放拦截请求，并按现有方式打开会员支付页面：

从支付页面返回播放页后，SDK 会重新校验权益：

用户已获得权益：继续按照所选臻品或 DTS 音质准备并播放。

用户仍无权益：preloadForPlay() 返回错误码 50029。接入方可提示原因，并选择降为普通音质重新播放或结束本次播放。

2.7 助唱歌词

使用 SDK 的 LyricView 或 LyricSurfaceView 时，按以下步骤接入助唱标记。

2.7.1 绑定歌词数据

每首歌资源就绪后，在原有初始化流程中，将 setLyricData() 改为三参数方法：

每次切歌重新绑定；没有助唱数据时，第三个参数传 null。原有两参数方法仍兼容。

2.7.2 控制助唱开关

SDK 初始化完成后，可在播放前或播放中调用：

开关默认关闭。播放中切换时，歌词组件自动刷新，无需重新绑定或重新播放。当前歌曲无有效助唱数据时临时显示普通歌词，下一首支持时按记忆设置恢复。

2.7.3 查询歌曲是否支持

使用 preloadForPlay() 成功返回的歌曲对象，或 onPlayPrepare / onPlayStart 回调中资源就绪的歌曲对象查询：

isSupportSingAssist() 表示已取得助唱数据；isSingAssistEnabled() 表示用户的开关设置。两者不等同，资源未就绪时不应据此判断歌曲是否支持。

使用注意：

时间轴、暂停/恢复和页面销毁解绑沿用原有方式，暂停/恢复适配见 3.1 节。

wrap_content 会随助唱内容调整高度；固定高度需预留标记显示空间。

3. 3.0 升级至 4.0 适配指南（接口变更说明）

3.1 歌词组件适配（LyricController）

变更说明：

在 SDK 3.0 中，LyricController 内部自动实现了 resume 和 pause 状态的监听。该逻辑在 4.0 中已被移除，以提高灵活性。

适配要求：

在 SDK 4.0 中，接入方需要在初始化歌词时主动监听播放器状态，控制歌词的滚动与暂停。

代码示例：

3.2 打分回调接口变更

打分相关回调发生变更，新增句子索引参数：

3.3 预加载接口调整

为区分“当前歌曲真实起播”和“后台预加载下一首歌曲”，SDK 4.0 新增以下接口：

3.3.1 当前歌曲播放

当前歌曲必须先调用 preloadForPlay()，成功后使用回调返回的 SongInfoObject 调用 play()：

注意事项：

preloadForPlay() 成功后，应在 3 秒内调用 play()。

必须使用成功回调中的 event.songInfoObject，不要继续使用原始歌曲对象。

超过 3 秒不会影响正常播放，但该次预加载不会再计入完整的真实起播技术上报。

重复调用 preloadForPlay() 时，前一次尚未播放的准备任务会被新的任务替代。

3.3.2 后台预加载下一首

如果接入方已经知道下一首歌曲，可以提前调用 preloadNext()：
但是必须在当前歌曲资源已经下载完毕后再预加载下一首（onAllResourceDownloadFinished回调）

当该歌曲真正需要播放时，仍需重新调用 preloadForPlay()：

preloadNext() 主要用于提前准备音频等可缓存资源，不产生真实起播技术上报，也不能替代播放前的 preloadForPlay()。真正播放时仍会执行必要的播放鉴权及 MV 播放准备流程。

3.3.3 旧接口兼容说明

原有的 preload() 接口仍然保留，但已标记为废弃：

旧接口调用方式	对应的新接口
`preload(song, result)`	`preloadForPlay(song, result)`
`preload(song, false, result)`	`preloadForPlay(song, result)`
`preload(song, true, result)`	`preloadNext(song, result)`

现有接入代码可以继续运行，但建议接入方逐步迁移到语义更加明确的 preloadForPlay() 和 preloadNext()。

KtvSdk4.0接入文档

KtvSdk 4.0 版本更新与接入指南#

1. 版本概述#

2. 新增功能#

2.1 PK / 合唱#

2.2 动效歌词#

2.3 定制录制时长#

2.4 公播歌单段落起播#

2.5 智能降码流#

2.6 臻品 / DTS 音质（4.1.09 新增）#

2.6.1 判断歌曲支持的音质#

2.6.2 请求臻品或 DTS 音质#

2.6.3 不支持目标音质时的处理#

2.6.4 会员权益阻断#

2.7 助唱歌词#

2.7.1 绑定歌词数据#

2.7.2 控制助唱开关#

2.7.3 查询歌曲是否支持#

3. 3.0 升级至 4.0 适配指南（接口变更说明）#

3.1 歌词组件适配（LyricController）#

3.2 打分回调接口变更#

3.3 预加载接口调整#

3.3.1 当前歌曲播放#

3.3.2 后台预加载下一首#

3.3.3 旧接口兼容说明#

KtvSdk 4.0 版本更新与接入指南

1. 版本概述

2. 新增功能

2.1 PK / 合唱

2.2 动效歌词

2.3 定制录制时长

2.4 公播歌单段落起播

2.5 智能降码流

2.6 臻品 / DTS 音质（4.1.09 新增）

2.6.1 判断歌曲支持的音质

2.6.2 请求臻品或 DTS 音质

2.6.3 不支持目标音质时的处理

2.6.4 会员权益阻断

2.7 助唱歌词

2.7.1 绑定歌词数据

2.7.2 控制助唱开关

2.7.3 查询歌曲是否支持

3. 3.0 升级至 4.0 适配指南（接口变更说明）

3.1 歌词组件适配（LyricController）

3.2 打分回调接口变更

3.3 预加载接口调整

3.3.1 当前歌曲播放

3.3.2 后台预加载下一首

3.3.3 旧接口兼容说明