🌀 Maboroshi (幻) - 终端音乐播放器

一个基于 Rust 和 TUI 的轻量级音乐播放器，通过 yt-dlp 支持 YouTube、Bilibili 等多平台搜索和播放音乐。

🚀 快速开始

# macOS 一键安装
curl -fsSL https://raw.githubusercontent.com/KayneWang/maboroshi/main/install.sh | sh

# 安装依赖（必需）
brew install yt-dlp mpv

# 运行
maboroshi

Windows 用户请参考 Windows 安装与方式 3：从源码编译。

✨ 特性

🔍 多源音乐搜索 - 支持 YouTube、Bilibili 等多个平台搜索并播放音乐
⚙️ 配置文件支持 - 自定义搜索源、缓存大小、音量步长等参数
📁 多分组收藏夹 - 按名称创建多个分组（如「薛之谦」、「纯音乐」），支持重命名、删除、移动歌曲、一键批量收藏
🔄 多种播放模式 - 随机播放、单曲循环、列表循环、顺序播放
🎯 智能缓存 - 搜索结果分页缓存 + 音频 URL 缓存，翻页和重播更流畅
🔊 实时音量控制 - +/- 调节音量，通过 mpv IPC 实时同步
📋 实时日志 - 仅记录关键操作结果和错误，不展示过程噪音
🎨 美观界面 - 简洁的 TUI 界面，状态一目了然

📦 依赖

在使用前，请确保系统已安装以下工具：

yt-dlp - 用于搜索和获取音频流
mpv - 音频播放器

macOS 安装

brew install yt-dlp mpv

Windows 安装

推荐使用 Scoop 安装依赖，它会自动把 mpv.exe / yt-dlp.exe 注册到 %PATH%：

# 安装 Scoop（如果没装过）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

# 安装 mpv 和 yt-dlp
scoop install mpv yt-dlp

⚠️ 不建议用 winget install mpv.net —— mpv.net 是 GUI 前端，不会把命令行 mpv.exe 加到 PATH。如果必须用 winget，请选择官方 mpv 源或手动把 mpv.exe 所在目录加到 %PATH%。

安装完重新打开 PowerShell 让 PATH 生效，验证：

mpv --version
yt-dlp --version

建议在 Windows Terminal 下运行以获得正确的 UTF-8 与颜色显示。

🛠️ 从源码构建（cargo install）时还需要 Visual Studio Build Tools（勾选"使用 C++ 的桌面开发"工作负载）才能找到 MSVC linker (link.exe)。下载：https://visualstudio.microsoft.com/visual-cpp-build-tools/。如果想避免装 VS，也可以切换到 GNU 工具链：rustup toolchain install stable-x86_64-pc-windows-gnu && rustup default stable-x86_64-pc-windows-gnu，但需要 scoop install mingw。

🚀 安装

方式 1：下载预编译二进制（推荐）

从 Releases 页面下载适合你系统的二进制文件：

macOS (Apple Silicon)

# 下载最新版本
curl -L https://github.com/KayneWang/maboroshi/releases/latest/download/maboroshi-macos-aarch64 -o maboroshi

# 添加执行权限
chmod +x maboroshi

# 移动到系统路径（可选）
sudo mv maboroshi /usr/local/bin/

macOS (Intel)

curl -L https://github.com/KayneWang/maboroshi/releases/latest/download/maboroshi-macos-x86_64 -o maboroshi
chmod +x maboroshi
sudo mv maboroshi /usr/local/bin/

Windows (x86_64)

# 下载最新版本
Invoke-WebRequest -Uri https://github.com/KayneWang/maboroshi/releases/latest/download/maboroshi-windows-x86_64.exe -OutFile maboroshi.exe

# 把所在目录加到 %PATH%，或直接放到已在 PATH 的目录中（例如 Scoop 的 ~/scoop/apps/<bin>）

方式 2：一键安装脚本

curl -fsSL https://raw.githubusercontent.com/KayneWang/maboroshi/main/install.sh | sh

方式 3：从源码编译

# 克隆仓库
git clone https://github.com/KayneWang/maboroshi.git
cd maboroshi

# 编译并安装
cargo install --path .

Windows 用户也可直接走方式 1 下载预编译二进制；从源码构建需要先安装 Rust 工具链。maboroshi --upgrade 在 Windows 下为 no-op，升级请重新下载二进制，或在源码目录执行 git pull && cargo install --path .。

安装后可以直接运行：

maboroshi

🎮 使用方法

命令行选项

maboroshi              # 启动音乐播放器
maboroshi --version    # 显示版本信息
maboroshi --upgrade    # 升级到最新版本（仅 Unix；Windows 下打印手动升级提示）
maboroshi --help       # 显示帮助信息

基本操作

按键	功能
`s`	进入搜索模式
`Enter`	确认搜索 / 播放选中的歌曲
`Esc`	取消搜索 / 返回收藏列表
`↑` / `↓`	列表选歌 / 搜索模式下浏览历史记录
`←` / `→`	搜索结果：上一页/下一页 \| 播放：快退/快进
`Space`	暂停/继续播放
`+` / `-`	增大/减小音量（步长可配置，默认 ±5%）
`f`	收藏/取消收藏（播放中）；移除选中收藏（浏览时）
`F`	将搜索结果全部收藏到当前激活分组
`m`	切换播放模式
`q`	退出播放器

收藏分组管理

按键	功能
`Tab`	切换到下一个分组
`Shift+Tab`	切换到上一个分组
`g`	新建分组（输入名称后 Enter 确认）
`R`	重命名当前分组（预填当前名称，可直接修改）
`D`	删除当前分组（需按 `y` 二次确认）
`M`	将选中歌曲移动到其他分组（浮层选择目标分组）

播放模式

随机播放 - 随机播放收藏列表中的歌曲（默认）
单曲循环 - 重复播放当前歌曲
列表循环 - 循环播放收藏列表
顺序播放 - 顺序播放收藏列表，播完停止

使用流程

搜索音乐
- 按 s 进入搜索模式
- 输入歌曲名或歌手名
- 按 Enter 确认搜索
- 系统会显示搜索结果（数量由配置的 max_results 决定，默认 15 条）
浏览搜索结果
- 使用 ↑ ↓ 键在当前页选择歌曲
- 使用 ← → 键翻页浏览更多结果
- 支持智能缓存，已访问的页面会瞬间加载
- 按 Enter 播放选中的歌曲
收藏分组管理
- 在搜索结果页按 f 收藏单首歌曲，按 F 一键全部收藏当前页所有结果
- 收藏会自动保存到 ~/.maboroshi_favorites.json
- 在收藏列表界面：
  - Tab / Shift+Tab 切换分组
  - g 新建分组，R 重命名，D 删除（二次确认）
  - M 将选中歌曲移动到其他分组
  - f 直接移除选中歌曲
Playlist 工作流（歌单导入） Maboroshi 支持直接解析 YouTube 或 Bilibili 的歌单（Playlist）链接，这是批量导入歌曲最快的方式：
- 复制外部歌单的 URL（例如 YouTube Playlist 链接）
- 按 s 进入搜索模式，粘贴链接并按 Enter
- 等待解析完成，结果页会展示歌单内的所有歌曲
- 按大写 F，一键将整张歌单全部保存到当前你所在的分组（自动跳过重复歌曲）
- 提示：结合"分组管理"功能，你可以先按 g 创建一个新分组（比如"日系摇滚"），然后再执行上述导入操作，轻松实现歌单的本地归档。
列表播放
- 在收藏列表中使用 ↑ ↓ 选择歌曲
- 按 Enter 播放
- 歌曲播放完毕会自动播放下一首（根据播放模式）

🗂️ 文件位置与缓存清理

配置文件: ~/.config/maboroshi/config.toml
收藏列表: ~/.maboroshi_favorites.json（含所有分组数据）
离线音频缓存: ~/.cache/maboroshi/audio/（用于秒开已播放歌曲）
URL 缓存: 内存中（重启后清空）
mpv IPC 端点: Unix 下为 /tmp/maboroshi.sock，Windows 下为 \\.\pipe\maboroshi 命名管道（可配置）

Windows 下 ~ 会展开为 %USERPROFILE%，例如 C:\Users\<name>\.config\maboroshi\config.toml、C:\Users\<name>\.maboroshi_favorites.json。

🧹 清理音频缓存

为了实现"越用越快"和节省流量，程序会在后台将播放过的音频缓存到本地（受配置项 offline_audio 控制）。注意：取消收藏不会自动删除对应的缓存文件。如果你发现硬盘占用过大，可以直接清空缓存目录：

