Skip to content
Back to search

musicbox

网易云音乐命令行版本

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/darknessomi--musicbox/badge.svg)](/listings/darknessomi--musicbox)

HTML

<a href="/listings/darknessomi--musicbox"><img src="/api/listings/darknessomi--musicbox/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

推荐用 [uv](https://docs.astral.sh/uv/) 或 [pipx](https://pipx.pypa.io/) 安装为全局命令 `musicbox`;参与开发见下文「本地开发」。

环境要求

- Python 3.10 及以上 - `mpg123`(MP3)、`mpv`(可选,FLAC / Hi-Res)

安装系统依赖

macOS:

brew install mpg123 mpv uv

Ubuntu/Debian:

sudo apt-get install mpg123 mpv

CentOS/Red Hat:

sudo yum install -y python3-devel mpg123 mpv

安装 MusicBox

**PyPI**(可能落后于源码):

uv tool install netease-musicbox
# 或 pipx install NetEase-MusicBox

**源码**(全局命令;改代码后需重装,开发期可用 `-e`):

git clone https://github.com/darknessomi/musicbox.git
cd musicbox
uv tool install .      # 或 pipx install .
uv tool install -e .   # 可编辑安装,源码改动即时生效

**本地开发**(不装全局命令):

git clone https://github.com/darknessomi/musicbox.git
cd musicbox
uv sync
uv run musicbox

可选依赖

- `aria2`:缓存歌曲 - `libnotify-bin`:Linux 消息提示 - `qtpy python-dbus dbus qt`:桌面歌词。根据系统 Qt 版本,可能还需要安装 `pyqt4`、`pyside` 或 `pyside2`

树莓派 / 老旧设备

Ubuntu 22.04 / 64 位树莓派系统自带 Python 3.10,可用 `pipx` 直接安装。低性能设备建议先只装 MP3 播放必需依赖,避免一次性拉取 `mpv` 的大量图形/视频依赖:

sudo apt-get update
sudo apt-get install -y --no-install-recommends pipx mpg123
pipx ensurepath
pipx install NetEase-MusicBox
musicbox

> 注意:项目要求 Python 3.10 及以上;旧版 Raspberry Pi OS / Debian 如果仍是 Python 3.9,不能直接安装当前版本。 >

已验证系统

- Ubuntu 24.04 LTS x64 - macOS 26.5 - Raspberry Pi 4 / Ubuntu 22.04 arm64(Docker 镜像:`balenalib/raspberrypi4-64-ubuntu:jammy`)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 241 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # NetEase-MusicBox
  2. [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
  3. ![PyPI - Version](https://img.shields.io/pypi/v/NetEase-MusicBox)
  4. ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/NetEase-MusicBox)
  5. 高品质网易云音乐命令行客户端,基于 Python 编写。
  6. 感谢为 MusicBox 的开发付出过努力的[每一个人](https://github.com/darknessomi/musicbox/graphs/contributors)。
  7. 网易云音乐 API 能力由 [NeteaseCloudMusicApiEnhanced/api-enhanced](https://github.com/neteasecloudmusicapienhanced/api-enhanced) 提供支持。
  8. ## Demo
  9. [![NetEase-MusicBox-GIF](demo.gif)](https://pypi.org/project/NetEase-MusicBox/)
  10. ## 功能特性
  11. - 支持多档音质播放:MP3(极高/较高/标准)及无损、高清臻音、超清母带等 FLAC,安装 `mpv` 后自动切换
  12. - 支持歌曲、艺术家、专辑、本地列表模糊搜索
  13. - 支持排行榜、新碟上架、精选歌单、主播电台、我的歌单、我的云盘、私人 FM 和每日推荐
  14. - 支持本地收藏、歌曲评论、专辑跳转、随心打碟和定时退出
  15. - 支持播放进度、播放模式、当前/历史播放列表和桌面歌词显示
  16. - 支持 Vim 风格快捷键、数字快捷键和自定义全局快捷键
  17. ## 安装
  18. 推荐用 [uv](https://docs.astral.sh/uv/) 或 [pipx](https://pipx.pypa.io/) 安装为全局命令 `musicbox`;参与开发见下文「本地开发」。
  19. ### 环境要求
  20. - Python 3.10 及以上
  21. - `mpg123`(MP3)、`mpv`(可选,FLAC / Hi-Res)
  22. ### 安装系统依赖
  23. macOS:
  24. ```bash
  25. brew install mpg123 mpv uv
  26. ```
  27. Ubuntu/Debian:
  28. ```bash
  29. sudo apt-get install mpg123 mpv
  30. ```
  31. CentOS/Red Hat:
  32. ```bash
  33. sudo yum install -y python3-devel mpg123 mpv
  34. ```
  35. ### 安装 MusicBox
  36. **PyPI**(可能落后于源码):
  37. ```bash
  38. uv tool install netease-musicbox
  39. # 或 pipx install NetEase-MusicBox
  40. ```
  41. **源码**(全局命令;改代码后需重装,开发期可用 `-e`):
  42. ```bash
  43. git clone https://github.com/darknessomi/musicbox.git
  44. cd musicbox
  45. uv tool install . # 或 pipx install .
  46. uv tool install -e . # 可编辑安装,源码改动即时生效
  47. ```
  48. **本地开发**(不装全局命令):
  49. ```bash
  50. git clone https://github.com/darknessomi/musicbox.git
  51. cd musicbox
  52. uv sync
  53. uv run musicbox
  54. ```
  55. ### 可选依赖
  56. - `aria2`:缓存歌曲
  57. - `libnotify-bin`:Linux 消息提示
  58. - `qtpy python-dbus dbus qt`:桌面歌词。根据系统 Qt 版本,可能还需要安装 `pyqt4`、`pyside` 或 `pyside2`
  59. ### 树莓派 / 老旧设备
  60. Ubuntu 22.04 / 64 位树莓派系统自带 Python 3.10,可用 `pipx` 直接安装。低性能设备建议先只装 MP3 播放必需依赖,避免一次性拉取 `mpv` 的大量图形/视频依赖:
  61. ```bash
  62. sudo apt-get update
  63. sudo apt-get install -y --no-install-recommends pipx mpg123
  64. pipx ensurepath
  65. pipx install NetEase-MusicBox
  66. musicbox
  67. ```
  68. > 注意:项目要求 Python 3.10 及以上;旧版 Raspberry Pi OS / Debian 如果仍是 Python 3.9,不能直接安装当前版本。
  69. >
  70. ### 已验证系统
  71. - Ubuntu 24.04 LTS x64
  72. - macOS 26.5
  73. - Raspberry Pi 4 / Ubuntu 22.04 arm64(Docker 镜像:`balenalib/raspberrypi4-64-ubuntu:jammy`)
  74. ## 使用
  75. 启动 MusicBox:
  76. ```bash
  77. musicbox
  78. ```
  79. 进入需要登录的功能时,终端会显示二维码。登录方式仅支持扫码登录,已不再支持账号密码登录。
  80. 1. 用网易云音乐手机 App 扫描二维码,并在手机上确认。
  81. 2. 登录成功后 Cookie 写入 `~/.local/share/netease-musicbox/cookie.txt`(未设置 `XDG_DATA_HOME` 时为 `~/.netease-musicbox/cookie.txt`)。
  82. 终端以字符块渲染二维码,窗口建议 ≥25 行、等宽字体。必须使用网易云音乐 App 扫描二维码并在手机上确认,不支持打开 URL 完成登录。
  83. ## CLI 与 AI Agent
  84. MusicBox 支持命令行和 AI Agent 调用:搜索歌曲、获取播放链接、播放控制、查询状态和登录都可以通过 `musicbox` 命令完成。
  85. ```bash
  86. musicbox search 邓丽君 --type song --json
  87. musicbox artist 6452 --limit 10 --json
  88. musicbox album 32311 --json
  89. musicbox song url 1847408145 --quality lossless --quiet
  90. musicbox play --id 1847408145 --json
  91. musicbox play --artist 6452 --limit 10
  92. musicbox play --album 32311
  93. musicbox play --songs 33894312 28258988
  94. musicbox pause --json
  95. musicbox status --json
  96. musicbox queue list --json
  97. musicbox auth login --no-wait --json
  98. musicbox download --playlist 3778678 --path ./music --json
  99. ```
  100. 安装 Agent Skill 后,可直接让 Codex、Claude Code、Cursor 等 Agent 操作 MusicBox:
  101. ```bash
  102. npx skills add darknessomi/musicbox -y
  103. ```
  104. ## 快捷键
  105. 带 `num +` 的快捷键支持数字修饰,先输入数字,再输入被修饰的按键。
  106. | 按键 | 功能 | 说明 |
  107. | --- | --- | --- |
  108. | `j` | Down | 下移 |
  109. | `k` | Up | 上移 |
  110. | `num + j` | Quick Jump | 快速向后跳转 n 首 |
  111. | `num + k` | Quick Up | 快速向前跳转 n 首 |
  112. | `h` | Back | 后退 |
  113. | `l` | Forward | 前进 |
  114. | `u` | Prev Page | 上一页 |
  115. | `d` | Next Page | 下一页 |
  116. | `f` | Search | 当前列表模糊搜索 |
  117. | `[` | Prev Song | 上一曲 |
  118. | `]` | Next Song | 下一曲 |
  119. | `num + [` | Quick Prev Song | 快速前 n 首 |
  120. | `num + ]` | Quick Next Song | 快速后 n 首 |
  121. | `num + Shift + g` | Index for Song | 跳到第 n 首 |
  122. | `=` | Volume + | 音量增加 |
  123. | `-` | Volume - | 音量减少 |
  124. | `Space` | Play/Pause | 播放/暂停 |
  125. | `?` | Shuffle | 手气不错 |
  126. | `m` | Menu | 主菜单 |
  127. | `p` | Present/History | 当前/历史播放列表 |
  128. | `i` | Music Info | 当前音乐信息 |
  129. | `Shift + p` | Playing Mode | 播放模式切换 |
  130. | `a` | Add | 添加曲目到打碟 |
  131. | `Shift + a` | Enter Album | 进入专辑 |
  132. | `g` | To the First | 跳至首项 |
  133. | `Shift + g` | To the End | 跳至尾项 |
  134. | `z` | DJ List | 打碟列表 |
  135. | `s` | Star | 添加到收藏 |
  136. | `c` | Collection | 收藏列表 |
  137. | `r` | Remove | 删除当前条目 |
  138. | `Shift + j` | Move Down | 向下移动当前项目 |
  139. | `Shift + k` | Move Up | 向上移动当前项目 |
  140. | `Shift + c` | Cache | 缓存歌曲到本地 |
  141. | `,` | Like | 喜爱 |
  142. | `.` | Trash FM | 删除 FM |
  143. | `/` | Next FM | 下一 FM |
  144. | `q` | Quit | 退出 |
  145. | `t` | Timing Exit | 定时退出 |
  146. | `w` | Quit & Clear | 退出并清除用户信息 |
  147. ## 配置
  148. 配置文件位于 `~/.netease-musicbox/config.json`,可配置缓存、快捷键、消息提示和桌面歌词。
  149. 无损播放相关配置:
  150. - `music_quality`:音质等级,可填数字或 level 名称。
  151. | 配置值 | 说明 |
  152. | --- | --- |
  153. | `jymaster` | 超清母带,192kHz/24bit |
  154. | `4` / `hires` | 高清臻音,96kHz/24bit |
  155. | `3` / `lossless` | 无损,最高 48kHz/16bit |
  156. | `0` / `exhigh` | 极高,最高 320kbps |
  157. | `1` / `higher` | 较高,192kbps |
  158. | `2` / `standard` | 标准,128kbps |
  159. - `player_backend`:默认 `mpg123`;设为 `mpv` 则全程用 `mpv`,否则仅 FLAC 自动切到 `mpv`。
  160. - `mpv_parameters`: 传给 `mpv` 的额外参数列表。
  161. 由于歌曲 API 只接受中国大陆地区访问,非中国大陆地区用户需要自行设置代理。可用 polipo 将 socks5 代理转换成 http 代理:
  162. ```bash
  163. export http_proxy=http://IP:PORT
  164. export https_proxy=http://IP:PORT
  165. curl -L ip.cn
  166. ```
  167. 确认显示 IP 属于中国大陆地区即可。
  168. ## 排错
  169. - 某些歌曲不能播放且总时长为 `00:01` 时,通常是版权问题。
  170. - 特定终端不能播放时,先检查同一终端下 `mpg123` 能否正常使用,再检查其他终端下 `musicbox` 能否正常使用。报告 issue 时请附上这些检查结果和终端报错。
  171. - 可通过 `tail -f ~/.local/share/netease-musicbox/musicbox.log` 查看日志。
  172. ## 更新日志
  173. 详见 [CHANGELOG.md](CHANGELOG.md)。
  174. ## License
  175. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.