CloudMusic

CloudMusic 是一个网易云音乐终端客户端，提供两套可直接使用的界面：

• cloudmusic：基于 Textual 的分栏 TUI
• cloudmusic-ascii：纯 ASCII 复古 CLI

项目同时附带 musicctl 命令行工具、Rofi / Waybar bridge、歌单导出/下载能力，以及一键本地安装脚本。

功能概览

• 双界面：Fancy Textual TUI + Retro ASCII CLI
• 播放控制：播放 / 暂停 / 上下首 / 停止 / 快进后退 / 音量 / 循环 / 随机
• 资源浏览：我的歌单、排行榜、每日推荐、私人 FM、云盘歌曲、推荐歌单
• 内容管理：新建/重命名/删除歌单，添加/移除歌曲，收藏歌曲/歌单/专辑/歌手
• 元数据功能：歌词、歌曲详情、评论、专辑页、歌手页
• 下载与导出：歌曲下载、歌单下载、JSON / CSV / M3U 导出
• 桌面集成：musicctl bridge、scripts/RofiBeats_CloudMusic.sh

依赖

运行时至少需要：

• python 3.10+
• 一个可用播放器，推荐 mpv

可选播放器与集成组件：

• mpv：推荐，功能最完整
• ffmpeg：提供 ffplay 作为兜底播放器
• vlc：提供 vlc / cvlc 兜底播放器
• rofi：Rofi / RofiBeats 菜单集成
• qrencode、wl-clipboard、libnotify：提升 QR 登录辅助体验

安装

方式一：本地一键安装

git clone https://github.com/vimalinx/CloudMusic.git
cd CloudMusic
./install.sh
source ~/.zshrc

安装完成后常用命令：

cloudmusic
cloudmusic-ascii
cloudmusic-start
musicctl

方式二：开发/源码安装

git clone https://github.com/vimalinx/CloudMusic.git
cd CloudMusic
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

方式三：Arch / AUR 打包文件

仓库内已附带 cloudmusic-git 的 AUR 打包文件：

• packaging/aur/cloudmusic-git/PKGBUILD
• packaging/aur/cloudmusic-git/.SRCINFO

如果 AUR 包已发布，可直接安装：

yay -S cloudmusic-git

如果只是本地试打包：

cd packaging/aur/cloudmusic-git
makepkg -si

先登录，再进 TUI

当前推荐先用 musicctl 完成登录，再启动图形 TUI / ASCII CLI。

自动导入浏览器 Cookie

musicctl login-auto
musicctl whoami

也可以指定浏览器：

musicctl login-auto --browser chrome
musicctl login-auto --browser chromium --profile "Default"

QR 登录

musicctl login-qr
musicctl whoami

手动 Cookie 登录

musicctl login --cookie 'MUSIC_U=xxx; __csrf=yyy'
musicctl whoami

退出登录

musicctl logout

启动方式

Fancy TUI

cloudmusic
# 或
cloudmusic --fancy
# 或
musicctl tui-full

Retro ASCII CLI

cloudmusic-ascii
# 或
musicctl tui-full --retro

启动器

./start.sh
./start.sh fancy
./start.sh ascii

常用操作

Fancy TUI 关键键位

• Enter：执行当前区域动作；在歌单区打开歌单，在歌曲区播放当前歌曲
• Tab / Shift+Tab：切换区域焦点
• Ctrl+1/2/3/4：快速聚焦歌单 / 歌曲 / 搜索 / 音量
• Space：播放 / 暂停
• n / p：下一首 / 上一首
• x：停止播放
• , / .：后退 / 前进 10 秒
• s / l：随机 / 循环
• /：聚焦本地筛选
• Ctrl+f：云搜索
• ?：键位帮助
• q：退出

Retro ASCII CLI 关键键位

• Tab / ← / →：切换 pane
• j / k / ↑ / ↓：移动选择
• Enter：歌单 pane 里加载歌单；歌曲 pane 里播放歌曲
• Space：播放 / 暂停
• n / p：下一首 / 上一首
• l：循环
• x：随机
• + / -：调节速度
• s：停止
• r：刷新
• q：退出

musicctl CLI

搜索

musicctl search "周杰伦"

歌单操作

musicctl playlist ls --uid <uid>
musicctl playlist create "夜间循环"
musicctl playlist rename --id <playlist_id> --name "新名字"
musicctl playlist delete --id <playlist_id>

导出 / 下载

musicctl playlist pull --id <playlist_id> --format json
musicctl playlist sync --dir ./exports/sync
musicctl song download --id <song_id> --out ./song.mp3
musicctl playlist download --id <playlist_id> --dir ./downloads

播放

musicctl play url 20744694
musicctl play url 20744694 --play
musicctl play stop

Rofi / Waybar / RofiBeats 集成

Bridge 命令

musicctl bridge status
musicctl bridge search --keyword "周杰伦" --limit 20
musicctl bridge play --song-id 210049
musicctl bridge playlists --limit 50
musicctl bridge playlist-tracks --playlist-id 123456 --limit 200
musicctl bridge control --action play-pause
musicctl bridge play-playlist --playlist-id 123456 --start-song-id 654321

项目附带脚本

scripts/RofiBeats_CloudMusic.sh
scripts/cloudmusic_qr_helper.sh

这两个脚本现在同时支持：

• 仓库内直接运行
• 系统安装后通过 musicctl 运行

AUR / 系统安装场景下，建议的命令名是：

cloudmusic-rofi
cloudmusic-qr-helper

配置文件

配置文件位置：~/.config/cloudmusic/config.yaml

quality: exhigh
download_dir: ~/Music/CloudMusic
max_concurrent_downloads: 5
theme: dark
volume: 70
loop_mode: all
shuffle: false
base_url: https://music.163.com

说明：

• theme 支持：dark、light、dracula、nord、retro
• volume 会被限制在 0..100
• ASCII 模式默认使用 retro 主题

已验证内容

当前仓库最近一次完整回归包括：

• pytest：87 passed
• python -m compileall cloudmusic cli tests
• bash -n：安装脚本 / 启动脚本 / Rofi 脚本 / QR helper
• 真机冒烟：musicctl whoami、bridge playlists、bridge search、bridge play
• TUI 冒烟：Fancy / ASCII 都能成功启动

开发

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

相关文档

• QUICK_START.md
• CHANGELOG.md
• ROFIBEATS_INTEGRATION.md
• CONTRIBUTING.md