Your TV's remote is now Telegram

A bot that turns any Linux box plugged into a TV into an mpv-powered media center you control from the couch — or the other side of the world. No port forwarding, no VPN, no smart-TV apps — by default it only makes outbound connections.

Get started Source ↗

Features

Around 40 commands behind a Telegram user-ID allowlist — these are the highlights.

📋Browse your library

Categories → playlists as inline buttons, full-text search, an episode picker and chapter jumps.

🔗Stream any link

Send a YouTube / SoundCloud / any yt-dlp URL — it plays on the TV, subtitles fetched automatically.

🧩Even pages yt-dlp can't read

Drop-in site plugins, plus an optional headless-Chromium fallback that sniffs the stream from JavaScript-only players.

🔎Search YouTube from chat

/yt lofi beats — top results with thumbnails, tap one to play.

📨Forward video files

Any Telegram video plays on the TV — up to 2 GB with a local Bot API server.

🎛Full transport control

The now-playing panel rides on every "▶ Playing" message: pause, seek, %-jump, volume, mute, speed, tracks, 📸 shot, ⏺ clip, 📥 upload, 🗑 close.

📥Upload what's playing

One tap sends the current file — or the downloaded stream, with a live progress bar — to the chat. Up to 2 GB with a local Bot API server.

⏺Record & clip

Capture what's playing to an H.264 mp4, or the radio to a voice message, and get it right in the chat — tap once to start, again to stop.

🕘Watch history

Last 20 played, paginated. Tap the title to replay (streams resume from the saved position), tap the icon to copy the URL/path, tap 🗑 to remove the entry.

🔔Knows when you're done

"⏭ Now playing: 6/12" on episode change, "✅ Finished" at the end. /sleep 45m for bedtime.

📻Internet radio

The full SomaFM catalog and friends as presets, plus search across ~50k stations — tuned in about a second.

📺Live TV (IPTV)

/iptv BBC searches 50 000+ channels from the iptv-org catalogue — tap a result to stream live on the TV.

🌐Play from anything

Opt-in POST /play sends a link to the TV (or a whole list, played one after another), GET /status reads what's playing and POST /ctl pauses, seeks or changes the volume — behind a bearer token, from a script, a phone shortcut or another app, no Telegram needed. Off until you set a token.

🩺Runs itself

Auto-updating yt-dlp, playlist doctor & repair, disk GC, one-screen health check.

Telegram chat with tg-mpv-bot: category buttons, URL streaming and the now-playing panel

Install

You need a token from @BotFather and your user ID from @userinfobot. mpv on the host.

install from source
# needs uv → https://docs.astral.sh/uv/
git clone https://github.com/antlis/tg-mpv-bot
cd tg-mpv-bot && uv sync
cp .env.example .env   # BOT_TOKEN + ALLOWED_USERS
set -a; source .env; set +a
uv run bot.py
tg-mpv-bot-git
yay -S tg-mpv-bot-git
install -m600 /usr/share/doc/tg-mpv-bot/env.example \
  ~/.config/tg-mpv-bot.env
$EDITOR ~/.config/tg-mpv-bot.env
systemctl --user enable --now tg-mpv-bot
ghcr.io
docker pull ghcr.io/antlis/tg-mpv-bot:latest
# host networking + X11 bind mounts —
# see docker-compose.yml in the repo
flake
# BOT_TOKEN + ALLOWED_USERS in the environment
nix run github:antlis/tg-mpv-bot
# Chromium fallback: nix build .#with-browser
# home-manager: import homeManagerModules.default,
#   services.tg-mpv-bot.enable = true;

On Docker, mpv runs inside the container and renders onto the host's X11 display — GPU passthrough, audio socket ownership and window-focus glue all have sharp edges worth reading before you debug them the hard way: see Docker gotchas in the README.

Commands

Every command the bot understands — plus two that aren't commands at all: just send a link or a video file.

Browse & play

/library
browse by category, or tap 🔍 Search and reply with a title — opens with "▶ Continue: last watched"
/play <query>
play by name or number (/mpv works too)
/search [cat] <text>
every match as a play button
/random [category]
"just put something on"
/last
resume the last playlist or stream where you left off
/history
last 20 played, paginated — tap to replay, copy URL, or delete

Streaming & files

(send a link)
any YouTube / SoundCloud / yt-dlp URL just plays
(send a video file)
plays on the TV — up to 2 GB with a local Bot API server
/url <link>
the explicit version of sending a link
/yt <search>
search YouTube — top results as buttons with thumbnails
/radio [search]
internet radio: 50+ presets incl. the full SomaFM catalog
/iptv [search]
live TV — search 50 000+ channels from the iptv-org catalogue

Transport

/info
now-playing panel — it also rides on every "▶ Playing" message
/toggle
play / pause (also /pause, /unpause)
/fwd · /back
seek +30s / −10s
/goto <pos>
jump to 1:23:45, 90 (s) or 75%
/speed [x]
0.75–2× buttons, or any value like 1.5
/quit
stop playback entirely

Playlist navigation

/next · /prev
next / previous item
/ep [n]
episode picker buttons, or jump straight to item n
/chapters
movie / YouTube chapters as jump buttons
/shuffle
shuffle the current playlist
/loop
toggle playlist looping

Sound & subtitles

/volup · /voldown
volume ±10 (/mute to silence)
/audio
switch audio track (e.g. Spanish → English)
/sub
switch subtitle track (/sub_toggle to hide)
/night
loudness normalization: explosions ↓, dialogue ↑

Comfort

/sleep <time>
stop after 45m / 1.5h (off cancels)
/notify
toggle "⏭ now playing" / "✅ finished" messages
/shot
screenshot of the current frame, sent to the chat
/record
record the video (→ mp4) or radio (→ voice) and send it

Library & maintenance

/scan
create playlists for newly-added media
/doctor
report playlists with missing files
/fix
repair broken playlists (re-point moved files)
/health
one screen: mpv, yt-dlp, API server, disks
/update_ytdlp
bump yt-dlp — the fix when YouTube breaks
/help
all of this, inside Telegram