https://github.com/migwynkriid/harmonica
Harmonica - A music oriented discord bot using yt-dlp and ffmpeg to play from YouTube and various platforms in voice channels
https://github.com/migwynkriid/harmonica
discord discord-bot discord-bot-basic discord-py discordbot discordmusic discordmusicbot discordmusicbots-com ffmpeg genius music music-bot music-player musicbot play playmusic python spotify yt-dl yt-dlp
Last synced: about 1 year ago
JSON representation
Harmonica - A music oriented discord bot using yt-dlp and ffmpeg to play from YouTube and various platforms in voice channels
- Host: GitHub
- URL: https://github.com/migwynkriid/harmonica
- Owner: migwynkriid
- License: unlicense
- Created: 2024-12-07T10:34:40.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-19T10:49:54.000Z (about 1 year ago)
- Last Synced: 2025-03-27T05:35:07.165Z (about 1 year ago)
- Topics: discord, discord-bot, discord-bot-basic, discord-py, discordbot, discordmusic, discordmusicbot, discordmusicbots-com, ffmpeg, genius, music, music-bot, music-player, musicbot, play, playmusic, python, spotify, yt-dl, yt-dlp
- Language: Python
- Homepage:
- Size: 681 KB
- Stars: 7
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Harmonica - Discord Music Bot 🎵
[](https://www.python.org/downloads/)
[](https://discordpy.readthedocs.io/en/stable/)
[](https://github.com/yt-dlp/yt-dlp)
[](LICENSE)
[]()
[](https://spotipy.readthedocs.io/)
# ⚙️ Public Harmonica Instance for your server
A self-hosted Discord bot that uses YT-DLP to play audio from YouTube, Spotify, direct links, and livestreams in your Discord voice channels.
## ✨ Features
### 🎵 Music Support
- Multi-platform support (YouTube, Spotify, direct links)
- Multi-server support
- High-quality audio streaming
- Livestream support
- Playlist support
### 📢 Sponsorblock
- Intergrated Sponsorblock
- Remove sponsor, intro, outro, selfpromo, interaction, and music offtopic from the audio
- Configurable via the config.json, by default it is disabled
### 🎚️ Playback Control
- Basic controls (play, pause, skip)
- Queue management
- Loop mode with count option
- Shuffle functionality
- Real-time track information
### 🎯 Smart Features
- ⚡ Advanced Caching System:
- Automated local caching for faster playback
- Skip YouTube queries for cached songs
- Intelligent cache management
- Reduced bandwidth usage
- YouTube search integration
- Spotify playlist parsing
- Genius lyrics integration
- Automatic FFmpeg setup
- Configurable auto-leave
- Download cleanup
### ⚙️ Administration
- Role-based permissions
- Configurable command prefix
- Detailed logging system
- Auto-updates capability
> ⚠️ **Note**: This bot is currently in development. While functional, it's recommended for use on a single private Discord server only.
## ⚡ Quick Start
1. Install Python 3.8+
2. Run `pip install -r requirements.txt`
3. Rename `.env.example` to `.env` and add your Discord token
4. Run `python bot.py`
## 🔧 Detailed Setup
### Core Setup
1. **Python Installation**
- Install Python 3.8 or higher
- Verify installation: `python --version`
2. **Dependencies**
```bash
pip install -r requirements.txt
```
3. **Discord Bot Token**
- Rename `.env.example` to `.env`
- Add your token:
```
DISCORD_TOKEN=your_token_here
```
4. **Configuration**
- Edit `config.json` to set:
- Owner ID
- Command Prefix
- Permissions
- Autoleave
- Default Volume
- Auto Clear Downloads
- Log Level
- UI Buttons
- Sponsorblock
### Optional Features
1. **Spotify Integration**
- Rename `.spotifyenv.example` to `.spotifyenv`
- Add credentials:
```
SPOTIPY_CLIENT_ID=your_client_id_here
SPOTIPY_CLIENT_SECRET=your_client_secret_here
```
- Get credentials from [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/applications)
2. **Genius Lyrics**
- Edit `.geniuslyrics` (created on first startup)
- Add your [Genius API](https://genius.com/api-clients) credentials
3. **YouTube Authentication**
- Install [Get Cookies.txt extension](https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)
- Export cookies and place in root directory
- [Learn more about cookies setup](https://github.com/yt-dlp/yt-dlp/wiki/FAQ#how-do-i-pass-cookies-to-yt-dlp)
## 🎮 Commands
### Music Playback
- `!play [URL/search]` - Play audio from URL or search
- `!search [term]` - Search YouTube for a song
- `!pause` - Pause playback
- `!resume` - Resume playback
- `!stop` - Stop and clear queue
- `!skip` - Skip current track
- `!replay` - Replay current track
- `!random` - Searches for a random song on YouTube
- `!randomradio` - Play a random radio station
- `!loop [count]` - Toggle loop mode (optional count)
- `!nowplaying` - Show current track info
### Queue Management
- `!queue` - Show queue
- `!clear` - Clear entire queue
- `!clear [position]` - Remove specific track
- `!shuffle` - Shuffle queue
### Voice Channel
- `!join` / `!summon` - Join your channel
- `!leave` / `!disconnect` - Leave channel
### Lyrics & Information
- `!lyrics` - Get lyrics for current song
### System Commands
- `!alias [add/remove/list]` - Manage aliases
- `!ping` - Show bot status
- `!version` - Show bot version
- `!log` - Log current context
- `!prefix` - Change command prefix
- `!restart` - Restart bot (Owner)
- `!logclear` - Clear logs (Owner)
- `!update` - Update bot files (Owner)
- `!cookie` - Update cookies.txt (Owner)
- `!help` - Show all commands
## 🔍 Troubleshooting
### Common Issues
- **FFmpeg Issues**:
- Windows: Relaunch after first install
- macOS: Automatic installation
- Linux: Automatic installation
- **YouTube Sign-In Error/403 Error**: Check/update cookies.txt
## 📋 System Requirements
- Python 3.8+
- FFmpeg
- Stable internet connection
- Discord Bot Token
## License notes:
This project is licensed under the Unlicense. Giving the user complete freedom to use, modify, and distribute the software. This repository primarily uses yt-dlp, which is licensed under GPL-2.0. This repository does not bundle or modify yt-dlp—it only installs it if necessary. For more information, visit: https://github.com/yt-dlp/yt-dlp.