# 歌词打分组件 Kotlin API (/zh-CN/api-reference/online-ktv/android/auikaraoke/api/lyrics-api)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
本文提供在线 K 歌房歌词评分组件相关 API。
:::warning[注意]
本文仅适用于歌词评分组件 v1.1.1。
:::
## KaraokeView [#karaokeview]
歌词评分组件的基础接口类，实现歌词同步、演唱评分的主要功能。
:::warning[注意]
请确保在主线程中调用该类下的 API。
:::
### KaraokeView [#karaokeview-1]
```java
public KaraokeView(LyricsView lyricsView, ScoringView scoringView);
```
创建 `KaraokeView` 实例。
**参数**
- `lyricsView`：用于显示歌词的 `LyricsView` 对象。
- `scoringView`：用于显示评分的 `ScoringView` 对象。
### parseLyricsData [#parselyricsdata]
```java
public static LyricsModel parseLyricsData(File file);
```
解析歌词文件数据。
**参数**
- `file`：要解析的歌词文件对象，支持 XML 文件或 LRC 文件。
**返回值**
- 方法调用成功时返回一个 `LyricModel` 对象，包含解析后的歌词数据模型。
- 方法调用失败时返回 `null`。
### setLyricsData [#setlyricsdata]
```java
public void setLyricsData(LyricsModel model);
```
设置歌词数据模型。
该方法用于设置歌词数据模型，在调用该方法前，你需要先调用 `parseLyricsData` 方法解析歌词数据并获取相应的歌词数据模型对象以便于歌词显示。
**参数**
- `model`：[`LyricsModel`](#LyricsModel) 对象，表示歌词数据模型，包含歌曲的基本信息、歌词信息等。如果传入 `null`，表示当前歌曲为纯音乐，没有对应的歌词信息。
### reset [#reset]
```java
public void reset();
```
重置歌词及评分设置。
当一首歌曲播放完毕，或在播放过程中切到另外一首歌曲时，需要调用该方法来重置歌词、评分设置。
**参数**
- `lyrics`：要添加的 `LyricsView` 对象，用于显示歌词。若传入 `null`，表示不添加歌词视图。
- `scoring`：要添加的 `ScoringView` 对象，用于显示评分。若传入 `null`，表示不添加评分视图。
### setProgress [#setprogress]
```java
public void setProgress(long progress);
```
把歌曲当前的播放进度同步给歌词、评分组件。
在实现歌词和歌曲播放同步时，你需要调用该方法来将歌曲当前的播放进度设置给 `KaraokeView`，以便 `KaraokeView` 根据当前歌曲的播放位置显示对相应的歌词。
调用该方法前你需要先通过内置媒体播放器的 [`getPlayPosition`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-info) 方法获取歌曲当前的播放进度。声网建议你每 20 ms 调用一次该方法来把歌曲的播放进度同步给歌词评分组件。
**参数**
- `progress`：歌曲的播放进度，单位为 ms。
### setPitch [#setpitch]
```java
public void setPitch(float pitch);
```
把获取的实时人声音调同步给评分组件。
当你通过 `IRtcEngineEventHandler` 下的 [`onAudioVolumeIndication`](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 获取本地用户的人声音调后，你需要调用该方法把获取到的实时人声音调同步给评分组件用于演唱评分。
**参数**
- `pitch`：用户的实时人声音调。
### setKaraokeEvent [#setkaraokeevent]
```java
public void setKaraokeEvent(KaraokeEvent event);
```
设置歌词评分组件事件回调。
在调用该方法前，请确保已初始化 `KaraokeView` 对象。
**参数**
- `event`：歌词评分组件事件，详见 [`KaraokeEvent`](#KaraokeEvent)。
### setScoreAlgorithm [#setscorealgorithm]
```java
public void setScoringAlgorithm(IScoringAlgorithm algorithm);
```
自定义评分算法。
如果你不想使用评分组件默认的评分算法，你可以通过该方法来自定义评分算法。你自定义的评分算法对象应实现 `IScoringAlgorithm` 接口。
**参数**
- `algorithm`：实现了 [`IScoringAlgorithm`](#IScoringAlgorithm) 接口的评分算法对象。
### setScoringLevel [#setscoringlevel]
```java
public void setScoringLevel(int level);
```
设置得分的难易等级。
你可以通过该方法来设置演唱者得分的难易等级。
**参数**
- `level`：难度等级，取值范围为 [0,100]，默认值为 15。值越小表示难度等级越低，演唱者越容易得分。
你可以参考下表来设置不同难度：
| 难度 | 推荐取值 |
| :------- | :------- |
| 低难度 | 3 |
| 中低难度 | 15 |
| 中等难度 | 17 |
| 中高难度 | 25 |
| 高难度 | 35 |
### getScoringLevel [#getscoringlevel]
```java
public int getScoringLevel();
```
获取得分的难易等级。
当你调用 `setScoringLevel` 设置得分的难易程度后，可以调用该方法来获取当前你设置的得分难易程度。
**返回值**
- ≥ 0：方法调用成功，返回当前设置的得难易值。
- < 0：方法调用失败。
### setScoringCompensationOffset [#setscoringcompensationoffset]
```java
public void setScoringCompensationOffset(int offset);
```
调整演唱评分结果。
如果你的业务场景对演唱分数有特殊要求，你可以调用此方法来调整演唱评分的结果。
**参数**
- `offset`：额外增加或减少的分数，取值范围为 [-100, 100]，默认值为 0。
声网不建议你同时使用 `setScoringLevel` 和 `setScoreCompensationOffset` 来调整评分机制。
### getScoringCompensationOffset [#getscoringcompensationoffset]
```java
public int getScoringCompensationOffset();
```
获取调整后的分数结果。
当你调用 `setScoringCompensationOffset` 方法调整演唱评分的结果后，你可以调用过该方法来获取调整后的分数结果。
**返回值**
- 调整后的分数结果。
## KaraokeEvent [#karaokeevent]
`KaraokeView` 的核心事件回调。
### onDragTo [#ondragto]
```java
public void onDragTo(KaraokeView view, long position);
```
歌词拖动结束的回调。
如果你设置允许歌词拖动（将 `enableDragging` 设为 `true`），当歌词拖动结束后会触发此回调。你可以通过该回调获取歌词拖动后对应的播放位置。
**参数**
- `view`：`KaraokeView` 实例。
- `position`：歌词拖动后对应的歌曲播放位置，单位为毫秒。
### onLineFinished [#onlinefinished]
```java
public void onLineFinished(KaraokeView view, LyricsLineModel line, int score, int cumulativeScore, int index, int total);
```
一行歌词播放完毕回调。
当一行歌词播放完毕后，会触发该回调报告当前行的歌词的得分、累计得分等信息。
**参数**
- `view`：`KaraokeView` 实例。
- `line`：当前歌词行的信息，详见 [`LyricsLineModel`](#LyricsLineModel)。
- `score`：当前歌曲行的得分，取值范围 [0, 100]。
- `cumulativeScore`：当前累计得分。
- `Index`：歌词行数的索引号，最小值为 0。
- `total`：歌词的总行数。
### onRefPitchUpdate [#onrefpitchupdate]
```java
public void onRefPitchUpdate(float refPitch, int numberOfRefPitches);
```
歌词标准音高值回调。
歌词中每一个字都有自己的音符（tone），代表一个单独的音高值。SDK 会在播放到歌词的每一个字时触发该回调，报告当前音符的音高值，以及整首歌歌词中音符的个数。
**参数**
- `refPitch`：当前音符的音高值。
- `numberOfRefPitches`：整首歌歌词中音符的个数。如果你想要自定义评分算法，可以通过该参数在 App 层计算一首歌演唱的平均分。
## ScoringView [#scoringview]
该类提供评分组件的核心 API。
### setRefPitchStickDefaultColor [#setrefpitchstickdefaultcolor]
```java
public void setRefPitchStickDefaultColor(int color);
```
设置标准音高线的颜色。
**参数**
- `color`：标准音高线的颜色。
### setRefPitchStickHighlightedColor [#setrefpitchstickhighlightedcolor]
```java
public void setRefPitchStickHighlightedColor(int color);
```
设置人声音调与标准音高线匹配后，音高线的颜色。
**参数**
- `color`：标准音高线的颜色。
### setRefPitchStickHeight [#setrefpitchstickheight]
```java
public void setRefPitchStickHeight(float height);
```
设置标准音高线的高度。
**参数**
- `height`：标准音高线的高度，默认值为 6 dp。
### enableParticleEffect [#enableparticleeffect]
```java
public void enableParticleEffect(boolean enable);
```
设置是否开启粒子动画效果。
粒子动画可以在歌词或背景等区域中播放，以呈现各种漂亮、流畅且动感的效果，与歌声的节奏和音调进行同步。
**参数**
- `enable`：
- `true`：（默认）开启粒子动画效果。
- `false`：关闭粒子动画效果。
:::info[信息]
该方法可能会消耗较多系统性能，声网建议不要频繁调用该方法。
:::
### setParticles [#setparticles]
```java
public void setParticles(Drawable[] particles);
```
自定义粒子动画样式。
如果你不想使用声网默认的粒子动画样式，你可以调用该方法来自定义粒子动画样式。在调用该方法前，请确保你已经开启粒子动画效果，即 `enableParticleEffect` 设为 `true`。
**参数**
- `particles`：自定义粒子动画样式的对象。
:::info[信息]
该方法可能会消耗较多系统性能，声网建议不要频繁调用该方法。
:::
### setLocalPitchIndicator [#setlocalpitchindicator]
```java
public void setLocalPitchIndicator(Bitmap bitmap);
```
设置本地音高指示器的样式。
该方法用于设置本地音高指示器的样式，以可视化地表示当前音高值，并显示实时的音高的变化，帮助演唱者对自己的声音进行调准和校正。
**参数**
- `bitmap`：音高指示器的位图图像。如果你不想显示音高指示器，传入 `null`。
### reset [#reset-1]
```java
public void reset();
```
重置评分组件。
当一首歌曲播放完毕后或是播放过程中切到另外一首歌曲时，需要调用该方法来重置评分设置。
## LyricsView [#lyricsview]
该类提供歌词组件的核心 API。
### enableDragging [#enabledragging]
```java
public void enableDragging(boolean enable);
```
设置是否允许歌词拖动。
**参数**
- `enable`：是否允许拖动歌词：
- `true`：允许拖动歌词。
- `false`：不允许拖动歌词。
### setInactiveLineTextColor [#setinactivelinetextcolor]
```java
public void setInactiveLineTextColor(@ColorInt int color) {}
```
设置未在当前播放的歌词的颜色。
**参数**
- `color`：未在当前播放的歌词的颜色。
### setTextSize [#settextsize]
```java
public void setTextSize(float size) {}
```
设置未在当前播放的歌词文字大小。
**参数**
- `size`：歌词文字大小，单位为 pixel。
### setActiveLinePlayedTextColor [#setactivelineplayedtextcolor]
```java
public void setActiveLinePlayedTextColor(@ColorInt int color) {}
```
设置当前歌词行中，已播放的歌词的颜色。
**参数**
- `color`：歌词的颜色。
### setActiveLineUpcomingTextColor [#setactivelineupcomingtextcolor]
```java
public void setActiveLineUpcomingTextColor(@ColorInt int color) {}
```
设置当前歌词行中，待播放的歌词的颜色。
**参数**
- `color`：歌词的颜色。
### setCurrentLineTextSize [#setcurrentlinetextsize]
```java
public void setCurrentLineTextSize(float size) {}
```
设置当前播放的歌词行的文字大小。
**参数**
- `size`：歌词文字大小，单位为 pixel。
### setLabelShownWhenNoLyrics [#setlabelshownwhennolyrics]
```java
public void setLabelShownWhenNoLyrics(String label);
```
设置无歌词时显示的提示文字。
**参数**
- `label`：提示文字的内容。
### setLabelShownWhenNoLyricsTextSize [#setlabelshownwhennolyricstextsize]
```java
public void setLabelShownWhenNoLyricsTextSize(float size);
```
设置无歌词显示时，提示文字的大小。
**参数**
- `size`：歌词文字大小，单位为 pixel。
### setLabelShownWhenNoLyricsTextColor [#setlabelshownwhennolyricstextcolor]
```java
public void setLabelShownWhenNoLyricsTextColor(@ColorInt int color);
```
设置无歌词显示时，提示文字的颜色。
**参数**
- `color`：文字的颜色。
### enableStartOfVerseIndicator [#enablestartofverseindicator]
```java
public void enableStartOfVerseIndicator(boolean enable);
```
在播放歌曲前奏时是否显示等待圆点。
等待圆点是在播放器播放前奏时，歌词视图中显示一个提示，让用户知道何时应该开始唱歌。
**参数**
- `enable`：是否显示等待圆点：
- `true`：（默认）显示等待圆点。
- `false`：不显示等待圆点。
### setStartOfVerseIndicatorPaddingTop [#setstartofverseindicatorpaddingtop]
```java
public void setStartOfVerseIndicatorPaddingTop(float paddingTop);
```
设置等待圆点和歌词组件顶部之间的距离。
调用该方法前，请确保 `enableStartOfVerseIndicator` 为 `true`。
**参数**
- `paddingTop`：等待圆点和歌词组件顶部之间的距离，默认为 8 dp。
### setStartOfVerseIndicatorRadius [#setstartofverseindicatorradius]
```java
public void setStartOfVerseIndicatorRadius(float radius);
```
设置等待圆点的半径大小。
调用该方法前，请确保 `enableStartOfVerseIndicator` 为 `true`。
**参数**
- `radius`：等待圆点的半径，默认值 6 dp。
### setStartOfVerseIndicatorColor [#setstartofverseindicatorcolor]
```java
public void setStartOfVerseIndicatorColor(int color);
```
设置等待圆点的颜色。
调用该方法前，请确保 `enableStartOfVerseIndicator` 为 `true`。
**参数**
- `color`：等待圆点的颜色。
### reset [#reset-2]
```java
public void reset();
```
重置歌词组件。
当一首歌曲播放完毕后或是播放过程中切到另外一首歌曲时，需要调用该方法来重置歌词设置。
## IScoringAlgorithm [#iscoringalgorithm]
该类提供自定义评分相关的 API。
### getLineScore [#getlinescore]
```java
int getLineScore(LinkedHashMap pitchesForLine, final int indexOfLineJustFinished, final LyricsLineModel lineJustFinished);
```
获取当前行歌词的演唱得分。
当用户唱完一句歌词后，你可以调用该方法来自定义计算该行歌词的得分。
**参数**
- `pitchesForLine`：标准音高值。
- `indexOfLineJustFinished`：歌词行的索引号。
- `lineJustFinished`：当前歌词行的相关信息，详见 [`LyricsLineModel`](#LyricsLineModel)。
## Logger [#logger]
该接口类提供日志相关的 API。
### onLog [#onlog]
```java
void onLog(int level, String tag, String message);
```
`KaraokeView` 的日志回调。
你可以通过该回调来了解日志的相关内容，可用于排查问题。
**参数**
- `level`：日志的级别：
-`2`：详细的日志信息。
-`3`：调试级别的日志信息。
-`4`：一般信息级别的日志信息。
-`5`：警告级别的日志信息，表示可能存在的问题或潜在的错误。
-`6`：错误级别的日志信息，表示出现了错误或异常情况。
-`7`：中断级别的日志，表示出现了不可恢复的错误。
- `tag`：日志标签，用于进一步分类或标识日志。
- `message`：日志的具体内容，包含了要输出的信息。
## LyricsFileDownloader [#lyricsfiledownloader]
该类提供歌词文件下载及管理的相关方法。
### getInstance [#getinstance]
```java
public static LyricsFileDownloader getInstance(Context context)
```
获取歌词下载器单例实例。
在调用 `LyricsFileDownloader` 类下的其他方法前，你需要调用该方法获取`LyricsFileDownloader` 的单例实例。如果单例实例尚未初始化，此方法也将进行初始化。
**参数**
- `context`：与 App 当前状态相关联的 Context 对象，用于创建 `LyricsFileDownloader` 的单例实例。
**返回值**
- 一个 `LyricsFileDownloader` 实例。
### setLyricsFileDownloaderCallback [#setlyricsfiledownloadercallback]
```java
public void setLyricsFileDownloaderCallback(LyricsFileDownloaderCallback callback)
```
设置歌词文件下载回调。
**参数**
- `callback`：需要监听的事件回调，详见 [`LyricsFileDownloaderCallback`](#lyricsfiledownloadercallback)。
### setMaxFileNum [#setmaxfilenum]
```java
public void setMaxFileNum(int maxFileNum)
```
设置可缓存的歌词文件的最大数量。
当已缓存的歌词文件数量超过你所设置的值，歌词打分组件会自动清除最早下载的或已过期的歌词文件。
**参数**
- `maxFileNum`：可缓存的歌词文件的最大数量，默认值为 50。
### setMaxFileAge [#setmaxfileage]
```java
public void setMaxFileAge(long maxFileAge)
```
设置歌词文件的有效期。
如歌词文件过期，你需要重新下载才可以继续使用。
**参数**
- `maxFileAge`：歌词文件的有效期，默认值为 8 小时。
### download [#download]
```java
public int download(final String url)
```
下载歌词文件。
**参数**
- `url`：需要下载的歌词文件的 URL。如果你需要下载声网版权音乐的歌词，你需要先调用 [`getLyricWithSongCode`](/zh-CN/api-reference/rtc/android/play/drm) 获取指定歌曲的歌词下载地址，然后通过由此触发的 [`onLyricResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 回调来获取歌词的 `url`。
**返回值**
- 方法调用成功时返回一个 `requestId`，为本次请求的唯一标识。
- < 0：方法调用失败。如 `-1` 表示参数无效。
### cancelDownload [#canceldownload]
```java
public void cancelDownload(int requestId)
```
取消下载歌词文件。
参数：
- `requestId`：请求的唯一标识，当你成功调用 `download` 方法后会返回一个 `requestId`，将其传入此参数来取消该次歌词下载。
### cleanAll [#cleanall]
```java
public void cleanAll()
```
清除所有已缓存的歌词文件。
## LyricsFileDownloaderCallback [#lyricsfiledownloadercallback]
该类提供歌词下载的相关回调。
### onLyricsFileDownloadProgress [#onlyricsfiledownloadprogress]
```java
void onLyricsFileDownloadProgress(int requestId, float progress);
```
歌词文件下载进度回调。当你调用 `download` 开始下载歌词文件后，会触发该回调报告当前的下载进度。
**参数**
- `requestId`：本次请求的唯一标识。
- `progress`：歌词文件的下载进度：
- `[0,1)`：下载中。
- `1`：下载完成。
### onLyricsFileDownloadCompleted [#onlyricsfiledownloadcompleted]
```java
void onLyricsFileDownloadCompleted(int requestId, byte[] fileData, DownloadError error);
```
歌词文件下载完成回调。
当你调用 `download` 开始下载歌词，歌词下载完成后会触发此回调报告歌词下载完成或下载失败的原因。
**参数**
- `requestId`：本次请求的唯一标识。
- `fileData`：输出参数，表示歌词文件数据。
- `error`：下载出错的原因，详见 [`DownloadError`](#downloaderror)。`NULL` 表示没有错误，文件下载成功。
## LyricsLineModel [#lyricslinemodel]
```java
public class LyricsLineModel {
public static class Tone {
public long begin;
public long end;
public String word;
public int pitch = 0;
public long getDuration() {
return end - begin;
}
}
public List tones;
public long getStartTime() {}
public long getEndTime() {}
}
```
当前行的歌词的相关信息。
- `Tone`：当前音符的信息。
- `begin`：音符开始的时间，单位为毫秒。
- `end`：音符结束的时间，单位为毫秒。
- `word`：音符对应的文字。
- `pitch`：音符对应的音高值。
- `getDuration`：获取当前音符从开始到结束的时间。
- 返回值：当前音符从开始到结束的时间，单位为毫秒。
- `tones`：一行歌词里面包含的音符（tone）的个数。
- `getStartTime`：获取一行歌词开始的时间。
- 返回值：当前行歌词开始的时间，单位为毫秒。
- `getEndTime`：获取一行歌词结束的时间。
- 返回值：当前行歌词结束的时间，单位为毫秒。
## LyricsModel [#lyricsmodel]
```java
public class LyricsModel {
public List lines;
public long duration;
public long startOfVerse;
public String title;
public String artist;
}
```
歌词的数据模型。
- `lines`：当前行的歌词的相关信息，详见 [`LyricsLineModel`](#LyricsLineModel)。
- `duration`：歌词总演唱时长，单位为毫秒。
- `startOfVerse`：前奏结束的时间，单位为毫秒。
- `title`：歌曲名称。
- `artist`：歌手。
## Enum [#enum]
### DownloadError [#downloaderror]
```java
public enum DownloadError {
GENERAL(0),
REPEAT_DOWNLOADING(1),
HTTP_DOWNLOAD_ERROR(2),
HTTP_DOWNLOAD_ERROR_LOGIC(3),
UNZIP_FAIL(4);
}
```
歌词文件下载失败的原因。
- `GENERAL`：(0) 一般错误，无明确归因。
- `REPEAT_DOWNLOADING`：(1) 重复的 URL 请求。
- `HTTP_DOWNLOAD_ERROR`：(2) 执行 HTTP 请求时出错，如超时。
- `HTTP_DOWNLOAD_ERROR_LOGIC`：(3) HTTP 协议逻辑层错误，如 `500`。
- `UNZIP_FAIL`：(4) 解析歌词文件失败。