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 — 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.

🔎Search YouTube from chat

/mpv_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

One now-playing panel: pause, seek, %-jump, volume, speed, audio & subtitle tracks.

⏺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. /mpv_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)

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

🩺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

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

/mpv_list
browse by category — opens with "▶ Continue: last watched"
/mpv_play <query>
play by name or number (/mpv works too)
/mpv_search [cat] <text>
every match as a play button
/mpv_random [category]
"just put something on"
/mpv_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
/mpv_url <link>
the explicit version of sending a link
/mpv_yt <search>
search YouTube — top results as buttons with thumbnails
/mpv_radio [search]
internet radio: 50+ presets incl. the full SomaFM catalog
/mpv_iptv [search]
live TV — search 50 000+ channels from the iptv-org catalogue

Transport

/mpv_info
now-playing panel with all controls as buttons
/mpv_toggle
play / pause (also /mpv_pause, /mpv_unpause)
/mpv_fwd · /mpv_back
seek +30s / −10s
/mpv_goto <pos>
jump to 1:23:45, 90 (s) or 75%
/mpv_speed [x]
0.75–2× buttons, or any value like 1.5
/mpv_quit
stop playback entirely

Playlist navigation

/mpv_next · /mpv_prev
next / previous item
/mpv_ep [n]
episode picker buttons, or jump straight to item n
/mpv_chapters
movie / YouTube chapters as jump buttons
/mpv_shuffle
shuffle the current playlist
/mpv_loop
toggle playlist looping

Sound & subtitles

/mpv_volup · /mpv_voldown
volume ±10 (/mpv_mute to silence)
/mpv_audio
switch audio track (e.g. Spanish → English)
/mpv_sub
switch subtitle track (/mpv_sub_toggle to hide)
/mpv_night
loudness normalization: explosions ↓, dialogue ↑

Comfort

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

Library & maintenance

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