TopazBot - RTSP Discord Music bot for TopazChat

Japanese README (日本語)

---

🌟 Overview

TopazBot is a high-quality, low-latency Discord music bot that utilizes TopazChat's RTSP stream. It runs on servers like Linux and provides streamed audio to your Discord server.

Attention!!

"TopazBot" is under the MIT license, but "TopazChat" is not for commercial use.

✨ Key Features

• 🧠 High Quality: Stereo, high-fidelity, low-latency stream playback.
• 🔒 Secure: End-to-end encrypted voice with DAVE (Discord Audio Video Encryption).
• 🌐 Multi-format Support: Flexible stream processing with ffmpeg.

---

💎 About TopazChat

📝 Details

TopazChat is a high-quality, low-latency RTSP server. It is free for personal use.

TopazChat Download

The costs for TopazChat are covered by the developer, Hirotoshi Yoshitaka @TyounanMOTI.

Please consider donating to help with server maintenance and data transfer costs for audio/video streaming! → FANBOX

All sponsors of TopazChat are listed in SPONSORS.txt.

💬 Community

• TopazChat Discord Server

Join: https://discord.com/invite/fCMcJ8A

---

🚀 Quick Start

There are two ways to get started with TopazBot.

1. Use the Public Bot

This is the easiest way. You can add the bot to your Discord server using the link below:

Click here to add the bot

2. Self-Hosting

You can host the bot on your own server.

📋 Prerequisites

• Linux Server
• FFmpeg (RTSP-enabled)
• Node.js 22.x
• npm or yarn
• Discord Bot Token
• TopazChat Stream

📦 Dependencies

This library requires one dependency from each of the categories below to support various platforms.

The dependencies are listed in order of performance preference.

If you cannot install one of the options, try installing another.

🐧 Debian or Ubuntu

node & npm:

• node: >=22
• npm: >=10

discord.js (npm install)

• discord.js: ^14.26.5

@discordjs/voice (npm install):

• @discordjs/voice: ^0.19.2

@discordjs/opus (npm install):

• @discordjs/opus: "^0.10.0"

DAVE Encryption (npm install):

• @snazzah/davey: ^0.1.12

Encryption Libraries (npm install):

• sodium-native: ^5.1.0

Opus Libraries (npm install):

• @discordjs/opus: ^0.10.0

FFmpeg:

• FFmpeg (Please install on your server, e.g., apt install ffmpeg)

pm2 (npm install): [Optional]

• pm2

🛠️ Installation

# Clone the repository
git clone https://github.com/emerauda/TopazBot.git topazbot
cd topazbot

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit the .env file and set the required environment variables

⚙️ Configuration

Set the following environment variables in your .env file:

# Discord Bot Configuration
DISCORD_TOKEN=your_discord_bot_token

# RTSP Server Configuration (optional)
# Default: rtsp://topaz.chat/live
RTSP_SERVER_URL=rtsp://topaz.chat/live

Configuration Options:

Variable	Required	Default	Description
DISCORD_TOKEN	Yes	-	Discord bot token
RTSP_SERVER_URL	No	rtsp://topaz.chat/live	RTSP server base URL
USE_EXTERNAL_OPUS	No	1	1 = OggOpus output (recommended), 0 = AAC ADTS fallback
INPUT_IS_OPUS	No	0	1 = copy-remux only if the source really delivers Opus (TopazChat is AAC → keep 0; auto-fallback on mismatch)
FORCE_OPUS_REENCODE	No	0	1 = force libopus re-encode even when INPUT_IS_OPUS=1
LOW_LATENCY	No	0	1 = enable low-latency FFmpeg flags (nobuffer, analyzeduration=0)
OPUS_BITRATE	No	192k	Target Opus bitrate
AAC_BITRATE	No	OPUS_BITRATE	Bitrate for the AAC fallback (USE_EXTERNAL_OPUS=0)
CHANNEL_FIX_MODE	No	none	none / swap / left / right / mix (re-encode path only)
DOWNMIX_MONO	No	0	1 = downmix input to mono (-ac 1, re-encode path only)
COPY_WITH_DISCARDCORRUPT	No	0	1 = discard corrupt frames / regenerate PTS in copy mode too
PLAY_WAIT_MS	No	2000 / 300	Stabilization wait after playback starts (low-latency default: 300)
RESUME_WAIT_MS	No	3000 / 500	Wait before an auto-resume retry (low-latency default: 500)
DEBUG_FFMPEG	No	0	1 = log FFmpeg spawn args and stderr

When using the bot, streams will be accessed as ${RTSP_SERVER_URL}/${streamkey}.

🚀 Deployment

# Build
npm run build

# Start
npm run start

