KTV SDK 播放功能接入文档

1. 文件结构概述

KTV SDK 提供完整的本地/在线歌曲播放能力，支持 K 歌模式、听歌模式、UGC 作品播放等多种场景。核心播放器接口为 KaraokePlayer，配合资源预加载、播放回调、播放参数配置等机制，快速实现自定义的 K 歌播放界面。

主要功能：

歌曲音视频播放（原唱/伴奏切换、升降调、音量调节等）

歌曲资源预加载（避免卡顿，提升起播速度）

播放进度、状态、错误等回调

歌词、打分、MV兜底等扩展能力

核心组件

1.1 核心播放器接口

KaraokePlayer - 播放器核心接口

KaraokePlayerListener - 播放器回调监听器

KaraokePlayRequest - 播放请求对象

1.2 播放管理器

PlayerManager - 播放管理器，提供预加载和播放列表管理

PlayPreLoader - 预加载接口及其实现

1.3 登录相关

KtvLoginService - 登录服务

LoginEvent - 登录事件
详见文档 ktvSDK-登录

示例实现

PlayerDemoActivity - 播放器演示Activity

KtvPlayFragment - 播放Fragment实现

2. 详细说明

2.1 示例实现

2.1.1 播放资源预加载与调用播放

功能说明：
播放页面实现示例，包含完整的播放流程和错误处理。

关键特性：
在播放前应当先完成预加载

播放参数配置：

错误处理：
接收onPlayError回调

2.1.2 PlayLyric歌词初始化

功能说明：
歌词显示和控制的场景实现。
一般在onPlayPrepare之后或者onPlayStart回调中进行初始化
歌词初始化：

更多内容见 KtvSDK-歌词Lyric接入说明

2.2 KaraokePlayer 接口 (核心播放器)

功能说明：
KaraokePlayer是SDK的核心播放器接口，提供完整的音视频播放功能。

主要方法：

2.2.1 播放控制方法

注意事项：

stop()方法会释放所有播放资源

播放下一首时需要先调用stop()再调用play()

K歌模式下seek只能向后跳转，纯MV播放可以快进快退

2.2.2 播放状态获取

播放状态值：

STATE_IDLE: 0 - 空闲状态

STATE_START: 1 - 开始状态

STATE_PLAYING: 2 - 播放中

STATE_PAUSE: 3 - 暂停状态

STATE_ENDED: 4 - 播放结束

2.2.3 播放参数设置

默认播放类型：

DataSourceType.ORIGINAL - 原唱

DataSourceType.ACCOMPANY - 伴奏

2.2.4 监听器管理

OnScoreListener 细节见 KtvSDK-打分

2.2.5 歌词和打分相关

2.3 KaraokePlayerListener 播放回调监听器

功能说明：
播放器的核心回调接口，用于监听播放过程中的各种事件。

回调方法及调用顺序：

2.3.1 标准播放流程回调顺序

1. onPrePlay - 调用play()方法后立即回调
2. onPrepareResourceBufferingChange - 资源缓冲进度
3. onPlayPrepare - 播放资源准备完成
4. onVideoSizeChanged - 视频尺寸变化
5. onPlayStart - 播放开始
6. onLyricResourceChanged - 歌词资源更新完成（初始化歌词后会异步调用，也可能在onPlayStart前）
7. onPlayPositionChange - 播放进度更新（持续回调）
8. onVideoBufferPercentChange 视频缓冲进度
9. onBufferingStart/onBufferingEnd - 缓冲开始/结束
10. onPlayEnd - 播放结束

2.3.2 详细回调方法说明

播放生命周期回调：

播放控制回调：

进度和缓冲回调：

特殊功能回调：

重要注意事项：

onShowPicture回调非常重要，当视频播放失败时必须实现此回调显示封面图，否则会出现黑屏

onAllResourceDownloadFinished回调后才能进行下一首歌曲的预加载，否则会导致当前歌曲下载被取消

onPlayPositionChange会持续回调，用于更新播放进度UI

2.4 PlayerManager 播放管理器

功能说明：
PlayerManager是播放功能的核心管理器，提供预加载、播放列表管理等功能。

2.4.1 预加载功能

预加载事件类型：

2.4.2 权限管理（默认不调用）

使用示例：

2.5 KtvLoginService 登录服务

详情见 KtvSDK-登录接入说明

3. 组件关系和调用流程

3.1 整体架构关系

登录后
    ↓
PlayerManager.preload (播放管理器)
    ↓
PlayPreLoader (预加载器) → KaraokePlayer (播放器)
                                     ↓
                  KaraokePlayerListener (播放回调)

3.2 标准播放流程

3.2.1 初始化阶段

创建播放器

