From 833c6b7b0584b472eda0e73e0ee8dc608bc47861 Mon Sep 17 00:00:00 2001 From: saopig1 Date: Mon, 30 Mar 2026 13:38:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=A8=E4=B8=AD=E6=96=87=20README=20?= =?UTF-8?q?=E2=80=94=20=E5=BE=BD=E7=AB=A0=E3=80=81=E5=BF=AB=E9=80=9F?= =?UTF-8?q?=E5=BC=80=E5=A7=8B=E3=80=81=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E?= =?UTF-8?q?=E3=80=81FAQ=E3=80=81=E8=B4=A1=E7=8C=AE=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 371 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 193 insertions(+), 178 deletions(-) diff --git a/README.md b/README.md index e201e04..7f50289 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,85 @@

- TSMusicBot + TSMusicBot

TSMusicBot

- TeamSpeak 3 音乐机器人 — 网易云音乐 + QQ 音乐双平台，YesPlayMusic 风格 WebUI + TeamSpeak 3 音乐机器人 — 网易云音乐 + QQ 音乐双平台，YesPlayMusic 风格 WebUI 控制面板

- - - + + +

--- -## Features +## 功能特性 -- **Dual Music Source** — NetEase Cloud Music + QQ Music, unified search with source badges -- **Real TS3 Client Protocol** — Bot appears as a visible client (not invisible ServerQuery) -- **YesPlayMusic WebUI** — Beautiful dark/light theme, responsive design -- **Full Playback Control** — Play, pause, next, prev, seek, volume -- **4 Play Modes** — Sequential, loop, shuffle, shuffle-loop -- **Synced Lyrics** — Real-time scrolling lyrics with translation, server-side frame-accurate sync -- **Playlist Management** — Recommended, daily, personal FM, user playlists -- **Audio Quality** — Standard (128k) to Master Quality (4000k FLAC) -- **QR Code Login** — Scan to login NetEase / QQ Music accounts -- **Multi-Instance** — Manage multiple bots connected to different TS servers -- **Lazy URL Loading** — Playlist loads instantly, URL fetched on-demand (never expires) -- **One-Click Deploy** — FFmpeg bundled, Windows batch / Linux systemd / Docker +- **双音源支持** — 网易云音乐 + QQ 音乐，统一搜索，结果标注来源 +- **真实 TS3 客户端协议** — 机器人在 TeamSpeak 中可见（非 ServerQuery 隐身模式） +- **YesPlayMusic 风格 WebUI** — 精美界面，支持深色/浅色主题切换 +- **完整播放控制** — 播放/暂停/上一首/下一首/进度跳转/音量调节 +- **四种播放模式** — 顺序播放/循环播放/随机播放/随机循环 +- **实时歌词同步** — 歌词滚动显示，支持翻译歌词，服务端帧计数精确同步 +- **歌单管理** — 推荐歌单/我的歌单/每日推荐/私人FM，点击播放全部 +- **音质选择** — 标准(128k) / 较高(192k) / 极高(320k) / 无损(FLAC) / Hi-Res / 超清母带 +- **QR码登录** — 扫码登录网易云/QQ音乐账号，Cookie 自动持久化 +- **多实例管理** — 同时管理多个机器人，连接不同 TS 服务器 +- **播放历史** — 自动记录所有播放过的歌曲 +- **懒加载机制** — 歌单只存储元数据，播放时才获取链接（避免链接过期） +- **一键部署** — FFmpeg 内置，Windows 双击运行 / Linux systemd / Docker -## Screenshots +## 截图 -> *WebUI screenshots coming soon* +> *截图即将添加* -## Quick Start +## 快速开始 -### Option 1: Windows (Easiest) +### 方式一：Windows 一键部署（最简单） -```powershell -# 1. Clone -git clone https://github.com/YOUR_USERNAME/tsmusicbot.git -cd tsmusicbot +只需电脑有网络连接，其他一切自动安装。 -# 2. Setup (first time only — installs Node.js + all dependencies) -scripts\setup.bat - -# 3. Start -scripts\start.bat +``` +1. 下载或 clone 本项目 +2. 双击 scripts\setup.bat （首次安装，自动安装 Node.js 和所有依赖） +3. 双击 scripts\start.bat （启动机器人） +4. 浏览器打开 http://localhost:3000 ``` -Open **http://localhost:3000** and follow the setup wizard. +> `setup.bat` 会自动通过 winget 安装 Node.js（如果未安装），运行 `npm install` 安装所有依赖（包括内置 FFmpeg），最后构建项目。之后每次只需双击 `start.bat` 启动。 -### Option 2: Manual Install (Any OS) +### 方式二：手动安装（所有系统） -**Prerequisites:** [Node.js 20+](https://nodejs.org/) and a TeamSpeak 3 server. -FFmpeg is **bundled automatically** — no manual install needed. +**前置条件：** [Node.js 20+](https://nodejs.org/) 和一个 TeamSpeak 3 服务器。 +FFmpeg **已自动内置**，无需手动安装。 ```bash -# Clone +# 下载项目 git clone https://github.com/YOUR_USERNAME/tsmusicbot.git cd tsmusicbot -# Install dependencies +# 安装依赖 npm install cd web && npm install && cd .. -# Build +# 构建 npm run build -# Start +# 启动 npm start ``` -### Option 3: Docker +打开浏览器访问 **http://localhost:3000**，按照设置向导完成配置。 -All dependencies included. Zero configuration. +### 方式三：Docker 一键部署 + +所有依赖已内置（Node.js、FFmpeg、Opus 编码器），无需安装任何额外软件。 ```bash git clone https://github.com/YOUR_USERNAME/tsmusicbot.git @@ -87,159 +87,171 @@ cd tsmusicbot/scripts/docker docker-compose up -d ``` -Open **http://localhost:3000** +打开浏览器访问 **http://localhost:3000**
-Docker details +Docker 详细说明 -- First build takes a few minutes (compiling native modules) -- Uses `host` network mode for LAN TS3 server connectivity -- Data persisted in Docker named volume `tsmusicbot-data` -- Built-in health check at `/api/health` +- 首次构建需要几分钟（编译原生模块） +- 默认使用 `host` 网络模式，机器人可直接连接局域网 TS3 服务器 +- 数据持久化在 Docker 命名卷 `tsmusicbot-data` 中（数据库、Cookie、日志） +- 内置健康检查（`/api/health`），支持 Docker 自动重启 ```bash -docker logs -f tsmusicbot # View logs -docker-compose down # Stop -docker-compose up -d --build # Rebuild after code update +docker logs -f tsmusicbot # 查看日志 +docker-compose down # 停止 +docker-compose up -d --build # 代码更新后重新构建 ``` -If TS3 server is remote, edit `docker-compose.yml`: +如果 TS3 服务器在其他机器上，编辑 `docker-compose.yml`： ```yaml -# Replace network_mode: host with: +# 将 network_mode: host 替换为： ports: - "3000:3000" ```
-### Option 4: Linux (systemd) +### 方式四：Linux 一键安装 ```bash chmod +x scripts/install.sh sudo ./scripts/install.sh ``` -Auto-installs Node.js, dependencies, configures systemd service with auto-start. +自动安装 Node.js 和依赖，配置 systemd 服务，支持开机自启。 -## Usage +## 使用说明 -### First-Time Setup +### 首次配置 -1. Open **http://localhost:3000/setup** -2. Enter your TeamSpeak server address (default port: 9987) -3. Set bot nickname -4. (Optional) Scan QR code to login NetEase/QQ Music for VIP songs +1. 打开 **http://localhost:3000/setup** 进入设置向导 +2. 填写 TeamSpeak 服务器地址（默认端口：9987） +3. 设置机器人昵称 +4. （可选）扫码登录网易云/QQ音乐账号以播放 VIP 歌曲 -### WebUI Pages +### WebUI 页面说明 -| Page | Description | -|------|-------------| -| **Home** | Recommended playlists, daily picks, personal FM, my playlists | -| **Search** | Unified search across both platforms, results show source badge | -| **Playlist** | View playlist detail, play all (respects current play mode) | -| **Lyrics** | Full-screen synced lyrics with blurred album art background | -| **History** | All previously played songs | -| **Settings** | Theme, bot management, account login, audio quality, command prefix | +| 页面 | 功能 | +|------|------| +| **首页** | 推荐歌单、每日推荐、私人FM、我的歌单 | +| **搜索** | 双平台统一搜索，结果标注网易云/QQ来源 | +| **歌单** | 查看歌单详情，播放全部（根据当前播放模式选择首歌） | +| **歌词** | 全屏歌词页，实时同步滚动，模糊专辑封面背景 | +| **历史** | 播放历史记录 | +| **设置** | 主题切换、机器人管理、音乐账号登录、音质选择、命令前缀 | -### TeamSpeak Text Commands +### TeamSpeak 文字命令 -Control the bot by sending text messages in your TS channel: +在 TeamSpeak 频道中发送文字消息控制机器人： -| Command | Description | -|---------|-------------| -| `!play ` | Search and play | -| `!play -q ` | Search from QQ Music | -| `!add ` | Add to queue | -| `!pause` / `!resume` | Pause / Resume | -| `!next` / `!prev` | Next / Previous track | -| `!stop` | Stop and clear queue | -| `!vol <0-100>` | Set volume | -| `!queue` | Show queue | -| `!mode ` | Change play mode | -| `!playlist ` | Load playlist | -| `!album ` | Load album | -| `!fm` | Personal FM (NetEase) | -| `!lyrics` | Show lyrics | -| `!now` | Current track info | -| `!vote` | Vote to skip | -| `!help` | Help | +| 命令 | 说明 | +|------|------| +| `!play <歌名>` | 搜索并播放 | +| `!play -q <歌名>` | 从 QQ 音乐搜索 | +| `!add <歌名>` | 添加到播放队列 | +| `!pause` / `!resume` | 暂停 / 恢复播放 | +| `!next` / `!prev` | 下一首 / 上一首 | +| `!stop` | 停止播放并清空队列 | +| `!vol <0-100>` | 设置音量 | +| `!queue` | 查看播放队列 | +| `!mode ` | 切换播放模式 | +| `!playlist ` | 加载歌单 | +| `!album ` | 加载专辑 | +| `!fm` | 私人 FM（网易云） | +| `!lyrics` | 显示当前歌词 | +| `!now` | 当前播放信息 | +| `!vote` | 投票跳过当前歌曲 | +| `!move <频道名>` | 移动到指定频道 | +| `!help` | 显示帮助信息 | -> Default prefix: `!` (configurable in Settings). Aliases: `!p` = `!play`, `!s` = `!skip`, `!n` = `!next` +> 命令前缀默认为 `!`，可在设置页面修改。支持别名：`!p` = `!play`，`!s` = `!skip`，`!n` = `!next` -### Audio Quality +### 音质等级 -| Level | Bitrate | Format | Note | -|-------|---------|--------|------| -| Standard | 128kbps | MP3 | Free | -| Higher | 192kbps | MP3 | Free | -| **Exhigh** | **320kbps** | **MP3** | **Default** | -| Lossless | ~900kbps | FLAC | VIP required | -| Hi-Res | ~1500kbps | FLAC | VIP required | -| Master | ~4000kbps | FLAC | Premium VIP | +| 等级 | 码率 | 格式 | 说明 | +|------|------|------|------| +| 标准 | 128kbps | MP3 | 免费可用 | +| 较高 | 192kbps | MP3 | 免费可用 | +| **极高** | **320kbps** | **MP3** | **默认选择** | +| 无损 | ~900kbps | FLAC | 需要 VIP | +| Hi-Res | ~1500kbps | FLAC | 需要 VIP | +| 超清母带 | ~4000kbps | FLAC | 需要黑胶 VIP | -Change in Settings page. Takes effect immediately for subsequent songs. +在设置页面选择音质，立即生效（影响后续播放的歌曲）。 -## Architecture +## 项目架构 ``` tsmusicbot/ -├── src/ # Backend (TypeScript) -│ ├── audio/ # Audio pipeline: FFmpeg → PCM → Opus → 20ms frames -│ │ ├── encoder.ts # Opus encoder (@discordjs/opus) -│ │ ├── player.ts # FFmpeg player (bundled ffmpeg-static, frame-count tracking) -│ │ └── queue.ts # Play queue (4 modes, lazy URL) -│ ├── bot/ # Bot core -│ │ ├── commands.ts # Text command parser (prefix, aliases, permissions) -│ │ ├── instance.ts # Bot instance (TS3 + player + music provider) -│ │ └── manager.ts # Multi-instance lifecycle -│ ├── data/ # Data layer -│ │ ├── config.ts # JSON config -│ │ └── database.ts # SQLite (history, instances) -│ ├── music/ # Music sources -│ │ ├── provider.ts # Unified MusicProvider interface -│ │ ├── netease.ts # NetEase Cloud Music adapter -│ │ ├── qq.ts # QQ Music adapter -│ │ ├── auth.ts # Cookie persistence -│ │ └── api-server.ts # Embedded API servers (auto-start) -│ ├── ts-protocol/ # TS3 client protocol -│ │ └── client.ts # Full client (ECDH + AES-EAX encryption) -│ ├── web/ # Web backend -│ │ ├── server.ts # Express + WebSocket -│ │ └── api/ # REST API (bot, music, player, auth) -│ └── index.ts # Entry point -├── web/src/ # Frontend (Vue 3) +├── src/ # 后端源码 (TypeScript) +│ ├── audio/ # 音频管线：FFmpeg → PCM → Opus → 20ms 帧 +│ │ ├── encoder.ts # Opus 编码器 (@discordjs/opus) +│ │ ├── player.ts # FFmpeg 播放器（内置 ffmpeg-static，帧计数进度追踪） +│ │ └── queue.ts # 播放队列（4种模式，懒加载URL） +│ ├── bot/ # 机器人核心 +│ │ ├── commands.ts # 文字命令解析器（前缀、别名、权限） +│ │ ├── instance.ts # Bot 实例（绑定 TS3 + 播放器 + 音源） +│ │ └── manager.ts # 多实例生命周期管理 +│ ├── data/ # 数据层 +│ │ ├── config.ts # JSON 配置文件 +│ │ └── database.ts # SQLite 数据库（播放历史、实例持久化） +│ ├── music/ # 音源服务 +│ │ ├── provider.ts # 统一 MusicProvider 接口 +│ │ ├── netease.ts # 网易云音乐适配器 +│ │ ├── qq.ts # QQ 音乐适配器 +│ │ ├── auth.ts # Cookie 持久化存储 +│ │ └── api-server.ts # 嵌入式 API 服务（自动启动） +│ ├── ts-protocol/ # TS3 客户端协议 +│ │ └── client.ts # 完整客户端（ECDH + AES-EAX 加密协议） +│ ├── web/ # Web 后端 +│ │ ├── server.ts # Express + WebSocket 服务 +│ │ ├── websocket.ts # 实时状态广播 +│ │ └── api/ # REST API 路由 +│ │ ├── bot.ts # 机器人管理 CRUD +│ │ ├── music.ts # 搜索/歌单/歌词/音质 +│ │ ├── player.ts # 播放控制/队列/历史/跳转 +│ │ └── auth.ts # QR登录/Cookie/SMS +│ └── index.ts # 入口（启动所有服务） +├── web/src/ # 前端源码 (Vue 3) │ ├── components/ # Player, Navbar, Queue, CoverArt, SongCard │ ├── views/ # Home, Search, Playlist, Lyrics, History, Settings, Setup -│ ├── stores/ # Pinia (server-synced elapsed time) -│ └── styles/ # SCSS theme (dark/light) -├── scripts/ -│ ├── setup.bat # Windows first-time setup -│ ├── start.bat # Windows start script -│ ├── install.sh # Linux installer + systemd -│ └── docker/ # Dockerfile + docker-compose.yml -├── data/ # Runtime (auto-created): DB, cookies, logs -└── config.json # Config (auto-generated on first run) +│ ├── stores/ # Pinia 状态管理（含服务端时间同步） +│ ├── composables/ # WebSocket 自动重连 +│ └── styles/ # SCSS 主题变量（深色/浅色） +├── scripts/ # 部署脚本 +│ ├── setup.bat # Windows 首次安装 +│ ├── start.bat # Windows 启动脚本 +│ ├── install.sh # Linux 一键安装 + systemd 服务 +│ └── docker/ # Docker 部署文件 +│ ├── Dockerfile +│ └── docker-compose.yml +├── data/ # 运行时数据（自动创建，不上传） +│ ├── tsmusicbot.db # SQLite 数据库 +│ ├── cookies/ # 登录 Cookie +│ └── logs/ # 日志文件 +└── config.json # 配置文件（首次运行自动生成，不上传） ``` -## Tech Stack +## 技术栈 -| Layer | Technology | -|-------|-----------| -| Runtime | Node.js 20+, TypeScript 5 | -| Backend | Express 4, WebSocket (ws) | -| Database | better-sqlite3 (SQLite) | -| Audio | FFmpeg (ffmpeg-static), @discordjs/opus | -| TS3 Protocol | @honeybbq/teamspeak-client (full ECDH + AES-EAX) | -| NetEase API | NeteaseCloudMusicApi | -| QQ Music API | @sansenjian/qq-music-api | -| Frontend | Vue 3, Vite 5, Pinia, Vue Router 4 | -| Styling | SCSS (YesPlayMusic-inspired design) | -| Icons | @iconify/vue | -| Logging | pino | +| 层级 | 技术 | +|------|------| +| **运行时** | Node.js 20+, TypeScript 5 | +| **后端框架** | Express 4, WebSocket (ws) | +| **数据库** | better-sqlite3 (SQLite) | +| **音频处理** | FFmpeg (ffmpeg-static 内置), @discordjs/opus | +| **TS3 协议** | @honeybbq/teamspeak-client（完整客户端协议，ECDH + AES-EAX） | +| **网易云 API** | NeteaseCloudMusicApi | +| **QQ 音乐 API** | @sansenjian/qq-music-api | +| **前端框架** | Vue 3, Vite 5, Pinia, Vue Router 4 | +| **界面样式** | SCSS（YesPlayMusic 设计风格） | +| **图标** | @iconify/vue | +| **日志** | pino | -## Configuration +## 配置文件 -The `config.json` file is auto-generated on first run: +`config.json` 在首次运行时自动生成，可手动编辑： ```json { @@ -257,43 +269,46 @@ The `config.json` file is auto-generated on first run: } ``` -## FAQ +## 常见问题 -**Q: Bot connects but no sound in TeamSpeak?** -A: Make sure the bot is in the same channel as you. Check volume (`!vol 75`). Ensure the song has a playable URL (some VIP songs require login). +**Q：机器人连接了但 TeamSpeak 中听不到音乐？** +A：确保机器人和你在同一个频道。检查音量（`!vol 75`）。部分 VIP 歌曲需要先登录账号。 -**Q: "Cannot get play URL" error?** -A: Login to your music account in Settings (QR code scan). Many songs require authentication. +**Q：提示"无法获取播放链接"？** +A：在设置页面扫码登录音乐账号。许多歌曲需要登录后才能播放。 -**Q: How to change the bot's TS channel?** -A: Use `!move ` command, or set default channel in Settings when creating the bot. +**Q：如何更换机器人所在频道？** +A：使用 `!move <频道名>` 命令，或在设置页面创建机器人时指定默认频道。 -**Q: Can I run multiple bots?** -A: Yes. Create additional bot instances in Settings page, each connecting to a different TS server or channel. +**Q：可以同时运行多个机器人吗？** +A：可以。在设置页面创建多个实例，分别连接不同的 TS 服务器或频道。 -**Q: Port 3200 already in use?** -A: The QQ Music API auto-starts on port 3200. If a previous instance is still running, the app will reuse it. Kill old `node` processes if needed. +**Q：端口 3200 被占用？** +A：QQ 音乐 API 启动时自动监听 3200 端口。如果之前的进程还在运行，程序会自动复用。如需重启可手动结束 `node` 进程。 -**Q: Docker build fails?** -A: Native modules (opus, sqlite3) need compilation tools. The Dockerfile includes them. Make sure Docker has enough memory (2GB+). +**Q：Docker 构建失败？** +A：原生模块（opus、sqlite3）需要编译工具，Dockerfile 已包含。确保 Docker 有足够内存（建议 2GB+）。 -## Contributing +**Q：如何更新到新版本？** +A：`git pull` 拉取最新代码，然后 `npm install && npm run build && npm start` 重新构建启动。Docker 用户执行 `docker-compose up -d --build`。 -1. Fork the repository -2. Create your feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'feat: add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request +## 参与贡献 -## Acknowledgments +1. Fork 本仓库 +2. 创建功能分支 (`git checkout -b feature/新功能`) +3. 提交更改 (`git commit -m 'feat: 添加新功能'`) +4. 推送分支 (`git push origin feature/新功能`) +5. 提交 Pull Request -- [YesPlayMusic](https://github.com/qier222/YesPlayMusic) — UI design inspiration -- [TS3AudioBot](https://github.com/Splamy/TS3AudioBot) — Architecture reference -- [TS3AudioBot-NetEaseCloudmusic-plugin](https://github.com/ZHANGTIANYAO1/TS3AudioBot-NetEaseCloudmusic-plugin) — Lazy loading pattern -- [NeteaseCloudMusicApi](https://github.com/Binaryify/NeteaseCloudMusicApi) — NetEase Cloud Music API -- [@sansenjian/qq-music-api](https://github.com/sansenjian/qq-music-api) — QQ Music API -- [@honeybbq/teamspeak-client](https://www.npmjs.com/package/@honeybbq/teamspeak-client) — TS3 client protocol +## 致谢 -## License +- [YesPlayMusic](https://github.com/qier222/YesPlayMusic) — UI 设计灵感 +- [TS3AudioBot](https://github.com/Splamy/TS3AudioBot) — 架构参考 +- [TS3AudioBot-NetEaseCloudmusic-plugin](https://github.com/ZHANGTIANYAO1/TS3AudioBot-NetEaseCloudmusic-plugin) — 懒加载设计参考 +- [NeteaseCloudMusicApi](https://github.com/Binaryify/NeteaseCloudMusicApi) — 网易云音乐 API +- [@sansenjian/qq-music-api](https://github.com/sansenjian/qq-music-api) — QQ 音乐 API +- [@honeybbq/teamspeak-client](https://www.npmjs.com/package/@honeybbq/teamspeak-client) — TS3 客户端协议实现 + +## 开源许可 [MIT](LICENSE)