Skip to content

README.md

Latest commit

 

History

History
313 lines (238 loc) · 12 KB

README.md

File metadata and controls

313 lines (238 loc) · 12 KB
Raw
 ██╗  ██╗██╗   ██╗███████╗████████╗
 ██║ ██╔╝██║   ██║██╔════╝╚══██╔══╝
 █████╔╝ ██║   ██║███████╗   ██║
 ██╔═██╗ ██║   ██║╚════██║   ██║
 ██║  ██╗╚██████╔╝███████║   ██║
 ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝

     🎵 MUSIC BOT 🎵

  ⚡ yt-dlp Powered
  🤖 Clone System
  🚀 Cloud Ready

typing animation

Stars License Python

🚀 Features

Feature Description
🎧 VC Playback Stream music directly into Telegram voice chats
⚡ yt-dlp Engine Downloads audio via yt-dlp with Deno JS runtime support
🍪 Cookie Support Paste YouTube cookies as env var — no file upload needed
🔌 Download API Optional external download API with yt-dlp fallback
🤖 Clone System Add unlimited bot instances with /clone
🛡️ Admin Controls Kick, ban, mute, unmute group members
📊 Live Progress Bar Real-time progress updates every 10 seconds
🔄 Queue System Add multiple songs, auto-plays next in queue
🐳 Docker Ready Heroku deploys as container; other platforms as native Python
☁️ Cloud Ready Runs on Render, Koyeb, Railway, Heroku, or your VPS
🌱 Zero Database No MongoDB — pure in-memory state
🔥 Kurigram Powered Built on Kurigram — latest Telegram API features

📁 Project Structure

kustmusic/
├── main.py              ← Entry point, starts all services
├── config.py            ← All environment variables
├── state.py             ← In-memory state (queues, clients)
├── clients.py           ← Pyrogram + PyTgCalls client setup
├── server.py            ← Dummy HTTP server for Render/Koyeb
├── kust.env             ← Environment variable template
├── render.yaml          ← Render deployment config
├── Procfile             ← Koyeb/Heroku start command
├── cookies.txt          ← YouTube cookies (optional)
├── requirements.txt     ← Python dependencies
├── core/
│   ├── api.py           ← YouTube search + yt-dlp download
│   ├── guards.py        ← Admin check + rate limiting
│   ├── helpers.py       ← Formatting utilities
│   └── playback.py      ← Music streaming core logic
└── handlers/
    ├── router.py        ← Registers all command handlers
    ├── music.py         ← /play, /stop, /skip, /pause, /resume
    ├── admin.py         ← /kick, /ban, /mute, /unmute
    ├── system.py        ← /start, /ping, /clone, /active
    └── callbacks.py     ← Inline button handler

💡 Quick Deploy

🔴 Deploy on Render

⚠️ IMPORTANT — Fork the repo first. Do NOT deploy directly from the original.

Step 1 — Fork

  • Click Fork at the top of this page
  • This creates your own copy you can deploy from

Step 2 — Connect to Render

  1. Go to dashboard.render.com
  2. Click New + → Web Service
  3. Select "Build and deploy from a Git repository"
  4. Connect your GitHub and select your forked repo
  5. Render auto-detects render.yaml — all settings are pre-configured

Step 3 — Set Environment Variables

Add these in Render's Environment tab:

Variable Description Required
BOT_TOKEN Bot token from @BotFather ✅
ASSISTANT_SESSION Pyrogram string session for userbot ✅
API_ID From my.telegram.org ✅
API_HASH From my.telegram.org ✅
OWNER_ID Your Telegram user ID ✅
SEARCH_API_URL Leave blank for default search API ❌
DOWNLOAD_API_BASE Your download API base URL — leave blank to use yt-dlp ❌
YOUTUBE_COOKIES Paste your raw YouTube cookies here (see below) ❌

Step 4 — Deploy

  • Click "Create Web Service" — build takes ~3 minutes

💡 How to get ASSISTANT_SESSION: Use @StringFatherBot to generate a Pyrogram string session from your Telegram account.

🐳 Deploy on Heroku (Container Mode)

Heroku uses the included Dockerfile which installs FFmpeg + Deno automatically.

Step 1 — Set Heroku to container stack before deploying:

