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)

# 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+ and a TeamSpeak 3 server. FFmpeg is bundled automatically — no manual install needed.

# 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.

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

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:

# Replace network_mode: host with:
ports:
  - "3000:3000"

Option 4: Linux (systemd)

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 <song>	Search and play
!play -q <song>	Search from QQ Music
!add <song>	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 <seq|loop|random|rloop>	Change play mode
!playlist <ID>	Load playlist
!album <ID>	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:

{
  "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 <channel name> 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 — UI design inspiration
• TS3AudioBot — Architecture reference
• TS3AudioBot-NetEaseCloudmusic-plugin — Lazy loading pattern
• NeteaseCloudMusicApi — NetEase Cloud Music API
• @sansenjian/qq-music-api — QQ Music API
• @honeybbq/teamspeak-client — TS3 client protocol

License

MIT