歌词打分组件 Kotlin API

本文提供在线 K 歌房歌词评分组件相关 API。

KaraokeViewCopy Anchor Link

歌词评分组件的基础接口类，实现歌词同步、演唱评分的主要功能。

KaraokeViewCopy Anchor Link

public KaraokeView(LyricsView lyricsView, ScoringView scoringView);

创建 KaraokeView 实例。

参数

• lyricsView：用于显示歌词的 LyricsView 对象。
• scoringView：用于显示评分的 ScoringView 对象。

parseLyricsDataCopy Anchor Link

public static LyricsModel parseLyricsData(File file);

解析歌词文件数据。

参数

• file：要解析的歌词文件对象，支持 XML 文件或 LRC 文件。

返回值

• 方法调用成功时返回一个 LyricModel 对象，包含解析后的歌词数据模型。
• 方法调用失败时返回 null。

setLyricsDataCopy Anchor Link

public void setLyricsData(LyricsModel model);

设置歌词数据模型。

该方法用于设置歌词数据模型，在调用该方法前，你需要先调用 parseLyricsData 方法解析歌词数据并获取相应的歌词数据模型对象以便于歌词显示。

参数

• model：LyricsModel 对象，表示歌词数据模型，包含歌曲的基本信息、歌词信息等。如果传入 null，表示当前歌曲为纯音乐，没有对应的歌词信息。

resetCopy Anchor Link

public void reset();

重置歌词及评分设置。

当一首歌曲播放完毕，或在播放过程中切到另外一首歌曲时，需要调用该方法来重置歌词、评分设置。

参数

• lyrics：要添加的 LyricsView 对象，用于显示歌词。若传入 null，表示不添加歌词视图。
• scoring：要添加的 ScoringView 对象，用于显示评分。若传入 null，表示不添加评分视图。

setProgressCopy Anchor Link

public void setProgress(long progress);

把歌曲当前的播放进度同步给歌词、评分组件。

在实现歌词和歌曲播放同步时，你需要调用该方法来将歌曲当前的播放进度设置给 KaraokeView，以便 KaraokeView 根据当前歌曲的播放位置显示对相应的歌词。

调用该方法前你需要先通过内置媒体播放器的 getPlayPosition 方法获取歌曲当前的播放进度。声网建议你每 20 ms 调用一次该方法来把歌曲的播放进度同步给歌词评分组件。

参数

• progress：歌曲的播放进度，单位为 ms。

setPitchCopy Anchor Link

public void setPitch(float pitch);

把获取的实时人声音调同步给评分组件。

当你通过 IRtcEngineEventHandler 下的 onAudioVolumeIndication 获取本地用户的人声音调后，你需要调用该方法把获取到的实时人声音调同步给评分组件用于演唱评分。

参数

• pitch：用户的实时人声音调。

setKaraokeEventCopy Anchor Link

public void setKaraokeEvent(KaraokeEvent event);

设置歌词评分组件事件回调。

在调用该方法前，请确保已初始化 KaraokeView 对象。

参数

• event：歌词评分组件事件，详见 KaraokeEvent。

setScoreAlgorithmCopy Anchor Link

public void setScoringAlgorithm(IScoringAlgorithm algorithm);

自定义评分算法。

如果你不想使用评分组件默认的评分算法，你可以通过该方法来自定义评分算法。你自定义的评分算法对象应实现 IScoringAlgorithm 接口。

参数

• algorithm：实现了 IScoringAlgorithm 接口的评分算法对象。

setScoringLevelCopy Anchor Link

public void setScoringLevel(int level);

设置得分的难易等级。

你可以通过该方法来设置演唱者得分的难易等级。

参数

• level：难度等级，取值范围为 [0,100]，默认值为 15。值越小表示难度等级越低，演唱者越容易得分。

你可以参考下表来设置不同难度：

getScoringLevelCopy Anchor Link

public int getScoringLevel();

获取得分的难易等级。

当你调用 setScoringLevel 设置得分的难易程度后，可以调用该方法来获取当前你设置的得分难易程度。

返回值

• ≥ 0：方法调用成功，返回当前设置的得难易值。
• < 0：方法调用失败。

setScoringCompensationOffsetCopy Anchor Link

public void setScoringCompensationOffset(int offset);

调整演唱评分结果。

如果你的业务场景对演唱分数有特殊要求，你可以调用此方法来调整演唱评分的结果。

参数

• offset：额外增加或减少的分数，取值范围为 [-100, 100]，默认值为 0。

声网不建议你同时使用 setScoringLevel 和 setScoreCompensationOffset 来调整评分机制。

