Skip to content
View TgCaller's full-sized avatar
🎧
🎧
  • Powered by TGcaller
  • INDIA
  • 19:22 (UTC +05:30)

Block or report TgCaller

Block user

Prevent this user from interacting with your repositories and sending you notifications. Learn more about blocking users.

You must be logged in to block users.

Maximum 250 characters. Please don't include any personal information such as legal names or email addresses. Markdown supported. This note will be visible to only you.
Report abuse

Contact GitHub support about this user’s behavior. Learn more about reporting abuse.

Report abuse
TgCaller/README.md

TgCaller Banner

TgCaller

Modern, Fast, and Reliable Telegram Group Calls Library

Built for developers who need a simple yet powerful solution for Telegram voice and video calls

DocumentationExamplesCommunityIssues



Why TgCaller?

TgCaller is a next-generation Telegram group call engine — built for speed, reliability, and developer-first simplicity.
It delivers the performance you need, without the complexity you don’t.


✦ Fast & Lightweight

Engineered for optimal performance with minimal system usage. No bloat. No overhead.

✦ Easy to Use

A developer-friendly API that feels intuitive from the very first line of code.

✦ Stable by Default

Automatic reconnection, intelligent error handling, and smooth session management — all built-in.

✦ High-Quality Streaming

Stream crystal-clear audio and HD video seamlessly in Telegram group calls.

✦ Plugin-Based Architecture

Extend and customize core features effortlessly with a modular plugin system.

✦ Fully Documented

Complete guides, real-world examples, and full API references to support every stage of development.

✦ Built-In Power Tools

Includes advanced capabilities like YouTube streaming, Whisper transcription, and media filters — ready to go.


TgCaller isn’t just simple to adopt — it’s designed to grow with your vision.


Quick Start

Installation

# Install from PyPI
pip install tgcaller

# Install with video support
pip install tgcaller[media]

# Install with all features
pip install tgcaller[all]

Verify Installation

# Test installation
tgcaller test

# Check system info
tgcaller info

Expected Output:

 Testing TgCaller installation...
 Pyrogram imported successfully
 TgCaller types imported successfully
 TgCaller installation test completed successfully!

Basic Usage

import asyncio
from pyrogram import Client
from tgcaller import TgCaller

# Initialize
app = Client("my_session", api_id=API_ID, api_hash=API_HASH)
caller = TgCaller(app)

@caller.on_stream_end
async def on_stream_end(client, update):
    print(f"Stream ended in {update.chat_id}")

async def main():
    await caller.start()
    
    # Join voice call
    await caller.join_call(-1001234567890)
    
    # Play audio
    await caller.play(-1001234567890, "song.mp3")
    
    # Play video
    await caller.play(-1001234567890, "video.mp4")

if __name__ == "__main__":
    asyncio.run(main())

Audio Features

from tgcaller import AudioConfig

# High-quality audio
audio_config = AudioConfig(
    bitrate=128000,           # 128 kbps
    sample_rate=48000,        # 48 kHz
    channels=2,               # Stereo
    noise_suppression=True,   # Clean audio
    echo_cancellation=True    # No echo
)

await caller.play(chat_id, "audio.mp3", audio_config=audio_config)

Video Features

from tgcaller import VideoConfig

# HD video streaming
video_config = VideoConfig(
    width=1920,
    height=1080,
    fps=30,
    bitrate=2000000,          # 2 Mbps
    codec="h264"
)

await caller.play(chat_id, "video.mp4", video_config=video_config)

Advanced Features

** Bridged Calls**

Connect multiple chats for conference calls:

from tgcaller.advanced import BridgedCallManager

bridge_manager = BridgedCallManager(caller)
await bridge_manager.create_bridge("conference", [chat1, chat2, chat3])

** Microphone Streaming**

Stream live microphone input:

from tgcaller.advanced import MicrophoneStreamer

mic_streamer = MicrophoneStreamer(caller, chat_id)
await mic_streamer.start_streaming()

** Screen Sharing**

Share your screen in video calls:

from tgcaller.advanced import ScreenShareStreamer

screen_streamer = ScreenShareStreamer(caller, chat_id)
await screen_streamer.start_streaming(monitor_index=1)

** YouTube Integration**

Stream YouTube videos directly:

from tgcaller.advanced import YouTubeStreamer

youtube = YouTubeStreamer(caller)
await youtube.play_youtube_url(chat_id, "https://youtube.com/watch?v=...")

** Speech Transcription**

Real-time speech-to-text with Whisper:

from tgcaller.advanced import WhisperTranscription

transcriber = WhisperTranscription("base")
await transcriber.start_transcription()

** Audio/Video Filters**

Apply real-time effects:

from tgcaller.advanced import AudioFilters, VideoFilters

audio_filters = AudioFilters()
video_filters = VideoFilters()

