MusicFree 歌词源完整指南多源歌词聚合与歌词插件优先级【免费下载链接】MusicFree插件化、定制化、无广告的免费音乐播放器项目地址: https://gitcode.com/GitHub_Trending/mu/MusicFree切到一首日语歌进度条走了半首歌词栏还是空白这是 MusicFree 歌词源要处理的核心场景当歌曲来源平台没有歌词时它会走多源歌词聚合链路从本地文件、远程缓存、其他歌词插件里挨个找直到找到为止。下面按「一首歌找歌词的完整旅程」把这条链路讲透顺带说说你怎么动手调。取词旅程本地歌词 → 缓存 → 主源插件 → 相似歌名搜索先给结论一首歌的歌词从哪来是一条优先级明确的流水线越靠前越省事。本地手动上传的歌词你自己传上去的.lrc文件命中即返回不再联网。远程缓存之前通过网络取过并落盘的歌词存于cache/lrc/命中直接读文件。主源插件请求调用歌曲来源平台插件的getLyric方法实时取词取到后顺手写入缓存。相似歌名搜索以上全空且开了「歌词缺失时自动搜索歌词」才触发跨插件搜索兜底。核心代码就这几行在 src/core/lyricManager.ts 的refreshLyric里lrcSource (await this.pluginManager.getByMedia(currentMusicItem) ?.methods?.getLyric(currentMusicItem)) ?? null; // 主源拿不到且开启了自动搜索 if (!lrcSource this.appConfig.getConfig(lyric.autoSearchLyric)) { lrcSource await this.searchSimilarLyric(currentMusicItem); }兜底搜索的精髓在相似度比较拿歌名有别名用别名去每个可搜索的歌词插件里查前两条结果歌名加歌手名的编辑距离一个衡量两个字符串逐字差异大小的算法实现见 src/utils/minDistance.ts越小越可信完全一致直接短路const dist minDistance(keyword, musicItem.title) minDistance(item.artist, musicItem.artist); if (dist distance) { distance dist; // 记住当前最接近的候选 minDistanceMusicItem item; targetPlugin plugin; }注意搜索时会跳过当前歌曲的来源插件它已经失败过了并且每查完一个插件就检查一次「用户是不是已经切歌了」切歌就立刻放弃不浪费后面的请求。如何设置歌词插件优先级三层取词顺序「为什么有的插件先被尝试」答案分三层优先级歌词来源什么时候被用到用户能否干预1本地上传 远程缓存文件/缓存存在时直接命中可以上传即覆盖网络结果2主源插件缓存未命中时按歌曲的platform字段定位到对应插件不能由歌曲来源决定3其他备选源主源失败后按插件顺序逐个搜索可以在插件设置里拖排序第三层的「插件顺序」就是你调歌词插件优先级的地方。插件管理器把顺序持久化所有「按顺序」的查询都走同一份排序表src/core/pluginManager/index.tssetPluginOrder(sortedPlugins: Plugin[]) { const orderMap: Recordstring, number {}; sortedPlugins.forEach((plugin, index) { orderMap[plugin.name] index; // 位置即优先级 }); pluginMeta.setPluginOrder(orderMap); }也就是说自动搜索时谁先被查完全取决于你在设置里拖出来的顺序。把最靠谱的歌词源排第一冷门歌的兜底成功率会明显不同。LRC 解析时间戳换算、元数据标签与偏移校准拿到歌词文本后交给 src/utils/lrcParser.ts 里的LyricParser。它负责三件小事。时间轴解析[mm:ss.xx]形式的标记会被逐段换算成秒数解析后的歌词项按时间排序定位时从上次位置往前走进度条基本只前进这样查得更快// [xx:xx.xx] x s const nums timeStr.slice(1, timeStr.length - 1).split(:); for (let i 0; i nums.length; i) { result result * 60 nums[i]; }元数据标签歌词头部那些[xx:yy]行会被单独收集常见的有这些标签含义示例[ar:]艺术家[ar:周杰伦][ti:]歌名[ti:七里香][al:]专辑[al:七里香][offset:]时间偏移单位毫秒解析时自动除以 1000 转成秒[offset:500][by:]歌词制作者[by:MusicFree]偏移校准与跨源关联两个「救急」小能力。歌词整体快/慢半拍用updateLyricOffset(musicItem, offset)记一笔偏移下次解析时和 LRC 自带的[offset:]叠加生效歌词版本和音频对不上比如你下的是 live 版用associateLyric把这首歌的歌词指向另一首歌取词时会自动改走关联歌曲的来源插件。两者都不需要动歌词文件本身。用户实操调插件顺序、上传本地歌词、开自动搜索1. 调整歌词源插件顺序。效果决定自动搜索时谁先被查谁的后援靠后。操作设置 → 插件设置 → 排序src/pages/setting/settingTypes/pluginSetting/ 里的pluginSort视图把最信任的歌词源拖到最前。2. 上传本地歌词文件。效果该歌曲从此不再联网取词本地文件最高优先级。操作歌曲详情页 → 歌词面板 → 上传本地歌词uploadLocalLyric支持歌词和翻译两个槽位文件按本地目录/local_lrc/{平台MD5}/{歌曲ID MD5}.lrc落盘路径规则见 src/constants/pathConst.ts。3. 开关自动搜索与相关显示参数。效果控制「主源失败后要不要跨插件找」以及状态栏歌词的样式。配置项lyric.autoSearchLyric基础设置里叫「歌词缺失时自动搜索歌词」、lyric.showStatusBarLyric及配套的字体大小、颜色、位置topPercent/leftPercent等见 src/core/appConfig.ts。常见问题排查现象 → 原因 → 解法现象原因解法歌词栏一直空白主源没有自动搜索又关着或所有备选源都查不到打开lyric.autoSearchLyric再装一两个歌词源插件把靠谱的排前面歌词和进度对不上音频版本与歌词版本不一致live 版/加长版最常见先用updateLyricOffset校准偏移还不行就用跨源关联指向正确版本的歌词换一首歌时歌词先空白很久主源和缓存都没命中正在等跨插件搜索逐个返回属正常兜底流程常听的平台歌词源提前排到前面命中缓存后会快很多MusicFree 把「找歌词」拆成了本地、缓存、主源、搜索四层可组合的来源每一层都可以由你通过插件排序和参数配置来取舍——这正是插件化、可定制这个思路的落点不规定标准答案把顺序交给你。现在就去装两三个歌词源插件把顺序拖一拖再开一次自动搜索。【免费下载链接】MusicFree插件化、定制化、无广告的免费音乐播放器项目地址: https://gitcode.com/GitHub_Trending/mu/MusicFree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MusicFree 歌词源完整指南：多源歌词聚合与歌词插件优先级
MusicFree 歌词源完整指南多源歌词聚合与歌词插件优先级【免费下载链接】MusicFree插件化、定制化、无广告的免费音乐播放器项目地址: https://gitcode.com/GitHub_Trending/mu/MusicFree切到一首日语歌进度条走了半首歌词栏还是空白这是 MusicFree 歌词源要处理的核心场景当歌曲来源平台没有歌词时它会走多源歌词聚合链路从本地文件、远程缓存、其他歌词插件里挨个找直到找到为止。下面按「一首歌找歌词的完整旅程」把这条链路讲透顺带说说你怎么动手调。取词旅程本地歌词 → 缓存 → 主源插件 → 相似歌名搜索先给结论一首歌的歌词从哪来是一条优先级明确的流水线越靠前越省事。本地手动上传的歌词你自己传上去的.lrc文件命中即返回不再联网。远程缓存之前通过网络取过并落盘的歌词存于cache/lrc/命中直接读文件。主源插件请求调用歌曲来源平台插件的getLyric方法实时取词取到后顺手写入缓存。相似歌名搜索以上全空且开了「歌词缺失时自动搜索歌词」才触发跨插件搜索兜底。核心代码就这几行在 src/core/lyricManager.ts 的refreshLyric里lrcSource (await this.pluginManager.getByMedia(currentMusicItem) ?.methods?.getLyric(currentMusicItem)) ?? null; // 主源拿不到且开启了自动搜索 if (!lrcSource this.appConfig.getConfig(lyric.autoSearchLyric)) { lrcSource await this.searchSimilarLyric(currentMusicItem); }兜底搜索的精髓在相似度比较拿歌名有别名用别名去每个可搜索的歌词插件里查前两条结果歌名加歌手名的编辑距离一个衡量两个字符串逐字差异大小的算法实现见 src/utils/minDistance.ts越小越可信完全一致直接短路const dist minDistance(keyword, musicItem.title) minDistance(item.artist, musicItem.artist); if (dist distance) { distance dist; // 记住当前最接近的候选 minDistanceMusicItem item; targetPlugin plugin; }注意搜索时会跳过当前歌曲的来源插件它已经失败过了并且每查完一个插件就检查一次「用户是不是已经切歌了」切歌就立刻放弃不浪费后面的请求。如何设置歌词插件优先级三层取词顺序「为什么有的插件先被尝试」答案分三层优先级歌词来源什么时候被用到用户能否干预1本地上传 远程缓存文件/缓存存在时直接命中可以上传即覆盖网络结果2主源插件缓存未命中时按歌曲的platform字段定位到对应插件不能由歌曲来源决定3其他备选源主源失败后按插件顺序逐个搜索可以在插件设置里拖排序第三层的「插件顺序」就是你调歌词插件优先级的地方。插件管理器把顺序持久化所有「按顺序」的查询都走同一份排序表src/core/pluginManager/index.tssetPluginOrder(sortedPlugins: Plugin[]) { const orderMap: Recordstring, number {}; sortedPlugins.forEach((plugin, index) { orderMap[plugin.name] index; // 位置即优先级 }); pluginMeta.setPluginOrder(orderMap); }也就是说自动搜索时谁先被查完全取决于你在设置里拖出来的顺序。把最靠谱的歌词源排第一冷门歌的兜底成功率会明显不同。LRC 解析时间戳换算、元数据标签与偏移校准拿到歌词文本后交给 src/utils/lrcParser.ts 里的LyricParser。它负责三件小事。时间轴解析[mm:ss.xx]形式的标记会被逐段换算成秒数解析后的歌词项按时间排序定位时从上次位置往前走进度条基本只前进这样查得更快// [xx:xx.xx] x s const nums timeStr.slice(1, timeStr.length - 1).split(:); for (let i 0; i nums.length; i) { result result * 60 nums[i]; }元数据标签歌词头部那些[xx:yy]行会被单独收集常见的有这些标签含义示例[ar:]艺术家[ar:周杰伦][ti:]歌名[ti:七里香][al:]专辑[al:七里香][offset:]时间偏移单位毫秒解析时自动除以 1000 转成秒[offset:500][by:]歌词制作者[by:MusicFree]偏移校准与跨源关联两个「救急」小能力。歌词整体快/慢半拍用updateLyricOffset(musicItem, offset)记一笔偏移下次解析时和 LRC 自带的[offset:]叠加生效歌词版本和音频对不上比如你下的是 live 版用associateLyric把这首歌的歌词指向另一首歌取词时会自动改走关联歌曲的来源插件。两者都不需要动歌词文件本身。用户实操调插件顺序、上传本地歌词、开自动搜索1. 调整歌词源插件顺序。效果决定自动搜索时谁先被查谁的后援靠后。操作设置 → 插件设置 → 排序src/pages/setting/settingTypes/pluginSetting/ 里的pluginSort视图把最信任的歌词源拖到最前。2. 上传本地歌词文件。效果该歌曲从此不再联网取词本地文件最高优先级。操作歌曲详情页 → 歌词面板 → 上传本地歌词uploadLocalLyric支持歌词和翻译两个槽位文件按本地目录/local_lrc/{平台MD5}/{歌曲ID MD5}.lrc落盘路径规则见 src/constants/pathConst.ts。3. 开关自动搜索与相关显示参数。效果控制「主源失败后要不要跨插件找」以及状态栏歌词的样式。配置项lyric.autoSearchLyric基础设置里叫「歌词缺失时自动搜索歌词」、lyric.showStatusBarLyric及配套的字体大小、颜色、位置topPercent/leftPercent等见 src/core/appConfig.ts。常见问题排查现象 → 原因 → 解法现象原因解法歌词栏一直空白主源没有自动搜索又关着或所有备选源都查不到打开lyric.autoSearchLyric再装一两个歌词源插件把靠谱的排前面歌词和进度对不上音频版本与歌词版本不一致live 版/加长版最常见先用updateLyricOffset校准偏移还不行就用跨源关联指向正确版本的歌词换一首歌时歌词先空白很久主源和缓存都没命中正在等跨插件搜索逐个返回属正常兜底流程常听的平台歌词源提前排到前面命中缓存后会快很多MusicFree 把「找歌词」拆成了本地、缓存、主源、搜索四层可组合的来源每一层都可以由你通过插件排序和参数配置来取舍——这正是插件化、可定制这个思路的落点不规定标准答案把顺序交给你。现在就去装两三个歌词源插件把顺序拖一拖再开一次自动搜索。【免费下载链接】MusicFree插件化、定制化、无广告的免费音乐播放器项目地址: https://gitcode.com/GitHub_Trending/mu/MusicFree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考