KTV歌词SDK接入文档

概述

KtvSDK-歌词是一个用于显示卡拉OK歌词的组件库，支持多种歌词格式（QRC、LRC）和显示模式，提供KTV双行模式和多行滚动模式两种显示方式。组件具备丰富的样式自定义功能，包括字体、颜色、描边、阴影等效果。

主要功能

1. 核心功能

多格式支持: 支持QRC（带时间戳的精确歌词）和LRC（标准歌词）格式

双显示模式: KTV双行模式（左右交替显示）和多行滚动模式（传统歌词显示）

实时同步: 与播放器时间精确同步，支持歌词高亮和进度显示

样式自定义: 支持字体、颜色、大小、描边、阴影等全方位样式定制

动画效果: 支持平滑滚动、高亮渐变等动画效果

性能优化: 采用高效的绘制机制，支持可配置的刷新频率

2. 辅助功能

歌词监听: 提供歌词文本更新和倒计时回调

生命周期管理: 自动处理暂停、恢复、重置等状态

内存管理: 防止内存泄漏，支持资源自动释放

错误处理: 完善的异常处理和边界检查

使用示例

如果SongInfoObject.isMvHasLyric()不为true(即MV没有自带歌词)，则可显示歌词View。

1. 基础集成示例

以下是一个完整的歌词组件集成示例，展示了从布局定义到功能实现的完整流程：在onPlayStart后初始化Lyric：

2. 布局文件示例

播放页的布局中添加LyricView，样式可以通过布局中的参数控制

<com.tme.ktv.lyric.widget.LyricView
    android:id="@+id/lyric_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_gravity="center_horizontal|bottom"
    android:background="@android:color/transparent"
    android:paddingLeft="20dp"
    android:paddingRight="20dp"
    app:layoutMode="ktv"
    app:lineNumber="2"
    app:lightTextColor="#F04F43"
    app:lightUnselectTextColor="@android:color/white"
    app:lightUnselectTextStrokeWidth="5"
    app:lightUnselectTextStrokeColor="@android:color/black"
    app:textStrokeWidth="5"
    app:textStrokeColor="@android:color/black"
    app:strokeW="5"
    app:strokeColor="@android:color/white"
    app:lightTextSize="50dp"
    app:lineMargin="5dp"
    app:shadowColor="#5F000000"
    app:shadowEnable="true"
    app:textColor="@android:color/white"
    app:textSize="50dp"
    app:lightTextFont="@font/fangzheng_font"
    app:lightUnselectTextFont="@font/fangzheng_font"
    app:textFont="@font/fangzheng_font" />

更多布局请见 LyricParam - 歌词样式参数

API接入说明

1. LyricInitializer - 歌词初始化器

功能: 歌词组件的初始化配置类，采用建造者模式，用于配置歌词的各项参数。

1.1 主要方法

setLyricView(LyricView lyricView)

功能: 设置歌词显示视图

参数:

lyricView: LyricView实例，用于显示歌词的视图组件

返回值: LyricInitializer实例，支持链式调用

注意: 如果传入null，会自动清空时间轴

setLyricData(byte[] qrcBytes, byte[] lrcBytes)

功能: 设置歌词数据

参数:

qrcBytes: QRC格式歌词数据的字节数组，可为null

lrcBytes: LRC格式歌词数据的字节数组，可为null

返回值: LyricInitializer实例

注意: QRC和LRC至少需要提供一种格式

setLyricTimeLine(LyricTimeLine timeLine)

功能: 设置时间轴回调接口

参数:

timeLine: LyricTimeLine接口实现，用于获取当前播放时间

返回值: LyricInitializer实例

注意: 该接口会被频繁调用，需要保证性能

setIsShowLyric(Boolean isShowLyric)

功能: 设置是否显示歌词

参数:

isShowLyric: 布尔值，true表示显示歌词，false表示隐藏

返回值: LyricInitializer实例

注意: 通常根据歌曲是否有MV来决定是否显示歌词

build()

功能: 完成初始化配置，触发实际的歌词初始化逻辑

返回值: LyricInitializer实例

注意: 必须最后调用，会触发歌词解析等耗时操作

1.2 使用流程

创建LyricInitializer实例

按顺序调用配置方法

最后调用build()方法完成初始化

在播放页退出时调用setLyricView(null)释放资源

1.3 注意事项

必须在播放开始后（onPlayStart回调后）进行初始化

build()方法会触发歌词解析，建议在后台线程执行

LyricInitializer是单例模式，需要主动释放lyricView避免内存泄漏

2 LyricTimeLine - 时间轴接口

