VoiceFox 0.5.0 快捷键完整参考
当前文档对应 voicefox-old 旧版 TUI + 新功能整合线。快捷键支持通过 [keybindings] 自定义；运行时按 ? / F1 可查看当前实际生效的配置。
全局
| 键 | 动作 |
|---|---|
1~`8` |
队列/搜索/排行榜/歌单/收藏/历史/本地/设置 |
Tab / Shift+Tab |
下一页 / 上一页 |
Space |
播放/暂停 |
n / b |
下一首 / 上一首 |
m |
切换播放模式 |
] / [ |
队列页快进/后退 5 秒；搜索页切换音源 |
. / , |
音量 +5% / -5% |
Ctrl+L |
收藏当前播放歌曲 |
Ctrl+S |
下载当前歌曲；队列页下载选中歌曲 |
Ctrl+O |
下载面板 |
Ctrl+R |
重绘并重传封面 |
Ctrl+G |
把当前页面的面板布局恢复默认（队列的左右栏 / 封面与歌词分栏、榜单与歌单的列表宽度、设置页的分类栏与内嵌列表高度）。等价于表头右键菜单里的「恢复默认面板布局」，配置项一并删除，下次启动沿用默认比例 |
Esc |
取消/返回 |
? / F1 |
快捷键帮助 |
w |
打开/关闭频谱可视化 |
t |
打开睡眠定时器 |
q |
退出 |
队列
| 键/操作 | 动作 |
|---|---|
↑ / k |
上一项 |
↓ / j |
下一项 |
g / Home |
第一项 |
G / End |
最后一项 |
Ctrl+U / PageUp |
上翻页 |
Ctrl+D / PageDown |
下翻页 |
Enter |
播放选中歌曲 |
Shift+↑ / Shift+↓ |
上移/下移歌曲 |
d / Delete |
移除歌曲 |
Shift+D |
清空队列 |
/ |
队列筛选（歌曲名/歌手/专辑） |
Enter |
确认筛选 |
Esc |
退出并清空筛选 |
Backspace |
删除筛选字符 |
V |
歌词普通/全屏切换 |
| 鼠标左键拖动 | 队列排序 |
x |
打开选中歌曲的菜单（等同右键） |
| 鼠标右键 | 歌曲菜单（表头右键打开「列设置」） |
队列页裸
↑/↓专用于列表选择；音量方向键使用Ctrl+↑/↓。
搜索
| 键 | 动作 |
|---|---|
i / / |
输入搜索 |
Enter |
搜索 |
↑/k、↓/j |
导航 |
g/G、Home/End |
首项/末项 |
Ctrl+U/Ctrl+D |
翻页 |
Enter/l |
播放 |
a/A |
加入队尾/下一首 |
D |
下载 |
f |
收藏 |
←/[、→/] |
上一个/下一个音源 |
v |
音源版本列表 |
@ |
追搜歌手；B站结果按 UP 主处理 |
# |
追搜专辑 |
再按相同 @/# |
取消条件并恢复基础关键词 |
Esc |
退出输入/弹层 |
x |
打开选中结果 / 表头的菜单 |
排行榜
↑/k、↓/j 导航；Enter/l 进入/播放；g/G 首末项；Ctrl+U/Ctrl+D 翻页；a/A 加入队尾/下一首；D 下载；f 收藏；x 打开选中项菜单（表头右键为「列设置」）；Esc 返回。
热门歌单
←/→ 切换音源；↑/k、↓/j 导航；Enter/l 进入/播放；a/A 入队；f 收藏；/ 或 s 搜索歌单；r 刷新；x 打开选中项菜单（表头右键为「列设置」）；Esc 返回。
收藏
↑/k、↓/j 导航；Enter/l 播放；g/G 首末项；Ctrl+U/Ctrl+D 翻页；a/A 入队；s 排序；/ 筛选；d/Delete 取消收藏；f 收藏切换；x 打开选中歌曲菜单（表头右键为「列设置」）。
选中网易云音源时（P 切音源，收藏页默认就是网易云）：
- 列表上右键打开「网易云收藏」菜单，三行依次是：
登录 / 重新登录网易云、刷新网易云收藏、关闭（Esc或点菜单外也能关）。 - 该菜单在页面边缘右键时会自动内缩，保证三行都在屏幕内。
0.5.0 歌单互通快捷操作
- 自建歌单
Shift+E：导出 M3U8。 - 自建歌单
Shift+P：生成网易云只追加推送 Diff，确认后分批写入。 - 设置页可进入外部歌单导入入口，支持 M3U/M3U8、LX Music JSON、网易云 JSON。
网易云远程歌单
网易云歌单是只读镜像进远程缓存，不会写回网易云，也不会复制成本地歌单。
| 入口 | 操作 |
|---|---|
设置页（全局 8） |
任意分类按 P 进入「账号与网易云」面板；面板内 P 扫码登录、↑/↓ 选音源后 Enter 登录或退出登录；刷新远程歌单 / QQ 同步（暂未支持）走「账号与扫码」分类里的同名设置行（选中按 Enter） |
收藏页（全局 5） |
列表上右键 → 登录 / 重新登录网易云 或 刷新网易云收藏 |
| 弹层内 | Enter / s 确认刷新；Esc 取消或返回；失败时 r 重新预览 |
登录成功后会自动触发一次刷新，不用再手动按。刷新耗时与歌单数量成正比（约 23 个歌单实测 25 秒），期间弹层可 Esc 取消。
缓存位置：~/.local/share/voicefox/netease_collections.json（Linux，跟随 dirs::data_dir()）。
登录凭据位置：~/.config/voicefox/session/wy.json。
历史
↑/k、↓/j 导航；Enter/l 播放；g/G 首末项；Ctrl+U/Ctrl+D 翻页；a/A 入队；s 排序；/ 筛选；Delete 删除；Shift+X 清空历史；x 打开选中歌曲菜单（表头右键为「列设置」）。
本地音乐
↑/k、↓/j 导航；Enter/l 播放；a/A 入队；s 排序；r 重扫；/ 筛选；d/Delete 删除文件并确认；x 打开选中歌曲菜单（表头右键为「列设置」）。
界面主题
内置 voicefox（默认，手工调好的 Catppuccin 槽位）+ ratatui-themes
的 16 套具名主题（Dracula / Nord / Tokyo Night / Catppuccin / Gruvbox / Solarized /
Monokai Pro / Rosé Pine / Kanagawa / Everforest / Cyberpunk / Midnight Commander …）。
| 位置 | 操作 |
|---|---|
| 设置页 → 「界面」分类 | 第一行就是「界面主题」（值形如 Tokyo Night ›）：鼠标点击 / Enter / Space 都能打开主题菜单，当前主题打 ✓，选中立刻整界面换肤并落盘 |
| 设置页 → 任意分类 | p 循环切换主题（voicefox → 主题库 16 套 → 回到 voicefox）。注意：P（Shift+P）是「账号与扫码」面板，不是换主题 |
| 分类标题 | 主题入口所在分类的面板标题上会写 主题: <当前主题>，不用猜入口在哪 |
| 配置文件 | [theme] name = "tokyo-night"（kebab-case，与主题库一致） |
上一版把裸
p也当成”进账号面板”，文档里的p换主题实际按不出来；现在p= 换主题、P= 账号与扫码，两条路都按得动。
主题库只提供 10 个语义色（bg/fg/muted/accent/secondary/selection/error/warning/success/info），
项目在用的 surface / overlay 等层次色由 bg → fg 插值推导，色相槽位折叠到对应语义色上；
名字写错会回退到 voicefox，不会出现读不清的配色。
底部状态栏（快速控制栏）
状态栏每一段都能点：左键 = 快速切换，右键 = 精确选择菜单；鼠标悬停会高亮。
| 段 | 左键 | 右键 |
|---|---|---|
| 播放状态 | 播放 / 暂停 | 播放控制（播放暂停、上一首、下一首） |
| 当前歌曲 | 歌曲菜单 | 同左键（同一个菜单） |
| 音量 100% | 音量菜单 | 音量 ±5%、静音/恢复、设为 50%/100% |
| 列表循环 | 循环切换 | 5 种播放模式精确选择 |
| 音源 XXX | 音源面板 | 当前播放来源（只读）+ 解析策略 + 音源管理 |
| 音质 320K | 循环切换偏好 | 4 档精确选择 + 「用当前音质重新解析」 |
| 队列 52/100 | 跳到队列页并定位当前歌 | 上一首/下一首/清空队列 |
| 自定义音源 3/3 | JS 音源状态面板 | 逐项 ✓/✗ 与失败原因、重新加载、打开设置 |
| 下载 N 项 | 打开下载面板（Ctrl+O） | 同左键 |
| ⋯ 更多 | 打开被宽度收纳的段 | 同左键 |
要点：
- 当前播放来源与解析策略是两个概念：前者是这首歌实际从哪拿到地址（只读），
后者决定以后怎么解析（auto/prefer 指定平台/only 指定平台）。 - 「音质」左键循环只改偏好，不会打断正在播放的歌；想立即生效走右键的
「用当前音质重新解析这首歌」。 - 一行放不下的可交互段会收进「⋯ 更多」，任何终端宽度下都不会有点不到的控件。
- 状态栏高度 1~6 行：
ui.status_bar_height，或直接拖底栏顶行最右端的⇕把手
（悬停会高亮，往上拖变高、往下拖变矮，松开自动落盘）。 - 这些能力都有键盘等价路径：
Space播放暂停、m切换播放模式、./,音量、n/b上下首、1队列页、Ctrl+O下载面板；音源策略目前只在状态栏（鼠标）。
鼠标与可拖拽布局
| 操作 | 动作 |
|---|---|
列表行右键 / x |
打开该行的上下文菜单 |
| 表头右键 | 打开「列设置」：显示隐藏列、自动调整列宽、恢复默认列宽 |
| 拖动表头列分隔线 | 调整该列宽度（松开即按页面保存到配置） |
| 拖动面板分隔线 | 调整面板尺寸（队列、排行榜、歌单、设置页） |
拖动底栏顶行的 ⇕ 把手 |
调整底部快速控制栏的高度 1~6 行（松开落盘到 ui.status_bar_height） |
Esc（拖拽中） |
取消本次拖拽，还原到拖拽前的布局 |
| 滚轮 | 只在光标位于列表内时移动选中 |
菜单里的 ← 返回上级 或 Esc 可以从子菜单回到上一层；子菜单是逐级返回而不是直接关掉整个菜单。
下载面板
Ctrl+O 打开/关闭。↑/k、↓/j 导航；g/Home、G/End 首末项；Ctrl+U/Ctrl+D 翻页；c/d/Delete 取消活动下载或移除已结束记录；x 清理已结束任务；Esc 关闭；鼠标右键取消/删除当前记录，左键点面板外关闭。
底部会显示 ↑↓选择 · Del/右键删除。
歌手/专辑详情
右键歌曲 → 查看歌手/查看专辑。↑/k、↓/j 导航；Enter 播放/进入；a/A 入队；f 收藏；g/G 首末项；Ctrl+U/Ctrl+D 翻页；Esc 返回。
多歌手歌曲会分别显示 查看歌手：A、查看歌手：B，不会再要求把整个合作艺人字符串作为一个歌手查询。
设置
设置页只保留分类与导航键：设置项本身一律选中后用 Enter 激活（开关与取值行Space 等价），不再有几十个逐行字母 / 功能键，因此不会按错。
宽屏是”左分类栏 + 右设置项”，窄屏先看分类列表、Enter 进入分类、Esc 返回分类列表。
| 键 | 动作 |
|---|---|
← / → |
上一个 / 下一个分类 |
↑ / ↓（或 k / j） |
移动设置项光标；↓ 到底进入该分类的内嵌列表 |
Enter |
激活当前设置项：开关、取值菜单、输入浮层或一次性动作 |
Space |
开关行与取值行的快速激活（等价 Enter） |
Esc |
取消输入 / 窄屏返回分类列表 / 取消删除确认 |
p |
循环切换界面主题（立刻生效并落盘） |
P |
进入「账号与扫码」分类；已在该分类时对选中音源登录 / 退出登录（等价列表里的 Enter） |
Shift+P |
循环切换封面协议（auto → kitty → sixel → iterm2 → halfblocks） |
v |
打开「网易云远程歌单」窗口（只读浏览：列对齐、可滚动、s 切换排序、/ 过滤、Enter 跳到「歌单 · 我的歌单」并定位该歌单）。缓存为空时也会打开并给出刷新引导 |
a / d |
JS 音源列表聚焦时：添加音源 / 移除选中音源（d 需按两次确认） |
h |
JS 音源列表聚焦时：音源体检 |
a / d / r |
本地音乐目录列表聚焦时：添加目录 / 移除选中目录（两次确认）/ 重新扫描 |
Shift+← / Shift+→ |
状态栏字段列表聚焦时：左移 / 右移选中字段 |
内嵌管理列表（JS 音源 / 本地音乐目录 / 状态栏字段 / 扫码登录）的每一个操作都有
可见的命令行按钮，鼠标直接点按钮或列表条目即可；列表里的 Enter 对状态栏字段
是切换开关、对扫码登录是登录 / 退出登录。
上一版的
F1F10、Shift+F1Shift+F8以及整排字母快捷键已删除：
那些设置项现在都在「播放 / 音源与歌词 / 账号与扫码 / 通知与集成 / 下载 / 数据与本地库」
分类里，选中后按Enter即可。用户配置里残留的settings_*绑定会被保留但不再生效
（设置页不再拦截它们，按键会交给全局分发）。
快捷键配置格式
支持：j、Space、Enter、Esc、Up、Down、Left、Right、Home、End、PageUp、PageDown、Delete、F1~`F12，以及 Ctrl+/Shift+/Alt+` 组合。
示例：
[keybindings.global]
quit = "Ctrl+q"
play_pause = "Space"
next_track = "n"
prev_track = "b"
[keybindings.pages.main]
list_select_up = "Up"
list_select_down = "Down"
list_activate = "Enter"修改配置后重新启动 voicefox 即可加载。当前配置与默认值合并，未填写的动作继续使用默认绑定。
