Muncher Bot 🥢

Muncher is a consensus‑driven Discord bot that playfully detects when someone is munching in voice chat.
Instead of one person triggering it, members privately vote with !munch <target>.
When enough votes are cast (configurable threshold), the bot announces the result — or even plays a chewing sound clip.

---

✨ Features

• Consensus Voting: Users DM the bot with !munch <target>.
• Threshold Logic: Action triggers only when a percentage of channel members agree.
• Playful Responses: Posts a message in text chat or plays a sound in voice chat.
• Configurable: Threshold, channel names, and sound assets can be customized.
• Dockerized: Ready for container deployment.
• CI/CD: GitHub Actions workflow included for linting and testing.

---

📂 Project Structure

muncher/              ← project root
  src/                ← source code
    muncher/          ← Python package
      bot/            ← bot entrypoint
      utils/          ← vote logic
      sounds/         ← audio assets
  .docker/            ← Dockerfile
  .docs/              ← documentation
  .github/workflows/  ← CI/CD
  requirements.txt
  README.md

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• FFmpeg (for audio playback)
• A Discord bot token (create one at Discord Developer Portal)

Installation

git clone https://github.com/mozrin/muncher.git
cd muncher
pip install -r requirements.txt

Running

Set your bot token:

export DISCORD_TOKEN="your_token_here"

Run the bot:

python -m muncher

---

🐳 Docker

Build and run with Docker:

docker build -t muncher-bot -f .docker/Dockerfile .
docker run -e DISCORD_TOKEN="your_token_here" muncher-bot

---

⚙️ Configuration

• Threshold: Default is 30% of channel members. Set via MUNCH_THRESHOLD.
• Window: Default is 5 minutes (300s). Set via MUNCH_WINDOW.
• Announcement Channel: Set MUNCH_CHANNEL_ID to the ID of the channel where consensus should be announced.
• Sounds: Place .mp3 or .ogg files in src/muncher/sounds/.

---

🧪 Testing

Run unit tests:

export PYTHONPATH=src
pytest

---

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you’d like to change.
Make sure to update tests as appropriate.

---

📜 License

MIT License — free to use, modify, and distribute.

---

🎉 Credits

Built by Mozrin

Built with discord.py.
Inspired by the universal truth: “Yes, you are munching.”