getScoringCompensationOffsetCopy Anchor Link

public int getScoringCompensationOffset();

获取调整后的分数结果。

当你调用 setScoringCompensationOffset 方法调整演唱评分的结果后，你可以调用过该方法来获取调整后的分数结果。

返回值

• 调整后的分数结果。

KaraokeEventCopy Anchor Link

KaraokeView 的核心事件回调。

onDragToCopy Anchor Link

public void onDragTo(KaraokeView view, long position);

歌词拖动结束的回调。

如果你设置允许歌词拖动（将 enableDragging 设为 true），当歌词拖动结束后会触发此回调。你可以通过该回调获取歌词拖动后对应的播放位置。

参数

• view：KaraokeView 实例。
• position：歌词拖动后对应的歌曲播放位置，单位为毫秒。

onLineFinishedCopy Anchor Link

public void onLineFinished(KaraokeView view, LyricsLineModel line, int score, int cumulativeScore, int index, int total);

一行歌词播放完毕回调。

当一行歌词播放完毕后，会触发该回调报告当前行的歌词的得分、累计得分等信息。

参数

• view：KaraokeView 实例。
• line：当前歌词行的信息，详见 LyricsLineModel。
• score：当前歌曲行的得分，取值范围 [0, 100]。
• cumulativeScore：当前累计得分。
• Index：歌词行数的索引号，最小值为 0。
• total：歌词的总行数。

onRefPitchUpdateCopy Anchor Link

public void onRefPitchUpdate(float refPitch, int numberOfRefPitches);

歌词标准音高值回调。

歌词中每一个字都有自己的音符（tone），代表一个单独的音高值。SDK 会在播放到歌词的每一个字时触发该回调，报告当前音符的音高值，以及整首歌歌词中音符的个数。

参数

• refPitch：当前音符的音高值。
• numberOfRefPitches：整首歌歌词中音符的个数。如果你想要自定义评分算法，可以通过该参数在 App 层计算一首歌演唱的平均分。

ScoringViewCopy Anchor Link

该类提供评分组件的核心 API。

setRefPitchStickDefaultColorCopy Anchor Link

public void setRefPitchStickDefaultColor(int color);

设置标准音高线的颜色。

参数

• color：标准音高线的颜色。

setRefPitchStickHighlightedColorCopy Anchor Link

public void setRefPitchStickHighlightedColor(int color);

设置人声音调与标准音高线匹配后，音高线的颜色。

参数

• color：标准音高线的颜色。

setRefPitchStickHeightCopy Anchor Link

public void setRefPitchStickHeight(float height);

设置标准音高线的高度。

参数

• height：标准音高线的高度，默认值为 6 dp。

enableParticleEffectCopy Anchor Link

public void enableParticleEffect(boolean enable);

设置是否开启粒子动画效果。

粒子动画可以在歌词或背景等区域中播放，以呈现各种漂亮、流畅且动感的效果，与歌声的节奏和音调进行同步。

参数

• enable：
  • true：（默认）开启粒子动画效果。
  • false：关闭粒子动画效果。

setParticlesCopy Anchor Link

public void setParticles(Drawable[] particles);

自定义粒子动画样式。

如果你不想使用声网默认的粒子动画样式，你可以调用该方法来自定义粒子动画样式。在调用该方法前，请确保你已经开启粒子动画效果，即 enableParticleEffect 设为 true。

参数

• particles：自定义粒子动画样式的对象。

setLocalPitchIndicatorCopy Anchor Link

public void setLocalPitchIndicator(Bitmap bitmap);

设置本地音高指示器的样式。

该方法用于设置本地音高指示器的样式，以可视化地表示当前音高值，并显示实时的音高的变化，帮助演唱者对自己的声音进行调准和校正。

参数

• bitmap：音高指示器的位图图像。如果你不想显示音高指示器，传入 null。

resetCopy Anchor Link

public void reset();

重置评分组件。

当一首歌曲播放完毕后或是播放过程中切到另外一首歌曲时，需要调用该方法来重置评分设置。

LyricsViewCopy Anchor Link

该类提供歌词组件的核心 API。

enableDraggingCopy Anchor Link

public void enableDragging(boolean enable);

设置是否允许歌词拖动。

参数

• enable：是否允许拖动歌词：
  • true：允许拖动歌词。
  • false：不允许拖动歌词。

setInactiveLineTextColorCopy Anchor Link

public void setInactiveLineTextColor(@ColorInt int color) {}

设置未在当前播放的歌词的颜色。

参数

• color：未在当前播放的歌词的颜色。

setTextSizeCopy Anchor Link

public void setTextSize(float size) {}

设置未在当前播放的歌词文字大小。

参数

• size：歌词文字大小，单位为 pixel。

setActiveLinePlayedTextColorCopy Anchor Link

public void setActiveLinePlayedTextColor(@ColorInt int color) {}

设置当前歌词行中，已播放的歌词的颜色。

参数

• color：歌词的颜色。

setActiveLineUpcomingTextColorCopy Anchor Link

public void setActiveLineUpcomingTextColor(@ColorInt int color) {}

设置当前歌词行中，待播放的歌词的颜色。

参数

• color：歌词的颜色。

setCurrentLineTextSizeCopy Anchor Link

public void setCurrentLineTextSize(float size) {}

设置当前播放的歌词行的文字大小。

参数

• size：歌词文字大小，单位为 pixel。

setLabelShownWhenNoLyricsCopy Anchor Link

public void setLabelShownWhenNoLyrics(String label);

设置无歌词时显示的提示文字。

参数

• label：提示文字的内容。

setLabelShownWhenNoLyricsTextSizeCopy Anchor Link

public void setLabelShownWhenNoLyricsTextSize(float size);

设置无歌词显示时，提示文字的大小。

参数

• size：歌词文字大小，单位为 pixel。

setLabelShownWhenNoLyricsTextColorCopy Anchor Link

public void setLabelShownWhenNoLyricsTextColor(@ColorInt int color);

设置无歌词显示时，提示文字的颜色。

参数

• color：文字的颜色。

enableStartOfVerseIndicatorCopy Anchor Link

public void enableStartOfVerseIndicator(boolean enable);

在播放歌曲前奏时是否显示等待圆点。

等待圆点是在播放器播放前奏时，歌词视图中显示一个提示，让用户知道何时应该开始唱歌。

参数

• enable：是否显示等待圆点：
  • true：（默认）显示等待圆点。
  • false：不显示等待圆点。

setStartOfVerseIndicatorPaddingTopCopy Anchor Link

public void setStartOfVerseIndicatorPaddingTop(float paddingTop);

设置等待圆点和歌词组件顶部之间的距离。

调用该方法前，请确保 enableStartOfVerseIndicator 为 true。

参数

• paddingTop：等待圆点和歌词组件顶部之间的距离，默认为 8 dp。

setStartOfVerseIndicatorRadiusCopy Anchor Link

public void setStartOfVerseIndicatorRadius(float radius);

设置等待圆点的半径大小。

调用该方法前，请确保 enableStartOfVerseIndicator 为 true。

参数

• radius：等待圆点的半径，默认值 6 dp。

setStartOfVerseIndicatorColorCopy Anchor Link

public void setStartOfVerseIndicatorColor(int color);

设置等待圆点的颜色。

调用该方法前，请确保 enableStartOfVerseIndicator 为 true。

参数

• color：等待圆点的颜色。

resetCopy Anchor Link

public void reset();

重置歌词组件。

当一首歌曲播放完毕后或是播放过程中切到另外一首歌曲时，需要调用该方法来重置歌词设置。

IScoringAlgorithmCopy Anchor Link

该类提供自定义评分相关的 API。

getLineScoreCopy Anchor Link

int getLineScore(LinkedHashMap<Long, Float> pitchesForLine, final int indexOfLineJustFinished, final LyricsLineModel lineJustFinished);

获取当前行歌词的演唱得分。

当用户唱完一句歌词后，你可以调用该方法来自定义计算该行歌词的得分。

参数

• pitchesForLine：标准音高值。
• indexOfLineJustFinished：歌词行的索引号。
• lineJustFinished：当前歌词行的相关信息，详见 LyricsLineModel。

LoggerCopy Anchor Link

该接口类提供日志相关的 API。

onLogCopy Anchor Link

void onLog(int level, String tag, String message);

KaraokeView 的日志回调。

你可以通过该回调来了解日志的相关内容，可用于排查问题。

参数

• level：日志的级别： -2：详细的日志信息。 -3：调试级别的日志信息。 -4：一般信息级别的日志信息。 -5：警告级别的日志信息，表示可能存在的问题或潜在的错误。 -6：错误级别的日志信息，表示出现了错误或异常情况。 -7：中断级别的日志，表示出现了不可恢复的错误。

• tag：日志标签，用于进一步分类或标识日志。

• message：日志的具体内容，包含了要输出的信息。

LyricsFileDownloaderCopy Anchor Link

该类提供歌词文件下载及管理的相关方法。

getInstanceCopy Anchor Link

public static LyricsFileDownloader getInstance(Context context)