设置监听器

3.2.2 播放阶段

构建歌曲信息

预加载歌曲

开始播放

3.3 歌曲信息：SongInfoObject

    public String getMid();          // 歌曲mid 
    public String getOriUrl();       // 歌曲原唱URL
    public String getAccUrl();       // 歌曲消音伴奏URL
    public boolean hasAccUrl();      //是否有伴奏
    public boolean hasOriUrl();      //是否有原唱

    public byte[] mNodeBytes;        // 打分 Note 数据
    public byte[] mQycBytes;         // 加密 QRC 歌词
    public byte[] mLrcBytes;         // 加密 LRC 歌词

    public int isMvHasLyric();       // MV是否带歌词,0表示无歌词，1表示有歌词
    
    pulic getAlbumImage();           //获取歌曲专辑封面图片URL地址
    pulic getMvCoverImage();           //获取MV封面图片
    public getSingerLandscapeBigPicUrls(); //歌手横屏大图
    public getSingerVerticalBigPicUrls();   //歌手竖屏大图

    ....

3.3.1 播放类型SongType

3.4 播放参数

起播参数：SongInfoObject.Builder

播放时禁止MV：setEnableMV(false)

播放公播歌曲（仅点歌机厂商适用）：setQueryPublicSong(true)

setOnlinePlayBackupMVFilePath()
设置在线播放时的兜底MV地址，MV文件找产品提供。

KtvSdk视频播放策略
1.
调用KaraokePlayer.play()后，MV开始播放。若歌曲原MV播放失败，则播放兜底视频。
2.
播放兜底视频 -> 检测在线播放还是离线播放 -> 优先用本地的K歌MV，否则用在线配置的兜底MV。
3.
兜底视频播放失败后，粒子动画启用？则进行粒子动画播放。
4.
粒子动画不启用？回调onShowPicture

默认值：空。播放兜底MV时，如果有设置此地址，则播放此地址的内容，否则播放默认线上配置的兜底MV。
注意：只能播放K歌提供的兜底MV！

setOfflinePlayBackupMVFilePath()
设置离线播放时的兜底MV地址，MV文件找产品提供。
默认值：空。播放兜底MV时，如果有设置此地址，则播放此地址的内容，否则播放默认线上配置的兜底MV。
注意：只能播放K歌提供的兜底MV！

全局播放参数：KtvPlayerConfig

大多数开关都需要在commit()方法之前设置，只能commit一次。

切换播放器类型

exo和mediaplayer都支持，不过我们默认用exo，因为exo的定制性强我们做了很多适配，只有exo播不了的场景才建设手动切mediaplayer。
sdk支持三种播放器选择方式：

DecodeTypeAuto: 自动判断（推荐）

DecodeTypeMediaPlayer：使用MediaPlayer播放

DecodeTypeExoPlayer：使用ExoPlayer播放
推荐使用DecodeTypeAuto，会用上我们积累的一些机型兼容策略。如果兼容有问题，可反馈给K歌，再不行可尝试使用mediaplayer.

打分开关

ksong.support.player.KtvPlayerConfig#setEnableScore(false)   //关闭打分

开启人声加密
人声存储在私有目录，默认不加密，如果有严格的安全需求，可用此开启人声文件加密。
ksong.support.player.KtvPlayerConfig#setEncryptInputAudio()
可用AudioPlaybackPlayer.clearCache()方法清除本地录音播放时的临时文件。

禁止视频播放失败后的撒花动画效果
默认值：true
ksong.support.player.KtvPlayerConfig#setEnableFlowAnimationBackupPlayer(false)

开启缓存文件的md5校验
计算md5会增加起播耗时，除非有碰到缓存文件错误的问题，否则不要开启。
默认值：false。
setEnableCacheFileMd5Check()

设置接口超时时间

//接口连接超时, 默认30s
ksong.support.player.KtvPlayerConfig#setHttpConnectTimeoutMs()
//接口read超时，默认30s
ksong.support.player.KtvPlayerConfig#setHttpReadTimeoutMs()

处理与语音助手冲突：给AudioRecord设置独立的音源(audioSource)
如果要与语音助手同时使用，可以有两种处理方式：
方法一：给K歌sdk的AudioRecord设置独立的音源(audioSource)，语音助手用另外的audioSource。
设置方法ksong.support.player.KtvPlayerConfig#setAudioRecordSource
方法二：自定义声音输入通道，给sdk传递声音。此方法厂商实现复杂，一般不推荐。