功能: 提供当前播放时间的回调接口，是歌词与播放器时间同步的桥梁。

2.1 接口方法

int getLyricTime()

功能: 获取当前歌词时间

返回值: 当前播放时间，单位为毫秒

注意: 该方法会被频繁调用，实现时需要保证性能

2.2 实现示例

2.3 注意事项

返回值应该是准确的播放时间

该接口会被高频调用，避免在实现中进行复杂计算

使用@Keep注解防止混淆

3 LyricController - 歌词控制器

功能: 歌词系统的核心控制器，采用单例模式，继承自KaraokePlayerListener，负责统一管理歌词的显示、控制和生命周期。

3.1 主要属性

mQrcBytes: QRC格式歌词数据

mLrcBytes: LRC格式歌词数据

mLyricView: 歌词显示视图

mLyricTimeLine: 时间轴接口

mIsShowLyric: 是否显示歌词标志

lyricParam: 歌词样式参数

3.2 核心方法

getInstance()

功能: 获取单例

返回值: LyricController实例

注意: 使用双重检查锁定保证线程安全

initLyric()

功能: 初始化歌词，设置数据和时间轴

注意: 内部方法，通过LyricInitializer.build()调用

setIsShowLyric(Boolean isShow)

功能: 控制歌词显示/隐藏

参数:

isShow: 是否显示歌词

注意: 会同时控制视图的可见性

addLyricListener(LyricListener lyricListener)

功能: 添加歌词监听器

参数:

lyricListener: 歌词监听器实现

3.3 数据获取方法

getTimeArray()

功能: 获取歌词时间数组

返回值: int[]，歌词各句的时间戳数组

用途: 用于打分系统

sentenceCount()

功能: 获取歌词句数

返回值: int，歌词总句数

用途: 用于打分系统

getLastSentenceEndTime()

功能: 获取最后一句歌词结束时间

返回值: long，最后一句歌词的结束时间戳

用途: 用于打分系统

getFirstLyricStartTime()

功能: 获取第一句歌词开始时间

返回值: long，第一句歌词的开始时间戳

用途: 用于倒计时功能

3.4 播放器回调方法

组件会自动响应播放器状态变化：

onPlayStart(): 播放开始时的处理

onResume(): 恢复播放时恢复歌词显示

onPause(): 暂停播放时暂停歌词显示

4 LyricView - 歌词显示视图

功能: 歌词显示的主要视图组件，继承自FrameLayout，负责歌词的渲染和用户交互。

4.1 主要属性

mLyricUpdateTime: 歌词刷新间隔时间（16-200ms）

mLayoutMode: 布局模式（KTV模式或多行模式）

param: 歌词样式参数

4.2 核心方法

setLyricUpdateTime(int updateTime)

功能: 设置歌词刷新间隔

参数:

updateTime: 刷新间隔，单位毫秒，范围16-200

注意: 建议设置为64ms，过小会影响性能

setLyricTextAndTimeLine(byte[] qrcBytes, byte[] lrcBytes, LyricTimeLine timeLine)

功能: 设置歌词数据和时间轴

参数:

qrcBytes: QRC歌词数据

lrcBytes: LRC歌词数据

timeLine: 时间轴接口

返回值: LyricView实例

注意: 内部方法，通过LyricInitializer调用

switchMode(int mode)

功能: 切换显示模式

参数:

mode: 显示模式，LyricParam.LAYOUT_MODE_KTV或LyricParam.LAYOUT_MODE_LINES

注意: 切换模式会重置歌词状态

reset()

功能: 重置歌词状态

返回值: LyricView实例

注意: 清空当前歌词数据和显示状态

setLyricViewListener(LyricListener listener)

功能: 设置歌词监听器

参数:

listener: 歌词监听器实现

4.3 监听器接口

LyricListener

OnLyricTextUpdate(String text): 歌词文本更新回调

OnLyricCountDown(int countDown): 歌词倒计时回调

4.4 生命周期管理

组件会自动处理以下生命周期：

onAttachedToWindow(): 视图附加时启动刷新

onDetachedFromWindow(): 视图分离时停止刷新

5 LyricParam - 歌词样式参数

功能: 管理歌词的所有样式参数，支持Builder模式构建和XML属性配置。

5.1 主要参数分类

文本样式参数:

textSize: 普通文本大小

textColor: 普通文本颜色

textFont: 普通文本字体

lightTextSize: 高亮文本大小

lightTextColor: 高亮文本颜色

lightTextFont: 高亮文本字体

lightUnSelectTextSize: 未选中高亮文本大小

