按键歌词显示插件的使用说明

dockkey2023

# StreamDock 歌词显示插件

在 StreamDock 按键屏上实时同步显示当前播放音乐的歌词，支持多种音乐播放软件。

---

## 目录

- [功能概览](#功能概览)
- [系统要求](#系统要求)
- [安装步骤](#安装步骤)
- [启动与停止](#启动与停止)
- [配置选项](#配置选项)
- [使用指南](#使用指南)
- [项目结构](#项目结构)
- [工作原理](#工作原理)
- [常见问题与排查](#常见问题与排查)
- [开发者信息](#开发者信息)

---

## 功能概览

| 功能 | 说明 |
|------|------|
| 实时歌词显示 | 自动检测当前播放的音乐，获取并同步显示歌词 |
| 双源歌词获取 | 网易云音乐 API 优先获取，失败时自动回退至 QQ 音乐 API，大幅提升歌词覆盖率 |
| 多播放器兼容 | 支持 Spotify、QQ音乐、Apple Music 等所有使用 Windows 媒体会话的播放器 |
| 媒体控制 | 可将按键配置为上一曲/下一曲/播放暂停，同时显示歌词 |
| 自定义背景 | 支持透明背景、纯色背景、自定义图片背景、GIF 动图背景 |
| 歌词偏移调节 | 当歌词与音乐不同步时，可手动调节时间偏移 |
| 多段落显示 | 通过段落索引，可在多个按键上分别显示歌词的不同片段 |
| 开机自启动 | 可将后端服务配置为开机自动运行 |

---

## 系统要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Windows 10 及以上 |
| StreamDock 软件 | 4.1 及以上版本 |

> **无需安装 Python**：插件已内置 `lyric_fetcher.exe` 独立可执行文件，所有依赖已打包在内，用户无需额外安装 Python 或任何依赖库即可使用。

---

## 安装步骤

### 第一步：安装插件

将整个 `com.zsss.lyrics.sdPlugin` 文件夹复制到 StreamDock 的插件目录：

```
%APPDATA%\HotSpot\StreamDock\plugins\
```

即：

```
C:\Users\<你的用户名>\AppData\Roaming\HotSpot\StreamDock\plugins\
```

复制完成后，重启 StreamDock 软件，插件将自动加载。

### 第二步：启动后端服务

插件前端（按键显示）由 StreamDock 自动管理，但歌词获取后端需要手动启动。请参阅下方 [启动与停止](#启动与停止) 章节。

---
## 启动与停止

### 启动后端

双击运行插件目录下的`lyric_fetcher.exe`或`start_background.bat`，该脚本会：

- **优先使用内置 exe**：如果插件目录下存在 `lyric_fetcher.exe`，直接启动该可执行文件（无需 Python 环境）
- **回退到 Python**：如果 exe 不存在，则检测系统中的 `pythonw.exe` 并通过 Python 运行 `lyric_fetcher.py`
- 服务监听地址为 `127.0.0.1:48888`

启动成功后，命令提示符窗口会自动关闭，后端在后台静默运行。

### 停止后端

双击运行插件目录下的 `stop.bat`，该脚本会：

- 读取 `lyric_fetcher.pid` 文件获取进程 PID
- 精确终止对应进程
- 如果 PID 文件不存在，则按进程名（`lyric_fetcher.exe`）查找并终止

### 配置开机自启动

双击运行插件目录下的 `install_autostart.bat`，该脚本会：

1. 优先使用 **Windows 任务计划程序** 创建登录时自动运行的任务（任务名：`LyricsFetcher`）
2. 如果任务计划程序创建失败，则回退到在 **启动文件夹** 中创建快捷方式

如需取消自启动，打开 **任务计划程序**（`taskschd.msc`），找到并删除 `LyricsFetcher` 任务即可。

---

## 配置选项

在 StreamDock 中将歌词插件拖入按键后，点击按键即可打开属性检查器（设置面板），包含以下配置项：

### 功能类型

| 选项 | 说明 |
|------|------|
| 仅显示歌词 | 按键仅用于显示歌词，点击无其他操作 |
| 上一曲 + 歌词 | 点击按键执行"上一曲"操作，同时显示歌词 |
| 播放/暂停 + 歌词 | 点击按键执行"播放/暂停"操作，同时显示歌词 |
| 下一曲 + 歌词 | 点击按键执行"下一曲"操作，同时显示歌词 |

### 歌词段落索引 (posIndex)

- 默认值：`0`
- 说明：每个按键最多显示 4 个字符。通过段落索引可以选择显示歌词的不同片段：
  - `0` → 显示第 1-4 个字符
  - `1` → 显示第 5-8 个字符
  - `2` → 显示第 9-12 个字符
  - 以此类推
- 用途：在多个按键上分别设置不同的段落索引，可以拼接显示更长的歌词

### 歌词时间偏移 (lyricOffset)

- 默认值：`+1.2s`
- 范围：`-5.0s` 至 `+5.0s`，步进 0.1s
- 说明：当歌词与音乐不同步时，通过调整偏移量来校正。正值使歌词提前显示，负值使歌词延后显示

### 字体大小 (fontSize)

- 默认值：`28`
- 范围：`10` 至 `60`
- 说明：歌词文字的字体大小（像素），按键画布为 144×144 像素

### 字体颜色 (fontColor)

- 默认值：`#ffffff`（白色）
- 说明：歌词文字的颜色，可通过颜色选择器自定义

### 背景模式 (bgMode)

| 选项 | 说明 |
|------|------|
| 透明背景 | 按键背景透明，仅显示歌词文字（带阴影） |
| 纯色背景 | 使用指定的纯色作为背景 |
| 自定义图片 | 上传一张图片作为背景（支持 PNG、JPEG、BMP、WebP） |
| GIF 动图 | 上传 GIF 动图作为背景（需安装 Pillow） |

### 背景颜色 (bgColor)

- 默认值：`#000000`（黑色）
- 说明：仅在背景模式为"纯色背景"时显示和生效

### 背景文件上传

- 仅在背景模式为"自定义图片"或"GIF 动图"时显示
- 操作步骤：
  1. 点击"选择文件"选取本地图片或 GIF
  2. 点击"上传背景"将文件上传至后端
  3. 上传成功后状态会显示绿色提示
  4. 如需更换，重新选择文件并上传即可
  5. 如需清除，点击"清除背景文件"按钮

> **注意**：背景文件是全局共享的，所有按键实例使用同一背景。上传新背景会替换旧背景。

---

## 使用指南

### 基本使用：单按键显示歌词

1. 确保后端已启动（运行 `start_background.bat`）
2. 在 StreamDock 软件中，从插件列表找到"按键歌词显示"
3. 将其拖入一个按键位置
4. 开始播放音乐，歌词将自动显示在按键上

### 进阶使用：多按键拼接长歌词

由于每个按键只能显示 4 个字符，可以通过多个按键拼接显示更长的歌词：

1. 将歌词插件拖入多个相邻按键
2. 对每个按键设置不同的"歌词段落索引"：
   - 第 1 个按键：段落索引 = `0`
   - 第 2 个按键：段落索引 = `1`
   - 第 3 个按键：段落索引 = `2`
   - 以此类推
3. 这样多个按键将分别显示歌词的不同片段，拼接成完整歌词行

### 使用媒体控制功能

1. 打开按键的属性检查器
2. 将"功能类型"从"仅显示歌词"改为需要的控制类型（如"下一曲 + 歌词"）
3. 点击该按键即可执行对应的媒体控制操作
4. 歌词仍然会正常显示在按键上

### 自定义背景样式

**透明背景**：适合配合 StreamDock 的整体主题，歌词文字带有黑色阴影以保证可读性。

**纯色背景**：选择与歌词颜色对比明显的背景色，例如白色文字搭配黑色背景。

**图片背景**：上传喜欢的图片，图片会自动缩放至 144×144 像素。建议使用正方形图片以获得最佳效果。

**GIF 动图**：上传 GIF 动图，每帧会自动提取并缩放。需要安装 Pillow 库。GIF 帧动画会持续播放。

---

---
## 常见问题与排查

### 按键显示"后端未运行"

**原因**：后端服务未启动或已崩溃。

**解决方法**：
1. 运行 `start_background.bat` 启动后端
2. 检查后端是否正常运行：在浏览器中访问 `http://127.0.0.1:48888/health`，应返回 `ok`
3. 如果端口 48888 被占用，检查是否有其他实例在运行，先运行 `stop.bat` 再重新启动

### 歌词不显示或显示歌曲标题

**原因**：歌词搜索失败或该歌曲在网易云和 QQ 音乐数据库中均不存在。

**解决方法**：
1. 确认网络连接正常
2. 插件已支持网易云 + QQ 音乐双源获取，大部分歌曲均可找到歌词
3. 极少数小众或未上架歌曲可能两个平台均无法找到歌词
4. 如果歌曲名包含特殊字符，可能影响搜索结果

### 歌词与音乐不同步

**解决方法**：
1. 打开按键属性检查器
2. 调整"歌词时间偏移"滑块
3. 正值使歌词提前显示，负值使歌词延后显示
4. 默认偏移为 +1.2s，通常可以补偿网络延迟

### 某些音乐播放器无法识别

**原因**：插件依赖 Windows 系统媒体会话（SMTC），播放器需要支持该接口。

**解决方法**：
1. 确认使用的播放器支持 Windows 媒体会话控制
2. Spotify、QQ音乐、网易云音乐、Apple Music 等主流播放器均支持
3. 网页版播放器通常不支持，请使用桌面客户端

### GIF 背景不生效

**原因**：GIF 处理需要 Pillow 库支持。

**解决方法（使用 exe）**：GIF 支持已内置在 `lyric_fetcher.exe` 中，无需额外操作。如果 GIF 仍不生效，请确认使用的是最新构建的 exe。

**解决方法（使用 Python）**：
1. 安装 Pillow：`pip install Pillow`
2. 重启后端服务
3. 重新上传 GIF 文件

### 后端启动失败

**可能原因及解决方法**：

| 原因 | 解决方法 |
|------|---------|
| `lyric_fetcher.exe` 不存在且 Python 未安装 | 确保插件目录下存在 `lyric_fetcher.exe`，或安装 Python 3.11+ |
| `pythonw.exe` 找不到（回退模式） | 确认 Python 安装目录下存在 `pythonw.exe` |
| `winsdk` 未安装（回退模式） | 执行 `pip install winsdk` |
| `requests` 未安装（回退模式） | 执行 `pip install requests` |
| 端口 48888 被占用 | 运行 `stop.bat` 终止旧进程后重试 |
| exe 被 Windows Defender 拦截 | 在 Windows 安全中心将 exe 添加为排除项 |

### 如何确认后端是否正在运行

方法一：在浏览器中访问 `http://127.0.0.1:48888/health`，返回 `ok` 表示正常运行。

方法二：在浏览器中访问 `http://127.0.0.1:48888/data`，应返回包含 `pos`、`lrc`、`title` 等字段的 JSON 数据。

方法三：打开任务管理器，查找 `lyric_fetcher.exe` 或 `pythonw.exe` 进程。

### 如何卸载插件

1. 运行 `stop.bat` 停止后端服务
2. 如已配置开机自启动，在任务计划程序中删除 `LyricsFetcher` 任务
3. 删除插件文件夹 `com.zsss.lyrics.sdPlugin`
4. 重启 StreamDock 软件

---

## 开发者信息

- **作者**：Zsss
- **版本**：2.0.0
- **SDK 版本**：2
- **插件 UUID**：`com.zsss.lyrics.action`
- **后端版本**：v5.2
- **StreamDock SDK 文档**：[https://sdk.key123.vip/guide/events-received.html](https://sdk.key123.vip/en/guide/events-received.html)