Skip to content

About

JustMusic Telegram Bot — Multi-platform music search, download, lyrics, charts, Shazam, VPN proxy, and Mini App

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

JustMusic

A feature-rich Telegram music bot that allows users to search, download, and manage music from multiple platforms including Deezer, Spotify, YouTube, and more.

Features

  • 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

Supported Platforms

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

Quick Start

1. Prerequisites

2. Installation

# 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 keys

3. Run the Bot

python bot.py

4. Commands

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

5. Telegram 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:

  1. Deploy the Next.js app (located in the project root) to Vercel, Netlify, or any hosting
  2. Set MINI_APP_URL in your .env to the deployed URL
  3. In @BotFather, set the Menu Button to open the Mini App URL
  4. Users can also open it via /app or 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.

6. Inline Usage

Send a Deezer, Spotify, or YouTube link directly to the bot to get an instant download.

Project Structure

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

Configuration

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

SoftEther VPN Proxy (Optional)

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).

How It Works

  1. A SoftEther VPN Client tunnel is established on the host machine
  2. SoftEther exposes a local SOCKS5/HTTP proxy (default: 127.0.0.1:1080)
  3. All bot API requests (Deezer, Spotify, YouTube) are routed through this proxy
  4. When VPN is active, the bot's egress IP appears as the VPN server's location

Supported Backends

Backend Description
softether SoftEther VPN Client (recommended)
openvpn OpenVPN with custom config
external_proxy Use an existing SOCKS5/HTTP proxy

VPN Commands (Admin Only)

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

VPN Configuration

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

Installing SoftEther VPN Client

# 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 myvpn

License

GNU General Public License v3.0

About

JustMusic Telegram Bot — Multi-platform music search, download, lyrics, charts, Shazam, VPN proxy, and Mini App

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages