Install & Compatibility
Where this runs
tested against v2.2.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.2s · import 0.000s · 141MB
136MB installed
● package 136MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VideoStream
✓ from ntgcalls import VideoStream
AudioStream
✓ from ntgcalls import AudioStream
VideoFrame
✓ from ntgcalls.types import VideoFrame
AudioFrame
✓ from ntgcalls.types import AudioFrame
This quickstart demonstrates how to initialize an `ntgcalls.VideoStream` from a local video file and read a few frames. Note that `ntgcalls` relies on `ffmpeg` being installed on your system and an actual video file as input to function correctly. This example will not play audio/video; it merely processes frames from the stream.
import asyncio
from ntgcalls import VideoStream
import os
async def main():
# To run this quickstart, you MUST have ffmpeg installed and available in your system's PATH.
# You also need a video file for input. Replace 'your_video.mp4' with an actual path.
# For quick testing, you can set an environment variable: export VIDEO_PATH="/path/to/your_video.mp4"
video_input_path = os.environ.get('VIDEO_PATH', 'test_video.mp4') # Use an actual video file path
if not os.path.exists(video_input_path):
print(f"Warning: Video file '{video_input_path}' not found.")
print("Please ensure you have a video file for input and ffmpeg is installed.")
print("You can set the VIDEO_PATH environment variable to point to your video file.")
print("Example: `export VIDEO_PATH=~/Videos/my_test.mp4` then run the script.")
return
print(f"Attempting to process video stream from: {video_input_path}")
try:
# Create a VideoStream instance from a file path
# ntgcalls uses ffmpeg internally to process this file
video_stream = VideoStream(video_input_path)
# Start the video stream. This initializes the underlying ffmpeg process.
await video_stream.start()
print("Video stream started. Reading a few frames...")
frame_count = 0
# Iterate over the stream to get video frames
async for frame in video_stream:
if frame:
print(f"Got video frame {frame_count}: {frame.data_length} bytes, {frame.width}x{frame.height}")
frame_count += 1
if frame_count >= 3: # Read a few frames then stop for demonstration
print("Read 3 frames, stopping for quickstart demonstration.")
break
else:
# This might happen if stream ends or no frames are ready yet
print("No video frame available yet or stream ended.")
break
if frame_count == 0:
print("No frames were successfully read. Check ffmpeg installation and video input path.")
# Stop the video stream and release resources
await video_stream.stop()
print("Video stream stopped.")
except FileNotFoundError as e:
print(f"Error: {e}. This often means ffmpeg is not found or the video file is incorrect.")
print("Please ensure ffmpeg is installed and accessible in your system's PATH.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
print("Ensure your video file is valid and ffmpeg can process it.")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
gotchantgcalls relies heavily on `ffmpeg` for all media processing. `ffmpeg` must be installed on your system and accessible via the system PATH, otherwise streams will fail to initialize with an `OSError` or `FileNotFoundError`.fixInstall `ffmpeg` for your operating system (e.g., via `apt-get install ffmpeg`, `brew install ffmpeg`, or download from `ffmpeg.org`) and ensure its binaries are added to your system's PATH.
affects: All versions
gotchaAll operations in ntgcalls are asynchronous. Misusing synchronous calls or forgetting `await` before calling an asynchronous method will result in `RuntimeWarning` (coroutine was never awaited) or `TypeError`.fixAlways use `await` when calling asynchronous functions or methods provided by `ntgcalls`, and ensure your code runs within an `asyncio` event loop.
affects: All versions
breakingEnsure `ntgcalls`, `pytgcalls`, and `pyrogram` versions are compatible. New major releases of `pytgcalls` or `pyrogram` may introduce API changes that require an `ntgcalls` update to maintain functionality.fixRegularly check the `ntgcalls` GitHub README or PyPI page for recommended compatible versions of `pytgcalls` and `pyrogram`. Update all libraries (`pip install --upgrade ntgcalls pytgcalls pyrogram`) if you encounter unexpected behavior.
affects: Between major/minor versions of dependent libraries
gotchaStreams must be explicitly started with `await stream.start()` and stopped with `await stream.stop()` to properly manage underlying resources (like `ffmpeg` processes) and prevent resource leaks.fixAlways pair `stream.start()` with `stream.stop()` (ideally in a `try...finally` block or using `async with` if supported) to ensure proper resource cleanup.
affects: All versions
breakingntgcalls requires Python 3.10 or higher. Running on older Python versions will lead to `SyntaxError` or import failures due to its reliance on modern async features and type hints.fixUpgrade your Python environment to version 3.10 or newer. `pyenv` or virtual environments can help manage multiple Python versions.
affects: <=1.x
Audit
Dependencies
pyrogramrequiredCore Telegram client library, required for interacting with Telegram API.
pytgcallsrequiredHigh-level call management, integrates with ntgcalls streams to provide call functionality.
vidgearoptionalProvides advanced video processing features, e.g., for complex video sources beyond basic file input.