设置音频输出参数：streamType(默认AudioManager.STREAM_MUSIC）、AudioContentType、AudioAttributes等

    //Android版本>=Android5.0
    ksong.support.player.KtvPlayerConfig#setAudioAttributes()
    
    //Android版本<Android5.0时设置streamType
    ksong.support.player.KtvPlayerConfig#setStreamType()

设置AudioDeviceInfo

ksong.support.player.KtvPlayerConfig#setPreferredDevice((AudioDeviceInfo deviceInfo)

开启下载限速
可在调用PlayerManager.preload()前设置下载速度限速(KB/s)，默认不限速。注意：此方法仅针对离线下载(isOfflineDownload=true)场景生效。起播后，下载限速会自动取消。

ksong.support.player.KtvPlayerConfig#setDownloadSpeedLimit(500)  //限制离线下载速度为500 KB/s

LoopMode（播放列表建议自己做，不推荐设置）

默认播放类型：DataSourceType

视频填充模式：VideoScaleType

默认为FILL_FIT模式：

3.5 设置音频、视频清晰度

详见文档：切换音视频清晰度

3.6 播放回调KaraokePlayerListener

3.7 播放错误了怎么办？

如何查询错误原因
可以过滤sdk的日志来查询常见错误，过滤关键字 onPlayError或onExecuteFail
如果错误日志看不出问题，可咨询K歌开发确定原因。

视频为什么会黑屏，有没有优化方式？
常见原因是视频因设备不支持播放等原因播放失败时，厂商没有实现onShowPicture接口显示大图。
视频播放失败后，此回调会返回一个歌曲封面图url，厂商接收到此回调后，可在KtvVideoLayout上覆盖一个图片控件显示大图兜底。
如果此时没有显示歌词组件，需要接入方主动显示歌词，避免没有MV不显示歌词的问题

4. 重要注意事项

4.1 播放器使用注意事项

资源管理

播放下一首前必须调用stop()释放当前资源

页面销毁时必须调用stop()避免内存泄漏

不要对KtvVideoLayout进行多次addView/removeView操作

回调处理

必须实现onShowPicture回调显示封面图，避免视频播放失败时黑屏

onAllResourceDownloadFinished回调后才能进行下一首预加载

onPlayPositionChange用于更新播放进度UI

权限管理

K歌模式需要录音权限 songType == SongType.SONG_TYPE_K_SONG

听歌模式不需要录音权限 songType == SongType.SONG_TYPE_KSONG_LISTEN

4.2 预加载注意事项

预加载时机

同一时间只能预加载一首歌曲

新的预加载会取消之前的预加载

收到onAllResourceDownloadFinished后才能预加载下一首

不要在UI线程阻塞等待预加载完成，一切通过回调异步处理。

预加载优先级

使用preloadNow()可以设置高优先级

高优先级预加载会取消其他预加载任务

4.3 错误处理

播放错误

监听onPlayError回调

根据错误类型进行相应处理

网络错误

预加载失败时提供重试机制

弱网环境下适当降低清晰度

4.4 性能优化

内存管理

及时释放播放器资源

避免内存泄漏

网络优化

合理使用预加载功能

根据网络状况调整清晰

KtvSDK-播放

KTV SDK 播放功能接入文档#

1. 文件结构概述#

主要功能：#

核心组件#

1.1 核心播放器接口#

1.2 播放管理器#

1.3 登录相关#

示例实现#

2. 详细说明#

2.1 示例实现#

2.1.1 播放资源预加载与调用播放#

2.1.2 PlayLyric歌词初始化#

2.2 KaraokePlayer 接口 (核心播放器)#

2.2.1 播放控制方法#

2.2.2 播放状态获取#

2.2.3 播放参数设置#

2.2.4 监听器管理#

2.2.5 歌词和打分相关#

2.3 KaraokePlayerListener 播放回调监听器#

2.3.1 标准播放流程回调顺序#

2.3.2 详细回调方法说明#

2.4 PlayerManager 播放管理器#

2.4.1 预加载功能#

2.4.2 权限管理（默认不调用）#

2.5 KtvLoginService 登录服务#

3. 组件关系和调用流程#

3.1 整体架构关系#

3.2 标准播放流程#

3.2.1 初始化阶段#

3.2.2 播放阶段#

3.3 歌曲信息：SongInfoObject#

3.3.1 播放类型SongType#

3.4 播放参数#

起播参数：SongInfoObject.Builder#

全局播放参数：KtvPlayerConfig#

LoopMode（播放列表建议自己做，不推荐设置）#

默认播放类型：DataSourceType#

视频填充模式：VideoScaleType#

3.5 设置音频、视频清晰度#

3.6 播放回调KaraokePlayerListener#

3.7 播放错误了怎么办？#

4. 重要注意事项#

4.1 播放器使用注意事项#

4.2 预加载注意事项#

4.3 错误处理#

4.4 性能优化#