A Telegram voice-chat music & video bot.
Stream YouTube tracks (or your own audio/video files) straight into a group voice chat — with a rich inline player, playlists, audio effects, live-call title updates, and per-group rankings.
- Features · Requirements · Quick start · Docker · Setup · Configuration
- Commands · Audio effects · Settings · Rankings
- Troubleshooting · Known Issues · Contributing · Support · License
- Music & video streaming — play YouTube audio or video into a voice chat.
- Inline player — pause / resume / skip / stop / seek / rewind / replay / volume, all from buttons.
- Audio effects — Bass Boost, Nightcore, Slowed, Lofi, 8D.
- Playback speed — from
0.5xto2.0x. - Loop modes — off / repeat-track / repeat-queue.
- Playlists — load a whole YouTube playlist (lazy-fetched 10 tracks at a time), plus save / load / delete named playlists.
- Rankings — daily, weekly and global top-listeners, rendered as banner images.
- Telegram files — reply to an audio/video file to queue it directly.
- Live streams — plays YouTube live streams.
- Inline search — type
@YourBot song namein any chat to search YouTube. - Live call title — updates the group call title to the currently playing track.
- Voice-chat welcome — greets listeners inside the voice chat when they join.
- Multi-chat — serves many groups at once.
- Permissions — group-admins plus a per-group "VC admin" system.
- Broadcast — owner-only message broadcast to all users/groups.
With Docker you only need Docker and a MongoDB (or Atlas). The table below is for running without Docker.
Runtime (not installable via pip):
| Dependency | Why | Install |
|---|---|---|
| Python 3.11 | runtime | python.org |
| ffmpeg | audio effects + re-encoding | apt install ffmpeg (or ffmpeg.org) |
yt-dlp CLI |
live-stream URL extraction | installed automatically by run.sh |
| MongoDB | all persistence | mongodb.com or Atlas |
| Deno | YouTube JS-challenge solving for yt-dlp |
installed automatically by run.sh |
Note on Deno: it is required for solving YouTube's JS challenges.
run.shinstalls it automatically if missing.
Python packages are listed in requirements.txt and installed automatically by run.sh.
The easiest way to run Telecast is with Docker. The image already includes Python 3.11, ffmpeg, the yt-dlp CLI and Deno, so the host only needs Docker.
git clone https://github.com/bisnuray/Telecast.git
cd Telecast
# 1. Fill in your credentials
cp .env.example .env
nano .env
# 2. Add your YouTube cookies (see "YouTube cookies" below)
mkdir -p cookies
# place your Netscape-format cookies at cookies/yt.txt
# 3. Build and start
docker compose up -d --builddocker compose up -d --build # build and start
docker compose logs -f telecast # follow logs
docker compose down # stopcookies/is mounted read-only,logs/is mounted sologs/bot.logstays on the host.- The bot's
.sessionfile is kept in thetelecast-datavolume, so it survives rebuilds. - After changing code, run
docker compose up -d --buildagain.
Local MongoDB (optional): if you don't use Atlas, start the bundled MongoDB too and set MONGODB_URI=mongodb://mongo:27017/vcbot in .env:
docker compose --profile mongo up -d --buildInstall the requirements yourself, or let run.sh do it. It installs/upgrades the Python dependencies, yt-dlp, Deno and ffmpeg if missing, then starts the bot:
./run.shOr manually:
pip install -r requirements.txt
python3.11 bot.pyDon't run the Docker container and the bot without Docker at the same time — both would use the same bot token.
- Go to my.telegram.org and log in.
- Create an app to get
API_IDandAPI_HASH. - Create your bot with @BotFather to get
BOT_TOKEN.
The bot uses two accounts:
telecast— your bot (runs onBOT_TOKEN).user_client— a user account (runs onSESSION_STRING). This is the account that actually joins the voice chat and streams, because Telegram requires a user (not a bot) to stream audio in a voice chat.
Generate the session string using @TgDevToolBot:
- Open Telegram and start @TgDevToolBot.
- Select 🔐 Pyrogram Session from the menu.
- Enter your
API_IDandAPI_HASHwhen prompted. - Log in with the user account's phone number and the OTP code.
- Copy the resulting string into
.envasSESSION_STRING.
Use a local MongoDB (mongodb://localhost:27017/vcbot) or a free MongoDB Atlas cluster. Put the URI in .env.
YouTube may block downloads from datacenter IPs ("Sign in to confirm you're not a bot"). To avoid this, export your browser's YouTube cookies in Netscape format and save them to cookies/yt.txt.
- Easiest method: a browser extension such as Get cookies.txt LOCALLY.
- The file must be Netscape/HTTP-cookie format (
# Netscape HTTP Cookie Fileheader followed by tab-separated rows).
All configuration lives in .env (see .env.example).
| Variable | Required | Default | Description |
|---|---|---|---|
API_ID |
Yes | — | Telegram app ID |
API_HASH |
Yes | — | Telegram app hash |
BOT_TOKEN |
Yes | — | Bot token from BotFather |
SESSION_STRING |
Yes | — | User-account string session |
MONGODB_URI |
Yes | mongodb://localhost:27017/vcbot |
MongoDB connection URI |
LOG_LEVEL |
— | INFO |
Logging level |
LOG_CHAT_ID |
— | 0 |
Chat ID to receive log notifications |
MAX_QUEUE_SIZE |
— | 100 |
Max tracks per queue |
MAX_CONCURRENT_CHATS |
— | 50 |
Max simultaneous voice chats |
MAX_PLAYLIST_TRACKS |
— | 50 |
Max tracks loaded from a playlist |
MAX_TRACK_DURATION |
— | 7200 |
Max track length (seconds) |
AUTOPLAY_BATCH_SIZE |
— | 5 |
Related tracks queued when autoplay is allowed |
AUTOPLAY_PROMPT_TIMEOUT |
— | 90 |
Seconds to wait for an answer to the autoplay prompt |
CACHE_CHAT_ID |
— | 0 |
Channel used to cache uploaded audio by file_id |
PREFETCH_ENABLED |
— | true |
Pre-download the next track while the current one plays |
YOUTUBE_PROXY |
— | — | Proxy for yt-dlp, search and live streams (http://user:pass@host:port) |
SESSION_DIR |
— | . |
Folder for the bot's .session file (/app/data in Docker) |
Note:
BOT_OWNER_ID(used for/restart,/broadcast, and/logs) is hardcoded intelecast/core/config.py. Change it to your own Telegram user ID before deploying.
Commands work with both / and . prefixes (e.g. /play or .play). Most work only in groups where the bot is present.
| Command | Description |
|---|---|
/start |
Show the welcome message |
/help |
Show help |
/play <query|url|playlist> |
Play a song / video / playlist from YouTube |
/pause |
Pause playback |
/resume |
Resume playback |
/skip |
Skip to the next track |
/stop / /end |
Stop and leave the voice chat |
/seek <seconds> |
Seek forward (+) or backward (−) |
/rewind |
Rewind 10 seconds |
/vcmute |
Mute the voice chat |
/vcunmute |
Unmute the voice chat |
/playlist |
Show the current queue |
/clearplaylist |
Clear upcoming tracks |
/settings |
Open the settings menu (admin) |
/vcadmin |
Grant voice-chat control to a user (admin) |
/vcunadmin |
Revoke voice-chat control (admin) |
/rank / /ranking |
View group rankings |
/status |
Show bot statistics |
/restart |
Restart the bot (owner) |
/broadcast |
Broadcast a replied-to message (owner) |
/logs |
View and clear the bot log file (owner) |
The now-playing message includes a full control bar:
- ⏯ Pause / Resume, ⏭ Skip, ⏹ Stop
- 🔁 Loop (off / track / queue)
- ⏪ Rewind, ⏩ Seek, 🔃 Replay
- 🔊 Volume, 🔇/🔊 Mute / Unmute
- 🎚 Effects & ⏩ Speed menus
- 📜 Queue pager, 🔀 Shuffle, 🗑 Clear queue
| Effect | Button |
|---|---|
| Normal | 🎵 Normal |
| Bass Boost | 🔊 Bass Boost |
| Nightcore | ⚡ Nightcore |
| Slowed | 🐢 Slowed |
| Lofi | 📻 Lofi |
| 8D | 🎧 8D |
Playback speed presets: 0.5x, 0.75x, 1.0x, 1.25x, 1.5x, 2.0x.
Open with /settings (admin). Available toggles:
- Mode — audio or video
- Quality — 360p / 480p / 720p / 1080p
- Audio quality — low / medium / high
- Autoplay — when the queue drains, ask whether to keep playing related songs
- Title update — update the live call title to the current track
- Admin-only mode — restrict playback to admins/VC-admins
- Shuffle
- Mention requester
- Playlist permission — who may load playlists (everyone / admins)
- Autoplay permission — who may answer the autoplay prompt (everyone / admins)
- VC Welcome — greet listeners when they join the voice chat
With Autoplay on, the bot never starts related songs on its own — it asks first. When the last queued track ends, it posts the track it just played with two buttons:
| Button | Result |
|---|---|
| Play Related Songs | Queues AUTOPLAY_BATCH_SIZE related tracks (from YouTube's own related list) and keeps playing |
| No Thanks | Stops playback and leaves the voice chat |
If nobody answers within AUTOPLAY_PROMPT_TIMEOUT seconds, playback stops. When the
related batch drains, the bot asks again — so it behaves like a radio while still
giving the group a decision point. Related songs are only offered when the last track
was a YouTube one; tracks longer than MAX_TRACK_DURATION are skipped.
Autoplay permission decides who may press those buttons:
- Everyone (default) — any member of the group can answer
- Admins — only group admins and VC admins can answer; others get an alert
When someone joins the voice chat while music is playing, the assistant posts a short greeting inside the call — the text bubble that appears over the voice chat:
👋 Welcome, Alex! Enjoy the music 🎶
Each listener is greeted once per call. If they leave and rejoin the same voice chat, nothing is sent; when the call ends and a new one starts, they are greeted again. The assistant never greets itself.
Turn it off per group with 👋 VC Welcome in /settings (on by default).
Two things to know:
- Greetings use Telegram's in-call messages, which only exist while the assistant is in the call — so they appear during playback, not in the group's message history.
- The voice chat must have messages enabled (an admin setting in Telegram). If they are off, Telegram rejects the message; the bot logs why and posts nothing to the group instead of falling back to a normal chat message.
/rank renders a banner image of top listeners.
- Daily and Weekly — per-group.
- Global — across all groups.
Switch between them using the inline buttons on the ranking message.
| Problem | Fix |
|---|---|
| "Sign in to confirm you're not a bot" | YouTube is bot-checking your IP. Add/refresh cookies/yt.txt, or route through a proxy/residential IP. |
"Network is unreachable" to googlevideo.com |
YouTube CDN is unreachable from your server. Try a different region or a proxy. |
| Download fails for some tracks | Make sure yt-dlp is up to date (pip install -U yt-dlp). |
| User account won't join the call | The user account must be in the group and the bot must be admin. |
| Title doesn't update | The user account needs the "Manage Voice Chats" admin permission. |
SESSION_STRING invalid |
Regenerate the string session (see Setup). |
When a track plays with an audio effect (Bass Boost, Nightcore, Slowed, Lofi, or 8D), the bot may not auto-leave the voice chat after it ends. With 🎵 Normal, it leaves correctly.
The effect runs through an FFmpeg filter chain that can block the end-of-stream signal, so the bot doesn't detect that the track has finished. The fix belongs in telecast/services/stream.py (end-of-stream detection) and telecast/services/effects.py (filter chain) — contributions welcome!
Contributions are welcome!
- Fork the repo and clone your fork.
- Install Python 3.11 and the dependencies (
pip install -r requirements.txt). - Make your changes, keeping the style consistent with the rest of the project.
- Test by running the bot (
python3.11 bot.py) and checkinglogs/bot.log. - Open a pull request describing what changed and why.
Don't commit secrets — .env, *.session*, and cookies/yt.txt are gitignored.
- Update channel: @itsSmartDev
- Discussion chat: @DevChatZone
This project is licensed under the MIT License. You are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell the software, provided the copyright notice above is included in all copies or substantial portions.
© @itsSmartDev — copyright holder.
Built with Pyrogram (via the kurigram fork), py-tgcalls, ntgcalls, yt-dlp, MongoDB/motor, Pillow and numpy.
Ethics Reminder: Simply modifying a few lines of code does not constitute original authorship. When forking a project, always fork responsibly and give proper credit to the original creators.