# Add echo effect
filtered_audio = audio_filters.apply_echo(audio_data, delay=0.3)

# Add blur effect
filtered_video = video_filters.apply_blur(video_frame, kernel_size=15)

** Custom API**

Extend with REST API:

from tgcaller.advanced import CustomAPIHandler

api = CustomAPIHandler(caller, port=8080)
await api.start_server()

# Now you can control via HTTP:
# POST /play {"chat_id": -1001234567890, "source": "song.mp3"}

CLI Tool

TgCaller comes with a built-in CLI tool for testing and management:

# Show help
tgcaller --help

# Test installation
tgcaller test --api-id YOUR_API_ID --api-hash YOUR_API_HASH

# Show system information
tgcaller info

CLI Commands:

  • tgcaller test - Test TgCaller installation
  • tgcaller info - Show system information
  • tgcaller --version - Show version

Examples

Music Bot

from tgcaller import TgCaller
from pyrogram import Client, filters

app = Client("music_bot")
caller = TgCaller(app)

@app.on_message(filters.command("play"))
async def play_music(client, message):
    if len(message.command) < 2:
        return await message.reply("Usage: /play <song_name>")
    
    song = message.command[1]
    
    # Join call if not already joined
    if not caller.is_connected(message.chat.id):
        await caller.join_call(message.chat.id)
    
    # Play song
    await caller.play(message.chat.id, f"music/{song}.mp3")
    await message.reply(f" Playing: {song}")

@caller.on_stream_end
async def next_song(client, update):
    # Auto-play next song logic here
    pass

app.run()

Advanced Conference Bot

from tgcaller.advanced import BridgedCallManager, WhisperTranscription

# Create conference bridge
bridge_manager = BridgedCallManager(caller)
await bridge_manager.create_bridge("meeting", [chat1, chat2, chat3])

# Add real-time transcription
transcriber = WhisperTranscription("base")
await transcriber.start_transcription()

Docker Support

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    ffmpeg \
    libopus-dev \
    && rm -rf /var/lib/apt/lists/*

# Install TgCaller
RUN pip install tgcaller[all]

# Copy your bot
COPY . /app
WORKDIR /app

CMD ["python", "bot.py"]

Docker Compose:

version: '3.8'
services:
  tgcaller-bot:
    build: .
    environment:
      - API_ID=${API_ID}
      - API_HASH=${API_HASH}
      - BOT_TOKEN=${BOT_TOKEN}
    volumes:
      - ./downloads:/app/downloads
    ports:
      - "8080:8080"

Performance

Feature TgCaller pytgcalls Improvement
Connection Time ~1s ~3s 3x faster
Memory Usage 80MB 150MB 47% less
CPU Usage Low High 60% less
Error Rate <2% ~8% 4x more reliable
Features 25+ 10 2.5x more

Advanced Configuration

FFmpeg Parameters

from tgcaller import TgCaller

caller = TgCaller(app, ffmpeg_parameters={
    'before_options': '-re',
    'options': '-vn -preset ultrafast'
})

Multiple Clients

# Manage multiple Telegram accounts
clients = [Client(f"session_{i}") for i in range(5)]
callers = [TgCaller(client) for client in clients]

# Start all
for caller in callers:
    await caller.start()

P2P Calls

from tgcaller.advanced import P2PCallManager

p2p = P2PCallManager(caller)
await p2p.create_direct_call(user1_id, user2_id)

Dependencies

Core Dependencies:

  • pyrogram>=2.0.106 - Telegram client
  • aiortc>=1.6.0 - WebRTC support
  • aiofiles>=23.1.0 - Async file operations
  • aiohttp>=3.8.4 - HTTP client

Media Processing:

  • ffmpeg-python>=0.2.0 - Media processing
  • numpy>=1.24.0 - Audio/video arrays
  • opencv-python>=4.7.0 - Video processing

Audio Processing:

  • pyaudio>=0.2.11 - Audio I/O
  • soundfile>=0.12.1 - Audio file handling

Advanced Features:

  • openai-whisper - Speech transcription
  • yt-dlp>=2023.6.22 - YouTube downloading
  • mss - Screen capture

Optional:

  • TgCrypto - For faster Pyrogram performance

Development

Setup

git clone https://github.com/tgcaller/tgcaller.git
cd tgcaller

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

Testing

# Run all tests
pytest

# Test with coverage
pytest --cov=tgcaller tests/

# Test installation
tgcaller test

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

Documentation


Community


License

This project is licensed under the MIT License - see the LICENSE file for details.


💖 Sponsor

Jhoommusic Banner
Crafted with ❤️ by Jhoommusic — blending community spirit with professional-grade audio & video streaming for Telegram bots.

Pinned Loading

  1. TgCaller TgCaller Public

    An open-source library to handle high-quality group calls in Telegram bots.

    Python 4 1