{"id":21201650,"url":"https://github.com/giabb/bardboard","last_synced_at":"2026-04-13T03:40:04.858Z","repository":{"id":263192419,"uuid":"889633073","full_name":"giabb/BardBoard","owner":"giabb","description":"A simple Discord soundboard bot that enhances your D\u0026D sessions (or whatever you like) with atmospheric sounds and music. Built with JavaScript and featuring a clean, Bootstrap-powered web interface.","archived":false,"fork":false,"pushed_at":"2025-03-06T20:41:33.000Z","size":14522,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-06T21:28:19.526Z","etag":null,"topics":["container","discord-bot","discord-js","dockerfile","express-js","javascript","nodejs","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giabb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-16T20:25:27.000Z","updated_at":"2025-03-06T20:41:15.000Z","dependencies_parsed_at":"2025-03-06T21:35:13.887Z","dependency_job_id":null,"html_url":"https://github.com/giabb/BardBoard","commit_stats":null,"previous_names":["giabb/bardboard"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giabb%2FBardBoard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giabb%2FBardBoard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giabb%2FBardBoard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giabb%2FBardBoard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giabb","download_url":"https://codeload.github.com/giabb/BardBoard/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243654402,"owners_count":20325894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container","discord-bot","discord-js","dockerfile","express-js","javascript","nodejs","self-hosted"],"created_at":"2024-11-20T20:10:21.954Z","updated_at":"2026-04-13T03:40:04.844Z","avatar_url":"https://github.com/giabb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n   \n# 🎵 BardBoard \u0026 Dragons 🐉\n\n**Your personal soundboard, right inside Discord.**\n\nPlay sound effects, ambient music, and voice lines directly into your voice channel — all from a single, clean web interface. Perfect for D\u0026D sessions, watch parties, or anything in between.\n\n[![License](https://img.shields.io/badge/License-GPL%203.0-red.svg)](LICENSE.md)\n[![Discord](https://img.shields.io/badge/Made%20for-Discord-5865F2.svg)](https://discord.com)\n[![Docker](https://img.shields.io/badge/Runs%20on-Docker-2496ED.svg)](https://docker.com)\n\n[![Release](https://img.shields.io/github/v/release/giabb/BardBoard)](https://github.com/giabb/BardBoard/releases)\n[![Node](https://img.shields.io/node/v/discord.js)](https://nodejs.org)\n\u003c!--[![Stars](https://img.shields.io/github/stars/giabb/BardBoard?style=flat)](https://github.com/giabb/BardBoard/stargazers)\n[![Issues](https://img.shields.io/github/issues/giabb/BardBoard)](https://github.com/giabb/BardBoard/issues)\n[![Discussions](https://img.shields.io/github/discussions/giabb/BardBoard)](https://github.com/giabb/BardBoard/discussions)--\u003e\n\n\n\u003c/div\u003e\n\n---\n\n## 📋 Table of Contents\n- [✨ What is BardBoard?](#-what-is-bardboard)\n- [📋 What You'll Need](#-what-youll-need)\n- [🚀 Getting Started](#-getting-started)\n- [🎵 Adding Your Sounds](#-adding-your-sounds)\n- [🎮 How to Use It](#-how-to-use-it)\n- [⚠️ Troubleshooting](#-troubleshooting)\n- [⚙️ Advanced Configuration](#-advanced-configuration)\n- [🗺️ What's Coming Next](#-whats-coming-next)\n- [🤝 Contributing](#-contributing)\n- [👥 Contributors](#-contributors)\n- [📄 License](#-license)\n\n---\n\n## ✨ What is BardBoard?\n\nBardBoard is a Discord bot with a built-in web soundboard. You open it in your browser, see all your sounds laid out as buttons, and tap one — it plays instantly in your Discord voice channel. Everyone in the channel hears it.\n\n![BardBoard GUI](https://i.ibb.co/TqYC52jD/bardboard21.png)\n\nIt's designed with tabletop RPG sessions in mind (think ambient tavern music, dramatic battle effects, NPC voices), but it works great for anything where you want to drop sounds into a group call.\n\n**What makes it nice to use:**\n- One-tap playback — no typing commands, just click\n- Organise sounds into categories with folders — they show up as sections automatically\n- Volume control, repeat, and a seekable progress bar\n- A \"Now Playing\" bar that highlights which sound is active\n- Works on desktop and mobile browsers\n\n---\n\n## 📋 What You'll Need\n\nBefore you start, make sure you have these:\n\n- **A Discord account** and a server where you want to use it\n- **Docker Desktop** installed on your computer — [download it here](https://docs.docker.com/get-docker/) (it's free)\n- **A Discord Bot Token** — don't worry, I'll walk you through creating one below\n\nThat's it. No coding required.\n\n---\n\n## 🚀 Getting Started\n\n### Step 1 — Get a Discord Bot Token\n\n1. You can follow [this guide](https://www.writebots.com/discord-bot-token/) to create a Discord Bot and get a Discord Bot Token\n\n### Step 2 — Invite the Bot to Your Server\n\n1. From your bot page in the [Discord Developer page](https://discord.com/developers/applications), go to the **OAuth2** tab → **OAuth2 URL Generator**\n2. Under Scopes, tick **bot**\n3. Under Bot Permissions tick **Connect** and **Speak**\n4. Copy the URL at the bottom and open it in your browser\n5. Pick your server and click **Authorize**\n\n### Step 3 — Find Your Voice Channel ID\n\n1. Enable [Developer Mode](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID#h_01HRSTXPS5CRSRTWYCGPHZQ37H)\n2. Retrieve your [Channel ID](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID#h_01HRSTXPS5FMK2A5SMVSX4JW4E)\n\n### Step 4 — Download and Configure BardBoard\n\n1. Download or clone this repository to a folder on your computer\n2. Inside that folder, copy the file `.env.sample` and rename it to `.env`\n3. Open it and replace the values with your own Discord Bot Token and Voice Channel ID retrieved in Step 1 and 3.\n4. (Optional) Enable the login screen by setting:\n   - `AUTH_USER` / `AUTH_PASS` for the credentials\n   - `SESSION_SECRET` to a long random string (32+ chars)\n   - `SESSION_DIR` (optional) if you want to store sessions outside the container (Docker mounts `./sessions`)\n\n### Step 5 — Start It Up (With Docker)\n\n1. Open a terminal (or PowerShell on Windows) in the BardBoard folder\n2. Run this single command: `docker compose up --build -d`\n3. Wait a few seconds for it to start up\n4. Open your browser and go to **http://localhost:3000**\n\nYou should see the BardBoard interface. If your voice channel ID is set correctly and the bot is in your server, you're all set! 🎉\n\n### Optional — Run Locally (without Docker)\n\nIf you prefer running directly on your machine:\n\n1. Install Node.js (v18+ recommended) and make sure `ffmpeg` is in your PATH.\n2. Install dependencies: `npm install`\n3. Copy `.env.sample` to `.env` and fill in the required values.\n4. Start the app: `node BardBoard.js`\n5. Open **http://localhost:3000**\n\n---\n\n## 🎵 Adding Your Sounds\n\nYou can add sounds in two ways:\n\n- **In-browser upload:** Click **Add Song**, drag \u0026 drop files (or browse), pick a category or create a new one, then upload.\n- **Manual:** Drop audio files into the `audio-files` folder inside the project directory. Refresh the page to see them.\n\n**Supported formats:** MP3, WAV, OGG, M4A\n\n### Organising with Categories\n\nWant to keep things tidy? Put sounds into subfolders — each subfolder becomes its own labelled section on the soundboard.\n\n```\naudio-files/\n├── Tavern.mp3\n├── Intro.ogg\n├── Combat/\n│   ├── Clash.mp3\n│   ├── Bash.wav\n│   └── Roar.ogg\n└── NPCs/\n    ├── Merchant.mp3\n    └── Guard.mp3\n```\n\nThis would give you a soundboard with a few loose sounds at the top, then a **Combat** section, then an **NPCs** section — each with their own buttons.\n\nThe categories can be collapsed and expanded, and each category has its own colour!\nYou can also delete songs or entire categories directly from the web UI (with a confirmation prompt).\n\n---\n\n## 🎮 How to Use It\n\nOpen **http://localhost:3000** in any browser on your network. Here's what you'll find:\n\n### The Soundboard\n\nThe main area of the page is your soundboard — a grid of buttons, one per sound, optionally divided by categories. Just **tap or click** a button and it plays in your Discord voice channel immediately. The button for the currently playing sound lights up so you always know what's on.\n\n### The Controls (top bar)\n\n- 🔊 **Volume slider** — Drag it left or right to adjust how loud the sound plays in Discord. Changes apply instantly.\n- ⏸️ **Pause / ▶️ Resume** — Tap this to pause the current sound and to enable resume button. Tap again to resume the song.\n- 🔁 **Repeat** — Tap this to loop the current sound. It'll keep playing on repeat until you stop it or play something else. Tap again to turn it off.\n- ⏹️ **Stop** — Stops whatever is currently playing.\n\n### Now Playing Bar\n\nRight below the controls you'll see a strip that shows you what's playing right now, along with a **progress bar**. You can **click or drag** anywhere on that bar to jump to a different part of the sound — handy if you want to skip to a specific moment in a longer track.\n\n### Search Bar\n\nBelow the playing bar, you can find a search bar. This bar filters songs and categories.\n\n### Add Song (Upload)\n\nClick **Add Song** next to the search bar to open the upload modal. You can drag multiple files, remove them before uploading, and choose a category (or create a new one).\n\n### Using It on Mobile\n\nThe soundboard works on phones and tablets too. The progress bar supports touch dragging, so seeking works just as well on mobile as on desktop.\n\n---\n\n## ⚠️ Troubleshooting\n\n**Nothing is playing when I tap a button**\n- Make sure the bot is in your Discord server and has the **Connect** and **Speak** permissions in the voice channel\n- Check that `CHANNEL_ID` in your `.env` file matches the voice channel you want the bot to join\n\n**The soundboard is empty**\n- Make sure there are audio files in the `audio-files/` folder\n- Supported formats are MP3, WAV, OGG, and M4A — other formats won't show up\n\n**The bot isn't online in Discord**\n- Double-check your `DISCORD_TOKEN` in the `.env` file — make sure there are no extra spaces or line breaks\n- Try restarting with `docker compose restart`\n\n**I don't see the login screen**\n- Make sure both `AUTH_USER` and `AUTH_PASS` are set (auth is off if either is empty)\n- Restart the container after changing `.env`\n\n**I changed my sounds but they didn't update**\n- The soundboard reads files live, so new files should appear on the next page refresh. If they don't, make sure the files are inside the `audio-files/` folder or a first level subfolder (not a subfolder of a subfolder and so on)\n\n**Something else is wrong**\n- You can check what's happening behind the scenes by running `docker compose logs -f` in your terminal — it'll show you any error messages from the bot\n- If you're still stuck, open an [issue](https://github.com/giabb/BardBoard/issues) and I'll help! If you can attach the result of the previous command it will be much easier to understand the issue for me! \n\n---\n\n## ⚙️ Advanced Configuration\n\nIf you want to tweak limits, auth, or run the UI from another host, these env vars are available:\n\n**Core**\n- `BOT_PORT` (default `3000`) — Port for the web UI/API.\n- `DISCORD_TOKEN` — Your bot token (required).\n- `CHANNEL_ID` — Voice channel ID (required).\n- `NOISES_FOLDER` (default `!noises`) — Category folder name for overlay sounds.\n\n**Auth \u0026 Sessions (optional)**\n- `AUTH_USER` / `AUTH_PASS` — Enable login when both are set.\n- `SESSION_SECRET` — Change this from the default `change-me` for security.\n- `SESSION_DIR` (default `./sessions`) — Where session files are stored (mounted in Docker).\n- `LOGIN_REMEMBER_DAYS` (default `30`) — \"Remember me\" cookie duration in days.\n\n**Uploads \u0026 Rate Limits**\n- `UPLOAD_MAX_MB` (default `50`) — Max size (MB) per uploaded file.\n- `RATE_LIMIT_AUDIO` (default `120`) — Requests per minute for audio actions.\n- `RATE_LIMIT_FILES` (default `60`) — Requests per minute for file actions.\n\n**CORS (when UI and API are on different hosts)**\n- `CORS_ORIGINS` — Comma-separated list of allowed origins (leave blank if UI + API are on the same host).\n\n**Local (non-Docker) run**\n- `ffmpeg` must be installed and available in your PATH for seek to work.\n- Audio dependencies like `libsodium` are required for Discord voice support.\n\n---\n\n## 🗺️ What's Coming Next\n\nHere's what's on the horizon for BardBoard:\n\n- [ ] 💬 **Discord slash commands** — Play sounds with `/play` directly in chat, in addition to the web UI\n- [ ] 🌐 **Multi-channel support** — Run separate soundboards for different voice channels at the same time\n- [ ] ✨ **Make things simpler** — I know the whole setup can be a lot for most of the users, so I hope to make things easier in the future! \n\n---\n\n## 🤝 Contributing\n\nBardBoard is open source and contributions are welcome! Whether it's a bug fix, a new feature, or just a typo in the docs — it all helps.\n\n### 🐛 Found a Bug?\nOpen an [issue](https://github.com/giabb/BardBoard/issues) and describe what happened. Include any error messages you see (you can get them with `docker compose logs -f`).\n\n### 💡 Got an Idea?\nOpen an issue and describe the feature! Explain what problem it solves and how you imagine it working.\n\n### 💻 Want to Write Code?\n1. Fork the repository\n2. Create a branch for your change (`git checkout -b feature/your-feature`)\n3. Make your changes and commit them with a clear message\n4. Push to your fork and open a Pull Request\n\n### 📖 Docs \u0026 Typos\nEven small improvements to the README or documentation are appreciated — just fork, edit, and open a PR.\n\n---\n\n## 👥 Contributors\n\n\u003cdiv align=\"center\"\u003e\n\n**Project Creator \u0026 Maintainer**\n\n[![Giovanbattista Abbate](https://github.com/giabb.png?size=100)](https://github.com/giabb)\n\n**[Giovanbattista Abbate](https://github.com/giabb)**\n\n\u003c/div\u003e\n\n---\n\n*Want to contribute? See the [Contributing](#-contributing) section above!*\n\n## 📄 License\n\nThis project is licensed under the **GNU General Public License v3.0**.\n\nThis means you can:\n- ✅ Use the software for any purpose\n- ✅ Study and modify the source code\n- ✅ Distribute copies of the software\n- ✅ Distribute modified versions\n\n**Requirements:**\n- 📋 Include the original license\n- 📋 State changes made to the code\n- 📋 Make source code available when distributing\n\nSee the [LICENSE.md](LICENSE.md) file for complete details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built for tabletop adventurers and Discord groups everywhere**\n\n[⭐ Star this repo](https://github.com/giabb/BardBoard) • [🐛 Report Issues](https://github.com/giabb/BardBoard/issues) • [💬 Discussions](https://github.com/giabb/BardBoard/discussions)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiabb%2Fbardboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiabb%2Fbardboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiabb%2Fbardboard/lists"}