TgMusicBot - Telegram Music Bot

Telegram Group Calls Streaming bot with some useful features, written in Python with Py-Tgcalls. Supporting platforms like YouTube, Spotify, Apple Music, Soundcloud, JioSaavn and more.

@FallenBeatzBot - Try it now!

---

🚫 Tired of IP Bans from YouTube?

Say goodbye to restrictions with our Premium Music API – your ultimate solution for seamless, high-quality downloads.

• Easy Integration – Just set API_URL & API_KEY variables in your bot configuration.
• High-Quality Downloads – Get music from Spotify, SoundCloud, and YouTube in top quality.

📩 Contact me on Telegram to get access or use @FallenApiBot

---

Want to use cookies?

📘 Check out this guide for instructions on downloading and using them.

---

Features

• Multi-Platform Support - Play music from Spotify, YT-Music, YouTube, JioSaavn, Apple Music, SoundCloud and Telegram files.
• Playlists & Queue - Seamless music playback with queue management.
• Full Playback Controls - Skip, Pause, Resume, End, Mute, Unmute, Volume, Loop, Seek.
• Group Voice Chats - Supports Telegram group voice chats (requires admin permissions).
• Optimized Performance - Fully async, efficient, and lightweight.
• Easy Deployment - Pre-configured Docker setup.
• Multi-Language Support - Available in English, Hindi, Spanish, Arabic, and more. Easily extendable with your own translations.
• Open-Source & Free - Built from scratch using PyTdBot & PyTgCalls.

  💡 Prefer using Pyrogram instead of PyTdBot? Check out the Pyro-Branch.

---

Installation

Dependency Tree: Click to expand

tgmusicbot v1.2.0
├── aiofiles v24.1.0
├── apscheduler v3.11.0
│   └── tzlocal v5.3.1
├── cachetools v5.5.2
├── kurigram v2.2.3
│   ├── pyaes v1.6.1
│   └── pysocks v1.7.1
├── meval v2.5
├── ntgcalls v2.0.0rc5
├── pillow v11.2.1
├── psutil v7.0.0
├── py-tgcalls v2.2.0rc3
│   ├── aiohttp v3.11.18
│   │   ├── aiohappyeyeballs v2.6.1
│   │   ├── aiosignal v1.3.2
│   │   │   └── frozenlist v1.6.0
│   │   ├── attrs v25.3.0
│   │   ├── frozenlist v1.6.0
│   │   ├── multidict v6.4.3
│   │   ├── propcache v0.3.1
│   │   └── yarl v1.20.0
│   │       ├── idna v3.10
│   │       ├── multidict v6.4.3
│   │       └── propcache v0.3.1
│   ├── deprecation v2.1.0
│   │   └── packaging v25.0
│   └── ntgcalls v2.0.0rc5
├── py-yt-search v0.3
│   ├── httpx v0.28.1
│   │   ├── anyio v4.9.0
│   │   │   ├── idna v3.10
│   │   │   └── sniffio v1.3.1
│   │   ├── certifi v2025.4.26
│   │   ├── httpcore v1.0.9
│   │   │   ├── certifi v2025.4.26
│   │   │   └── h11 v0.16.0
│   │   └── idna v3.10
│   └── python-dotenv v1.1.0
├── pycryptodome v3.22.0
├── pydantic v2.11.4
│   ├── annotated-types v0.7.0
│   ├── pydantic-core v2.33.2
│   │   └── typing-extensions v4.13.2
│   ├── typing-extensions v4.13.2
│   └── typing-inspection v0.4.0
│       └── typing-extensions v4.13.2
├── pymongo v4.13.0
│   └── dnspython v2.7.0
├── pytdbot v0.9.3
│   ├── aio-pika v9.5.5
│   │   ├── aiormq v6.8.1
│   │   │   ├── pamqp v3.3.0
│   │   │   └── yarl v1.20.0 (*)
│   │   ├── exceptiongroup v1.2.2
│   │   └── yarl v1.20.0 (*)
│   └── deepdiff v8.4.2
│       └── orderly-set v5.4.0
├── pytgcrypto v1.2.9.2
├── python-dotenv v1.1.0
├── pytz v2025.2
├── tdjson v1.8.49
├── ujson v5.10.0
├── yt-dlp v2025.4.30
├── black v25.1.0 (extra: dev)
│   ├── click v8.1.8
│   ├── mypy-extensions v1.1.0
│   ├── packaging v25.0
│   ├── pathspec v0.12.1
│   └── platformdirs v4.3.7
├── ruff v0.11.7 (extra: dev)
└── setuptools v78.1.1 (extra: dev)

📌 Docker Installation (Recommended) (Click to expand)

🐳 Prerequisites

1. Install Docker:
   • Linux
   • Windows/Mac

🚀 Quick Setup

1. Clone the repository:

   git clone https://github.com/AshokShau/TgMusicBot.git && cd TgMusicBot

🔧 Configuration

1. Prepare environment file:

   cp sample.env .env

2. Edit configuration (choose one method):

   • Beginner-friendly (nano):

     nano .env

     • Edit values
     • Save: Ctrl+O → Enter → Ctrl+X

   • Advanced (vim):

     vi .env

     • Press i to edit
     • Save: Esc → :wq → Enter

🏗️ Build & Run

1. Build Docker image:

   docker build -t tgmusicbot .

2. Run container (auto-restarts on crash/reboot):

   docker run -d \
     --name tgmusicbot \
     --env-file .env \
     --restart unless-stopped \
     tgmusicbot

🔍 Monitoring

1. Check logs:

   docker logs -f tgmusicbot

   (Exit with Ctrl+C)

⚙️ Management Commands

• Stop container:

  docker stop tgmusicbot

• Start container:

  docker start tgmusicbot

• Update the bot:

  docker stop tgmusicbot
  docker rm tgmusicbot
  git pull origin master
  docker build -t tgmusicbot .
  docker run -d --name tgmusicbot --env-file .env --restart unless-stopped tgmusicbot

📌 Step-by-Step Installation Guide (Click to Expand)

🛠️ System Preparation

1. Update your system (Recommended):

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

2. Install essential tools:

   sudo apt-get install git python3-pip ffmpeg tmux -y

⚡ Quick Setup

1. Install UV package manager:

   pip3 install uv

2. Clone the repository:

   git clone https://github.com/AshokShau/TgMusicBot.git && cd TgMusicBot

🐍 Python Environment

1. Create virtual environment:

   uv venv

2. Activate environment:

   • Linux/Mac: source .venv/bin/activate
   • Windows (PowerShell): .\.venv\Scripts\activate

3. Install dependencies:

   uv pip install -e .

🔐 Configuration

1. Setup environment file:

   cp sample.env .env

2. Edit configuration (Choose one method):

   • For beginners (nano editor):

     nano .env

     • Edit values
     • Save: Ctrl+O → Enter → Ctrl+X

   • For advanced users (vim):

     vi .env

     • Press i to edit
     • Save: Esc → :wq → Enter

🤖 Running the Bot

1. Start in tmux session (keeps running after logout):

   tmux new -s musicbot
   tgmusic

   Tmux Cheatsheet:

   • Detach: Ctrl+B then D
   • Reattach: tmux attach -t musicbot
   • Kill session: tmux kill-session -t musicbot

🔄 After Updates

To restart the bot:

tmux attach -t musicbot
# Kill with Ctrl+C
tgmusic

Deploy on Heroku (Click to expand)

---

Configuration

📌 Environment Variables (Click to expand)

🔑 Required Variables

• API_ID – Get from my.telegram.org
• API_HASH – Get from my.telegram.org
• TOKEN – Get from @BotFather

🔗 String Sessions

• STRING1 - Pyrogram String Session, STRING2 ... STRING10

Get from @StringFatherBot

🛠️ Additional Configuration

• OWNER_ID – Your Telegram User ID
• MONGO_URI – Get from MongoDB Cloud
• API_URL – Get from @FallenApiBot (API for unlimited downloads)
• API_KEY – Required for API_URL
• DOWNLOADS_DIR – Directory for downloads and TDLib database
• SUPPORT_GROUP – Support Group Link
• SUPPORT_CHANNEL – Support Channel Link
• IGNORE_BACKGROUND_UPDATES – Ignore background updates
• LOGGER_ID – Log Group ID
• AUTO_LEAVE – Leave all chats for all userbot clients.
• MIN_MEMBER_COUNT – Minimum number of members required for the bot to stay in a group.

🎵 Music Download Options

• PROXY – Optional; Proxy URL for yt-dlp
• DEFAULT_SERVICE – Default search platform (Options: youtube, spotify, jiosaavn)
• DOWNLOADS_DIR – Directory for downloads and TDLib database

🍪 Cookies

• COOKIES_URL – URLs for downloading cookies (More info here)

---

🎮 Usage

1. Add @FallenBeatzBot to a group and grant admin permissions.
2. Use /start to initialize the bot.
3. Use /help to view the list of available commands.

---

Contributing

Contributions are welcome! If you'd like to contribute:

1. Fork the repository.
2. Make meaningful changes – improve features, fix bugs, or optimize performance.
3. Submit a pull request with a clear explanation of your changes.

🔹 Avoid submitting minor PRs for small typos or README tweaks unless they significantly improve clarity.

---

License

This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.

---

Credits

• AshokShau - Creator & Maintainer
• Thanks to all contributors & bug hunters for improving the project!
• Special thanks to PyTgCalls for their outstanding work.

---

💖 Support the Project

Love TgMusicBot? Help keep it running!

💰 Donate via Crypto, PayPal, or UPI – Contact me on Telegram for details.

Every contribution helps! ❤️

---

🔗 Links

Follow me on GitHub for updates.
Star the repository on GitHub to support the project.

📢 Join our Telegram community: