Music TUI

在终端里听 QQ 音乐和网易云音乐。扫码登录自己的账号，浏览歌单、搜索歌曲和歌手，用键盘或鼠标控制播放。

Music TUI 支持跨页播放、手动待播、同步歌词、音质选择和播放会话恢复。浏览其他列表时，当前音乐会继续播放。

日间界面 · 歌手详情 · 更新记录

安装

PyPI 包名为 melody-tui，安装后的启动命令为 music-tui。

需要 Python 3.13+、uv 和 mpv。音频由本机 mpv 进程播放。

macOS：

brew install uv mpv
uv tool install --python 3.13 melody-tui
music-tui

Linux 请先用系统包管理器安装 mpv，并安装 uv，再执行上面的 uv tool install 命令。 播放器通过 Unix socket 控制 mpv；当前 CI 验证 Linux 和 macOS。

升级和查看版本：

uv tool upgrade melody-tui
music-tui --version

music-tui -v 同样可以查看版本。查看所有命令行选项：music-tui --help。

第一次听歌

1. 运行 music-tui。首次进入 QQ 音乐，之后沿用上次使用的平台。
2. 按 l，用 QQ 音乐手机 App 扫描终端中的二维码并确认。二维码过期时按 r 刷新。
3. 在左侧选择歌单并按 Enter，再在右侧选歌并按 Enter 播放。
4. 按 Space 暂停或继续，按 n / p 切歌，按 q 退出。

QQ 歌单包含「我喜欢」、自建和收藏歌单。有效登录状态会保存在本机，后续启动会自动检查。 常见的 80×24 终端可以显示主界面和登录页。

按 F2 可在 QQ 音乐与网易云 Enhanced 之间切换。切换会停止当前播放并清空队列，各平台分别保存账号状态。 首次使用网易云请先完成下一节的配置。

网易云音乐配置

默认通过 NeteaseCloudMusicApiEnhanced 接入，不需要申请开发者应用。使用本机服务需要 Node.js 22+ 和 npx。

macOS：

brew install node
music-tui --setup-netease
music-tui --netease-service
music-tui --source netease

向导中选择「本机服务」，它会选择空闲端口并保存地址。第二条 Music TUI 命令才会启动服务。 进入播放器后按 l，用网易云音乐手机 App 扫码确认。

本机服务由 launchd 在后台运行，关闭终端不影响服务，异常退出后会自动重启。 注销或重启电脑后，需要再次运行 music-tui --netease-service。

music-tui --netease-service-status  # 查看服务状态
music-tui --netease-service-stop    # 停止服务

首次启动会下载固定版本 @neteasecloudmusicapienhanced/api@4.41.1。 服务绑定 127.0.0.1，自动设置 ENABLE_GENERAL_UNBLOCK=false 和 ENABLE_PROXY=false。

Linux 等其他系统可手动运行服务，保持该终端开启：

HOST=127.0.0.1 PORT=3000 ENABLE_GENERAL_UNBLOCK=false ENABLE_PROXY=false \
  npx --yes @neteasecloudmusicapienhanced/api@4.41.1

然后在另一个终端运行 music-tui --setup-netease，选择「已有服务」，填写 http://127.0.0.1:3000，再运行 music-tui --source netease。 已有服务必须关闭全局解锁功能。临时覆盖保存的地址可用：

music-tui --source netease --netease-api-url http://127.0.0.1:3000

已有获批应用凭证和设备参数的用户，也可通过命令行使用网易云官方接入：

music-tui --netease-backend official --setup-netease
music-tui --source netease --netease-backend official

官方接入不在 F2 菜单中，暂不支持歌词、喜欢状态和新建歌单；支持向自己的歌单添加歌曲。 详细配置、日志位置和官方接入参数见网易云配置指南。

日常操作

找歌与管理歌单

• 按 / 输入歌名或歌手并回车，进行全站搜索。
• 打开歌单后按 f，按歌名或歌手筛选整个歌单，包含尚未浏览的分页。清空输入并回车恢复完整歌单。
• 按 [ / ] 翻页，也可点击列表下方的翻页按钮。先按 Esc 将焦点移出输入框。
• 点击歌手名或按 i 进入歌手详情，查看简介和歌曲；热门／最新排序覆盖整个歌手歌曲列表。按 Esc 返回原页面。
• 按 s 喜欢或取消喜欢选中歌曲，按 w 加入已有可写歌单，按 Ctrl+N 新建歌单。加入歌曲时也可选择新建歌单。

