编写你的第一个BetterLyrics插件从自定义歌词源到罗马音转写的30分钟完整教程【免费下载链接】BetterLyrics一款优雅且高度自定义的歌词可视化与全能音乐播放应用基于 WinUI3/Win2D 构建 | An elegant and deeply customizable lyrics visualizer versatile music player, built with WinUI3/Win2D项目地址: https://gitcode.com/jayfunc/BetterLyricsBetterLyrics 是一款优雅且高度自定义的歌词可视化与音乐播放应用。它的插件系统允许你通过几行代码扩展应用自定义歌词源从任意网站抓取歌词、歌词翻译、罗马音转写如日文假名转罗马音、中文转拼音。本教程带你从零开始30 分钟内完成你的第一个 BetterLyrics 插件——一个能搜索歌词并提供罗马音转写的小插件。一、快速认识 BetterLyrics 插件体系在动手之前先看看 BetterLyrics 的歌词可视化效果——这正是插件歌词数据的最终展示舞台整个插件体系由官方 SDKBetterLyrics.Sdk提供核心就是三个功能接口详见 BetterLyrics.Sdk/README.md接口作用本教程IPlugin所有插件的入口声明标题、作者、版本等元数据✅ 必须实现ILyricsSource自定义歌词搜索与抓取✅ 实现ILyricsTransliterator转写能力汉字→罗马音/拼音✅ 实现ILyricsTranslator歌词翻译了解即可 推荐继承泛型基类 PluginBase它会自动生成设置界面并绑定配置省去大量样板代码。二、准备工作克隆仓库并找到 SDK只需三步搭建环境约 5 分钟克隆仓库git clone https://gitcode.com/jayfunc/BetterLyrics cd BetterLyrics/src/BetterLyrics.DotNet编译 SDK 项目验证环境dotnet build BetterLyrics.Sdk/BetterLyrics.Sdk.csproj你的插件项目只需引用这个 SDK 程序集即可使用全部接口。SDK 的完整文档就在 BetterLyrics.Sdk/README.md建议收藏备用。三、编写自定义歌词源实现 ILyricsSource歌词源插件的核心是GetLyricsAsync方法——BetterLyrics 播放歌曲时会传入歌曲信息你返回抓取到的歌词即可。创建MyLyricsPlugin.cs先让插件继承PluginBase并实现 ILyricsSourcepublic class MyLyricsPlugin : PluginBaseMyConfig, ILyricsSource { public override string Title 我的歌词源; public async TaskLyricsSearchResult GetLyricsAsync( string title, string artist, string album, double duration, CancellationToken token) { // 用 title artist 去你的歌词网站搜索并下载 var raw await FetchFromYourServiceAsync(title, artist, token); return new LyricsSearchResult(title, artist, album, duration, raw); } }返回的 LyricsSearchResult 是一个记录类型包含原始歌词Raw还可以同时携带Translation翻译、Transliteration转写和Reference出处链接——一次请求就能把多层歌词全部带回。四、进阶为日文歌添加罗马音转写想给歌词加上罗马音只需再实现 ILyricsTransliterator让插件同时具备双能力public async Taskstring? GetTransliterationAsync( string text, LanguageTag? targetLangTag, CancellationToken token) { // 例如调用转换库把「ありがとう」转成 arigatou return RomajiConverter.ToRomaji(text); }宿主应用会自动识别这个能力在需要转写的场景播放日文歌、用户开启转写层时调用它。你甚至还可以借助宿主注入的IAIService调用内置的 AI 能力来完成更智能的转写。五、3行代码搞定插件设置界面BetterLyrics 会根据你的配置类自动生成设置界面无需写任何 UI 代码。定义一个配置类继承PluginConfigBasepublic class MyConfig : PluginConfigBase { public string ApiKey { get Get(); set Set(value); } public int MaxRetry { get Get(3); set Set(value); } }string属性 → 自动变成文本框敏感信息可改用SettingBuilder.Passwordbool属性 → 开关int/double→ 数字框生成规则由 SettingBuilder 完成而 PluginBase 会在初始化时通过GetSettingDefDict()自动扫描这些属性。配置项会出现在设置页的插件管理器中实时生效。六、发布并加载你的插件编译你的插件项目生成.dll输出文件将 DLL 放入 BetterLyrics 的插件目录插件目录路径可在运行时上下文 IPluginContext 的PluginDirectory中查看重启 BetterLyrics在设置 → 插件管理器中找到并启用我的歌词源播放一首歌曲——你的歌词源会被自动调用罗马音转写层即刻生效。七、常见问题与下一步Q插件里能调用 BetterLyrics 内置的 AI 吗可以。在InitializeAsync中通过Context.AIService获取服务调用ChatAsync(systemPrompt, userPrompt)即可用 LLM 辅助歌词搜索或转写。Q如何做多语言支持通过Context.Localizer[Key]读取本地化字符串CurrentLanguage可获取当前语言方便为不同地区用户展示不同的设置文案。Q如何获取插件文件所在目录IPluginContext.PluginDirectory属性会直接返回宿主为你分配的目录适合存放缓存文件。下一步建议给插件加上翻译能力实现ILyricsTranslator接口参考核心项目中 LyricsSearchService 了解宿主如何调度多个歌词源阅读 插件服务实现 了解插件加载全流程 恭喜你现在你已经掌握了 BetterLyrics 插件开发的完整链路实现 IPlugin → 接入歌词源 → 叠加罗马音转写 → 自动生成设置界面 → 发布加载。去创作属于你的歌词插件吧【免费下载链接】BetterLyrics一款优雅且高度自定义的歌词可视化与全能音乐播放应用基于 WinUI3/Win2D 构建 | An elegant and deeply customizable lyrics visualizer versatile music player, built with WinUI3/Win2D项目地址: https://gitcode.com/jayfunc/BetterLyrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