获取歌词下载器单例实例。

在调用 LyricsFileDownloader 类下的其他方法前，你需要调用该方法获取LyricsFileDownloader 的单例实例。如果单例实例尚未初始化，此方法也将进行初始化。

参数

• context：与 App 当前状态相关联的 Context 对象，用于创建 LyricsFileDownloader 的单例实例。

返回值

• 一个 LyricsFileDownloader 实例。

setLyricsFileDownloaderCallbackCopy Anchor Link

public void setLyricsFileDownloaderCallback(LyricsFileDownloaderCallback callback)

设置歌词文件下载回调。

参数

• callback：需要监听的事件回调，详见 LyricsFileDownloaderCallback。

setMaxFileNumCopy Anchor Link

public void setMaxFileNum(int maxFileNum)

设置可缓存的歌词文件的最大数量。

当已缓存的歌词文件数量超过你所设置的值，歌词打分组件会自动清除最早下载的或已过期的歌词文件。

参数

• maxFileNum：可缓存的歌词文件的最大数量，默认值为 50。

setMaxFileAgeCopy Anchor Link

public void setMaxFileAge(long maxFileAge)

设置歌词文件的有效期。

如歌词文件过期，你需要重新下载才可以继续使用。

参数

• maxFileAge：歌词文件的有效期，默认值为 8 小时。

downloadCopy Anchor Link

public int download(final String url)

下载歌词文件。

参数

• url：需要下载的歌词文件的 URL。如果你需要下载声网版权音乐的歌词，你需要先调用 getLyricWithSongCode 获取指定歌曲的歌词下载地址，然后通过由此触发的 onLyricResult 回调来获取歌词的 url。

返回值

• 方法调用成功时返回一个 requestId，为本次请求的唯一标识。
• < 0：方法调用失败。如 -1 表示参数无效。

cancelDownloadCopy Anchor Link

public void cancelDownload(int requestId)

取消下载歌词文件。

参数：

• requestId：请求的唯一标识，当你成功调用 download 方法后会返回一个 requestId，将其传入此参数来取消该次歌词下载。

cleanAllCopy Anchor Link

public void cleanAll()

清除所有已缓存的歌词文件。

LyricsFileDownloaderCallbackCopy Anchor Link

该类提供歌词下载的相关回调。

onLyricsFileDownloadProgressCopy Anchor Link

void onLyricsFileDownloadProgress(int requestId, float progress);

歌词文件下载进度回调。当你调用 download 开始下载歌词文件后，会触发该回调报告当前的下载进度。

参数

• requestId：本次请求的唯一标识。
• progress：歌词文件的下载进度：
  • [0,1)：下载中。
  • 1：下载完成。

onLyricsFileDownloadCompletedCopy Anchor Link

void onLyricsFileDownloadCompleted(int requestId, byte[] fileData, DownloadError error);

歌词文件下载完成回调。

当你调用 download 开始下载歌词，歌词下载完成后会触发此回调报告歌词下载完成或下载失败的原因。

参数

• requestId：本次请求的唯一标识。
• fileData：输出参数，表示歌词文件数据。
• error：下载出错的原因，详见 DownloadError。NULL 表示没有错误，文件下载成功。

LyricsLineModelCopy Anchor Link

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<Tone> tones;
    public long getStartTime() {}
    public long getEndTime() {}
}

当前行的歌词的相关信息。

• Tone：当前音符的信息。

  • begin：音符开始的时间，单位为毫秒。
  • end：音符结束的时间，单位为毫秒。
  • word：音符对应的文字。
  • pitch：音符对应的音高值。
  • getDuration：获取当前音符从开始到结束的时间。
    • 返回值：当前音符从开始到结束的时间，单位为毫秒。

• tones：一行歌词里面包含的音符（tone）的个数。

• getStartTime：获取一行歌词开始的时间。

  • 返回值：当前行歌词开始的时间，单位为毫秒。

• getEndTime：获取一行歌词结束的时间。

  • 返回值：当前行歌词结束的时间，单位为毫秒。

LyricsModelCopy Anchor Link

public class LyricsModel {
    public List<LyricsLineModel> lines;
    public long duration;
    public long startOfVerse;
    public String title;
    public String artist;
}

歌词的数据模型。

• lines：当前行的歌词的相关信息，详见 LyricsLineModel。
• duration：歌词总演唱时长，单位为毫秒。
• startOfVerse：前奏结束的时间，单位为毫秒。
• title：歌曲名称。
• artist：歌手。

EnumCopy Anchor Link

DownloadErrorCopy Anchor Link

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) 解析歌词文件失败。