{"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":"python","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,"search_vec":"'2.1.0':75 '3.10':53 'act':29 'asyncio':83 'audio':21,79 'backend':35 'call':4,27,78 'chat':47 'compat':60 'current':50,72 'cycl':69 'direct':43 'enabl':38 'ffmpeg':82 'follow':66 'handl':17 'implement':15 'level':34 'librari':10,49 'low':33 'low-level':32 'maintain':59 'media':42 'nativ':2,14 'new':56 'ntgcall':1,6 'provid':12 'pyrogram':64 'pytgcal':37,62 'python':9,52 'real':19 'real-tim':18 'releas':55,68 'seamless':39 'stream':5,24,40,81 'support':51 'telegram':3,26,45,76 'time':20 'typic':65 'version':57,73 'video':23,80 'voic':46 'voip':77 'within':25","created_at":"2026-04-16T18:48:41.276051+00:00","updated_at":"2026-04-16T18:48:41.276051+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nImportError: cannot import name 'VideoStream' from 'ntgcalls' (/tmp/tmp3yfciz6f/venv/lib/python3.12/site-packages/ntgcalls.cpython-312-x86_64-linux-gnu.so)"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.2.4","cli_name":"","cli_version":null,"type":"library","homepage":"https://pytgcalls.github.io/","github":"https://github.com/pytgcalls/ntgcalls.git","docs":"https://pytgcalls.github.io/NTgCalls","changelog":"https://pytgcalls.github.io/PyTgCalls/Changelogs","pypi":"https://pypi.org/project/ntgcalls/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"skip","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-08-01","install_tag":null}}