AmbiBot

A Discord ambience and soundboard bot built for tabletop sessions. AmbiBot streams music from URLs, drops a one-click theme picker for your campaign moods, and plays local BGM/SFX clips straight into voice - all through slash commands.

                     _     _ _           _
     /\             | |   (_) |         | |
    /  \   _ __ ___ | |__  _| |__   ___ | |_
   / /\ \ | '_ ` _ \| '_ \| | '_ \ / _ \| __|
  / ____ \| | | | | | |_) | | |_) | (_) | |_
 /_/    \_\_| |_| |_|_.__/|_|_.__/ \___/ \__|

Features

🎵 URL Streaming

/play <url> extracts audio via yt-dlp and streams it into your current voice channel. The bot auto-joins your channel (or moves to it), normalizes volume to a comfortable level, and reports the now-playing title.

🎚️ Theme Picker

/theme reads your playlist.txt and renders a row of buttons - one per mood category (Battle, Calm, Adventure, Exploration, Mystery, Horror, or whatever you define). Click a category and AmbiBot stops whatever is playing and starts that theme's track. Downloads are retried with exponential backoff, so a flaky extraction won't kill the session.

🔊 Local Soundboard

/play_local scans sounds/BGM/ and sounds/SFX/ for .mp3 files and builds a button for each. Tap a button to play that clip in voice - handy for stingers, background loops, and one-shot effects. Any track already playing is stopped first.

🧹 Message Purge

/purge <amount> bulk-deletes between 1 and 1000 messages from the current channel. Requires the Manage Messages permission and verifies the bot has it before acting.

🚀 Windows Launcher

zlauncher.bat prints the ASCII banner, optionally self-updates from git on startup (toggled in settings.py), and runs the bot from the local venv.

Architecture

ambibot/
├── main.py               # Entry point: loads token, sets intents, auto-loads every cog
├── settings.py           # Config: update toggle, sound directories, permission tiers
├── requirements.txt      # Python dependencies (disnake, yt-dlp, PyNaCl, ...)
├── example_playlist.txt  # Sample theme playlist (copy to playlist.txt)
├── ascii.txt             # Startup banner
├── zlauncher.bat         # Windows launcher with optional git self-update
├── cogs/
│   ├── play.py           # /play - stream audio from a URL via yt-dlp
│   ├── theme.py          # /theme - button-based mood/theme picker from playlist.txt
│   ├── local.py          # /play_local - button soundboard from sounds/BGM + sounds/SFX
│   └── purge.py          # /purge - bulk-delete messages
└── sounds/
    ├── BGM/              # Local background-music .mp3 files
    └── SFX/              # Local sound-effect .mp3 files

main.py walks the cogs/ directory and loads every .py file as an extension, so new commands are added simply by dropping a cog in.

Tech Stack

Component	Purpose
Python 3.x	Runtime
disnake 2.10.1	Discord API wrapper (slash commands, buttons, voice)
yt-dlp	Audio extraction from URLs for /play and /theme
FFmpeg	Decodes audio for streaming (FFmpegPCMAudio)
PyNaCl	Voice encryption required for Discord voice
configparser	Reads token and guild ID from secrets.ini

Getting Started

Prerequisites

• Python 3.x
• FFmpeg on your PATH (or ffmpeg.exe alongside the bot)
• A Discord bot application with the Message Content intent enabled

Clone

git clone https://github.com/osyra42/ambibot.git
cd ambibot

Virtual Environment & Dependencies

python -m venv venv
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate

pip install -r requirements.txt

Configuration

AmbiBot reads its secrets from a secrets.ini file (git-ignored, never commit it). Create one in the repo root:

[bot]
BOT_TOKEN = your-discord-bot-token
GUILD_IDS = your-server-id

• BOT_TOKEN - the token from your Discord Developer Portal application
• GUILD_IDS - the server (guild) ID slash commands are registered to

Other options live in settings.py:

• check_for_updates - if True, the launcher pulls the latest master on startup
• dir_to_BGM / dir_to_SFX - local sound directories
• permissions - permission tiers

Playlist

Copy the sample and edit it to taste (the live file is git-ignored):

cp example_playlist.txt playlist.txt

Format is INI-like: a [Category] header followed by one URL per line, with an optional ; description after the URL:

[Battle]
https://www.youtube.com/watch?v=OOBLHj8OQEc  ; Epic D&D Music for Battles

Run

python main.py

On Windows you can instead double-click zlauncher.bat, which shows the banner, optionally self-updates, and launches from the venv.

Commands

Command	Description
/play <url>	Stream audio from a URL into your voice channel
/theme	Show mood buttons from playlist.txt; click one to play it
/play_local	Show a button per local BGM/SFX .mp3; click one to play it
/purge <amount>	Delete 1-1000 messages (needs Manage Messages)

All commands auto-connect the bot to your current voice channel (or move it there). You must be in a voice channel for the audio commands to work.

Troubleshooting

• "You need to be in a voice channel" - join a voice channel before running /play, /theme, or /play_local.
• No audio / player errors - confirm FFmpeg is installed and on your PATH; player errors are printed to the console.
• Commands don't appear - check GUILD_IDS in secrets.ini matches your server; slash commands are registered per guild.
• "The video is still processing" - the URL couldn't be extracted yet; /theme retries automatically, /play you can retry manually.
• Bot won't start - make sure secrets.ini exists with a valid [bot] section, and the Message Content intent is enabled in the Developer Portal.
• /purge fails - the bot needs the Manage Messages permission in the channel.

License

Released under the MIT License.