# Register commands
npm run register

# Start the program using pm2
npm i pm2 -g
pm2 start npm -n TopazBot -- start

---

🎮 Command List

TopazBot supports the following slash commands.

▶️ /play

• Description: Plays the RTSP stream from TopazChat using the specified stream key.
• Usage: /play StreamKey: <your_stream_key>
• Parameters:
  • StreamKey (required): Your TopazChat stream key.

🔄 /resync

• Description: Attempts to reconnect if the connection is unstable or the stream is interrupted.
• Usage: /resync or /resync StreamKey: <your_stream_key>
• Parameters:
  • StreamKey (optional): Stream key to resync. Defaults to the last played one.

⏹️ /stop

• Description: Stops the current stream playback and disconnects from the voice channel.
• Usage: /stop

🎚️ Playback Behavior

• Auto-resume: If the stream is interrupted (e.g. the streamer restarts), the bot keeps the connection and resumes playback automatically when the stream comes back.
• Auto-disconnect: If no playback succeeds for 30 minutes (e.g. the streamer never comes back), the bot leaves the voice channel automatically. Healthy long-running streams are never cut off.
• Stream switching: Running /play with a different stream key while playing switches to the new stream.
• Failure handling: If the first playback attempt fails, the bot reports the error and leaves the voice channel.
• Graceful shutdown: On SIGINT/SIGTERM (e.g. pm2 stop/pm2 restart), all sessions are cleaned up — no orphan FFmpeg processes or voice connections are left behind.

---

📜 Legal

• Terms of Service
• Privacy Policy

---

🏗️ Architecture

graph TD
    subgraph "Discord Server"
        User
        DiscordVoiceChannel[Discord Voice Channel]
    end

    subgraph "Your Server (VPS)"
        TopazBot
        FFmpeg
    end

    subgraph "TopazChat Server"
        TopazChat
    end

    User -- "/play" --> TopazBot
    TopazBot -- "RTSP Stream Request" --> TopazChat
    TopazChat -- "RTSP Stream" --> FFmpeg
    FFmpeg -- "Opus Audio" --> TopazBot
    TopazBot -- "Sends Audio" --> DiscordVoiceChannel

Loading

🔧 Tech Stack

Category	Technology	Version
Language	TypeScript	^6.0.3
Runtime	Node.js	>=22.x
Framework	discord.js	^14.26.5
Audio Processing	@discordjs/voice	^0.19.2
DAVE Encryption	@snazzah/davey	^0.1.12
Media Processing	FFmpeg	-
RTSP Server	TopazChat	-
Opus Library	@discordjs/opus	^0.10.0
Encryption	sodium-native	^5.1.0
Package Manager	npm	>=10
Testing	Jest	^30.4.2
Linter	ESLint	^10.7.0
Formatter	Prettier	^3.9.5

---

🧪 Development

📝 Scripts

Command	Description
npm run build	Build TypeScript
npm run start	Build and start the bot
npm run dev	Start with ts-node (dev)
npm run register	Register Discord slash commands
npm run lint	Run ESLint
npm run lint:fix	Run ESLint with auto-fix
npm run format	Apply Prettier formatting
npm run format:check	Check Prettier formatting
npm run typecheck	Type-check without emitting
npm run test	Run tests
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests with coverage

🔍 Debugging

# Start local development server
npm run dev

# Run tests
npm test

# Generate coverage report
npm run test:coverage

The coverage report can be viewed on Codecov

---

📂 Code structure

The code for this bot is optimized for TopazChat, but it also works with other RTSP servers via the RTSP_SERVER_URL environment variable.

Here is the code I used for reference: discordjs-japan/Playing Audio (in Japanese)

Created by Discord.js Japan user Group

---

🤝 Contributing to TopazBot

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please read our Contributing Guidelines for more details on the process and what we expect.

---

❤️ Donations

📻 TopazBot

Please consider donating to help maintain the public TopazBot server.

• TopazBot GitHub Sponsors

💎 TopazChat

The developer of TopazChat, Hirotoshi Yoshitaka, is seeking donations to cover server maintenance and data transfer costs.

• TopazChat FANBOX

🙏 Credits

📻 TopazBot

• Aoi Emerauda @emerauda

💎 TopazChat

• Hirotoshi Yoshitaka @TyounanMOTI TopazChat Developer

📄 License

This project is released under the MIT License. See the LICENSE file for details.

---

👥 Team

---

📞 Support

• 🐛 Bug Reports: Issues
• 💡 Feature Requests: Discussions
• 📧 Contact: [email protected]

---

🌟 Star History

---

📊 Statistics

---

⭐ If you like this project, please give it a star! ⭐

Made with ❤️ by Aoi Emerauda