# Desktop-sing **Repository Path**: xiaohao3/Desktop-sing ## Basic Information - **Project Name**: Desktop-sing - **Description**: 一个常驻桌面的歌词悬浮条：自动读取 **QQ音乐 / 网易云音乐 / 酷狗音乐**（或其它接入 Windows 系统媒体栏的播放器 - **Primary Language**: Python - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-18 - **Last Updated**: 2026-09-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 桌面歌词 Desktop-sing 一个常驻桌面的歌词悬浮条：自动读取 **QQ音乐 / 网易云音乐 / 酷狗音乐**（或其它接入 Windows 系统媒体栏的播放器）正在播放的歌曲，显示专辑封面 + 卡拉OK式逐句歌词，配色随封面自动变化。 ## 核心功能 - **自动跟随播放**：通过 Windows 系统媒体控制（SMTC）读取当前歌曲（标题 / 歌手 / 专辑 / 封面 / 播放进度），换歌自动切换；同时开着多个播放器时跟随正在播放的那个。播放进度做**连续性校正**—— 本地按真实时间外推，播放器小抖动、上报滞后甚至上报冻结（音乐在放但播放器位置不上报）都不会拽停歌词，只有快进 / 拖动 / 大幅回退才重新对齐 - **歌词自动匹配（多源择优）**：播网易云的歌优先走网易云接口（weapi 加密搜索 + 歌词接口，独家版权歌匹配更好），否则按 QQ音乐 → 网易云 → **酷狗** → **LRCLIB** 依次取词；每个来源先算 **质量分**（有逐字 +30 / 有翻译 +12 / 行数 / 末行是否贴合歌曲全长）再择优，拿到「逐字 + 翻译」的满配结果就提前收工。结果本地缓存 - **逐字歌词四来源**：QQ `trans`、网易云 YRC / `tlyric`、**酷狗 KRC**（自带逐字时间轴与 `[language:]` 译文）、LRCLIB——任意一个能拿到逐字就按逐字渲染 - **歌词清洗**：自动剔除空行 / 纯符号行、**版权声明与制作名单**（`作词：`／`小提琴：` 等 60+ 种角色，"角色 + 冒号"才算，不会误伤正常歌词）、同一时间戳的重复行只留第一条，并按时间重排 - **繁简转换（可选）**：内置 900+ 组高频繁简对照；把完整对照表放到 `%APPDATA%\Desktop-sing\t2s.tsv`（每行「繁体简体」）即可覆盖内置表。未收录的字符原样保留 - **卡拉OK视觉**： - 当前句流光填色（渐变色取自专辑封面主色） - 封面主色同时驱动胶囊底色、边框、均衡器与进度条 - 行切换滑入淡入动画、胶囊宽度平滑过渡、播放中标题旁有均衡器律动 - **氛围光晕**：卡片外圈铺一层封面主色径向光晕，随音乐轻微呼吸 - **翻译 / 音译歌词**：QQ音乐 `trans`、网易云 `tlyric` 自动解析并按时间轴匹配到对应行，以小一号、副主色着色显示在当前句下方（可开关） - **9 种逐字动画**：流光滑入 / 字字上浮 / 缩放入场 / 纯淡入 / 弹跳落字 / 波浪起伏 / 扇形展开 / 打字机 / 无动画——逐字（不是逐行）驱动，唱到哪个字就动哪个字 - **字体库（免费商用字体一键下载 + 国内镜像回退）**：内置钉钉进步体、MiSans、阿里巴巴普惠体 3.0、思源黑体、霞鹜文楷、得意黑 6 款**免费商用**字体，面板里点一下即下载安装并立即生效；每款按「主 CDN → ghfast.top / ghproxy.net 等国内镜像」顺序自动回退 - **桌面集成**：置顶无边框悬浮条、拖拽移动（位置记忆）、鼠标点击穿透、**位置锁定**（防误拖）、托盘图标控制、**暂停自动淡出** - **摆放位置预设（7 个锚点）**：底部居中（贴任务栏上方，默认）/ 顶部居中 / 屏幕正中 / 四角，右键或托盘菜单一键切换。存的是**相对屏幕安全区的锚点**而非绝对坐标，换分辨率、改任务栏高度、插拔外接屏后仍然贴边；手动拖过会自动落到「自由摆放」并记住坐标 - **全局快捷键**：`Ctrl+Alt+P` 播放/暂停、`Ctrl+Alt+,` / `.` 上/下一首、`Ctrl+Alt+[` / `]` 歌词偏移、`L` 显示隐藏、`S` 设置、`T` 样式、`D` 显示模式、`G` 锁定位置、`B` 氛围屏保—— **默认关闭**（避免和别的软件抢键），被占用的组合会自动跳过并提示 - **氛围屏保（黑底防烧屏）**：全屏待机画面——纯黑打底 + 封面主色大光晕 + 低亮度大时钟 + 当前歌词，所有元素按**互不相同的慢周期**漂移，长时间挂着也不会烧屏；可设空闲 N 分钟自动进入（默认 10 分钟），系统锁屏期间不会重复启动，按任意键 / 点一下鼠标退出 - **开机自启 + 进程保活**：自启写入注册表 Run 项；保活由轻量守护进程守着，进程被强杀 / 崩溃后自动拉起（退避重启避免崩溃风暴）；应用内点「退出」是正常退出，守护进程随之下班 - **设置面板**：卡片式深色 UI，按「歌词同步 / 外观 / 字体库 / 悬浮窗 / 氛围屏保 / 系统」分组，配色实时跟随专辑封面主色 - **播放控制**：上一首 / 播放·暂停 / 下一首，悬停一键控制条 + 双击播放/暂停；歌词偏移校准（±5s）；「重新获取歌词」可手动纠正匹配错误 - **检查更新（内置源，开箱即用）**：无需手填地址——GitHub Releases 负责查新版本号，下载默认走**蓝奏云镜像**（国内直连更快），弹窗里蓝奏云 / GitHub 两个渠道任选； GitHub 不畅时自动改走国内可直连的 `update.json` 清单镜像（jsDelivr），任一源失败不影响其它源；也可在设置里把更新地址换成自己的 GitHub Releases / 通用 JSON 清单（留空即恢复内置源） ## 可调项（均在设置面板里，自动保存）滑条一律**粗粒度（10% 一档）**。 | 分组 | 项目 | 范围 | | --- | --- | --- | | 歌词同步 | 歌词偏移 | -5s ~ +5s 滑条（0.5s 步进）+ 提前/延后/归零快捷按钮 | | 外观 | 悬浮样式 | 原生浮字 / 玻璃胶囊 / iOS 音乐卡片 / 黑胶唱片 / Spotify 声波 | | 外观 | 字体 | **字体库已装字体**（MiSans 为默认）+ 系统已装精选字体 | | 外观 | 字号 | 60% ~ 180%（10% 一档），卡片尺寸随字号自适应 | | 外观 | 透明度 | 30% ~ 100%（10% 一档） | | 外观 | 逐字动画 | 流光滑入 / 字字上浮 / 缩放入场 / 纯淡入 / 弹跳落字 / 波浪起伏 / 扇形展开 / 打字机 / 无动画 | | 外观 | 边缘虚化 | 开关 + 虚化宽度 0~60px（10px 一档） | | 外观 | 显示模式 | 常驻桌面 / 置顶悬浮 | | 外观 | 封面 / 翻译歌词 / 进度时间 | 三个开关 | | 字体库 | 6 款免费商用字体 | 一键下载（几 MB ~ 26MB），下载后按钮变「使用」 | | 悬浮窗 | 氛围光晕 / 暂停自动淡出 / 位置锁定 / 点击穿透 | 开关，另有「重置位置」「预览屏保」按钮 | | 氛围屏保 | 风格 / 空闲自动进入 / 阈值 / 仅空闲时启动 | 3D 粒子 / 极简 / 音浪 / 星轨四选一 + 3~60 分钟阈值 | | 系统 | 开机自启 / 进程保活 / 全局快捷键 / 启动自动检查更新 | 开关 + 更新地址输入框（留空 = 内置源）+ 「立即检查更新」按钮 | --- ## 构建与开发指南 ### 1. 环境依赖需要 Windows 10/11 与 Python 3.8+： ```bat pip install -r requirements.txt ``` ### 2. 运行 ```bat pythonw lyrics_overlay.py :: 无控制台启动（或双击启动桌面歌词.bat） python lyrics_overlay.py --selftest :: 自检：SMTC 会话探测 + 5 种样式渲染 ``` 所有离屏脚本（测试、预览、巡检）都不需要显示器和真实播放器，前置条件只有一条： ```bat set QT_QPA_PLATFORM=offscreen ``` ### 3. 打包 exe Qt6/PySide6 需要 **PyInstaller 5+**（系统 Python 自带的 3.6 太旧）。先建一次构建虚拟环境（用 `--system-site-packages` 继承系统已装的 PySide6 / winsdk，不污染系统环境）： ```bat python -m venv .buildenv --system-site-packages .buildenv\Scripts\python.exe -m pip install -U "pyinstaller>=6" ``` 之后每次发版只需一条命令： ```bat .buildenv\Scripts\python.exe build_exe.py :: 精简（默认） .buildenv\Scripts\python.exe build_exe.py --full :: 带全部内置字体（+15MB） .buildenv\Scripts\python.exe build_exe.py --no-font :: 不内置字体，体积最小 .buildenv\Scripts\python.exe build_exe.py --dir :: onedir 目录版（启动更快） ``` - 版本号自动取自 `lyrics_overlay.py` 的 `APP_VERSION` - 产物带变体后缀、互不覆盖：默认 / `-lite`（--no-font）/ `-full` - 自动收集 `fonts/`、`winsdk`（SMTC 后端）与 `Crypto`；**排除 pywin32 整族** （本项目不用它，装残会让 PyInstaller 的 pythoncom hook 直接崩） - 存在 `icon.ico` / `version_info.txt` 时自动带上 `--icon` / `--version-file` - 历史产物自动挪进 `dist\archive\`（只改名不删除），旧版本随时能找回来 ### 4. 安装包与便携版 ```bat .buildenv\Scripts\python.exe build_exe.py --dir :: 先产出 dist\Desktop-sing-v<版本>\ python pkg_portable.py :: 便携版 zip makensis.exe installer\installer.nsi :: 安装版 exe（NSIS 3.11） ``` - **安装版**（NSIS）：欢迎 → 隐私声明（须勾选同意）→ 安装目录（默认 `D:/Desktop-sing`，无 D 盘或目录不可写时自动兜底 `%LOCALAPPDATA%\Desktop-sing`）→ 组件 → 完成可勾选立即运行；带完整卸载器。安装/卸载前会检测并提示关闭正在运行的实例，并对目标目录做**可写性实测探测**，覆盖「进程占用」与「目录无权限」两类失败 - **便携版**：解压即用，内含 `Desktop-sing.exe`、`使用说明.txt`、`隐私声明.txt`、`卸载桌面歌词.bat` - `pkg_portable.py` 里的源目录与输出名含版本号（当前写死 v1.0.0），发新版时需同步更新 - 卸载脚本会先自复制到 `%TEMP%` 再运行，因此能连程序目录（含脚本自身）一起删干净 ### 5. 回归测试 ```bat python smoke_test.py ``` 离屏跑 30+ 组用例：逐字时间轴、翻译映射、5 种样式渲染、控制条命中、设置面板、9 种逐字动画逐帧、屏保渲染与版式门禁、歌词格式识别（含酷狗 KRC 往返解密）、多源抓词（打桩不走网络）、配置沙箱、悬停控制条避让等。测试会临时改写配置并在结束时自动还原。 > **写渲染断言必须用 `grab()`，不要用 `render(pixmap)`**：本环境下 `QWidget.render(pm)` > 画不出任何东西（采出来全透明），断言会静默通过、什么都验不到。`widget.grab()` 才真的走一遍 > `paintEvent`（且不需要先 `show()`）。 ### 6. 项目结构 ``` lyrics_overlay.py 主程序（单文件） smoke_test.py 离屏回归测试 preview_render.py 预览图生成（每套样式出浅底 + 深底两版） _cfg_sandbox.py 巡检共用的配置沙箱（按脚本名备份 + 跨进程锁 + 兜底还原） _diag_*.py 性能 / 视觉 A-B / 版式 / 屏保等量化巡检工具 _diag_update_lanzou.py 更新源逻辑巡检（多源探测 / 镜像挂载 / 版本比较） _diag_update_dialog.py 更新弹窗离屏渲染巡检（按钮与链接布局） update.json 国内清单镜像内容（jsDelivr 直读，发版时同步版本号与蓝奏云链接） build_exe.py 打包 exe pkg_portable.py 打包便携版 zip check_ver.py 产物版本信息校验 installer/installer.nsi NSIS 安装器源码 NOTICE.md 第三方来源与许可说明启动桌面歌词.bat 双击启动（pythonw，无控制台）卸载桌面歌词.bat 自搬迁后清理程序目录与配置 site/ 官网落地页（纯静态，无构建、无 CDN 依赖） site/tools/make_assets.py 官网图片资源生成器（从 preview/ 派生 assets/） fonts/ 随程序分发的 MiSans（缺失时回落系统字体） preview/ 预览图输出目录 ``` 官网是纯静态单页（HTML + CSS + 原生 JS，不引任何 CDN / 框架），把 `site/` 整个目录传到任意静态托管即可；本地直接双击 `site/index.html` 也能完整浏览。 --- ## 已知限制 - 播放器需接入系统媒体栏（QQ音乐 NT / 网易云新版默认接入；部分老版本或迷你模式可能没有） - 播放器独家版权不覆盖的歌在对应平台搜不到原唱（例如周杰伦在网易云无版权），此时会落到另一来源或 LRCLIB；翻唱歌词的逐行时间与原唱录音不一定一致 - 网易云 weapi 搜索依赖 `pycryptodome`；未安装时自动降级到老接口（匹配质量变差） - 翻译歌词依赖音源是否提供（QQ `trans` / 网易云 `tlyric`），LRCLIB 兜底来源通常没有翻译 - 逐字（卡拉OK字级）时间轴支持网易云 YRC、酷狗 KRC 与增强 LRC 来源，QQ 等行级来源会借网易云同曲时间轴补逐字，拿不到时按行内均匀推进 - **QQ 音乐的 QRC 逐字歌词未接入**：QRC 需要 3DES 解密，实测多种密钥/模式组合都拿不到合法 zlib 流，因此 QQ 仍走 LRC（逐行），其独家逐字内容会借网易云补 - 制作名单识别是**启发式**：基于「角色词 + 冒号」，遇到未收录的写法可能漏过，可在 `_CREDIT_ROLE` 里补词 - 繁简转换内置的是**高频字表**（900+ 组），少见繁体字不在表内会原样保留；需要完整转换请自备 `t2s.tsv` - Apple Music（TTML）/ Spotify / Musixmatch 等来源**未接入**：它们需要用户侧凭据，与本程序「零配置」的定位不符 - 全局快捷键需要独占组合键；被其它程序占用时会自动跳过并在启用时提示，该项**默认关闭** - 字体库自带 jsDelivr 主源 + 国内镜像回退；若全部失败，面板按钮会变「重试」 - 氛围屏保的「空闲自动进入」靠 `GetLastInputInfo` 判断键鼠空闲；播放视频时系统仍算「有输入」 - 打包成 exe 后 `fonts/` 目录可能不可写，因此字体库一律下载到 `%APPDATA%\Desktop-sing\fonts` ## 致谢与许可本项目参考了以下开源项目的**思路**（均为 Python 重写，未复制源码）： - **[Lyricify-Lyrics-Helper](https://github.com/WXRIW/Lyricify-Lyrics-Helper)**（WXRIW，Apache-2.0）—— KRC 解密与格式解析、格式自动识别、时间轴偏移/降级、酷狗/LRCLIB 取词、多源搜索匹配、歌词优化（信息行处理、繁简转换） - **[FluentFlyout](https://github.com/unchihugo/FluentFlyout)**（Hugo Li 等，GPL-3.0）—— 仅参考 UI/交互概念（可定制浮层位置、平滑入场动画），**未使用其任何源码** 完整的许可义务与声明见 **[NOTICE.md](NOTICE.md)**。