{"id":9142,"library":"ntgcalls","title":"ntgcalls - Native Telegram Calls Streaming","description":"ntgcalls is a Python library that provides a native implementation for handling real-time audio and video streams within Telegram calls. It acts as the low-level backend for `pytgcalls`, enabling seamless streaming of media directly into Telegram voice chats. The library currently supports Python 3.10+ and releases new versions to maintain compatibility with `pytgcalls` and `pyrogram`, typically following their release cycles, with the current version being 2.1.0.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/pytgcalls/ntgcalls","tags":["telegram","voip","calls","audio","video","streaming","ffmpeg","asyncio"],"install":[{"cmd":"pip install ntgcalls","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core Telegram client library, required for interacting with Telegram API.","package":"pyrogram","optional":false},{"reason":"High-level call management, integrates with ntgcalls streams to provide call functionality.","package":"pytgcalls","optional":false},{"reason":"Provides advanced video processing features, e.g., for complex video sources beyond basic file input.","package":"vidgear","optional":true}],"imports":[{"symbol":"VideoStream","correct":"from ntgcalls import VideoStream"},{"symbol":"AudioStream","correct":"from ntgcalls import AudioStream"},{"symbol":"VideoFrame","correct":"from ntgcalls.types import VideoFrame"},{"symbol":"AudioFrame","correct":"from ntgcalls.types import AudioFrame"}],"quickstart":{"code":"import asyncio\nfrom ntgcalls import VideoStream\nimport os\n\nasync def main():\n    # To run this quickstart, you MUST have ffmpeg installed and available in your system's PATH.\n    # You also need a video file for input. Replace 'your_video.mp4' with an actual path.\n    # For quick testing, you can set an environment variable: export VIDEO_PATH=\"/path/to/your_video.mp4\"\n    video_input_path = os.environ.get('VIDEO_PATH', 'test_video.mp4') # Use an actual video file path\n\n    if not os.path.exists(video_input_path):\n        print(f\"Warning: Video file '{video_input_path}' not found.\")\n        print(\"Please ensure you have a video file for input and ffmpeg is installed.\")\n        print(\"You can set the VIDEO_PATH environment variable to point to your video file.\")\n        print(\"Example: `export VIDEO_PATH=~/Videos/my_test.mp4` then run the script.\")\n        return\n\n    print(f\"Attempting to process video stream from: {video_input_path}\")\n    try:\n        # Create a VideoStream instance from a file path\n        # ntgcalls uses ffmpeg internally to process this file\n        video_stream = VideoStream(video_input_path)\n\n        # Start the video stream. This initializes the underlying ffmpeg process.\n        await video_stream.start()\n        print(\"Video stream started. Reading a few frames...\")\n\n        frame_count = 0\n        # Iterate over the stream to get video frames\n        async for frame in video_stream:\n            if frame:\n                print(f\"Got video frame {frame_count}: {frame.data_length} bytes, {frame.width}x{frame.height}\")\n                frame_count += 1\n                if frame_count >= 3: # Read a few frames then stop for demonstration\n                    print(\"Read 3 frames, stopping for quickstart demonstration.\")\n                    break\n            else:\n                # This might happen if stream ends or no frames are ready yet\n                print(\"No video frame available yet or stream ended.\")\n                break\n\n        if frame_count == 0:\n            print(\"No frames were successfully read. Check ffmpeg installation and video input path.\")\n\n        # Stop the video stream and release resources\n        await video_stream.stop()\n        print(\"Video stream stopped.\")\n\n    except FileNotFoundError as e:\n        print(f\"Error: {e}. This often means ffmpeg is not found or the video file is incorrect.\")\n        print(\"Please ensure ffmpeg is installed and accessible in your system's PATH.\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n        print(\"Ensure your video file is valid and ffmpeg can process it.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"fix":"Install `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.","message":"ntgcalls 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `await` when calling asynchronous functions or methods provided by `ntgcalls`, and ensure your code runs within an `asyncio` event loop.","message":"All 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly 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.","message":"Ensure `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.","severity":"breaking","affected_versions":"Between major/minor versions of dependent libraries"},{"fix":"Always pair `stream.start()` with `stream.stop()` (ideally in a `try...finally` block or using `async with` if supported) to ensure proper resource cleanup.","message":"Streams 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to version 3.10 or newer. `pyenv` or virtual environments can help manage multiple Python versions.","message":"ntgcalls 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.","severity":"breaking","affected_versions":"<=1.x"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `ffmpeg` for your operating system and ensure its executable is discoverable by your system's PATH environment variable.","cause":"`ffmpeg` is not installed on the system or not in the system's PATH, which ntgcalls uses internally for media processing.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'"},{"fix":"Ensure all calls to async methods are prefixed with `await`, e.g., `await video_stream.start()`.","cause":"An asynchronous method, such as `stream.start()`, was called without the `await` keyword in an asynchronous context.","error":"RuntimeWarning: coroutine 'VideoStream.start' was never awaited"},{"fix":"If you intend to iterate for frames, use `async for frame in video_stream:`. If you meant to call a method, ensure it's `await video_stream.method()`.","cause":"Attempting to `await` a `VideoStream` object directly when it should be iterated asynchronously to get frames, or a method call was intended.","error":"TypeError: object VideoStream is not awaitable"},{"fix":"Ensure `ntgcalls` is updated to the latest version (`pip install --upgrade ntgcalls`) and verify the correct import path from the official documentation.","cause":"An older or incompatible version of `ntgcalls` is installed, or the import path for `VideoStream` (or `AudioStream`) has changed between versions.","error":"ImportError: cannot import name 'VideoStream' from 'ntgcalls'"}]}