██╗  ██╗██╗   ██╗███████╗████████╗
 ██║ ██╔╝██║   ██║██╔════╝╚══██╔══╝
 █████╔╝ ██║   ██║███████╗   ██║
 ██╔═██╗ ██║   ██║╚════██║   ██║
 ██║  ██╗╚██████╔╝███████║   ██║
 ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝

     🎵 MUSIC BOT 🎵

  ⚡ yt-dlp Powered
  🤖 Clone System
  🚀 Cloud Ready

---

🚀 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 / ʟᴏᴄᴀʟ 」─

🔧 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