🎵 Lightweight Discord Music Bot (ARM64 / x86 / Homelab / VPS)

---

🇬🇧 ENGLISH VERSION

A lightweight, ultra-efficient Discord music bot designed specifically for low-resource devices (ARM64 processors, Raspberry Pi, postmarketOS) and standard commercial VPS servers (x86_64).

Built with Python 3.11, discord.py, yt-dlp, and spotipy. Utilizes native system FFmpeg integration, running at under 60 MB RAM and eliminating legacy Java runtime bottlenecks.

✨ Features

• 🚀 Multi-Architecture Native Support – Full compatibility with ARM64 (Raspberry Pi, postmarketOS) and x86_64 (Standard VPS, Synology, Unraid).
• 🎶 Multi-Source Audio – Playback from YouTube (single tracks & full playlists) and keyword search (ytsearch).
• 🟢 Spotify Integration – Converts Spotify tracks and playlist URLs into YouTube streams automatically.
• 🔀 Shuffle & Queue System – Randomize current playback queue (!shuffle) with seamless track transitions.
• 🐳 Containerized & 12-Factor Ready – Isolated Docker environment utilizing an .env file for secret management.

---

📌 Command Cheat Sheet

Command	Description	Example
!play <url / query>	Plays audio from YT, queues YT/Spotify playlists, or searches by phrase.	!play Metallica One
!shuffle	Randomly shuffles the current queue.	!shuffle
!skip	Skips the currently playing track.	!skip
!stop	Stops playback, clears the queue, and disconnects the bot.	!stop

---

🚀 Setup Guide: Homelab (ARM64 / Local)

1. Clone the repository

git clone [https://github.com/YOUR_USERNAME/your-repo-name.git](https://github.com/YOUR_USERNAME/your-repo-name.git)
cd your-repo-name

2. Environment Configuration

Create a .env file in the root directory:

cp .env.example .env
nano .env

Fill in your secrets:

DISCORD_TOKEN=your_discord_bot_token_here
SPOTIPY_CLIENT_ID=your_spotify_client_id_here
SPOTIPY_CLIENT_SECRET=your_spotify_client_secret_here

3. Run via Docker

docker compose up -d --build

---

🌐 Setup Guide: Deployment on VPS (x86_64 / Cloud)

1. Prepare server (Ubuntu / Debian)

sudo apt update && sudo apt upgrade -y
curl -fsSL [https://get.docker.com](https://get.docker.com) -o get-docker.sh
sudo sh get-docker.sh

2. Clone and Deploy

git clone [https://github.com/YOUR_USERNAME/your-repo-name.git](https://github.com/YOUR_USERNAME/your-repo-name.git)
cd your-repo-name
cp .env.example .env
nano .env
docker compose up -d --build

---

---

🇵🇱 WERSJA POLSKA

Lekki, ultra-wydajny bot muzyczny na Discorda zaprojektowany z myślą o urządzeniach o ograniczonych zasobach (procesory ARM64, Raspberry Pi, postmarketOS) oraz komercyjnych serwerach VPS (x86_64).

Zbudowany w oparciu o Python 3.11, discord.py, yt-dlp oraz spotipy. Wykorzystuje bezpośrednią integrację z natywnym FFmpeg, zużywając poniżej 60 MB RAM i eliminując problemy z przestarzałymi silnikami Javy.

✨ Funkcje

• 🚀 Natywna wieloplatformowość (Multi-Arch) – Pełna kompatybilność z ARM64 (Raspberry Pi, postmarketOS) oraz x86_64 (Standardowe VPS-y, Synology, Unraid).
• 🎶 Obsługa wielu źródeł – Odtwarzanie z YouTube (pojedyncze utwory i playlisty) oraz wyszukiwanie fraz słownych (ytsearch).
• 🟢 Integracja ze Spotify – Automatyczne konwertowanie linków utworów i playlist ze Spotify na odpowiedniki z YouTube.
• 🔀 Funkcja Shuffle & Queue – Losowe mieszanie kolejki (!shuffle) oraz automatyczne przechodzenie do kolejnych utworów.
• 🐳 Pełna konteneryzacja – Izolowane środowisko z plikiem .env (12-Factor App methodology).

---

📌 Ściągawka Komend

Komenda	Opis	Przykład
!play <link / fraza>	Odtwarza utwór z YT, dodaje playlistę YT/Spotify lub szuka po nazwie.	!play sanah szampan
!shuffle	Losowo miesza aktualną kolejkę utworów.	!shuffle
!skip	Pomija aktualnie grany utwór i przechodzi do następnego.	!skip
!stop	Zatrzymuje odtwarzanie, czyści kolejkę i odłącza bota od kanału.	!stop

---

🚀 Instrukcja Instalacji: Homelab (Lokalnie / postmarketOS / Raspberry Pi)

1. Klonowanie repozytorium i przygotowanie katalogu

git clone [https://github.com/TWOJA_NAZWA_UZYTKOWNIKA/nazwa-twojego-repo.git](https://github.com/TWOJA_NAZWA_UZYTKOWNIKA/nazwa-twojego-repo.git)
cd nazwa-twojego-repo

2. Konfiguracja zmiennych środowiskowych

Stwórz plik .env w głównym katalogu projektu:

cp .env.example .env
nano .env

Uzupełnij go swoimi danymi:

DISCORD_TOKEN=your_discord_bot_token_here
SPOTIPY_CLIENT_ID=your_spotify_client_id_here
SPOTIPY_CLIENT_SECRET=your_spotify_client_secret_here

3. Uruchomienie kontenera

docker compose up -d --build

---

🌐 Instrukcja Wdrożenia na VPS (Hetzner, DigitalOcean, OVH itp.)

1. Przygotowanie czystego serwera VPS (Ubuntu / Debian)

sudo apt update && sudo apt upgrade -y
curl -fsSL [https://get.docker.com](https://get.docker.com) -o get-docker.sh
sudo sh get-docker.sh

2. Pobranie projektu i uruchomienie produkcyjne

git clone [https://github.com/TWOJA_NAZWA_UZYTKOWNIKA/nazwa-twojego-repo.git](https://github.com/TWOJA_NAZWA_UZYTKOWNIKA/nazwa-twojego-repo.git)
cd nazwa-twojego-repo
cp .env.example .env
nano .env
docker compose up -d --build

---

📂 Project Architecture / Architektura Projektu

├── .env                # Environment variables (git-ignored)
├── .env.example        # Template for environment variables
├── .gitignore          # Git ignore rules
├── bot.py              # Main bot application (Python 3.11)
├── Dockerfile          # Image build instructions (python:3.11-slim + FFmpeg)
├── docker-compose.yml  # Service orchestration file
└── README.md           # Documentation

---

🛡️ License / Licencja

MIT License. Free for personal use and modification.