A multi-purpose Discord bot for personal use. It combines a fully featured music player, an in-character AI chatbot, a media downloader, and a handful of server-utility commands.
/play [URL/keyword]— play audio from a URL or by searching YouTube. Powered by yt-dlp, so YouTube, Niconico, SoundCloud, BiliBili and many other sites are supported./play-file— upload a local audio/video file and play it./play-channel— collect links posted in a given channel and queue them as a playlist./search— browse YouTube search results and pick a track to play.- Queue management:
/queue,/clear,/shuffle,/repeat. - Playback control:
/pause,/resume,/stop,/skip,/replay,/volume, plus an interactive player message and/playerto move it. /connect//disconnectto manage the voice connection, and/voiceto hear Mashiro speak.
Mention the bot or DM it to chat with Mashiro in character. Responses are generated with Google Gemini 1.5 Pro on whitelisted guilds, falling back to a free GPT-4o-mini backend (g4f) elsewhere. Conversations are kept per-channel and expire after inactivity; reset them with /reset-conversation. The model can also trigger actions inline — e.g. start playing a requested song or send a selfie.
/dl video//dl audio— get a direct download link for a video or its audio (also available as message context-menu commands).
/replace-url vxtwitter— auto-convert X (Twitter) links tovxtwitter.comfor rich embeds./replace-url phixiv— auto-convert Pixiv links tophixiv.net.
/send-message— schedule a message to be sent at a specific date/time./nick change//nick restore//nick remove— bulk-manage member nicknames (admin only)./vc stats— show information about your current voice channel;/vc kick-timer— auto-disconnect yourself after a set duration./kotobagari— toggle word-filtering in the current channel (admin only)./mashiro— get a random character quote./ping,/help.
Run /help in Discord for the full, up-to-date command list.
Click the link to install the bot on your guilds.
- Python 3.10
- Pycord for the Discord API
- yt-dlp + FFmpeg for media
- google-generativeai / g4f for chat
- Docker for deployment
- Python 3.10+ and FFmpeg installed (the provided Docker image bundles FFmpeg for you).
- A Discord bot token with the necessary intents enabled.
Create a .env file in the project root:
DISCORD_BOT_TOKEN=your-discord-bot-token
GOOGLE_API_KEY=your-google-generative-ai-key # optional; required only for Gemini-backed chatThe bot runs alongside a PO Token provider so that YouTube playback works from datacenter/VPS IPs (otherwise YouTube responds with "Sign in to confirm you're not a bot"). The image is built by GitHub Actions and published to GitHub Packages (ghcr.io/mimaraka/mashiro). Use Docker Compose to pull it and start both services:
docker compose pull
docker compose up -dFor age-restricted videos or when the PO Token alone is not enough, place a cookies.txt (Netscape format, exported from a logged-in browser via an extension such as "Get cookies.txt LOCALLY") in the project root. It is auto-detected and mounted by docker-compose.yml. If you don't use cookies, remove the ./cookies.txt volume line from docker-compose.yml.
⚠️ Using a logged-in account's cookies from a datacenter IP carries an account-ban risk; prefer a throwaway account.
pip install -r requirements.txt
python main.pymain.py # Entry point: loads cogs and starts the bot
constants.py # Bot IDs, regex patterns, yt-dlp/FFmpeg options, etc.
character_config.py # Character persona, command descriptions, response text
cogs/ # Feature modules (music, character/chat, downloader, ...)
modules/ # Shared helpers (chat client, embeds, music engine, ...)
data/ # Assets (selfies, voice clips) and saved/temp state
When using this bot, please review the following documents: