qq_music_aum：群晖Audio Station歌词插件使用指南

🔧核心功能解析

歌词自动匹配

适用场景：音乐播放时自动显示歌词
操作效果：插件会根据当前播放歌曲信息，自动从QQ音乐获取并展示歌词内容，无需手动搜索。

翻译内容智能拼接

适用场景：需要查看歌词翻译时
操作效果：当QQ音乐存在歌词翻译内容时，插件会自动将翻译文本拼接在原歌词下方，实现双语对照显示。

📌3步完成插件安装

第1步：获取插件文件

✅ 访问项目仓库，下载最新版本的插件压缩包
✅ 解压压缩包，得到扩展名为.aum的插件文件

第2步：安装插件到Audio Station

✅ 打开群晖Audio Station应用
✅ 进入「设置」→「歌词插件」页面
✅ 点击「新增」按钮，选择解压得到的.aum文件
✅ 确认安装并等待进度完成

第3步：启用插件

✅ 在歌词插件列表中，勾选已安装的qq_music_aum插件
✅ 重启Audio Station使设置生效

⚠️兼容性矩阵与避坑指南

插件版本	功能状态	适用场景
v1.8及以下	❌ 不推荐使用	官方接口调整导致无法正常工作
v1.9	⚠️ 有限支持	快速搜索接口，结果数量较少
v1.10+	✅ 推荐使用	搜索结果完整，与历史版本体验一致

⚠️ 注意：请务必使用v1.10以上版本以获得最佳体验，旧版本可能因接口变更导致功能失效

常见调用场景示例

场景1：基础歌词获取

插件核心通过歌曲ID调用QQ音乐API获取歌词，关键逻辑如下：

// 核心流程示意（实际代码位于src/qqSource.php）
function fetchLyrics($songInfo) {
    $searchResult = searchSong($songInfo['title'], $songInfo['artist']);
    if ($searchResult) {
        $lyricData = getLyricById($searchResult['song_id']);
        return formatLyric($lyricData);
    }
    return null;
}

场景2：翻译内容处理

翻译文本拼接逻辑位于src/qqTranslation.php，实现方式：

// 翻译拼接示意
function combineLyricWithTranslation($original, $translation) {
    if (empty($translation)) return $original;
    // 按行匹配原歌词与翻译
    $originalLines = explode("\n", $original);
    $transLines = explode("\n", $translation);
    $result = [];
    foreach ($originalLines as $index => $line) {
        $result[] = $line;
        if (isset($transLines[$index])) {
            $result[] = "（翻译：{$transLines[$index]}）";
        }
    }
    return implode("\n", $result);
}

功能验证与测试

可通过test.php文件进行插件功能测试，执行方法：

php test.php

测试将模拟不同歌曲信息的歌词获取过程，输出API调用结果和歌词解析状态。

项目结构说明

qq_music_aum/
├── src/                # 核心代码目录
│   ├── qqHandler.php   # 主逻辑处理
│   ├── qqSource.php    # 歌词数据源接口
│   ├── qqTranslation.php # 翻译处理模块
│   └── INFO            # 插件信息文件
├── test.php            # 功能测试脚本
└── README.md           # 项目说明文档