tgrtmp

tgrtmp is a high-performance RTMP(S) publishing client for Telegram livestreams.

Features

tgrtmp offers numerous advantages, including:

• Easy to Use: One call to go live; a worker thread does the rest
• High Performance: Demuxing, pacing, and sending run in a fast native engine
• Zero Transcoding: H.264/AAC frames pass through untouched
• Player Controls: Pause, play, mute, and a live position, VLC-style, from any thread
• Playlists: Queue files, skip, reorder, and chain episodes while live; it all plays on one connection
• Endless Channels: Looping restarts a file on the same timeline: one uninterrupted stream, forever
• DVR for Live Sources: Any growing .read(n) handle, with an opt-in rolling window (buffer_size) that lets pause hold its point

Requirements

• Python 3.10+
• A Telegram livestream RTMP URL and stream key
• Media in H.264 + AAC (MPEG-TS, MP4, or MKV); other codecs are rejected, not transcoded

Installation

pip install --upgrade tgrtmp

tgrtmp builds from source on install, so it needs a C++ compiler and the OpenSSL development headers; the installation guide has the one command for your system.

Examples

Publish a file and hold the last frame when it ends:

import time
import tgrtmp

player = tgrtmp.publish(
    "movie.mp4",
    "rtmps://dc4-1.rtmp.t.me/s/",
    "STREAM_KEY",
    log=print,
)

# The file plays in real time; at the end the last frame is held
# so the stream stays live until you stop it.
while not player.stopped:
    time.sleep(1)

Control it while it runs; every call is thread-safe:

player.pause()       # viewers see a still frame; the connection stays alive
player.play()
player.mute()
player.position      # seconds into the source
player.stats         # one dict: bitrate, frames, loops, state
player.stop()

Turn it into a 24/7 channel:

player = tgrtmp.publish("movie.mp4", url, key, loop=True)

Queue a playlist and edit it while live:

player = tgrtmp.publish("intro.mp4", url, key, playlist=["a.mp4", "b.mp4"])

player.next()            # skip the intro
player.add("c.mp4")      # append to the queue

Not sure about a file? Ask before you stream:

tgrtmp.needs_transcode("clip.mkv")   # True means: transcode it first

For more examples, check the examples folder.

Documentation

The full documentation (quick start, guides, and API reference) lives at tgrtmp.pages.dev.

Thanks to

• You for viewing or using this project.

• MadelineProto for documenting the RTMP behavior of Telegram's servers

License

MIT License