持续维护最后验证：2026-10-03T00:00:00Z

VoiceFox 0.5.0 使用与功能指南

本页保留早期页面/音源说明结构，并补充当前 0.5.0 功能入口。

0.5.0 新增与变化

w 打开实时频谱，Linux 优先读取 PipeWire 默认输出 monitor，采集断开自动重连。
t 打开睡眠定时器，到点先淡出再暂停。
Windows 接入 SMTC 与系统硬件媒体控制。
歌单支持 M3U/M3U8、LX Music JSON、网易云 JSON 导入和 M3U8 导出。
网易云支持本地歌单/收藏只追加推送，以及远程歌单只读镜像缓存。
设置页增加缓存清理入口；本地音乐列表增加「播放」状态。

voicefox 是 Rust + ratatui + libmpv 构建的终端音乐播放器。当前 voicefox-old 发布线保留原有稳定 TUI 页面，同时整合新的音源、下载、登录、歌词、封面、本地音乐和跨平台运行时能力。

页面

队列：播放队列、歌曲信息、歌词、拖拽排序、筛选、全屏歌词。
搜索：聚合搜索、音源切换、@ 歌手追搜、# 专辑追搜、音源版本选择。
排行榜：按音源浏览实时榜单。
热门歌单：按音源浏览、搜索、分页和收藏歌单。
收藏：歌曲收藏、筛选、排序。
历史：播放历史、筛选、排序、删除。
本地音乐：目录监听、标签、封面、歌词、CUE 分轨、文件诊断。
设置：音源、播放器、界面、歌词、下载、快捷键以及账号/同步相关入口。

完整快捷键见 ../KEYBINDINGS.md。

0.3.15 快捷键重点：↑/↓ 可用于列表导航；队列 / 进入筛选，V 切换全屏歌词；搜索 @ 追搜歌手、# 追搜专辑；下载面板支持 ↑/↓、Del 与鼠标右键。全局 Ctrl+↑/↓ 调整音量。

播放器能力

libmpv 进程内播放，不依赖外部 mpv 命令。
128K / 320K / FLAC / Hi-Res 等音质档位由音源实际提供情况决定。
ReplayGain、均衡器、声道、左右平衡。
列表循环、单曲循环、随机、顺序、播完停止。
A-B 循环、淡入、淡出、无缝切换。
在线播放失败时支持跨音源/解析器回退。

歌词与下载

支持 LRC、KRC、QRC、YRC 以及翻译/罗马音数据。下载歌词会过滤非标准 LRC 数据，避免把网易云接口原始 JSON 写入 .lrc。

下载支持并发分片、CDN 回退、重试、大小/MD5 校验、标签、封面、标准 LRC、取消与清理。失败任务只保留在当前下载任务视图，不再重复写入持久下载历史。

本地音乐

支持 MP3、FLAC、M4A、OGG、OPUS、WAV、WMA、AAC、APE、AIFF 等常见格式及 CUE 分轨。支持增量扫描、标签、封面、内嵌/同名歌词以及重复、损坏、缺失文件诊断。

当前音源

音源	搜索	播放	歌词	封面	歌手/专辑	歌单	榜单	链接直解	登录
酷我 `kw`	✓	✓	✓	✓	✓	✓	✓	✓	—
酷狗 `kg`	✓	✓	✓	✓	✓	✓	✓	✓	扫码/个人歌单
QQ `tx`	✓	✓	✓	✓	✓	✓	✓	✓	扫码/个人歌单
网易云 `wy`	✓	✓	✓	✓	✓	✓	✓	✓	扫码/个人歌单
咪咕 `mg`	✓	✓	✓	✓	✓	✓	✓	✓	—
哔哩哔哩 `bili`	✓	✓	✓	✓	✓	✓	✓	✓	扫码
千千 `qianqian`	✓	✓	✓	✓	✓	✓	—	✓	—
JOOX `joox`	✓	✓	✓	✓	✓	✓	—	✓	—
5sing `fivesing`	✓	✓	✓	✓	—	✓	—	✓	—
Jamendo `jamendo`	✓	✓	✓	✓	—	✓	—	✓	—
Apple Music `apple`	✓	✓（试听）	✓	✓	—	✓	—	✓	—
汽水 `soda`	✓	✓	✓	✓	—	✓	—	✓	—
本地 `local`	—	✓	✓	✓	✓	—	—	—	—

“✓”表示代码层已实现/声明对应能力；具体歌曲仍可能受到平台接口、地区、账号权限或版权限制影响。Apple Music 当前为试听片段，不应视为完整曲目下载源。

JS 音源可以动态加载多个社区脚本，具体能力由脚本声明，可参与搜索、播放 URL、歌词和封面解析。

跨音源同步

VoiceFox 提供独立的跨音源同步层，用于本地歌单/收藏与网易云音乐、QQ 音乐之间的增量同步。同步默认采用双向、非镜像策略，执行前生成 Diff，不会因为一侧缺少歌曲就自动删除另一侧内容。

匹配优先级为 ISRC、同平台 ID、精确元数据、元数据+时长、模糊元数据，无法可靠匹配的歌曲会进入未匹配列表。歌单映射会持久化保存，以减少后续同步对名称的依赖。

当前网易云与 QQ 音乐均已有同步适配器；QQ 音乐写入接口仍需要真实账号端到端验证。网易云扫码登录如果出现“检测到当前设备环境异常，本次操作已拦截”，属于平台风控拒绝当前登录环境，不应通过连续扫码或轮询重试规避。详细架构与限制见 SYNC.md。

通知与平台

Linux：D-Bus 桌面通知和 MPRIS。
Windows：Shell_NotifyIconW 通知区气泡。
- 使用 voicefox 应用图标，并遵循系统的提示音与勿扰设置。
- 发送新通知前撤下本应用上一条气泡；其他应用正在显示气泡时，新通知仍可能进入 Windows 气泡队列。
- 通知区图标在最后一次通知 10 秒后移除。
- 不提供专辑封面、操作按钮和通知中心历史。
Windows SMTC / 硬件媒体键：已实现，支持系统媒体控制、硬件媒体键、蓝牙耳机控制以及歌曲/封面信息。

输入法与中文输入

在搜索框、筛选栏、各输入弹窗里输入中文时，输入法的候选框跟随终端光标。

终端光标的位置现在由「当前获得焦点的文本输入」决定：进入输入模式时光标会停在
文本插入点（也就是候选框该出现的位置），退出输入模式后隐藏。这样候选框不会在
输入框和底部状态栏之间来回跳（issue #42 的成因：ratatui 用差分渲染，未显式设置
光标位置时它只隐藏光标、不移动光标，光标就停在”本帧最后一个变化的单元格”上，
而这个格子会随着哪些行发生变化而改变）。

因此输入框里的插入点用终端自己的光标表示，不再额外画一个 █ 字符——否则会
和终端光标重影。如果你希望关闭终端光标（例如使用 cursor_shape 配置），它仍然
只影响显示，候选框定位不受影响。

主题与背景

默认配色是 Catppuccin Mocha（背景 #1e1e2e），可以在 [theme] 里逐个覆盖。
颜色值支持四种写法：

写法	例子	说明
跟随终端	`"default"`	映射到终端自己的默认前景/背景色。也接受 `reset` / `terminal` / `none` / `transparent` / `-`
16 色名	`"red"`、`"light_blue"`、`"dark_gray"`	走终端调色板
十六进制	`"#cba6f7"`、`"#abc"`	3 位缩写会展开成 6 位
256 色号	`"236"`、`"color236"`	引用终端调色板，适合做”半透明感”

让背景跟随终端（配合透明终端 / 壁纸）：

[theme]
base = "default"

有一点要先说清楚：面板（状态栏、通知、弹层、列表选中行）各自使用 surface* /
mantle / crust 作为底色，所以透明只作用于最底层，行为类似 nvim 的
Normal 与 Pmenu。如果你要的是整体半透明，把这些字段也一起改成 default
或改用 256 色号。

主题值写错时不会让程序崩溃，也不会静默生效：无法识别的值会回退到默认色，并在
日志里给出一条 主题色 theme.xxx 无法识别 的提示。