搜索结果的 ♥ / ♡ / ? 分别表示已喜欢、未喜欢和状态未知。点击标记也能切换喜欢状态。 按 Ctrl+R 刷新当前列表和喜欢状态；查询失败时显示未知，修改失败时保留上次确认的状态。

点击歌曲、歌手或时长表头可排序，点击「序」恢复原顺序；o 也可切换本页排序。 歌曲排序只影响当前页显示，播放仍按来源顺序。歌单侧栏可按名称或累计播放量排序。

播放队列与手动待播

从歌单、搜索结果、筛选结果或歌手歌曲列表中选歌播放，会以该列表建立队列，并从所选歌曲开始跨页播放。 浏览其他列表或筛选歌曲不会改变队列；再次选歌播放才会替换队列。

按 r 切换顺序播放、列表循环、单曲循环和随机播放。顺序播放到末尾停止；随机播放按轮打乱，每轮不重复，p 可返回播放历史中的上一首。

浏览时选中歌曲并按 a 加入手动待播。它们按添加顺序优先播放，听完继续原列表。 按 F3 查看队列，在队列页可以：

开始新列表或切换平台会清空手动待播。按 g 返回当前播放来源，并定位歌曲。

播放页、歌词与音质

按 F7 打开独立播放页，通过「概览 / 歌词 / 队列」页签查看封面、歌曲信息、同步歌词和待播内容。 按 F4 直接查看歌词，支持可用译文；没有时间信息的歌词可手动滚动。按 F7 或 Esc 返回浏览页，音乐继续播放。

按 u 查看当前歌曲可用的音质，未播放时查看选中歌曲。 播放中切换音质会保留进度和暂停状态；后续歌曲继续使用首选音质。 音质取决于歌曲音源、账号和会员权限。首选音质不可用时，逐档尝试至标准音质，并显示实际音质；下一首仍从首选档开始。 网络、登录或播放器错误不会触发降档。所有档位都失败时显示具体错误，等待重试或手动切歌。

继续上次播放与最近记录

音量、音质和播放模式按平台保存。队列、手动待播、筛选结果、随机历史和进度按平台与账号分别保存。 重新启动后按 F6 继续上次会话，应用会重新获取播放地址；启动时不会自动播放。

按 F8 查看当前账号的最近播放，按 Enter 以单曲队列重播。 Tab 切换最近歌曲／来源，o 打开原来源并保留当前播放。最多保留 100 首歌曲，匿名播放不写入历史。

快捷键速查

输入框内可以正常输入空格和字母；按 Esc 返回歌曲区域后再使用字母快捷键。F1 可随时打开帮助。

底部的上一首、暂停／继续、下一首按钮也可直接点击。主题默认跟随系统，手动选择会保存。

常见问题

本机数据

以下为默认路径。数据文件支持 XDG_DATA_HOME，配置文件支持 XDG_CONFIG_HOME；登录凭证和播放状态文件权限为 0600。

会话和历史只保存恢复播放所需的曲目信息、来源及状态，不保存 Cookie 或播放地址。 删除对应平台的登录凭证可清除本机保存的登录状态。修改服务配置后需重新启动播放器。

从源码运行与开发

git clone https://github.com/FlyTOmeLight/music-tui.git
cd music-tui
uv sync --locked
uv run music-tui

源码运行时，将上文的 music-tui 命令替换为 uv run music-tui 即可。 项目使用 Textual 构建界面、QQMusicApi 访问 QQ 音乐接口、mpv 播放音频，依赖版本由 uv.lock 固定。

修改 Python 代码后运行 Black，交付前执行：

uv run black src tests
uv run black --check src tests
uv run ruff check src tests
uv run pytest -q
uv build
bash scripts/check_install.sh

测试使用离线音乐响应；mpv 集成测试播放本地生成的静音 WAV。 GitHub Actions 在 Linux/macOS 上执行检查、构建及仓库外安装验证。 已登录 QQ 的开发者还可运行 uv run python scripts/check_live_ui.py，验证真实播放与不同终端尺寸的布局。

项目结构 · 开发约定 · 网易云接入说明 · 反馈问题

许可证：GPL-3.0-or-later。