agent-lx-music

English | 简体中文

基于 Unix 哲学设计的高性能命令行音乐播放器，由 Rust 强力驱动，完美兼容 lx-music 音源脚本。项目彻底抛弃了臃肿的 Electron 框架，改用高度优化的 QuickJS 沙箱环境运行 JS 解析脚本，并通过脱钩的 POSIX 守护进程组（setsid）将音频高保真解码与播放工作完全委托给 headless mpv 实例处理。

核心特性

QuickJS 隔离沙箱：基于 rquickjs，在安全隔离的沙箱环境内运行传统的 lx-music 音源解析脚本。
脱钩式守护进程设计：利用 POSIX setsid 机制在独立的后台进程组中拉起 mpv，实现非阻塞的音频控制流，命令行退出后后台音乐依然能稳定播放。
SQLite 透明数据库缓存：本地保存歌单、支持年龄限制自动清理的播放历史、收藏夹，并透明地对已解析歌词进行本地缓存，实现零延迟、零网络请求的二次秒开。
静态歌词与封面图处理：支持主歌词、翻译歌词、罗马音轨道的格式化 LRC 快速输出与文件导出；基于魔法字节（Magic Bytes）检测图像文件头签名，规避不稳定 MIME 报头并精确自动补全后缀名。
音频直通式容器部署：深度兼容无根（rootless）Podman / Docker 容器化部署，可通过卷映射直通宿主机 PulseAudio/Pipewire 音频通道。
大模型 Agent 智能驱动：预置了符合 XDG 规范的智能技能文件（music-discovery、audio-analysis、listening-companion），完美适配多模态大语言模型（如 Gemini 1.5 Pro）直接对歌曲进行分析、检索与音乐伴侣闲聊。

快速上手 (Quick Start)

1. 安装外部系统依赖 (External Dependencies)

alx 依赖底层的系统音频输出驱动与高保真解码后端。在编译和运行本项目之前，您需要安装以下外部依赖项：

mpv (核心必须)：充当 headless 播放解调后端。
libmpv-dev (或 mpv-devel) (编译必须)：供 Rust 核心原生链接和调用 mpv 进程间套接字。
alsa-lib (或 libasound2-dev) (Linux 必须)：用于对接底层 ALSA 发声通道。
beets (可选依赖)：当您需要将本播放器与本地个人音乐库进行同步管理时使用。

主流操作系统/发行版安装命令一览：

Debian / Ubuntu / Deepin / Mint:

sudo apt update
sudo apt install -y libasound2-dev libmpv-dev mpv beets

Fedora / RHEL / CentOS:

sudo dnf install -y alsa-lib-devel mpv-devel mpv beets

Arch Linux / Manjaro:
```
sudo pacman -Sy alsa-lib mpv beets
```
Alpine Linux:
```
apk add alsa-lib-dev mpv-dev mpv beets
```
macOS (via Homebrew):
```
brew install mpv beets
```

2. 获取并本地编译 (Build from Source)

环境依赖安装就绪后，直接克隆并编译本项目：

# 1. 克隆代码仓库
git clone https://github.com/Xuepoo/agent-lx-music.git
cd agent-lx-music

# 2. 编译 Release 生产二进制包
cargo build --release

# 3. 查看全局使用菜单
./target/release/alx --help

(注意：您也可以直接前往 GitHub 的 Releases 页面，下载开箱即用的预编译二进制或 .deb / .rpm / .apk 安装包。)

3. 三步极速配置开歌 (Bootstrap)

# 第一步：获取并注册一个自定义的外部解析源脚本
alx source add https://example.com/custom-source.js

# 第二步：全网搜索您想听的音乐
alx search "周杰伦 晴天"
# 检索将返回一个 4 位的临时 CLI ID (如 c12a)

# 第三步：顺序载入并开始顺序后台顺序后台播放
alx play c12a

基础命令速查

# 1. 异步多媒体播放状态控制
alx now                    # 展示实时的播放进度卡片
alx volume +10 / alx volume -10
alx seek +30 / alx seek 2:30
alx pause / alx resume / alx stop
alx quit                   # 彻底优雅关闭 mpv 后台守护进程

# 2. LRC 歌词与封面图获取
alx lyric <cli_id>         # 打印同步的 LRC 歌词
alx lyric <cli_id> --save  # 自动导出为 .lrc 文件到下载文件夹
alx pic <cli_id> --save    # 下载专辑封面图并自动修正文件后缀

技术文档导览

本项目的全部核心设计细节、参数及数据持久化模型，均存放于 docs/ 目录中：

CLI 使用手册 — 每一个子命令与全局选项的配置与用法说明
音源桥接 API 规范 — 沙箱隔离环境内音源事件的回调契约
XDG 路径配置指南 — 环境变量优先级与路径解析规则
SQLite 数据模型 — 完整的本地关系数据表实体与视图设计

许可证与免责声明

本项目基于 MIT 许可证开源。

免责声明与补充协议

请务必阅读并签署项目协议与免责声明了解关于第三方音乐源使用限制、版权数据处理（24小时内清空）、非商业探索性质及技术学习交流的具体协议条款。

lux-native 0.2.1