{"id":13611025,"url":"https://github.com/MarshalX/tgcalls","last_synced_at":"2025-04-13T01:34:20.873Z","repository":{"id":44125478,"uuid":"318597435","full_name":"MarshalX/tgcalls","owner":"MarshalX","description":"Voice chats, private incoming and outgoing calls in Telegram for Developers","archived":false,"fork":false,"pushed_at":"2023-01-09T19:21:32.000Z","size":31492,"stargazers_count":521,"open_issues_count":13,"forks_count":91,"subscribers_count":18,"default_branch":"dev","last_synced_at":"2024-11-05T05:50:20.700Z","etag":null,"topics":["async","asynchronous","calls","ffmpeg","group-chat","lib","library","mtproto","pyrogram","pytgcalls","python","realtime","telegram","telethon","tgcalls","video-call","voice","voice-chat","voip","webrtc"],"latest_commit_sha":null,"homepage":"https://t.me/tgcallslib","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MarshalX.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"MarshalX"}},"created_at":"2020-12-04T18:04:13.000Z","updated_at":"2024-10-31T03:43:45.000Z","dependencies_parsed_at":"2023-02-08T13:46:27.392Z","dependency_job_id":null,"html_url":"https://github.com/MarshalX/tgcalls","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarshalX%2Ftgcalls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarshalX%2Ftgcalls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarshalX%2Ftgcalls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarshalX%2Ftgcalls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarshalX","download_url":"https://codeload.github.com/MarshalX/tgcalls/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223558484,"owners_count":17165140,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","asynchronous","calls","ffmpeg","group-chat","lib","library","mtproto","pyrogram","pytgcalls","python","realtime","telegram","telethon","tgcalls","video-call","voice","voice-chat","voip","webrtc"],"created_at":"2024-08-01T19:01:51.035Z","updated_at":"2025-04-13T01:34:20.866Z","avatar_url":"https://github.com/MarshalX.png","language":"Python","funding_links":["https://github.com/sponsors/MarshalX"],"categories":["Python","Libraries","webrtc"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/MarshalX/tgcalls\"\u003e\n        \u003cimg src=\"https://github.com/MarshalX/tgcalls/raw/main/.github/images/logo.png\" alt=\"tgcalls\"\u003e\n    \u003c/a\u003e\n    \u003cbr\u003e\n    \u003cb\u003eVoice chats, private incoming and outgoing calls in Telegram for Developers\u003c/b\u003e\n    \u003cbr\u003e\n    \u003ca href=\"https://github.com/MarshalX/tgcalls/tree/main/examples\"\u003e\n        Examples\n    \u003c/a\u003e\n    •\n    \u003ca href=\"https://tgcalls.org\"\u003e\n        Documentation\n    \u003c/a\u003e\n    •\n    \u003ca href=\"https://t.me/tgcallslib\"\u003e\n        Channel\n    \u003c/a\u003e\n    •\n    \u003ca href=\"https://t.me/tgcallschat\"\u003e\n        Chat\n    \u003c/a\u003e\n\u003c/p\u003e\n\n## Telegram WebRTC (VoIP) [![Mentioned in Awesome Telegram Calls](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/tgcalls/awesome-tgcalls)\n\nThis project consists of two main parts: [tgcalls](#tgcalls), [pytgcalls](#pytgcalls).\nThe first is a C++ Python extension.\nThe second uses the extension along with MTProto and provides high level SDK.\nAll together, it allows you to create userbots that can record and\nbroadcast in voice chats, make and receive private calls.\n\n#### Pyrogram's snippet\n```python\nfrom pyrogram import Client, filters\nfrom pyrogram.utils import MAX_CHANNEL_ID\n\nfrom pytgcalls import GroupCallFactory\n\napp = Client('pytgcalls')\ngroup_call = GroupCallFactory(app).get_file_group_call('input.raw')\n\n\n@group_call.on_network_status_changed\nasync def on_network_changed(context, is_connected):\n    chat_id = MAX_CHANNEL_ID - context.full_chat.id\n    if is_connected:\n        await app.send_message(chat_id, 'Successfully joined!')\n    else:\n        await app.send_message(chat_id, 'Disconnected from voice chat..')\n\n\n@app.on_message(filters.outgoing \u0026 filters.command('join'))\nasync def join_handler(_, message):\n    await group_call.start(message.chat.id)\n\n\napp.run()\n```\n\n#### Telethon's snippet\n```python\nfrom telethon import TelegramClient, events\n\nfrom pytgcalls import GroupCallFactory\n\napp = TelegramClient('pytgcalls', api_id, api_hash).start()\ngroup_call_factory = GroupCallFactory(app, GroupCallFactory.MTPROTO_CLIENT_TYPE.TELETHON)\ngroup_call = group_call_factory.get_file_group_call('input.raw')\n\n\n@app.on(events.NewMessage(outgoing=True, pattern=r'^/join$'))\nasync def join_handler(event):\n    chat = await event.get_chat()\n    await group_call.start(chat.id)\n\napp.run_until_disconnected()\n```\n\n### Features\n\n- Python solution.\n- Prebuilt wheels for macOS, Linux and Windows.\n- Supporting popular MTProto libraries: Pyrogram, Telethon.\n- Abstract class to implement own MTProto bridge.\n- Work with voice chats in channels and chats.\n- Multiply voice chats ([example](https://github.com/MarshalX/tgcalls/blob/main/examples/radio_as_smart_plugin.py)).\n- System of custom handlers on events.\n- Join as channels or chats.\n- Join using invite (speaker) links.\n- Speaking status with voice activity detection.\n- Mute/unmute, pause/resume, stop/play, volume control and more...\n\n### Available sources of input/output data transfers\n\n- Raw (`GroupCallRaw`, [example with pyav](https://github.com/MarshalX/tgcalls/blob/main/examples/pyav.py),\n[example of restreaming](https://github.com/MarshalX/tgcalls/blob/main/examples/restream_using_raw_data.py))\n  — to send and receive data in `bytes` directly from Python.\n- File (`GroupCallFile`, [playout example](https://github.com/MarshalX/tgcalls/blob/main/examples/file_playout.py),\n  [recording example](https://github.com/MarshalX/tgcalls/blob/main/examples/recorder_as_smart_plugin.py))\n  — to use audio files including named pipe (FIFO).\n- Device (`GroupCallDevice`, [example](https://github.com/MarshalX/tgcalls/blob/main/examples/device_playout.py)) — \nto use system virtual devices. Please don't use it with real microphone, headphones, etc.\n\nNote: All audio data is transmitted in PCM 16 bit, 48k. \n[Example how to convert files using FFmpeg](#audio-file-formats).\n\n### Requirements\n\n- Python 3.7 or higher.\n- A [Telegram API key](https://docs.pyrogram.org/intro/setup#api-keys).\n\n### TODO list\n- Incoming and Outgoing private calls \n(already there and working, but not in the release version).\n- Group Video Calls\n[and more...](https://github.com/MarshalX/tgcalls/issues)\n\n### Installing\n\n#### For Pyrogram\n``` bash\npip3 install -U pytgcalls[pyrogram]\n```\n\n#### For Telethon\n``` bash\npip3 install -U pytgcalls[telethon]\n```\n\n\u003chr\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/MarshalX/tgcalls\"\u003e\n        \u003cimg src=\"https://github.com/MarshalX/tgcalls/raw/main/.github/images/tgcalls.png\" alt=\"tgcalls\"\u003e\n    \u003c/a\u003e\n    \u003cbr\u003e\n    \u003ca href=\"https://pypi.org/project/tgcalls/\"\u003e\n        PyPi\n    \u003c/a\u003e\n    •\n    \u003ca href=\"https://github.com/MarshalX/tgcalls/tree/main/tgcalls\"\u003e\n        Sources\n    \u003c/a\u003e\n\u003c/p\u003e\n\n## tgcalls \n\nThe first part of the project is C++ extensions for Python. [Pybind11](https://github.com/pybind/pybind11)\nwas used to write it. Binding occurs to the [tgcalls](https://github.com/TelegramMessenger/tgcalls)\nlibrary by Telegram, which is used in all official clients. \nTo implement the binding, the code of Telegram Desktop and Telegram Android was studied.\nChanges have been made to the Telegram library. \nAll modified code is [available as a subtree](https://github.com/MarshalX/tgcalls/tree/main/tgcalls/third_party/lib_tgcalls)\nin this repository. The main ideas of the changes is to improve \nthe sound quality and to add ability to work with third party audio device modules.\nIn addition, this binding implemented custom audio modules. These modules are allowing\ntransfer audio data directly from Python via bytes, transfer and control \nthe playback/recording of a file or a virtual system device.\n\n### How to build\n\nShort answer for Linux:\n```bash\ngit clone git@github.com:MarshalX/tgcalls.git --recursive\ncd tgcalls\n```\nFor x86_64:\n```bash\ndocker-compose up tgcalls_x86_64\n```\nFor AArch64 (ARM64):\n```bash\ndocker-compose up tgcalls_aarch64\n```\n\nPython wheels will be available in `dist` folder in root of `tgcalls`.\n\nMore info:\n- [Manylinux](build/manylinux/dev).\n- [Ubuntu](build/ubuntu).\n- [macOS](build/macos).\n- [Windows](build/windows).\n\nAlso, you can investigate into [manylinux GitHub Actions builds](build/manylinux).\n\n### Documentation\n\nTemporarily, instead of documentation, you can use [an example](pytgcalls/pytgcalls)\nalong with MTProto.\n\n\u003chr\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/MarshalX/tgcalls\"\u003e\n        \u003cimg src=\"https://github.com/MarshalX/tgcalls/raw/main/.github/images/pytgcalls.png\" alt=\"pytgcalls\"\u003e\n    \u003c/a\u003e\n    \u003cbr\u003e\n    \u003ca href=\"https://tgcalls.org\"\u003e\n        Documentation\n    \u003c/a\u003e\n    •\n    \u003ca href=\"https://pypi.org/project/pytgcalls/\"\u003e\n        PyPi\n    \u003c/a\u003e\n    •\n    \u003ca href=\"https://github.com/MarshalX/tgcalls/tree/main/pytgcalls\"\u003e\n        Sources\n    \u003c/a\u003e\n\u003c/p\u003e\n\n## pytgcalls \n\nThis project is implementation of using [tgcalls](#tgcalls) \nPython binding together with [MTProto](https://core.telegram.org/mtproto).\nBy default, this library are supports [Pyrogram](https://github.com/pyrogram/pyrogram)\nand [Telethon](https://github.com/LonamiWebs/Telethon) clients for working \nwith Telegram Mobile Protocol. \nYou can write your own implementation of abstract class to work with other libraries.\n\n### Learning by example\n\nVisit [this page](https://github.com/MarshalX/tgcalls/tree/main/examples) to discover the official examples.\n\n### Documentation\n\n`pytgcalls`'s documentation lives at [tgcalls.org](https://tgcalls.org).\n\n### Audio file formats\n\nRAW files are now used. You will have to convert to this format yourself\nusing ffmpeg. The example how to transcode files from a code is available [here](https://github.com/MarshalX/tgcalls/blob/e0b2d667728cc92cc0da437b9c85bcc909e4ac9c/examples/player_as_smart_plugin.py#L41).\n\nFrom mp3 to raw (to play in voice chat):\n```\nffmpeg -i input.mp3 -f s16le -ac 2 -ar 48000 -acodec pcm_s16le input.raw\n```\n\nFrom raw to mp3 (files with recordings):\n```\nffmpeg -f s16le -ac 2 -ar 48000 -acodec pcm_s16le -i output.raw clear_output.mp3\n```\n\nFor playout live stream you can use this one:\n```\nffmpeg -y -i http://stream2.cnmns.net/hope-mp3 -f s16le -ac 2 -ar 48000 -acodec pcm_s16le input.raw\n```\n\nFor YouTube videos and live streams you can use youtube-dl:\n```\nffmpeg -i \"$(youtube-dl -x -g \"https://youtu.be/xhXq9BNndhw\")\" -f s16le -ac 2 -ar 48000 -acodec pcm_s16le input.raw\n```\n\nAnd set input.raw as input filename.\n\n\u003chr\u003e\n\n### Getting help\n\nYou can get help in several ways:\n- We have a community of developers helping each other in our \n[Telegram group](https://t.me/tgcallschat).\n- Report bugs, request new features or ask questions by creating \n[an issue](https://github.com/MarshalX/tgcalls/issues/new) or \n[a discussion](https://github.com/MarshalX/tgcalls/discussions/new).\n\n### Contributing\n\nContributions of all sizes are welcome.\n\n### Special thanks to\n\n- [@FrayxRulez](https://github.com/FrayxRulez) for amazing code of [Unigram](https://github.com/UnigramDev/Unigram).\n- [@john-preston](https://github.com/john-preston) for [Telegram Desktop](https://github.com/telegramdesktop/tdesktop) and [tgcalls](https://github.com/TelegramMessenger/tgcalls).\n- [@bakatrouble](https://github.com/bakatrouble/) for help and inspiration by [pytgvoip](https://github.com/bakatrouble/pytgvoip).\n- [@delivrance](https://github.com/delivrance) for [Pyrogram](https://github.com/pyrogram/pyrogram).\n- [@Lonami](https://github.com/Lonami) for [Telethon](https://github.com/LonamiWebs/Telethon).\n\n### License\n\nYou may copy, distribute and modify the software provided that modifications\nare described and licensed for free under [LGPL-3](https://www.gnu.org/licenses/lgpl-3.0.html).\nDerivatives works (including modifications or anything statically\nlinked to the library) can only be redistributed under LGPL-3, but\napplications that use the library don't have to be.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMarshalX%2Ftgcalls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMarshalX%2Ftgcalls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMarshalX%2Ftgcalls/lists"}