TSMusicBot
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
## Screenshots
> *WebUI screenshots coming soon*
## Quick Start
### Option 1: Windows (Easiest)
```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
```
Open **http://localhost:3000** and follow the setup wizard.
### 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.
```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
All dependencies included. Zero configuration.
```bash
git clone https://github.com/YOUR_USERNAME/tsmusicbot.git
cd tsmusicbot/scripts/docker
docker-compose up -d
```
Open **http://localhost:3000**
Docker details
- 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`
```bash
docker logs -f tsmusicbot # View logs
docker-compose down # Stop
docker-compose up -d --build # Rebuild after code update
```
If TS3 server is remote, edit `docker-compose.yml`:
```yaml
# Replace network_mode: host with:
ports:
- "3000:3000"
```
### Option 4: Linux (systemd)
```bash
chmod +x scripts/install.sh
sudo ./scripts/install.sh
```
Auto-installs Node.js, dependencies, configures systemd service with auto-start.
## 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
### WebUI Pages
| 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 |
### TeamSpeak Text Commands
Control the bot by sending text messages in your TS channel:
| 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 |
> Default prefix: `!` (configurable in Settings). Aliases: `!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 |
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)
│ ├── 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)
```
## 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 |
## Configuration
The `config.json` file is auto-generated on first run:
```json
{
"webPort": 3000,
"locale": "zh",
"theme": "dark",
"commandPrefix": "!",
"commandAliases": { "p": "play", "s": "skip", "n": "next" },
"neteaseApiPort": 3001,
"qqMusicApiPort": 3200,
"adminPassword": "",
"adminGroups": [],
"autoReturnDelay": 300,
"autoPauseOnEmpty": true
}
```
## 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: "Cannot get play URL" error?**
A: Login to your music account in Settings (QR code scan). Many songs require authentication.
**Q: How to change the bot's TS channel?**
A: Use `!move ` command, or set default channel in Settings when creating the bot.
**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: 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: Docker build fails?**
A: Native modules (opus, sqlite3) need compilation tools. The Dockerfile includes them. Make sure Docker has enough memory (2GB+).
## Contributing
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
- [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
[MIT](LICENSE)