Voice & Video Calls

Tobigram features native, high-level support for Telegram Voice Chats, Video Streams, and Private Calls. Media streaming is executed directly through client methods without requiring manual WebRTC negotiation or third-party client instantiations.


Requirements & Installation

Audio and video streaming requires WebRTC media engines. You can install Tobigram with the optional calls dependencies:

# With pip
pip install "tobigram[calls]"

# Or with uv
uv add "tobigram[calls]"

This installs: - ntgcalls: High-performance C++ WebRTC bindings for Telegram calls. - py-tgcalls: Stream pipeline and FFmpeg shell connector.


Streaming in Groups and Channels

Tobigram exposes high-level methods on the Client class to stream audio and video into any group voice chat or channel live stream.

1. Playing Video Streams

You can stream local video files or live remote streams (e.g. MP4, HLS, RTMP, HTTP) directly into a voice chat:

from pyrogram import Client

app = Client("my_account")

async def main():
    async with app:
        chat_id = -1001234567890

        # Stream a 720p HD video file or URL
        call = await app.play_video(
            chat_id,
            "https://samplelib.com/mp4/sample-30s-720p.mp4"
        )
        print(f"Streaming video in call ID: {call.id}")

app.run(main())

2. Playing Audio Streams

To stream audio (music, radio, podcasts) with video automatically muted/disabled:

from pyrogram import Client

app = Client("my_account")

async def main():
    async with app:
        chat_id = -1001234567890

        # Stream a local MP3 or live Internet radio
        call = await app.play_audio(
            chat_id,
            "https://stream.zeno.fm/f3wvbbqmdg8uv"
        )
        print(f"Playing audio in: {chat_id}")

app.run(main())

3. Zero-Disk In-Memory Telegram Media Streaming

Tobigram natively supports streaming Telegram files (Message, Audio, Video, Document, Voice, or file ID strings) directly into voice chats with zero disk footprint. Chunks are piped in RAM on-the-fly directly to the calling engine:

@app.on_message(filters.command("play") & filters.reply)
async def play_handler(client, message):
    replied = message.reply_to_message

    # Stream Telegram audio directly without downloading to disk
    await client.play_audio(message.chat.id, replied.audio)

    # Or stream full message (automatically extracts audio/video/document)
    await client.play_audio(message.chat.id, replied)

    # Stream video into voice chat with video enabled
    await client.play_video(message.chat.id, replied.video)

    # Stream Telegram Document (e.g. uncompressed FLAC or MKV)
    await client.play_audio(message.chat.id, replied.document)

4. Joining without Media (Listener)

If you only want the client to join an active voice chat as a listener (with microphone muted and without streaming any media file):

# Joins voice chat as a muted listener with auto-generated SSRC
await app.join_group_call(chat_id, muted=True)

Playback Controls

While a call is active, you can control playback state and volume:

# Pause media stream
await app.pause_stream(chat_id)

# Resume media stream
await app.resume_stream(chat_id)

# Change playback volume (0 to 200%)
await app.change_call_volume(chat_id, volume=150)

# Leave the voice chat
await app.leave_group_call(chat_id)

Stream Lifecycle Events

Tobigram provides built-in update handlers and decorators for the complete streaming lifecycle:

1. When a Stream Starts (on_stream_start())

Triggered as soon as an audio or video stream begins playing in a voice chat. Perfect for sending “Now Playing” messages or logging:

from pyrogram import Client
from pyrogram.types import StreamStarted

app = Client("music_bot")

@app.on_stream_start()
async def handle_stream_start(client: Client, update: StreamStarted):
    print(f"Started streaming {update.stream_type} in {update.chat_id}: {update.media_path}")
    await client.send_message(
        update.chat_id,
        f"🎶 **Now Playing:** `{update.media_path}`"
    )

2. When a Stream Finishes (on_stream_end())

For music bots and playlist queues, the on_stream_end() decorator automatically receives an update when a track or video reaches the end:

from pyrogram import Client
from pyrogram.types import StreamEnded

app = Client("music_bot")

queue = ["song2.mp3", "song3.mp3"]

@app.on_stream_end()
async def handle_stream_end(client: Client, update: StreamEnded):
    print(f"Track finished in chat: {update.chat_id}")
    if queue:
        next_track = queue.pop(0)
        await client.play_audio(update.chat_id, next_track)

Voice Chat Administration

Tobigram provides full coverage of Telegram’s MTProto phone functions as clean, high-level methods:

Leaving a Call vs Ending a Call

It is important to distinguish between leaving a call and ending a call:

  • Leave Call (leave_group_call()): Stops your client’s media stream and disconnects your client from the voice chat without closing it for others.

  • End Call (end_group_call()): Admin action (corresponds to “End Video Chat” in the Telegram UI). Completely closes and destroys the voice chat for all members.


1-on-1 Private Calls

For direct peer-to-peer (P2P) calls between two users:

# 1. Initiate an outgoing call
call = await app.request_call(user_id=12345678, g_a_hash=b"...", protocol=protocol, video=False)

# 2. Accept an incoming call
await app.accept_call(call_id=call.id, access_hash=call.access_hash, g_b=b"...", protocol=protocol)

# 3. Confirm encryption keys
await app.confirm_call(call_id=call.id, access_hash=call.access_hash, g_a=b"...", key_fingerprint=123, protocol=protocol)

# 4. Hang up / Decline a private call
await app.discard_call(call_id=call.id, access_hash=call.access_hash)