A feature-rich Telegram music bot that allows users to search, download, and manage music from multiple platforms including Deezer, Spotify, YouTube, and more.
- Universal Music Search — Search across Deezer, Spotify, YouTube
- Download Music — Download tracks, albums in MP3, M4A, FLAC, OGG
- Multiple Qualities — Low, Medium, High, Lossless (FLAC)
- Lyrics — View and download song lyrics (LRC/TXT)
- YouTube Support — Download audio/video from YouTube
- Metadata Viewer — View ID3 tags of audio files
- Tags Editor — Edit metadata (title, artist, album, etc.)
- Link Converter — Convert links between Deezer, Spotify, YouTube
- Billboard Charts — Browse Top 100 charts
- Shazam Recognition — Identify songs from audio clips
- Multilingual — English, Arabic, French, Spanish, and more
- User Settings — Customizable default quality, format, language
- SoftEther VPN Proxy — Optional VPN tunnel to bypass geo-restrictions (admin)
- Telegram Mini App — Full-featured web app that opens inside Telegram
| Platform | Search | Download |
|---|---|---|
| Deezer | Yes | Yes |
| Spotify | Yes | Via Deezer |
| YouTube | Yes | Yes |
| Apple Music | Partial | Via Deezer |
| Amazon Music | Partial | Via Deezer |
| Tidal | Partial | Via Deezer |
| Qobuz | Partial | Via Deezer |
- Python 3.10+
- A Telegram Bot Token from @BotFather
- (Optional) Spotify API credentials from Spotify Developer Dashboard
- (Optional) FFmpeg installed on the system
- (Optional) SoftEther VPN Client for geo-restricted content
# Clone the repository
git clone https://github.com/yourusername/justmusic-bot.git
cd justmusic-bot
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# or: venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Copy and edit configuration
cp .env.example .env
# Edit .env with your bot token and API keyspython bot.py| Command | Description |
|---|---|
/start |
Start the bot and see welcome message |
/help |
Show all available commands |
/search <query> |
Search for a song, album, or artist |
/download <url> |
Download from Deezer/Spotify/YouTube link |
/lyrics <query> |
Get lyrics for a song |
/chart |
View Billboard Hot 100 chart |
/quality |
Change default audio quality |
/format |
Change default download format |
/language |
Change bot language |
/settings |
View current settings |
/identify |
Recognize a song (send audio after this command) |
/vpn |
Manage VPN proxy (admin-only) |
/app |
Open the JustMusic Mini App |
JustMusic includes a Telegram Mini App — a full-featured web application that opens inside Telegram with a native feel:
- Search — Browse music with platform filters (Deezer, Spotify, YouTube)
- Charts — Billboard Hot 100 ranked list with movement indicators
- Player — Mini player bar with track info, progress, and playback controls
- Settings — Quality, format, language configuration
- Dark/Light mode — Adapts to Telegram's theme automatically
- Pull to refresh — Native mobile gestures
- Haptic feedback — Tactile response on interactions
To set up the Mini App:
- Deploy the Next.js app (located in the project root) to Vercel, Netlify, or any hosting
- Set
MINI_APP_URLin your.envto the deployed URL - In @BotFather, set the Menu Button to open the Mini App URL
- Users can also open it via
/appor the welcome message button
The Mini App communicates with the bot via Telegram.WebApp.sendData(), sending download requests, search queries, and settings changes that the bot processes as web_app_data messages.
Send a Deezer, Spotify, or YouTube link directly to the bot to get an instant download.
justmusic-bot/
├── bot.py # Main entry point
├── config.py # Configuration management
├── requirements.txt # Python dependencies
├── .env.example # Environment variable template
├── handlers/ # Telegram command/message handlers
│ ├── __init__.py
│ ├── start.py # Start, help commands
│ ├── search.py # Music search handler
│ ├── download.py # Download handler
│ ├── lyrics.py # Lyrics handler
│ ├── convert.py # Link conversion handler
│ ├── charts.py # Billboard charts handler
│ ├── settings.py # User settings handler
│ ├── shazam.py # Song recognition handler
│ ├── metadata.py # Metadata viewer/editor
│ ├── vpn.py # VPN proxy management (admin)
│ └── miniapp.py # Telegram Mini App handler
├── services/ # External API integration services
│ ├── __init__.py
│ ├── deezer.py # Deezer API service
│ ├── spotify.py # Spotify API service
│ ├── youtube.py # YouTube download service
│ ├── lyrics_svc.py # Lyrics service
│ ├── converter.py # Cross-platform link conversion
│ ├── charts_svc.py # Billboard charts service
│ ├── shazam_svc.py # Audio recognition service
│ ├── metadata_svc.py # ID3 metadata service
│ └── vpn_proxy.py # SoftEther VPN proxy service
├── utils/ # Utility modules
│ ├── __init__.py
│ ├── keyboard.py # Inline keyboard builders
│ ├── formatting.py # Message formatting helpers
│ ├── i18n.py # Internationalization
│ └── db.py # User settings database
├── locales/ # Language files
│ ├── en.json # English
│ ├── ar.json # Arabic
│ └── fr.json # French
├── downloads/ # Temporary download storage
└── temp/ # Temporary processing files
Edit the .env file to configure the bot:
- BOT_TOKEN (required): Your Telegram bot token
- BOT_NAME (optional): Display name (default: "JustMusic")
- SPOTIFY_CLIENT_ID / SECRET (optional): For Spotify search
- DEEZER_ARL (optional): For premium Deezer quality
- DEFAULT_QUALITY:
low,medium,high,lossless - DEFAULT_FORMAT:
mp3,m4a,flac,ogg - MINI_APP_URL (optional): URL to your deployed Mini App frontend
The bot includes an optional built-in SoftEther VPN proxy that routes all API traffic through a VPN tunnel. This is useful for bypassing geo-restrictions on music platforms (e.g., accessing Spotify/Deezer from restricted regions).
- A SoftEther VPN Client tunnel is established on the host machine
- SoftEther exposes a local SOCKS5/HTTP proxy (default:
127.0.0.1:1080) - All bot API requests (Deezer, Spotify, YouTube) are routed through this proxy
- When VPN is active, the bot's egress IP appears as the VPN server's location
| Backend | Description |
|---|---|
softether |
SoftEther VPN Client (recommended) |
openvpn |
OpenVPN with custom config |
external_proxy |
Use an existing SOCKS5/HTTP proxy |
| Command | Description |
|---|---|
/vpn |
Show VPN control panel |
/vpn connect |
Connect to VPN |
/vpn disconnect |
Disconnect from VPN |
/vpn reconnect [server] |
Reconnect (optionally switch server) |
/vpn status |
Detailed status with egress info |
/vpn servers |
List configured servers |
/vpn test |
Test proxy latency (3-ping average) |
/vpn toggle |
Enable/disable VPN feature |
/vpn add |
Add a new VPN server |
/vpn remove <name> |
Remove a server profile |
Set in your .env file:
# Enable the VPN feature
VPN_ENABLED=true
# Auto-connect on bot startup
VPN_AUTO_CONNECT=true
# Backend: softether | openvpn | external_proxy
VPN_BACKEND=softether
# VPN server details
VPN_SERVER_NAME=US-East
VPN_SERVER_HOST=us1.vpn.example.com
VPN_SERVER_PORT=443
VPN_SERVER_HUB=VPN
VPN_PROXY_PORT=1080
VPN_PROXY_TYPE=socks5
# Optional authentication
VPN_USERNAME=myuser
VPN_PASSWORD=mypassword
# Route only music platform traffic (not Telegram API)
VPN_ONLY_MUSIC=true# Ubuntu/Debian
wget https://www.softether-download.com/files/softether/v4.38-9620-beta-2021.08.17-tree/Linux/softether-vpnclient-v4.38-9620-beta-2021.08.17-linux-x64-64bit.tar.gz
tar xzf softether-vpnclient-*.tar.gz
cd vpnclient
make
sudo ./vpnclient start
sudo ./vpncmd localhost /SERVER /CMD AccountCreate myvpn /SERVER:vpn.example.com:443 /HUB:VPN /USERNAME:user
sudo ./vpncmd localhost /SERVER /CMD AccountPasswordSet myvpn /PASSWORD:pass
sudo ./vpncmd localhost /SERVER /CMD AccountConnect myvpnGNU General Public License v3.0