youtube-music-cli：终端音乐播放器

项目简介

youtube-music-cli 是一个基于 TypeScript、React 和 Ink 构建的终端（TUI）YouTube Music 播放器。它把搜索、播放、队列管理、收藏、下载等操作全部放进命令行界面，适合习惯在终端里工作、又不想切换窗口听歌的用户。除了交互式 TUI，它还提供命令行子命令与浏览器端伴侣界面。

主要功能

• 终端界面：基于 Ink 的富终端 UI，支持 vim 风格键盘导航
• 搜索：查找歌曲、专辑、艺人和播放列表
• 队列管理：构建并管理播放队列，支持随机播放与循环模式
• 收藏：用 f 标记收藏，Shift+F 查看
• 音量控制：细粒度调节音量
• 智能推荐：根据当前曲目发现相关歌曲
• 主题：Dark、Light、Midnight、Matrix 四种主题
• 插件系统：可通过插件扩展功能
• 沉浸模式：--win32 启动全屏播放器，带音频可视化与 disco 效果
• 网页伴侣：--web 在浏览器中提供同步的播放控制、队列、搜索、音量等界面
• 播放列表同步：ymc sync 把 YouTube Music 播放列表同步到本地配置
• 下载：Shift+D 保存曲目、播放列表或艺人
• 收听统计：按 o 查看总时长、热门曲目/艺人、连续收听天数，并可用 S / E 分享
• 元数据标签：自动写入标题、艺人、专辑，可选封面
• Shell 补全：ymc completions <bash|zsh|powershell|fish> 生成补全脚本

安装与使用

需先安装 mpv（音频播放）与 yt-dlp（音频提取）：

# macOS
brew install mpv yt-dlp
# Ubuntu/Debian
sudo apt install mpv && pip install yt-dlp

再安装本工具（也提供 Homebrew、Scoop、安装脚本与 GitHub Releases 二进制）：

npm install -g @involvex/youtube-music-cli

启动交互式界面：

youtube-music-cli

常用命令：

youtube-music-cli play <video-id|youtube-url>
youtube-music-cli search "artist or song name"
youtube-music-cli playlist <playlist-id>
ymc sync <playlist-id|ytm-url>
ymc login

开启网页伴侣：

youtube-music-cli --web          # 默认 http://localhost:3000
youtube-music-cli --web-only     # 仅网页界面

登录可选，使用 OAuth2 Device Flow 或 cookie 方式（ymc login --cookies-from-browser edge）后可访问个人库、播放列表等个性化功能。

注意事项

• 必须先安装 mpv 和 yt-dlp，否则无法播放。
• 凭据保存在 ~/.youtube-music-cli/credentials.json，Unix 系统下权限为 0600。
• Linux 打包时，用 bun build --compile 生成的二进制不可 strip，否则会丢失内嵌的 JS/TS 代码；npm 包不受此限制。
• Windows 上从浏览器提取 cookie 依赖 Python 回退方案，若失败可改用 --cookies-file 传入导出的 cookies.txt。

---

本作品整理自 GitHub 开源项目 involvex/youtube-music-cli，原作者 @involvex，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。