rm -rf ~/.cache/maboroshi/audio/*

⚙️ 配置文件

Maboroshi 支持通过配置文件自定义行为。首次运行时会自动在 ~/.config/maboroshi/config.toml 创建默认配置文件。

配置示例

[search]
# 搜索源：youtube 或 bilibili
source = "youtube"
max_results = 15
timeout = 30
cookies_browser = "chrome"   # 留空 "" 则不使用浏览器 cookies（Windows 推荐）
cookies_file = ""            # 预先导出的 cookies.txt 路径，支持 ~ 展开

[cache]
url_cache_size = 30
url_cache_ttl = 7200  # 2 小时

[network]
play_timeout = 10

[playback]
default_mode = "shuffle"  # shuffle, single, list_loop, sequential
seek_seconds = 10         # 快进/快退秒数
volume_step = 5           # 每次按 +/- 调整的音量步长（0–130）

[paths]
socket_path = "/tmp/maboroshi.sock"
favorites_file = "~/.maboroshi_favorites.json"

支持的搜索源

Maboroshi 支持所有 yt-dlp 兼容的平台，常用选项包括：

YouTube (source = "yt" 或 "youtube"): 默认搜索源
Bilibili (source = "bili"): 哔哩哔哩视频平台
SoundCloud (source = "soundcloud"): 音乐分享平台
Spotify (source = "spotify"): 需要账号登录
Bandcamp (source = "bandcamp"): 独立音乐平台
Niconico (source = "niconico"): ニコニコ動画

也可以直接使用 yt-dlp 的搜索前缀格式（如 "ytsearch"、"bilisearch" 等）。

完整支持列表请查看: yt-dlp 支持的网站

更多配置选项请参考 config.example.toml

🐛 故障排除

搜索失败

确保 yt-dlp 已正确安装并在 PATH 中
检查网络连接
尝试更新 yt-dlp: brew upgrade yt-dlp 或 pip install -U yt-dlp

播放失败

确保 mpv 已正确安装
检查 IPC 端点是否被占用：Unix 下为 /tmp/maboroshi.sock，Windows 下为 \\.\pipe\maboroshi
查看日志区域的错误信息

Chrome Cookie 问题

如果遇到 YouTube 访问限制，yt-dlp 会自动使用 Chrome 的 cookies。确保：

Chrome 浏览器已安装
已登录 YouTube 账号

Windows 下 Chrome cookie 读取失败

Chrome 127+ 启用了 App-Bound Encryption，yt-dlp 在 Windows 上无法直接读取 Chrome cookie，表现为搜索失败、日志里出现 Could not copy Chrome cookie database（参考 yt-dlp#7271）。

解决方式任选其一：

不用 cookies：把 config.toml 里的 cookies_browser 改为 ""（默认已是空值）。对非年龄限制内容足够。
改用 Firefox：cookies_browser = "firefox"（Firefox 不受 App-Bound Encryption 影响）。
关闭 Chrome 后再运行：最省事，但每次都要关。
给 Chrome 加启动参数：右键 Chrome 快捷方式 → 属性 → 目标后面追加 --disable-features=LockProfileCookieDatabase，重新启动 Chrome。
导出 cookies.txt，用 cookies_file 指向它（最稳）：关闭 Chrome 后执行一次 yt-dlp --cookies-from-browser chrome --cookies cookies.txt，然后在 config.toml 里：
```
[search]
cookies_browser = ""
cookies_file = "C:/Users/xxx/cookies.txt"
```

📦 支持的平台

平台	架构	状态
macOS	Apple Silicon (ARM64)	✅ 预编译二进制
macOS	Intel (x86_64)	✅ 预编译二进制
Windows	x86_64	✅ 预编译二进制
Linux	x86_64	✅ 从源码编译

🤝 贡献

欢迎提交 Issue 和 Pull Request！

查看贡献指南了解如何参与项目开发。

📄 许可证

MIT License

🙏 致谢

Ratatui - 优秀的 TUI 框架
yt-dlp - 强大的视频下载工具
mpv - 高性能媒体播放器

Maboroshi (幻) - 在终端中享受音乐 🎵

Name		Name	Last commit message	Last commit date
Latest commit History 56 Commits
.github		.github
src		src
.gitignore		.gitignore
.gitmessage		.gitmessage
CHANGELOG.md		CHANGELOG.md
CHEATSHEET.md		CHEATSHEET.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
config.example.toml		config.example.toml
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

🌀 Maboroshi (幻) - 终端音乐播放器

🚀 快速开始

✨ 特性

📦 依赖

macOS 安装

Windows 安装

🚀 安装

方式 1：下载预编译二进制（推荐）

macOS (Apple Silicon)

macOS (Intel)

Windows (x86_64)

方式 2：一键安装脚本

方式 3：从源码编译

🎮 使用方法

命令行选项

基本操作

收藏分组管理

播放模式

使用流程

🗂️ 文件位置与缓存清理

🧹 清理音频缓存

⚙️ 配置文件

配置示例

支持的搜索源

🐛 故障排除

搜索失败

播放失败

Chrome Cookie 问题

Windows 下 Chrome cookie 读取失败

📦 支持的平台

🤝 贡献

📄 许可证

🙏 致谢

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 17

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages