Telegram VC Music Bot

A real starter project for a Telegram voice chat music bot using Python, Pyrogram, PyTgCalls, FFmpeg, and yt-dlp.

Features

• Play music in Telegram voice chats
• /play using song names, YouTube URLs, and Spotify links
• Queue support
• /skip, /stop, /pause, /resume
• /queue, /nowplaying
• Inline control buttons
• Dockerized deployment

Important notes

This bot is a starter project for a real VC music bot. Telegram voice chat bots usually require:

1. A bot token from BotFather
2. A Telegram API ID and API HASH from https://my.telegram.org
3. An assistant account string session so the assistant user can join voice chats reliably
4. The assistant account and bot must both be added to your group
5. The assistant account may need admin permissions in the group depending on your setup
6. A voice chat must already be started in the target group

Project structure

telegram-vc-music-bot/
├── bot/
│   ├── handlers.py
│   ├── keyboards.py
│   ├── logger.py
│   ├── models.py
│   ├── player.py
│   ├── queue_manager.py
│   └── search.py
├── .env.example
├── Dockerfile
├── docker-compose.yml
├── config.py
├── main.py
└── requirements.txt

Commands

• /play <query or playlist URL>
• /skip admin only
• /stop admin only
• /pause admin only
• /resume admin only
• /queue
• /nowplaying
• /ping

Setup

1. Create Telegram credentials

• Get API_ID and API_HASH from https://my.telegram.org
• Get BOT_TOKEN from @BotFather
• Generate a Pyrogram STRING_SESSION for an assistant Telegram account

2. Configure environment

Copy the example file:

cp .env.example .env

Then fill in your real values.

Deploy on Railway

This project is prepared for Railway using nixpacks.toml so FFmpeg is installed automatically.

Railway steps

1. Push this project to GitHub
2. Create a new Railway project
3. Choose Deploy from GitHub repo
4. Select this repository
5. In Railway Variables, add:
   • API_ID
   • API_HASH
   • BOT_TOKEN
   • STRING_SESSION
   • LOG_LEVEL = INFO
6. Deploy the service
7. Check logs to confirm the bot started

Required Railway environment variables

• API_ID
• API_HASH
• BOT_TOKEN
• STRING_SESSION
• COMMAND_PREFIX optional
• LOG_LEVEL optional

Notes for Railway

• FFmpeg is installed through nixpacks.toml
• The bot runs with python main.py
• Session files are not required because this template uses a string session for the assistant account
• If Railway restarts the service, the bot should reconnect automatically on the next deploy/start

Run with Docker

docker compose up --build -d

To view logs:

docker compose logs -f

Run without Docker

Install FFmpeg first.

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg python3 python3-pip -y

Install dependencies:

pip install -r requirements.txt

Run the bot:

python main.py

Group setup

1. Add the bot to your group
2. Add the assistant account to your group
3. Promote them if needed
4. Make sure the users who should control playback are admins
5. Start a Telegram voice chat in that group
6. Send /play never gonna give you up

Spotify support note

Spotify links are not streamed directly from Spotify. This starter resolves Spotify links as search metadata and tries to find a matching result on YouTube.

PyTgCalls compatibility review

A deploy review file has been added at:

• bot/compatibility_notes.md

Main likely issues before deploy:

1. Import paths can differ between PyTgCalls versions
2. join_group_call / change_stream signatures may vary
3. Stream-end event decorator behavior may vary by release
4. Assistant auto-join using exported invite links may fail in some group setups

If Railway logs show PyTgCalls import or runtime errors, the next fix is usually to pin a known-good version and adjust imports to that exact version.

Common issues

No active voice chat found

Start a voice chat in the group before using /play.

Assistant cannot join

Make sure the assistant account is valid, not restricted, and can join the group.

Telegram permissions

Your bot/assistant may need admin permissions depending on the group settings.

Streaming errors

Some source URLs may expire. In a production bot, you may want automatic refresh/re-resolution of streams.

Production upgrades included

• Auto-play next track when the current stream ends
• Better startup and shutdown logging
• Stream refresh retry when a source URL expires
• Railway-friendly process files (Procfile, runtime.txt, nixpacks.toml)
• Safer callback and command error handling
• /ping command for quick health checks
• Basic concurrency lock around playback state changes

Recommended next upgrades

• Better Spotify parsing for playlists/albums
• Playlist support
• Persistent queue storage
• Admin-only controls
• Volume controls
• Thumbnail-rich now playing cards
• Multi-group access control and moderation tools

Disclaimer

This project is provided as a starter template. Telegram VC library APIs can change over time, so you may need small compatibility updates depending on your installed versions.