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

voicefox

Rust / ratatui / libmpv 终端音乐播放器

CI

voicefox 将多音源音乐搜索、在线播放、本地音乐库、歌词、下载、收藏、历史和歌单管理整合进键盘优先的终端界面。当前稳定可用线已经推进到 0.5.0，在原有 TUI 基础上继续加入频谱、睡眠定时器、SMTC、歌单导入导出、网易云只追加推送和远程歌单缓存等能力。

0.5.0 当前新增能力

  • w：Linux PipeWire monitor 频谱，4096 点 FFT、50Hz–12kHz 对数频带、平滑与峰值保持，并在采集断流后自动重连。
  • t：睡眠定时，到点淡出后暂停。
  • Windows SMTC：硬件媒体键、系统媒体浮层、蓝牙耳机控制与歌曲/封面信息。
  • M3U/M3U8、LX Music JSON、网易云 JSON 导入；自建歌单 M3U8 导出。
  • 自建歌单/收藏向网易云只追加推送，先生成 Diff 再确认，不做远端删除。
  • 网易云远程歌单只读镜像缓存，按歌单 ID 增量合并并跨进程落盘。
  • 本地音乐增加「播放」列；修复表头列宽拖拽误触发换列、频谱断流冻结等问题。

主要功能

  • 多音源聚合搜索与失败换源
  • libmpv 播放、ReplayGain、EQ、A-B 循环、淡入淡出
  • 队列键盘/鼠标排序、筛选、全屏歌词
  • LRC/KRC/QRC/YRC 歌词、翻译与罗马音
  • 并发分片下载、完整性校验、标签/封面/LRC 写入
  • 本地音乐扫描、标签、封面、歌词、CUE 分轨与文件诊断
  • 收藏、历史、自建歌单、排行榜、热门歌单
  • Kitty / Sixel / iTerm2 封面协议与 Unicode fallback
  • Linux D-Bus/MPRIS、Windows 桌面提示路径
  • lx-music 兼容 JS 自定义音源
  • 可配置快捷键与运行时帮助
  • 跨音源歌单/收藏同步：Diff 预览、双向增量、持久化歌单映射与未匹配提示

当前音源

音源 主要能力
酷我 kw 搜索、播放、歌词、封面、歌手/专辑、歌单/分类、排行榜、链接直解
酷狗 kg 上述能力 + 扫码登录、个人歌单
QQ tx 上述能力 + 扫码登录、个人歌单
网易云 wy 搜索、播放、歌词、封面、歌手/专辑、歌单/分类、排行榜、链接直解、扫码登录、个人歌单
咪咕 mg 搜索、播放、歌词、封面、歌手/专辑、歌单/分类、排行榜、链接直解
哔哩哔哩 bili 搜索、视频音频播放、歌词/封面、歌手/UP 主、歌单/排行榜、链接直解、扫码登录
千千 qianqian 搜索、播放、歌词、封面、歌手/专辑、歌单/分类、链接直解
JOOX joox 搜索、播放、歌词、封面、专辑、歌单、链接直解
5sing fivesing 搜索、播放、歌词、封面、歌单、链接直解
Jamendo jamendo 搜索、播放、歌词、封面、专辑、歌单、链接直解
Apple Music apple 搜索、试听播放、歌词、封面、专辑/歌单、分类、链接直解
汽水 soda 搜索、播放、歌词、封面、歌单、链接直解
本地 local 本地文件扫描、播放、标签、封面、歌词、CUE、诊断

完整能力矩阵见 docs/USER_GUIDE.md。同步设计、使用原则与已知限制见 docs/SYNC.md。

快捷键速览

按键 功能
1~`8` 页面导航
Space 播放/暂停
n / b 下一首/上一首
m 播放模式
. / , 音量
Ctrl+L 收藏当前歌曲
Ctrl+S 下载
Ctrl+O 下载面板
Ctrl+R 重绘/重传封面
V 队列歌词全屏
/ 支持筛选的页面进入筛选
? / F1 快捷键帮助
q 退出

完整按页面快捷键见 KEYBINDINGS.md。

安装

Windows

Release 提供包含 voicefox.exe 与 libmpv-2.dll 的压缩包。

Linux

需要 libmpv：Arch 可 sudo pacman -S mpv，Debian/Ubuntu 可 sudo apt install libmpv-dev。

macOS

brew install mpv
cargo build --release

从源码构建

git clone https://github.com/emoeem/voicefox.git
cd voicefox
cargo build --release
cargo run --release

文档

验证

cargo fmt --all
cargo test -p voicefox-app
cargo test -p lx-core
cargo test -p lx-lyric
cargo check -p voicefox-app --target x86_64-pc-windows-gnu

License

MIT