heroku login
heroku create your-app-name
heroku stack:set container -a your-app-name
git push heroku main

Or use the one-click button above — then run:

heroku stack:set container -a your-app-name

💡 The heroku.yml file in the repo tells Heroku to build from Dockerfile. All other platforms (Render, Railway, Koyeb) ignore heroku.yml and use their own config files — they deploy as normal Python without Docker.

🤖 Clone System

Once deployed, you can add multiple bot instances with /clone:

/clone <BOT_TOKEN>
  • Send this in private chat with your deployed bot
  • Get new bot tokens from @BotFather
  • Each clone runs independently with its own owner
  • No limit — add as many as you need

Check active bots:

/active

(Main owner only)

🍪 Cookies Setup (Optional)

Add YouTube cookies to bypass rate limits and age restrictions. No file needed — just paste the content directly as an environment variable.

How to get your cookies:

  1. Install "Get cookies.txt LOCALLY" extension on Chrome/Firefox
  2. Open youtube.com and log in
  3. Click the extension → Export cookies for youtube.com
  4. Open the exported file in any text editor and copy all the text

How to set it:

  • On Render / Koyeb / Railway / Heroku: go to your service's Environment Variables, add YOUTUBE_COOKIES and paste the full cookie text as the value
  • On VPS: open your .env file and set YOUTUBE_COOKIES=<paste here> (use quotes if the text has newlines)

The bot writes the cookies to disk on startup automatically — no file upload needed.

⚠️ Never share your cookies publicly — they give access to your YouTube account.

🤖 AI Customization (Avoid Platform Bans)

Each deployment needs a unique codebase to avoid platform duplicate detection. Use any AI to help:

Prompt for Claude / ChatGPT:

I have a modular Telegram music bot with these files:
main.py, config.py, state.py, clients.py, server.py,
core/api.py, core/guards.py, core/helpers.py, core/playback.py,
handlers/router.py, handlers/music.py, handlers/admin.py,
handlers/system.py, handlers/callbacks.py

Please help me make this deployment unique by:
1. Renaming variables and functions to unique names across all files
2. Rewriting log/error messages to be different
3. Reorganizing code flow within functions (keeping same behavior)
4. Changing any hardcoded string literals to different wording

Keep all functionality exactly the same — only change names and structure
to make this deployment unique. Show me each file separately.

Here are the files: [PASTE EACH FILE CONTENT]

Steps:

  1. Open claude.ai or chatgpt.com
  2. Paste the prompt + all your file contents
  3. Get unique versions of each file
  4. Replace the files in your fork
  5. Deploy

🛠️ Environment Variables Reference

Copy kust.env and rename it to .env for local/VPS use.

Test Bot ➣ Kust Music

─「 ᴅᴇᴩʟᴏʏ ᴏɴ ᴠᴘs / ʟᴏᴄᴀʟ 」─

YouTube Tutorial

🔧 VPS Setup

  1. Update system

    sudo apt-get update && sudo apt-get upgrade -y

  2. Install dependencies

    sudo apt-get install python3-pip ffmpeg -y

  3. Clone the repo

    git clone https://github.com/kustbots/kustmusic && cd kustmusic

  4. Install Python packages

    pip3 install -U -r requirements.txt

  5. Setup environment

    cp kust.env .env
nano .env

    Fill in your variables, then Ctrl+X → Y → Enter to save.

  6. Run with tmux

    sudo apt install tmux -y
tmux new -s music
python3 main.py

    Press Ctrl+B then D to detach (bot keeps running).

📜 Commands

Command Description Who
/play <song> Play a song or YouTube URL Everyone
/skip Skip current song Admins
/stop Stop and clear queue Admins
/pause Pause playback Admins
/resume Resume playback Admins
/clear Clear the queue Admins
/ping Bot stats and latency Everyone
/clone <token> Add a new bot instance Anyone (private)
/active List all active bots Main Owner
/kick Kick a user (reply) Admins
/ban Ban a user (reply) Admins
/unban Unban a user (reply) Admins
/mute Mute a user (reply) Admins
/unmute Unmute a user (reply) Admins

─「 sᴜᴩᴩᴏʀᴛ 」─

Made with ❤️ by KustBots