{"id":25027624,"url":"https://github.com/migwynkriid/harmonica","last_synced_at":"2025-04-13T14:37:12.068Z","repository":{"id":266980263,"uuid":"899903648","full_name":"migwynkriid/Harmonica","owner":"migwynkriid","description":"Harmonica - A music oriented discord bot using yt-dlp and ffmpeg to play from YouTube and various platforms in voice channels","archived":false,"fork":false,"pushed_at":"2025-03-19T10:49:54.000Z","size":697,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-27T05:35:07.165Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/migwynkriid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-12-07T10:34:40.000Z","updated_at":"2025-03-19T10:49:58.000Z","dependencies_parsed_at":"2024-12-07T13:22:57.102Z","dependency_job_id":"319aff99-a7c5-43b1-a947-0f3027e65312","html_url":"https://github.com/migwynkriid/Harmonica","commit_stats":null,"previous_names":["migwynkriid/discord-ytdlp","migwynkriid/harmonica-discordbot-ytdlp","migwynkriid/harmonica"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migwynkriid%2FHarmonica","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migwynkriid%2FHarmonica/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migwynkriid%2FHarmonica/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migwynkriid%2FHarmonica/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/migwynkriid","download_url":"https://codeload.github.com/migwynkriid/Harmonica/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248730009,"owners_count":21152546,"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":["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"],"created_at":"2025-02-05T19:38:17.496Z","updated_at":"2025-04-13T14:37:11.765Z","avatar_url":"https://github.com/migwynkriid.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Harmonica - Discord Music Bot 🎵\n\n\u003cdiv align=\"center\"\u003e\n\n[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![Discord.py](https://img.shields.io/badge/Discord.py-2.0+-blue.svg)](https://discordpy.readthedocs.io/en/stable/)\n[![YT-DLP](https://img.shields.io/badge/YT--DLP-Latest-red.svg)](https://github.com/yt-dlp/yt-dlp)\n[![License](https://img.shields.io/badge/license-Unlicense-blue.svg)](LICENSE)\n[![Status](https://img.shields.io/badge/status-active-success.svg)]()\n[![SpotiPy](https://img.shields.io/badge/SpotiPy-2.23.0-brightgreen.svg)](https://spotipy.readthedocs.io/)\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \n\u003cdiv style=\"border: 2px solid #5865F2; border-radius: 10px; padding: 20px; margin: 20px 0; background-color: #f6f8fa;\"\u003e\n\n# ⚙️ Public Harmonica Instance for your server\n\n\u003ca href=\"https://discord.com/oauth2/authorize/?permissions=-805306431\u0026scope=bot\u0026client_id=1341757638433833021\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Invite%20Harmonica-Add%20to%20Discord-5865F2?style=for-the-badge\u0026logo=discord\u0026logoColor=white\" alt=\"Invite Harmonica\" width=\"300\"\u003e\n\u003c/a\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\nA self-hosted Discord bot that uses YT-DLP to play audio from YouTube, Spotify, direct links, and livestreams in your Discord voice channels.\n\n![Bot Preview](https://github.com/user-attachments/assets/1ee417c8-db7c-458c-987d-95dcd909ee47)\n\n## ✨ Features\n\n### 🎵 Music Support\n- Multi-platform support (YouTube, Spotify, direct links)\n- Multi-server support\n- High-quality audio streaming\n- Livestream support\n- Playlist support\n\n### 📢 Sponsorblock\n- Intergrated Sponsorblock\n- Remove sponsor, intro, outro, selfpromo, interaction, and music offtopic from the audio\n- Configurable via the config.json, by default it is disabled\n\n### 🎚️ Playback Control\n- Basic controls (play, pause, skip)\n- Queue management\n- Loop mode with count option\n- Shuffle functionality\n- Real-time track information\n\n### 🎯 Smart Features\n- ⚡ Advanced Caching System:\n  - Automated local caching for faster playback\n  - Skip YouTube queries for cached songs\n  - Intelligent cache management\n  - Reduced bandwidth usage\n- YouTube search integration\n- Spotify playlist parsing\n- Genius lyrics integration\n- Automatic FFmpeg setup\n- Configurable auto-leave\n- Download cleanup\n\n### ⚙️ Administration\n- Role-based permissions\n- Configurable command prefix\n- Detailed logging system\n- Auto-updates capability\n\n\u003e ⚠️ **Note**: This bot is currently in development. While functional, it's recommended for use on a single private Discord server only.\n\n## ⚡ Quick Start\n\n1. Install Python 3.8+\n2. Run `pip install -r requirements.txt`\n3. Rename `.env.example` to `.env` and add your Discord token\n4. Run `python bot.py`\n\n## 🔧 Detailed Setup\n\n### Core Setup\n1. **Python Installation**\n   - Install Python 3.8 or higher\n   - Verify installation: `python --version`\n\n2. **Dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Discord Bot Token**\n   - Rename `.env.example` to `.env`\n   - Add your token:\n     ```\n     DISCORD_TOKEN=your_token_here\n     ```\n\n4. **Configuration**\n   - Edit `config.json` to set:\n     - Owner ID\n     - Command Prefix\n     - Permissions\n     - Autoleave\n     - Default Volume\n     - Auto Clear Downloads\n     - Log Level\n     - UI Buttons\n     - Sponsorblock\n\n### Optional Features\n\n1. **Spotify Integration**\n   - Rename `.spotifyenv.example` to `.spotifyenv`\n   - Add credentials:\n     ```\n     SPOTIPY_CLIENT_ID=your_client_id_here\n     SPOTIPY_CLIENT_SECRET=your_client_secret_here\n     ```\n   - Get credentials from [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/applications)\n\n2. **Genius Lyrics**\n   - Edit `.geniuslyrics` (created on first startup)\n   - Add your [Genius API](https://genius.com/api-clients) credentials\n\n3. **YouTube Authentication**\n   - Install [Get Cookies.txt extension](https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)\n   - Export cookies and place in root directory\n   - [Learn more about cookies setup](https://github.com/yt-dlp/yt-dlp/wiki/FAQ#how-do-i-pass-cookies-to-yt-dlp)\n\n## 🎮 Commands\n\n### Music Playback\n- `!play [URL/search]` - Play audio from URL or search\n- `!search [term]` - Search YouTube for a song\n- `!pause` - Pause playback\n- `!resume` - Resume playback\n- `!stop` - Stop and clear queue\n- `!skip` - Skip current track\n- `!replay` - Replay current track\n- `!random` - Searches for a random song on YouTube\n- `!randomradio` - Play a random radio station\n- `!loop [count]` - Toggle loop mode (optional count)\n- `!nowplaying` - Show current track info\n\n### Queue Management\n- `!queue` - Show queue\n- `!clear` - Clear entire queue\n- `!clear [position]` - Remove specific track\n- `!shuffle` - Shuffle queue\n\n### Voice Channel\n- `!join` / `!summon` - Join your channel\n- `!leave` / `!disconnect` - Leave channel\n\n### Lyrics \u0026 Information\n- `!lyrics` - Get lyrics for current song\n\n### System Commands\n- `!alias [add/remove/list]` - Manage aliases\n- `!ping` - Show bot status\n- `!version` - Show bot version\n- `!log` - Log current context\n- `!prefix` - Change command prefix\n- `!restart` - Restart bot (Owner)\n- `!logclear` - Clear logs (Owner)\n- `!update` - Update bot files (Owner)\n- `!cookie` - Update cookies.txt (Owner)\n- `!help` - Show all commands\n\n## 🔍 Troubleshooting\n\n### Common Issues\n- **FFmpeg Issues**: \n  - Windows: Relaunch after first install\n  - macOS: Automatic installation\n  - Linux: Automatic installation\n\n- **YouTube Sign-In Error/403 Error**: Check/update cookies.txt\n\n## 📋 System Requirements\n- Python 3.8+\n- FFmpeg\n- Stable internet connection\n- Discord Bot Token\n\n## License notes:\n\nThis 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmigwynkriid%2Fharmonica","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmigwynkriid%2Fharmonica","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmigwynkriid%2Fharmonica/lists"}