Modern, Fast, and Reliable Telegram Group Calls Library
Built for developers who need a simple yet powerful solution for Telegram voice and video calls
Documentation • Examples • Community • Issues
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.
Engineered for optimal performance with minimal system usage. No bloat. No overhead.
A developer-friendly API that feels intuitive from the very first line of code.
Automatic reconnection, intelligent error handling, and smooth session management — all built-in.
Stream crystal-clear audio and HD video seamlessly in Telegram group calls.
Extend and customize core features effortlessly with a modular plugin system.
Complete guides, real-world examples, and full API references to support every stage of development.
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.
# Install from PyPI
pip install tgcaller
# Install with video support
pip install tgcaller[media]
# Install with all features
pip install tgcaller[all]# Test installation
tgcaller test
# Check system info
tgcaller infoExpected Output:
Testing TgCaller installation...
Pyrogram imported successfully
TgCaller types imported successfully
TgCaller installation test completed successfully!
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())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)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)Connect multiple chats for conference calls:
from tgcaller.advanced import BridgedCallManager
bridge_manager = BridgedCallManager(caller)
await bridge_manager.create_bridge("conference", [chat1, chat2, chat3])Stream live microphone input:
from tgcaller.advanced import MicrophoneStreamer
mic_streamer = MicrophoneStreamer(caller, chat_id)
await mic_streamer.start_streaming()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)Stream YouTube videos directly:
from tgcaller.advanced import YouTubeStreamer
youtube = YouTubeStreamer(caller)
await youtube.play_youtube_url(chat_id, "https://youtube.com/watch?v=...")Real-time speech-to-text with Whisper:
from tgcaller.advanced import WhisperTranscription
transcriber = WhisperTranscription("base")
await transcriber.start_transcription()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)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"}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 infoCLI Commands:
tgcaller test- Test TgCaller installationtgcaller info- Show system informationtgcaller --version- Show version
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()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()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"| 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 |
from tgcaller import TgCaller
caller = TgCaller(app, ffmpeg_parameters={
'before_options': '-re',
'options': '-vn -preset ultrafast'
})# 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()from tgcaller.advanced import P2PCallManager
p2p = P2PCallManager(caller)
await p2p.create_direct_call(user1_id, user2_id)Core Dependencies:
pyrogram>=2.0.106- Telegram clientaiortc>=1.6.0- WebRTC supportaiofiles>=23.1.0- Async file operationsaiohttp>=3.8.4- HTTP client
Media Processing:
ffmpeg-python>=0.2.0- Media processingnumpy>=1.24.0- Audio/video arraysopencv-python>=4.7.0- Video processing
Audio Processing:
pyaudio>=0.2.11- Audio I/Osoundfile>=0.12.1- Audio file handling
Advanced Features:
openai-whisper- Speech transcriptionyt-dlp>=2023.6.22- YouTube downloadingmss- Screen capture
Optional:
TgCrypto- For faster Pyrogram performance
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# Run all tests
pytest
# Test with coverage
pytest --cov=tgcaller tests/
# Test installation
tgcaller test- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
- API Reference - Complete API documentation
- Examples - Code examples and tutorials
- Migration Guide - Migrate from pytgcalls
- Plugin Development - Create custom plugins
- Advanced Features - Professional features guide
- Telegram Group - Get help and discuss
- GitHub Discussions - Feature requests and ideas
- GitHub Issues - Bug reports
This project is licensed under the MIT License - see the LICENSE file for details.
Crafted with ❤️ by Jhoommusic — blending community spirit with professional-grade audio & video streaming for Telegram bots.