lightUnselectTextColor: 未选中高亮文本颜色

描边样式参数:

mStrokeColor: 高亮文本描边颜色

mStrokeWidth: 高亮文本描边宽度

textStrokeColor: 普通文本描边颜色

textStrokeWidth: 普通文本描边宽度

lightUnselectTextStrokeColor: 未选中文本描边颜色

lightUnselectTextStrokeWidth: 未选中文本描边宽度

布局参数:

lineMargin: 行间距

lineNumber: 显示行数

retainNumber: 保留行数

layoutMode: 布局模式

LAYOUT_MODE_KTV = 1: KTV双行模式

LAYOUT_MODE_LINES = 2: 多行滚动模式

阴影效果参数:

isShadow: 是否启用阴影

shadowRadius: 阴影半径

shadowDx: 阴影X轴偏移

shadowDy: 阴影Y轴偏移

shadowColor: 阴影颜色

其他参数:

lyricBackgroundColor: 歌词背景颜色

updateTime: 刷新间隔时间

5.2 改变歌词组件的样式

如果需要改变歌词组件的样式，通过设置歌词View参数改变歌词样式，需要在onPlayStart回调后设置
注意：这里动态设置的参数和xml中设置的参数不是复用的，把需要的参数都主动设置一下
例子：

            val builder = LyricParam.Builder()
                    .setIsShadow(true)
                    .setLayoutMode(LAYOUT_MODE_LINES)
                    .setLineNumber(3)
                    .setUpdateTime(60)
                    .setLightClipOffsetX(0)
                    .setLightTextColor(resources.getColor(R.color.colorForgiven))
                    .setTextColor(resources.getColor(R.color.red_orange))
                    .setTextSize(200)
                    .setLightUnselectTextStrokeWidth(30)
                    .setLightTextSize(150)
                    .setLineMargin(30)
                    .setStrokeWidth(30)
                    .setLyricBackgroundColor(resources.getColor(R.color.colorGray))
                    .setLightUnselectTextColor(resources.getColor(R.color.colorLightBlack))
                    .build()
            LyricController.getInstance().lyricParam = builder

5.3 XML属性配置

支持在布局文件中直接配置样式属性，详见布局文件示例。

歌词组件自定义配置

属性名	说明
lineMargin	行间距
lineRate	行间距比率表示行间距与字体大小的比例
retainNumber	line模式控制保留的歌词行数
lineNumber	line模式歌词视图中要显示的歌词行数（如果是line模式此值需要设置，否则就用默认值了）
textSize	普通歌词文字的大小
textColor	普通歌词文字的颜色。
textFont	普通歌词文字使用的字体文件
textStrokeWidth	普通歌词的描边宽度
textStrokeColor	普通歌词的描边颜色
lyricBackgroundColor	歌词组件背景颜色
lightTextSize	唱歌时歌词选中部分文字的大小
lightTextColor	唱歌时歌词选中部分文字的颜色
lightTextFont	唱歌时歌词选中部分文字使用的字体文件
lightTextColorUnSelect	已过期
lightUnselectTextColor	唱歌时歌词已经被选中但是未被唱过部分的文字颜色
lightUnselectTextFont	唱歌时歌词已经被选中但是未被唱过部分文字使用的字体文件
lightUnselectTextStrokeWidth	唱歌时歌词已经被选中但是未被唱过文字的描边宽度
lightUnselectTextStrokeColor	唱歌时歌词已经被选中但是未被唱过部分文字描边的颜色。
shadowEnable	是否开启歌词文字的阴影效果
shadowRadius	歌词文字阴影的模糊半径
shadowDx	歌词文字阴影在 X 轴方向的偏移量
shadowDy	歌词文字阴影在 Y 轴方向的偏移量
shadowColor	歌词文字阴影的颜色
strokeColor	唱歌选中歌词时的歌词描边颜色
strokeW	唱歌选中歌词时的歌词描边宽度
flushTime	控制歌词刷新的时间间隔
layoutMode	设置歌词视图的布局模式（必须设置）
ktv	为layoutMode中的ktv模式,即左右两行歌词
line	为layoutMode中的line模式，即竖形滚动歌词

