3 步跑通 MusicBox网易云音乐命令行播放器从安装到源码完整指南【免费下载链接】musicbox网易云音乐命令行版本项目地址: https://gitcode.com/gh_mirrors/mu/musicboxMusicBox项目名NetEase-MusicBox是一个用 Python 编写的网易云音乐命令行播放器让你直接在终端里搜索、播放和管理歌曲而不必打开浏览器或桌面客户端。它用字符块渲染出菜单、进度条和歌词支持多档音质、扫码登录、本地缓存甚至能配合 AI Agent 通过命令控制播放。本文带你从装好依赖、扫码登录到读懂核心代码和配置一步步把它真正用起来。 安装依赖与系统环境MusicBox 要求Python 3.10 及以上。真正发声的部分依赖外部解码器按你需要的音质分两档装系统必装MP3可选FLAC / Hi-Res工具macOSmpg123mpvbrew install mpg123 mpv uvUbuntu / Debianmpg123mpvsudo apt-get install mpg123 mpvCentOS / Red Hatmpg123mpvsudo yum install -y mpg123 mpv 低配设备如树莓派建议只装mpg123跳过mpv避免拉入一大串图形/视频依赖。装好系统依赖后推荐用uv或pipx把 MusicBox 装成全局命令uv tool install netease-musicbox # 或 pipx install NetEase-MusicBox想参与开发的话克隆仓库后在目录里执行uv tool install .开发期可加-e实现源码改动即时生效或干脆用uv run musicbox在本地直接跑。项目元数据与依赖都声明在 pyproject.toml 里。 首次运行与扫码登录安装完成后在终端敲musicbox即可进入 TUI 界面第一次进入登录相关功能时终端会画出一个二维码。现在只支持扫码登录不再支持账号密码。用网易云音乐手机 App 扫码并确认Cookie 就会写入数据目录默认~/.netease-musicbox/cookie.txt。几个容易踩的点二维码靠字符块渲染窗口建议 ≥ 25 行并使用等宽字体。必须用手机 App 扫码确认不支持直接打开 URL 完成登录。⌨️ 界面操作与 Vim 风格快捷键MusicBox 的交互逻辑在 menu.py渲染层在 ui.py。它刻意沿用了 Vim 的操作习惯上手后效率很高。几个高频键按键作用j/k下移 / 上移[/]上一曲 / 下一曲Space播放 / 暂停m回到主菜单f当前列表模糊搜索i当前歌曲信息Shift p切换播放模式q退出带数字修饰的快捷键如num j快速跳 n 首、num Shift g跳第 n 首需要先输入数字再按被修饰的键。完整键位表见 README.md 的快捷键章节。 核心模块速览整个播放器都在 NEMbox/ 目录下各文件职责清晰方便按需阅读模块文件职责数据接口api.py封装网易云搜索、歌单、榜单、歌词、播放链接等全部请求播放引擎player.py管理播放队列、模式并在mpg123/mpv两种后端间切换加密处理encrypt.pyEAPI 请求加密与解密登录与接口调用的底层依赖命令行cli.py面向脚本与 AI Agent 的无状态命令入口支持--json输出后台守护daemon.py常驻进程musicboxd持有唯一播放状态通过本地 socket 响应控制指令界面渲染ui.py用 curses 画菜单、进度条、歌词和登录二维码菜单逻辑menu.py处理按键事件、页面跳转与搜索持久化storage.py把用户、收藏、歌曲元数据存进database.json桌面歌词osdlyrics.py基于 Qt 在桌面悬浮窗显示滚动歌词程序入口在main.py带参数时走 CLI 分支不带参数则拉起 TUI而init.py 负责在导入时自动创建好配置、缓存与日志目录保证首次运行就有齐全的文件结构。⚙️ 配置与数据文件路径规则集中在 const.py并遵循 XDG 标准。常用文件如下文件默认位置用途config.json~/.netease-musicbox/config.json主配置音质、后端、快捷键、桌面歌词cookie.txt数据目录下扫码登录后的凭证database.json数据目录下本地收藏、播放历史等数据musicbox.log数据目录下运行日志排错时先查它cached/缓存目录下本地缓存歌曲主配置由 config.py 读写。最常改的两项music_quality音质等级可填数字或名称。值说明0/exhigh极高最高 320kbps3/lossless无损 FLAC4/hires高清臻音 96kHz/24bitjymaster超清母带 192kHz/24bitplayer_backend默认mpg123只播 MP3设为mpv则全程用mpv否则仅 FLAC 自动切到mpv。⚠️ 网易云歌曲接口目前只接受中国大陆访问。如果你在海外需要自行设置代理并确认出口 IP 属于大陆地区后再运行。 进阶CLI 与 AI Agent 控制除了 TUIMusicBox 还能被脚本和 AI Agent 直接驱动。数据类命令搜索、歌单、榜单无状态可单独调用播放控制类命令则依赖后台守护进程 daemon.pymusicbox search 周杰伦 --type song --json musicbox play --id 1847408145 --json musicbox status --json仓库里的 skills/musicbox/SKILL.md 给出了完整的命令速查与「搜歌→播放→读回状态」的操作配方可以让 Cursor、Claude Code 等 Agent 安全地控制播放。注意 TUI 和守护进程互斥二者共用同一把运行锁不能同时启动。 常见问题排错某些歌曲总时长显示00:01通常是版权问题属正常现象。特定终端无法出声先确认同一终端下mpg123能否正常播放再换终端试musicbox定位是解码器还是环境问题。查日志tail -f ~/.local/share/netease-musicbox/musicbox.log实时跟踪运行状态。想更新版本或了解改动细节可参考 CHANGELOG.md项目基于 MIT 协议开源。装好、扫码、敲下musicbox音乐就响在终端里了。【免费下载链接】musicbox网易云音乐命令行版本项目地址: https://gitcode.com/gh_mirrors/mu/musicbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考