# music_box

**Repository Path**: javycoder/music_box

## Basic Information

- **Project Name**: music_box
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 局域网 AI 点歌台

基于 [NetEase-MusicBox](https://github.com/darknessomi/musicbox) 的网页 + AI Agent 点歌系统：局域网打开网页即可搜索点歌，或与 Agent 对话完成搜索 / 加入播放列表 / 立刻播放 / 切歌 / 调音量。音频在**运行主机本地**流式播放（不落地缓存）。

## 需求与能力

- **运行平台**：macOS、Windows 11、Debian（含 Debian 上 Docker）
- **共享队列**：所有人共用同一条播放列表，主机扬声器出声
- **网页三栏**：搜索、Agent 聊天、播放列表；底部当前曲目 / **播放进度与时间** / 音量 / 控制。移动端播放栏为文档流占位，避免挡住输入框
- **搜索模式**：歌曲智能搜、歌手热门、歌单名搜索、专辑名搜索；歌单/专辑可一键播放
- **AI Agent**：ReAct 调工具；Enter 发送、Shift+Enter 换行；支持「来几首某歌手」、歌单/专辑链接或 ID
- **智能选曲**：原唱优先、非演唱会优先、热度优先、可播放优先；版权不可播会明确提示
- **登录**：网易云 App 扫码；Cookie 本机（或容器卷）共享；定时检测过期
- **播放**：MusicBox daemon + `mpg123`（可选 `mpv`）取链流式播放；Web 与 CLI **共用固定 runtime 目录**
- **明确不做**（MusicBox 队列无对应能力）：删除列表中单曲、拖动/调整播放顺序、插队到下一首

## 架构

| 层级 | 说明 |
| --- | --- |
| 前端 | `frontend/` 静态页 + WebSocket |
| 后端 | FastAPI；`search_smart` + `catalog`（歌手热门/歌单专辑）+ MusicBox CLI |
| 播放 | `musicbox daemon`（Unix 域套接字；Windows 11 需 AF_UNIX）；歌单可用 `play --playlist` |
| AI | 默认 `glm-5.2`（Coding Plan `/api/coding/paas/v4`）；失败切 `glm-4.7-flash`（`/api/paas/v4`） |

## 配置

复制 `.env.example` 为 `.env` 并填写智谱 Key：

| 变量 | 含义 |
| --- | --- |
| `ZHIPU_API_KEY` | 智谱 Key |
| `ZHIPU_DEFAULT_MODEL` / `ZHIPU_DEFAULT_BASE_URL` | 默认 `glm-5.2` + Coding Plan 端点 |
| `ZHIPU_FALLBACK_MODEL` / `ZHIPU_FALLBACK_BASE_URL` | 备用 `glm-4.7-flash` |
| `HOST` / `PORT` | 监听地址（默认 `0.0.0.0:8765`） |
| `MUSICBOX_BIN` | musicbox 可执行文件名或路径 |
| `XDG_RUNTIME_DIR` | 可选。已含 `lan-music-agent` 或 `netease-musicbox-runtime` 时沿用；否则 macOS/Debian 落到 `~/.cache/lan-music-agent/runtime`，Windows 落到 `%TEMP%\lan-music-agent\runtime` |

本机访问 `http://127.0.0.1:8765`，局域网用 `http://<主机IP>:8765`。首次请在网页扫码登录网易云。

**请始终用 `./start.sh` / `start.ps1` 启动**，以便 runtime、venv 与端口清理一致。改代码后需重启服务进程。

---

## macOS

```bash
brew install python@3.12 mpg123
# 可选: brew install mpv
cp .env.example .env   # 填入 ZHIPU_API_KEY
chmod +x start.sh
./start.sh
```

---

## Windows 11

### 依赖

1. 安装 [Python 3.10+](https://www.python.org/downloads/)（勾选 Add python.exe to PATH）
2. 安装播放器 **mpg123**（推荐 [Scoop](https://scoop.sh/)）：
   ```powershell
   scoop install mpg123
   ```
   或使用 Chocolatey：`choco install mpg123`
3. MusicBox daemon 依赖 **Unix 域套接字**（Windows 10/11 已支持）。`start.ps1` 会设置统一的 `XDG_RUNTIME_DIR`。

### 启动

```powershell
copy .env.example .env
# 编辑 .env 填入 ZHIPU_API_KEY
.\start.bat
# 或: powershell -ExecutionPolicy Bypass -File .\start.ps1
```

若 PowerShell 禁止脚本，可临时：`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`。

Windows 上 Docker Desktop 把声音透出到主机扬声器不稳定，**建议本机直接跑 `start.ps1`/`start.bat`**，不要用容器播音频。

---

## Debian（本机）

```bash
sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-pip mpg123
# 可选（体积较大）: sudo apt-get install -y mpv
cp .env.example .env   # 填入 ZHIPU_API_KEY
chmod +x start.sh
./start.sh
```

`start.sh` 会尝试用 `lsof` / `fuser` / `ss` 释放占用端口，并固定 `XDG_RUNTIME_DIR`（默认 `~/.cache/lan-music-agent/runtime`）。

防火墙放行示例：

```bash
sudo ufw allow 8765/tcp
```

---

## Docker（Debian 主机）

适合在 Debian 上用容器跑服务，并通过 ALSA 使用**宿主机声卡**出声。

### 准备

```bash
cp .env.example .env   # 填入 ZHIPU_API_KEY
# 确认宿主有声卡设备
ls -l /dev/snd
```

### 构建与运行

```bash
docker compose up -d --build
docker compose logs -f
```

浏览器访问宿主机 `http://<Debian局域网IP>:8765`。

### 音频说明

- `docker-compose.yml` 已映射 `/dev/snd`、设置 `XDG_RUNTIME_DIR=/tmp/netease-musicbox-runtime`，并加入 `audio` 组
- 若无声：把用户加入 `audio` 组后重登；或检查是否被 Pulse 独占（可再挂载 Pulse socket，见 compose 注释）
- Cookie 持久化在命名卷 `musicbox-data`，扫码一次即可

### 常用命令

```bash
docker compose down
docker compose up -d --build
docker compose exec music musicbox auth status --json
```

Windows / macOS 上的 Docker Desktop **不保证**能把容器内声音送到本机扬声器；这两个平台请用对应原生启动脚本。

---

## 目录结构

```
music/
├── backend/app/           # FastAPI、MusicBox 封装、catalog、智谱 Agent、智能选曲
├── frontend/              # 网页静态资源
├── requirements.txt
├── start.sh               # macOS / Debian / 容器入口
├── start.ps1 / start.bat  # Windows 11
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md
```

## Agent 工具

`search_songs`、`artist_hot_songs`、`search_collections`、`play_collection`、`add_to_playlist`、`play_now`、`next_track`、`prev_track`、`pause`、`resume`、`get_playlist`、`get_player_status`、`clear_playlist`、`get_login_status`、`set_volume`。

## 开发说明

- 播放控制调用 `musicbox … --json`；失败 JSON 可能在 **stderr**，后端会解析 stdout/stderr
- `play_id` 预检一次链接后播放；去掉多余二次查链以降低 Agent 超时
- 用户给出明确 song id 时 Agent 只能播该 id；`copyright` / 超时错误原样透出
- 播放栏根据 `position`/`length` 显示进度，播放中前端本地插值（mpg123 不支持拖动 seek）
- `ensure_daemon` 带锁与短缓存，避免轮询与按钮并发时反复 `daemon start`
- `GET /api/player/status` 异常时返回降级 JSON（HTTP 200），操作类接口仍可能 400
- 歌手热门走网易云 `artists` hotSongs；专辑走 album API + 入队；歌单播放优先 `musicbox play --playlist`
- 搜索走 `search_smart`（歌手曲库 + 可播性校验）
- 登录：`auth login --no-wait` → 网页 QR → `auth login --check <unikey>`
- WebSocket `/ws` 周期性广播登录与播放状态
- 启动脚本会在占用端口时先结束旧进程再启动
- API Key 只放 `.env`，勿提交仓库

## 常见问题

- **想删列表里某一首 / 调顺序**：MusicBox 无此能力，当前仅支持清空整表后重新点歌
- **网页 player/status、toggle 400，但终端 musicbox 正常**：多为 `XDG_RUNTIME_DIR` 不一致或旧进程未重启；请用 `./start.sh` / `start.ps1` 重启
- **版权限制 / 点播放无效**：网易云无播放链接；界面会标「版权限制」
- **Docker 无声音**：确认 `--device /dev/snd`、用户在 `audio` 组
- **Windows / Debian daemon 失败**：确认 AF_UNIX 与 runtime 目录可写；安装 mpg123
- **局域网打不开**：放行 `PORT`，用主机局域网 IP
- **智谱失败**：检查 Key；备用模型用 `/api/paas/v4`，Coding Plan 用 `/api/coding/paas/v4`