2）. 如果需要改变歌词组件的样式
通过设置歌词View参数改变歌词样式，需要在onPlayStart回调后设置
注意：这里动态设置的参数和xml中设置的参数不是复用的，把需要的参数都主动设置一下
例子：

            val builder = LyricParam.Builder()
                    .setIsShadow(true)
                    .setLayoutMode(LAYOUT_MODE_LINES)
                    .setLineNumber(3)
                    .setUpdateTime(60)
                    .setLightClipOffsetX(0)
                    .setLightTextColor(resources.getColor(R.color.colorForgiven))
                    .setTextColor(resources.getColor(R.color.red_orange))
                    .setTextSize(200)
                    .setLightUnselectTextStrokeWidth(30)
                    .setLightTextSize(150)
                    .setLineMargin(30)
                    .setStrokeWidth(30)
                    .setLyricBackgroundColor(resources.getColor(R.color.colorGray))
                    .setLightUnselectTextColor(resources.getColor(R.color.colorLightBlack))
                    .build()
            LyricController.getInstance().lyricParam = builder

5.4 自定义配置

step1:在播放页的布局中添加LyricView，样式可以通过布局中的参数控制

step2:在onPlayStart后初始化Lyric：

歌词默认刷新频率为64ms, 如果觉得流畅度不够，可改为16ms(cpu占用会升高):

com.tme.ktv.lyric.widget.LyricView#setLyricUpdateTime(64)

由于LyricInitializer是单例，在播放页退出时需要主动释放lyricView 避免内存泄漏

LyricInitializer().setLyricView(null)

组件关系和调用流程

1. 初始化流程

LyricInitializer  →  LyricController  →  LyricView  →  LyricLayout  →  LyricLineUi

LyricInitializer 配置参数

LyricController 管理全局状态

LyricView 创建对应的Layout

LyricLayout 解析歌词数据，创建LineUi

LyricLineUi 负责具体的绘制

2. 刷新流程

LyricTimeLine.getLyricTime() → LyricLayout.onUpdateTime() → LyricLineUi.draw()

LyricTimeLine提供当前时间

LyricLayout根据时间更新位置

LyricLineUi根据位置绘制内容

3. 样式配置流程

LyricParam → TextPaint → LyricLineUi.draw()

LyricParam管理所有样式参数

创建对应的TextPaint对象

LyricLineUi使用Paint绘制文本

注意事项

1. 性能优化

歌词刷新间隔建议设置为64ms（16*4）

避免在主线程进行歌词解析

2. 内存管理

LyricInitializer是单例模式，必须在播放页退出时调用LyricInitializer.setLyricView(null)释放资源

及时调用reset()清理资源，如LyricView.reset(); LyricLayout.reset()

3. 线程安全

歌词数据解析建议在后台线程进行

UI更新必须在主线程执行

KtvSDK-歌词

KTV歌词SDK接入文档#

概述#

主要功能#

1. 核心功能#

2. 辅助功能#

使用示例#

1. 基础集成示例#

2. 布局文件示例#

API接入说明#

1. LyricInitializer - 歌词初始化器#

1.1 主要方法#

1.2 使用流程#

1.3 注意事项#

2 LyricTimeLine - 时间轴接口#

2.1 接口方法#

2.2 实现示例#

2.3 注意事项#

3 LyricController - 歌词控制器#

3.1 主要属性#

3.2 核心方法#

3.3 数据获取方法#

3.4 播放器回调方法#

4 LyricView - 歌词显示视图#

4.1 主要属性#

4.2 核心方法#

4.3 监听器接口#

4.4 生命周期管理#

5 LyricParam - 歌词样式参数#

5.1 主要参数分类#

5.2 改变歌词组件的样式#

5.3 XML属性配置#

5.4 自定义配置#

组件关系和调用流程#

1. 初始化流程#

2. 刷新流程#

3. 样式配置流程#

注意事项#

1. 性能优化#

2. 内存管理#

3. 线程安全#

KTV歌词SDK接入文档

概述

主要功能

1. 核心功能

2. 辅助功能

使用示例

1. 基础集成示例

2. 布局文件示例

API接入说明

1. LyricInitializer - 歌词初始化器

1.1 主要方法

1.2 使用流程

1.3 注意事项

2 LyricTimeLine - 时间轴接口

2.1 接口方法

2.2 实现示例

2.3 注意事项

3 LyricController - 歌词控制器

3.1 主要属性

3.2 核心方法

3.3 数据获取方法

3.4 播放器回调方法

4 LyricView - 歌词显示视图

4.1 主要属性

4.2 核心方法

4.3 监听器接口

4.4 生命周期管理

5 LyricParam - 歌词样式参数

5.1 主要参数分类

5.2 改变歌词组件的样式

5.3 XML属性配置

5.4 自定义配置

组件关系和调用流程

1. 初始化流程

2. 刷新流程

3. 样式配置流程

注意事项

1. 性能优化

2. 内存管理

3. 线程安全