TikTokLiveClone
==================
Original Details:
A Python library to connect to and read events from TikTok's LIVE service.
[](https://www.linkedin.com/in/isaac-kogan-5a45b9193/ )
[](http://hits.dwyl.com/isaackogan/TikTokLive)
[](https://discord.gg/e2XwPNTBBr)
<!-- [](https://pepy.tech/project/tiktoklive) -->
A Python library to receive and decode livestream events such as comments and gifts in real-time from TikTok's LIVE service by connecting to TikTok's internal Webcast service. This library includes a wrapper that
connects to the Webcast service using only a user's `unique_id` and allows you to join your livestream as well as that of other streamers. No credentials are required to use TikTokLive.
This library was originally based off of the
[TikTok-Live-Connector](https://github.com/zerodytrash/TikTok-Live-Connector)
by [@zerodytrash](https://github.com/zerodytrash/), but has since taken on its own identity as it has added more features & changed much of its core functionality.
Join the [support discord](https://discord.gg/e2XwPNTBBr) and visit the `#py-support` channel for questions, contributions and ideas. Feel free to make pull requests with missing/new features, fixes, etc.
> **UPDATE:**<br>Due to a change on the part of TikTok, versions prior to **v4.3.8** are no longer functional. If you are using an unsupported version, upgrade to the latest version using the `pip install TikTokLive --upgrade` command.
## Other Languages
TikTok LIVE is available in several alternative languages with only slight differences between the versions:
- **Node.JS:** https://github.com/zerodytrash/TikTok-Live-Connector
- **Go:** https://github.com/Davincible/gotiktoklive
- **C#/Unity:** https://github.com/frankvHoof93/TikTokLiveSharp
## Table of Contents
**Primary Information**
- [Documentation](https://isaackogan.github.io/TikTokLive/)
- [Contributors](#contributors)
- [License](#license)
- [Quickstart Examples](https://github.com/isaackogan/TikTokLive/tree/master/examples)
**Resources & Guides**
1. [David's Intro Tutorial](#tiktoklive-intro-tutorial)
2. [Getting Started](#getting-started)
3. [Params & Options](#Params-&-Options)
4. [Client Methods](#Methods)
5. [Client Attributes](#Attributes)
6. [TikTok Events](#Events)
## TikTokLive Intro Tutorial
I cannot recommend this tutorial enough for people trying to get started. It is succinct, informative and easy to understand, created by [David Teather](https://github.com/davidteather), the creator of the
Python [TikTok-Api](https://github.com/davidteather/TikTok-Api) package. Click the thumbnail to warp.
[](https://www.youtube.com/watch?v=307ijmA3_lc)
## Getting Started
1. Install the module via pip
```shell script
> pip install TikTokLive
```
2. Create your first chat connection
```python
from TikTokLive import TikTokLiveClient
from TikTokLive.types.events import CommentEvent, ConnectEvent
# Instantiate the client with the user's username
client: TikTokLiveClient = TikTokLiveClient(unique_id="@isaackogz")
# Define how you want to handle specific events via decorator
@client.on("connect")
async def on_connect(_: ConnectEvent):
print("Connected to Room ID:", client.room_id)
# Notice no decorator?
async def on_comment(event: CommentEvent):
print(f"{event.user.nickname} -> {event.comment}")
# Define handling an event via a "callback"
client.add_listener("comment", on_comment)
if __name__ == '__main__':
# Run the client and block the main thread
# await client.start() to run non-blocking
client.run()
```
For more examples, [see the examples folder](https://github.com/isaackogan/TikTokLive/tree/master/examples) provided in the tree.
## Params & Options
To create a new `TikTokLiveClient` object the following parameter is required. You can optionally add configuration options to this via kwargs.
`TikTokLiveClient(unique_id, **options)`
| Param Name | Required | Description |
|------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| unique_id | Yes | The unique username of the broadcaster. You can find this name in the URL.<br>Example: `https://www.tiktok.com/@isaackogz` => `isaackogz` |
| **options | No | Here you can set the following optional connection properties. If you do not specify a value, the default value will be used.<br><br>`process_initial_data` (default: `True`) <br> Define if you want to process initial data upon connecting (e.g. first 1-10 messages from BEFORE you connected).<br><br>`fetch_room_info_on_connect` (default: `True`) <br> Define if you want to fetch all room information on start. If this option is enabled, connection to offline rooms will be prevented. If enabled, the connect result contains the room info via the `room_info` attribute. You can also manually retrieve the room info (even in an unconnected state) using the `retrieve_room_info()` method.<br><br>`enable_detailed_gifts` (default: `False`) <br> Define if you want to receive extended information about gifts like gift name, cost and images which you can retrieve via the `available_gifts` attribute. When enabled, the `details` attribute in a `Gift` object will be populated.<br><br>`ws_ping_interval` (default: `10.0`) <br> The interval between keepalive pings on the websocket connection (in seconds).<br><br>`ws_timeout` (default: `10.0`)<br>How long to wait before the websocket connection is considered timed out (in seconds).<br><br>`http_timeout` (default: `10.0`) <br> How long to wait before considering an HTTP request in the http client timed out (in seconds).<br><br>`http_headers` (default: `{}`) <br> Additional HTTP client headers to include when making requests to the Webcast API AND connecting to the websocket server.<br><br>`http_params` (default: `{}`) <br>Additional HTTP client parameters to include when making requests to the Webcast API AND connecting to the websocket.<br><br>`loop` (default: `None`)<br>Optionally supply your own asyncio event loop for usage by the client. When set to None, the client pulls the current active loop or creates a new one. This option is mostly useful for people trying to nest asyncio.<br/><br/>`trust_env` (default: `False`)<br/>Whether to trust environment variables that provide proxies in httpx requests<br/><br/>`proxies` (default: `None`)<br/>Enable proxied requests by turning on forwarding for the HTTP "proxies" argument. Websocket connections will NOT be proxied<br/><br/>`lang` (default: `en-US`)<br/>Change the language. Payloads *will* be in English, but front-end content will be in the desired language!<br/><br/>`sign_api_key` (default: `None`)<br/>Parameter to increase the amount of connections allowed to be made per minute via a Sign Server API key. If you need this, contact the project maintainer.<br/><br/>`ssl_context` (default: `None`)<br/>Providing an SSLContext object overrides the default context used in HTTP requests made to TikTok. This is useful if TikTok sends invalid SSL signatures, as you can provide a "no verify" context. |
## Methods
A `TikTokLiveClient` object contains the following methods:
| Method Name | Description |
|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| run | Starts a connection to the live chat while blocking the main thread |
| start | (async) Connects to the live chat without blocking the main thread |
| stop | Turns off the connection to the live chat. |
| retrieve_room_info | (async) Gets the current room info from TikTok API |
| retrieve_available_gifts | (async) Retrieves a list of the available gifts for the room and adds it to the `extended_gift` attribute of the `Gift` object on the `gift` event, when enabled. |
| add_listener | Adds an *asynchronous* listener function (or, you can decorate a function with `@client.on("<event>")`) and takes two parameters, an event name and the payload, an AbstractEvent ||
| download | Start downloading the livestream video for a given duration or until stopped via the `stop_download` method. Supports the ability to add different flags, like `-c copy` which may reduce CPU usage by disabling transcoding. |
| stop_download | Stop downloading the livestream video if currently downloading, otherwise throws an error |
## Attributes
A `TikTokLiveClient` object contains the following attributes:
| Attribute Name | Description |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| room_id | The Room ID of the livestream room the client is currently connected to |
| room_info | Information about the given livestream room |
| unique_id | The TikTok username of the person whose livestream the client is currently connected to (e.g. @charlidamelio) |
| connected | Whether the client is currently connected to a livestream |
| connecting | Whether the client is currently connecting to a livestream |
| available_gifts | A dictionary containing K:V pairs of `Dict[int, GiftDetailed]`, where the int is the internal TikTok gift id | |
| proxies | Get the current proxies being used for HTTP requests.<br/><br/>**Note:** To set the active proxies, set the value of this attribute |
| loop | The asyncio event loop the client is running off of |
| http | The HTTP client TikTokLive uses to make all HTTP-based requests |
| websocket | The `WebcastWebsocketConnection` websocket client TikTokLive uses to manage its websocket connection |
| ffmpeg | The ffmpeg wrapper TikTokLive uses to manage ffmpeg-based stream downloads |
| viewer_count | The number of people currently watching the livestream broadcast. Updated automatically on a `viewer_update` event |
| top_viewers | The top N (usually ~1-20) users, ranked by coins gifted to the streamer, for the broadcast. Updated automatically on a `viewer_update` event |
## Events
A `TikTokLiveClient` object has the following events. You can add events either by doing `client.add_listener("event_name", callable)` or by decorating a function with `@client.on("event_name")` that includes an event
payload parameter.
### `connect`
Triggered when the websocket connection is successfully established.
```python
@client.on("connect")
async def on_connect(event: ConnectEvent):
print("Connected")
```
### `disconnect`
Triggered when the connection is terminated. You can call `start()` to reconnect . Note that you should wait a little bit before attempting a reconnect to to avoid being rate-limited.
```python
@client.on("disconnect")
async def on_disconnect(event: DisconnectEvent):
print("Disconnected")
```
### `like`
Triggered every time someone likes the stream.
```python
@client.on("like")
async def on_like(event: LikeEvent):
print(f"@{event.user.unique_id} liked the stream!")
```
### `join`
Triggered every time a new person joins the stream.
```python
@client.on("join")
async def on_join(event: JoinEvent):
print(f"@{event.user.unique_id} joined the stream!")
```
### `gift`
Triggered every time a gift arrives. Extra information can be gleamed off the `available_gifts` client attribute.
> **NOTE:** Users have the capability to send gifts in a streak. This increases the `event.gift.count` value until the user terminates the streak. During this time new gift events are triggered again and again with an increased `event.gift.count` value. It should be noted that after the end of the streak, another gift event is triggered, which signals the end of the streak via `event.gift.is_repeating`:`1`. This applies only to gifts with `event.gift.info.type`:`1`. This means that even if the user sends an `event.gift.info.type`:`1` gift only once, you may receive the event twice. Once with `event.gift.is_repeating`:`0` and once with `event.gift.is_repeating`:`1`. Therefore, the event should be handled as follows in one of TWO ways. These are the same, except the second is a 'higher level' implementation using TikTokLive API features:
```python
@client.on("gift")
async def on_gift(event: GiftEvent):
# If it's type 1 and the streak is over
if event.gift.info.type == 1:
if event.gift.is_repeating == 1:
print(f"{event.user.unique_id} sent {event.gift.count}x \"{event.gift.info.name}\"")
# It's not type 1, which means it can't have a streak & is automatically over
elif event.gift.info.type != 1:
print(f"{event.user.unique_id} sent \"{event.gift.info.name}\"")
```
```python
@client.on("gift")
async def on_gift(event: GiftEvent):
# Streakable gift & streak is over
if event.gift.streakable and not event.gift.streaking:
print(f"{event.user.unique_id} sent {event.gift.count}x \"{event.gift.info.name}\"")
# Non-streakable gift
elif not event.gift.streakable:
print(f"{event.user.unique_id} sent \"{event.gift.info.name}\"")
```
### `follow`
Triggered every time someone follows the streamer.
```python
@client.on("follow")
async def on_follow(event: FollowEvent):
print(f"@{event.user.unique_id} followed the streamer!")
```
### `share`
Triggered every time someone shares the stream.
```python
@client.on("share")
async def on_share(event: ShareEvent):
print(f"@{event.user.unique_id} shared the stream!")
```
### `more_share`
Triggered when 5 or 10 users join from a viewer's share link.
```python
@client.on("more_share")
async def on_connect(event: MoreShareEvent):
print(f"More than {event.amount} users have joined from {event.user.unique_id}'s share link!")
```
### `viewer_update`
Triggered every time the viewer count is updated. This event also updates the cached viewer count by default.
```python
@client.on("viewer_update")
async def on_connect(event: ViewerUpdateEvent):
# Viewer Count
print("Received a new viewer count:", event.viewer_count)
print("The client automatically sets the count as an attribute too:", client.viewer_count)
# Top VIewers
print("You can even get the top viewers (by coins gifted)!:", event.top_viewers)
print("The client automatically sets the top viewers as an attribute too:", client.top_viewers)
```
### `comment`
Triggered every time someone comments on the live.
```python
@client.on("comment")
async def on_connect(event: CommentEvent):
print(f"{event.user.nickname} -> {event.comment}")
```
### `emote`
Triggered when someone sends a subscription emote comment to the live chat.
```python
@client.on("emote")
async def on_connect(event: EmoteEvent):
print(f"{event.user.nickname} -> {event.emote.image.url}")
```
### `envelope`
Triggered when someone sends an envelope (treasure box) to the TikTok streamer.
```python
@client.on("envelope")
async def on_connect(event: EnvelopeEvent):
print(f"{event.treasure_box_user.unique_id} -> {event.treasure_box_data}")
```
### `ranking_update`
Triggered when a **stream** rank update is sent out. Can be `Weekly Ranking` or `Rising Star`!
```python
@client.on("ranking_update")
async def on_connect(event: RankingUpdateEvent):
print(f"{event.user.unique_id} has the rank #{event.rank} for the {event.type} leaderboard.")
```
### `user_ranking_update`
Triggered when a **user** rank update is sent out. Can be `Top Viewer`
status.
```python
@client.on("user_ranking_update")
async def on_connect(event: UserRankingUpdateEvent):
print(f"{event.user.unique_id} just became a #{event.rank} top viewer!")
```
### `mic_battle_start`
Triggered when a Mic Battle starts!
```python
@client.on("mic_battle_start")
async def on_connect(event: MicBattleStartEvent):
print(f"A Mic battle has started!")
```
### `mic_battle_update`
Triggered when information is received about a mic battle's progress.
```python
@client.on("mic_battle_update")
async def on_connect(event: MicBattleUpdateEvent):
print(f"An army in the mic battle has received points, or the status of the battle has changed!")
```
### `live_end`
Triggered when the live stream gets terminated by the host.
```python
@client.on("live_end")
async def on_connect(event: LiveEndEvent):
print(f"Livestream ended :(")
```
### `intro_message`
Triggered when an intro message is sent to the live room.
An intro message is basically a pinned message at the top of chat when you join a room.
This event only fires if "process_initial_data" is enabled and the streamer has an intro message configured.
```python
@client.on("intro_message")
async def on_connect(event: IntroMessageEvent):
print(f"Message: {event.message}")
```
### `unknown`
Triggered when ANY unknown event is received that is not yet handled by this client.
This includes both events where the protobuf has NOT been decoded, as well as events where it _has_ been decoded, but no event object has been created (e.g. it's useless data).
Use this event to debug and find new events to add to TikTokLive. Mention them [here](https://github.com/isaackogan/TikTokLive/issues/104) when you do.
This event is very advanced and handles both types of cases, an API to help you decode including offering the binary as base64.
You can plug base64 into https://protobuf-decoder.netlify.app/ to reverse-engineer the protobuf schema.
```python
@client.on("unknown")
async def on_connect(event: UnknownEvent):
print(f"Event Type: {event.type}")
print(f"Event Base64: {event.base64}")
```
### `error`
Triggered when there is an error in the client or error handlers.
If this handler is not present in the code, an internal default handler will log errors in the console. If a handler is added, all error handling (including logging) is up to the individual.
**Warning:** If you listen for the error event and do not log errors, you will not see when an error occurs. This expected behaviour, listening to the error event overrides & disables the built-in one.
```python
@client.on("error")
async def on_connect(error: Exception):
# Handle the error
if isinstance(error, SomeRandomError):
print("Handle some error!")
return
# Otherwise, log the error
# You can use the internal method, but ideally your own
client._log_error(error)
```
## Contributors
* **Isaac Kogan** - *Creator, Primary Maintainer, and Reverse-Engineering* - [isaackogan](https://github.com/isaackogan)
* **Zerody** - *Initial Reverse-Engineering Protobuf & Support* - [Zerody](https://github.com/zerodytrash/)
* **Davincible** - *Reverse-Engineering Stream Downloads* - [davincible](https://github.com/davincible)
* **David Teather** - *TikTokLive Introduction Tutorial* - [davidteather](https://github.com/davidteather)
See also the full list of [contributors](https://github.com/isaackogan/TikTokLive/contributors) who have participated in this project.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/aviongeno/TikTokLiveClone",
"name": "TikTokLiveClone",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "tiktok,tiktok live,python3,api,unofficial",
"author": "Reese Ramirez",
"author_email": "info@unofficiallydiagnosed.com",
"download_url": "https://files.pythonhosted.org/packages/9c/af/63eb144dffb923318affbb7917d8a48ce2cb8c2dab1d7dc09b4e77381eea/TikTokLiveClone-1.0.1.tar.gz",
"platform": null,
"description": "TikTokLiveClone\r\n==================\r\nOriginal Details:\r\n\r\nA Python library to connect to and read events from TikTok's LIVE service.\r\n\r\n[](https://www.linkedin.com/in/isaac-kogan-5a45b9193/ )\r\n[](http://hits.dwyl.com/isaackogan/TikTokLive)\r\n\r\n\r\n\r\n\r\n[](https://discord.gg/e2XwPNTBBr)\r\n\r\n<!-- [](https://pepy.tech/project/tiktoklive) -->\r\n\r\nA Python library to receive and decode livestream events such as comments and gifts in real-time from TikTok's LIVE service by connecting to TikTok's internal Webcast service. This library includes a wrapper that\r\nconnects to the Webcast service using only a user's `unique_id` and allows you to join your livestream as well as that of other streamers. No credentials are required to use TikTokLive.\r\n\r\nThis library was originally based off of the\r\n[TikTok-Live-Connector](https://github.com/zerodytrash/TikTok-Live-Connector)\r\nby [@zerodytrash](https://github.com/zerodytrash/), but has since taken on its own identity as it has added more features & changed much of its core functionality.\r\n\r\n\r\nJoin the [support discord](https://discord.gg/e2XwPNTBBr) and visit the `#py-support` channel for questions, contributions and ideas. Feel free to make pull requests with missing/new features, fixes, etc.\r\n\r\n> **UPDATE:**<br>Due to a change on the part of TikTok, versions prior to **v4.3.8** are no longer functional. If you are using an unsupported version, upgrade to the latest version using the `pip install TikTokLive --upgrade` command.\r\n\r\n## Other Languages\r\n\r\nTikTok LIVE is available in several alternative languages with only slight differences between the versions:\r\n\r\n- **Node.JS:** https://github.com/zerodytrash/TikTok-Live-Connector\r\n- **Go:** https://github.com/Davincible/gotiktoklive\r\n- **C#/Unity:** https://github.com/frankvHoof93/TikTokLiveSharp\r\n\r\n## Table of Contents\r\n\r\n**Primary Information**\r\n\r\n- [Documentation](https://isaackogan.github.io/TikTokLive/)\r\n- [Contributors](#contributors)\r\n- [License](#license)\r\n- [Quickstart Examples](https://github.com/isaackogan/TikTokLive/tree/master/examples)\r\n\r\n**Resources & Guides**\r\n\r\n1. [David's Intro Tutorial](#tiktoklive-intro-tutorial)\r\n2. [Getting Started](#getting-started)\r\n3. [Params & Options](#Params-&-Options)\r\n4. [Client Methods](#Methods)\r\n5. [Client Attributes](#Attributes)\r\n6. [TikTok Events](#Events)\r\n\r\n## TikTokLive Intro Tutorial\r\n\r\nI cannot recommend this tutorial enough for people trying to get started. It is succinct, informative and easy to understand, created by [David Teather](https://github.com/davidteather), the creator of the\r\nPython [TikTok-Api](https://github.com/davidteather/TikTok-Api) package. Click the thumbnail to warp.\r\n\r\n[](https://www.youtube.com/watch?v=307ijmA3_lc)\r\n\r\n## Getting Started\r\n\r\n1. Install the module via pip\r\n\r\n```shell script\r\n> pip install TikTokLive\r\n```\r\n\r\n2. Create your first chat connection\r\n\r\n```python\r\nfrom TikTokLive import TikTokLiveClient\r\nfrom TikTokLive.types.events import CommentEvent, ConnectEvent\r\n\r\n# Instantiate the client with the user's username\r\nclient: TikTokLiveClient = TikTokLiveClient(unique_id=\"@isaackogz\")\r\n\r\n\r\n# Define how you want to handle specific events via decorator\r\n@client.on(\"connect\")\r\nasync def on_connect(_: ConnectEvent):\r\n print(\"Connected to Room ID:\", client.room_id)\r\n\r\n\r\n# Notice no decorator?\r\nasync def on_comment(event: CommentEvent):\r\n print(f\"{event.user.nickname} -> {event.comment}\")\r\n\r\n\r\n# Define handling an event via a \"callback\"\r\nclient.add_listener(\"comment\", on_comment)\r\n\r\nif __name__ == '__main__':\r\n # Run the client and block the main thread\r\n # await client.start() to run non-blocking\r\n client.run()\r\n```\r\n\r\nFor more examples, [see the examples folder](https://github.com/isaackogan/TikTokLive/tree/master/examples) provided in the tree.\r\n\r\n## Params & Options\r\n\r\nTo create a new `TikTokLiveClient` object the following parameter is required. You can optionally add configuration options to this via kwargs.\r\n\r\n`TikTokLiveClient(unique_id, **options)`\r\n\r\n| Param Name | Required | Description |\r\n|------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\r\n| unique_id | Yes | The unique username of the broadcaster. You can find this name in the URL.<br>Example: `https://www.tiktok.com/@isaackogz` => `isaackogz` |\r\n| **options | No | Here you can set the following optional connection properties. If you do not specify a value, the default value will be used.<br><br>`process_initial_data` (default: `True`) <br> Define if you want to process initial data upon connecting (e.g. first 1-10 messages from BEFORE you connected).<br><br>`fetch_room_info_on_connect` (default: `True`) <br> Define if you want to fetch all room information on start. If this option is enabled, connection to offline rooms will be prevented. If enabled, the connect result contains the room info via the `room_info` attribute. You can also manually retrieve the room info (even in an unconnected state) using the `retrieve_room_info()` method.<br><br>`enable_detailed_gifts` (default: `False`) <br> Define if you want to receive extended information about gifts like gift name, cost and images which you can retrieve via the `available_gifts` attribute. When enabled, the `details` attribute in a `Gift` object will be populated.<br><br>`ws_ping_interval` (default: `10.0`) <br> The interval between keepalive pings on the websocket connection (in seconds).<br><br>`ws_timeout` (default: `10.0`)<br>How long to wait before the websocket connection is considered timed out (in seconds).<br><br>`http_timeout` (default: `10.0`) <br> How long to wait before considering an HTTP request in the http client timed out (in seconds).<br><br>`http_headers` (default: `{}`) <br> Additional HTTP client headers to include when making requests to the Webcast API AND connecting to the websocket server.<br><br>`http_params` (default: `{}`) <br>Additional HTTP client parameters to include when making requests to the Webcast API AND connecting to the websocket.<br><br>`loop` (default: `None`)<br>Optionally supply your own asyncio event loop for usage by the client. When set to None, the client pulls the current active loop or creates a new one. This option is mostly useful for people trying to nest asyncio.<br/><br/>`trust_env` (default: `False`)<br/>Whether to trust environment variables that provide proxies in httpx requests<br/><br/>`proxies` (default: `None`)<br/>Enable proxied requests by turning on forwarding for the HTTP \"proxies\" argument. Websocket connections will NOT be proxied<br/><br/>`lang` (default: `en-US`)<br/>Change the language. Payloads *will* be in English, but front-end content will be in the desired language!<br/><br/>`sign_api_key` (default: `None`)<br/>Parameter to increase the amount of connections allowed to be made per minute via a Sign Server API key. If you need this, contact the project maintainer.<br/><br/>`ssl_context` (default: `None`)<br/>Providing an SSLContext object overrides the default context used in HTTP requests made to TikTok. This is useful if TikTok sends invalid SSL signatures, as you can provide a \"no verify\" context. |\r\n\r\n\r\n## Methods\r\n\r\nA `TikTokLiveClient` object contains the following methods:\r\n\r\n| Method Name | Description |\r\n|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\r\n| run | Starts a connection to the live chat while blocking the main thread |\r\n| start | (async) Connects to the live chat without blocking the main thread |\r\n| stop | Turns off the connection to the live chat. |\r\n| retrieve_room_info | (async) Gets the current room info from TikTok API |\r\n| retrieve_available_gifts | (async) Retrieves a list of the available gifts for the room and adds it to the `extended_gift` attribute of the `Gift` object on the `gift` event, when enabled. |\r\n| add_listener | Adds an *asynchronous* listener function (or, you can decorate a function with `@client.on(\"<event>\")`) and takes two parameters, an event name and the payload, an AbstractEvent ||\r\n| download | Start downloading the livestream video for a given duration or until stopped via the `stop_download` method. Supports the ability to add different flags, like `-c copy` which may reduce CPU usage by disabling transcoding. |\r\n| stop_download | Stop downloading the livestream video if currently downloading, otherwise throws an error |\r\n\r\n## Attributes\r\n\r\nA `TikTokLiveClient` object contains the following attributes:\r\n\r\n| Attribute Name | Description |\r\n|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------|\r\n| room_id | The Room ID of the livestream room the client is currently connected to |\r\n| room_info | Information about the given livestream room |\r\n| unique_id | The TikTok username of the person whose livestream the client is currently connected to (e.g. @charlidamelio) |\r\n| connected | Whether the client is currently connected to a livestream |\r\n| connecting | Whether the client is currently connecting to a livestream |\r\n| available_gifts | A dictionary containing K:V pairs of `Dict[int, GiftDetailed]`, where the int is the internal TikTok gift id | |\r\n| proxies | Get the current proxies being used for HTTP requests.<br/><br/>**Note:** To set the active proxies, set the value of this attribute |\r\n| loop | The asyncio event loop the client is running off of |\r\n| http | The HTTP client TikTokLive uses to make all HTTP-based requests |\r\n| websocket | The `WebcastWebsocketConnection` websocket client TikTokLive uses to manage its websocket connection |\r\n| ffmpeg | The ffmpeg wrapper TikTokLive uses to manage ffmpeg-based stream downloads |\r\n| viewer_count | The number of people currently watching the livestream broadcast. Updated automatically on a `viewer_update` event |\r\n| top_viewers | The top N (usually ~1-20) users, ranked by coins gifted to the streamer, for the broadcast. Updated automatically on a `viewer_update` event |\r\n\r\n\r\n## Events\r\n\r\nA `TikTokLiveClient` object has the following events. You can add events either by doing `client.add_listener(\"event_name\", callable)` or by decorating a function with `@client.on(\"event_name\")` that includes an event\r\npayload parameter.\r\n\r\n### `connect`\r\n\r\nTriggered when the websocket connection is successfully established.\r\n\r\n```python\r\n@client.on(\"connect\")\r\nasync def on_connect(event: ConnectEvent):\r\n print(\"Connected\")\r\n```\r\n\r\n### `disconnect`\r\n\r\nTriggered when the connection is terminated. You can call `start()` to reconnect . Note that you should wait a little bit before attempting a reconnect to to avoid being rate-limited.\r\n\r\n```python\r\n@client.on(\"disconnect\")\r\nasync def on_disconnect(event: DisconnectEvent):\r\n print(\"Disconnected\")\r\n```\r\n\r\n### `like`\r\n\r\nTriggered every time someone likes the stream.\r\n\r\n```python\r\n@client.on(\"like\")\r\nasync def on_like(event: LikeEvent):\r\n print(f\"@{event.user.unique_id} liked the stream!\")\r\n```\r\n\r\n### `join`\r\n\r\nTriggered every time a new person joins the stream.\r\n\r\n```python\r\n@client.on(\"join\")\r\nasync def on_join(event: JoinEvent):\r\n print(f\"@{event.user.unique_id} joined the stream!\")\r\n```\r\n\r\n### `gift`\r\n\r\nTriggered every time a gift arrives. Extra information can be gleamed off the `available_gifts` client attribute.\r\n> **NOTE:** Users have the capability to send gifts in a streak. This increases the `event.gift.count` value until the user terminates the streak. During this time new gift events are triggered again and again with an increased `event.gift.count` value. It should be noted that after the end of the streak, another gift event is triggered, which signals the end of the streak via `event.gift.is_repeating`:`1`. This applies only to gifts with `event.gift.info.type`:`1`. This means that even if the user sends an `event.gift.info.type`:`1` gift only once, you may receive the event twice. Once with `event.gift.is_repeating`:`0` and once with `event.gift.is_repeating`:`1`. Therefore, the event should be handled as follows in one of TWO ways. These are the same, except the second is a 'higher level' implementation using TikTokLive API features:\r\n\r\n```python\r\n@client.on(\"gift\")\r\nasync def on_gift(event: GiftEvent):\r\n # If it's type 1 and the streak is over\r\n if event.gift.info.type == 1:\r\n if event.gift.is_repeating == 1:\r\n print(f\"{event.user.unique_id} sent {event.gift.count}x \\\"{event.gift.info.name}\\\"\")\r\n\r\n # It's not type 1, which means it can't have a streak & is automatically over\r\n elif event.gift.info.type != 1:\r\n print(f\"{event.user.unique_id} sent \\\"{event.gift.info.name}\\\"\")\r\n```\r\n\r\n```python\r\n@client.on(\"gift\")\r\nasync def on_gift(event: GiftEvent):\r\n # Streakable gift & streak is over\r\n if event.gift.streakable and not event.gift.streaking:\r\n print(f\"{event.user.unique_id} sent {event.gift.count}x \\\"{event.gift.info.name}\\\"\")\r\n\r\n # Non-streakable gift\r\n elif not event.gift.streakable:\r\n print(f\"{event.user.unique_id} sent \\\"{event.gift.info.name}\\\"\")\r\n\r\n```\r\n\r\n### `follow`\r\n\r\nTriggered every time someone follows the streamer.\r\n\r\n```python\r\n@client.on(\"follow\")\r\nasync def on_follow(event: FollowEvent):\r\n print(f\"@{event.user.unique_id} followed the streamer!\")\r\n```\r\n\r\n### `share`\r\n\r\nTriggered every time someone shares the stream.\r\n\r\n```python\r\n@client.on(\"share\")\r\nasync def on_share(event: ShareEvent):\r\n print(f\"@{event.user.unique_id} shared the stream!\")\r\n\r\n```\r\n\r\n### `more_share`\r\n\r\nTriggered when 5 or 10 users join from a viewer's share link.\r\n\r\n```python\r\n@client.on(\"more_share\")\r\nasync def on_connect(event: MoreShareEvent):\r\n print(f\"More than {event.amount} users have joined from {event.user.unique_id}'s share link!\")\r\n```\r\n\r\n\r\n### `viewer_update`\r\n\r\nTriggered every time the viewer count is updated. This event also updates the cached viewer count by default.\r\n\r\n```python\r\n@client.on(\"viewer_update\")\r\nasync def on_connect(event: ViewerUpdateEvent):\r\n\r\n # Viewer Count\r\n print(\"Received a new viewer count:\", event.viewer_count)\r\n print(\"The client automatically sets the count as an attribute too:\", client.viewer_count)\r\n \r\n # Top VIewers\r\n print(\"You can even get the top viewers (by coins gifted)!:\", event.top_viewers)\r\n print(\"The client automatically sets the top viewers as an attribute too:\", client.top_viewers)\r\n\r\n```\r\n\r\n### `comment`\r\n\r\nTriggered every time someone comments on the live.\r\n\r\n```python\r\n@client.on(\"comment\")\r\nasync def on_connect(event: CommentEvent):\r\n print(f\"{event.user.nickname} -> {event.comment}\")\r\n```\r\n\r\n### `emote`\r\n\r\nTriggered when someone sends a subscription emote comment to the live chat.\r\n\r\n```python\r\n@client.on(\"emote\")\r\nasync def on_connect(event: EmoteEvent):\r\n print(f\"{event.user.nickname} -> {event.emote.image.url}\")\r\n```\r\n\r\n### `envelope`\r\n\r\nTriggered when someone sends an envelope (treasure box) to the TikTok streamer.\r\n\r\n```python\r\n@client.on(\"envelope\")\r\nasync def on_connect(event: EnvelopeEvent):\r\n print(f\"{event.treasure_box_user.unique_id} -> {event.treasure_box_data}\")\r\n```\r\n\r\n### `ranking_update`\r\n\r\nTriggered when a **stream** rank update is sent out. Can be `Weekly Ranking` or `Rising Star`!\r\n\r\n```python\r\n@client.on(\"ranking_update\")\r\nasync def on_connect(event: RankingUpdateEvent):\r\n print(f\"{event.user.unique_id} has the rank #{event.rank} for the {event.type} leaderboard.\")\r\n```\r\n\r\n### `user_ranking_update`\r\n\r\nTriggered when a **user** rank update is sent out. Can be `Top Viewer`\r\n status.\r\n```python\r\n@client.on(\"user_ranking_update\")\r\nasync def on_connect(event: UserRankingUpdateEvent):\r\n print(f\"{event.user.unique_id} just became a #{event.rank} top viewer!\")\r\n```\r\n\r\n### `mic_battle_start`\r\n\r\nTriggered when a Mic Battle starts!\r\n\r\n```python\r\n@client.on(\"mic_battle_start\")\r\nasync def on_connect(event: MicBattleStartEvent):\r\n print(f\"A Mic battle has started!\")\r\n```\r\n\r\n### `mic_battle_update`\r\n\r\nTriggered when information is received about a mic battle's progress.\r\n\r\n```python\r\n@client.on(\"mic_battle_update\")\r\nasync def on_connect(event: MicBattleUpdateEvent):\r\n print(f\"An army in the mic battle has received points, or the status of the battle has changed!\")\r\n```\r\n\r\n\r\n### `live_end`\r\n\r\nTriggered when the live stream gets terminated by the host.\r\n\r\n```python\r\n@client.on(\"live_end\")\r\nasync def on_connect(event: LiveEndEvent):\r\n print(f\"Livestream ended :(\")\r\n```\r\n\r\n\r\n### `intro_message`\r\n\r\nTriggered when an intro message is sent to the live room.\r\nAn intro message is basically a pinned message at the top of chat when you join a room.\r\n\r\nThis event only fires if \"process_initial_data\" is enabled and the streamer has an intro message configured.\r\n\r\n```python\r\n@client.on(\"intro_message\")\r\nasync def on_connect(event: IntroMessageEvent):\r\n print(f\"Message: {event.message}\")\r\n```\r\n\r\n\r\n### `unknown`\r\n\r\nTriggered when ANY unknown event is received that is not yet handled by this client.\r\n\r\nThis includes both events where the protobuf has NOT been decoded, as well as events where it _has_ been decoded, but no event object has been created (e.g. it's useless data).\r\n\r\nUse this event to debug and find new events to add to TikTokLive. Mention them [here](https://github.com/isaackogan/TikTokLive/issues/104) when you do.\r\n\r\nThis event is very advanced and handles both types of cases, an API to help you decode including offering the binary as base64. \r\nYou can plug base64 into https://protobuf-decoder.netlify.app/ to reverse-engineer the protobuf schema.\r\n\r\n```python\r\n@client.on(\"unknown\")\r\nasync def on_connect(event: UnknownEvent):\r\n print(f\"Event Type: {event.type}\")\r\n print(f\"Event Base64: {event.base64}\")\r\n```\r\n\r\n### `error`\r\n\r\nTriggered when there is an error in the client or error handlers.\r\n\r\nIf this handler is not present in the code, an internal default handler will log errors in the console. If a handler is added, all error handling (including logging) is up to the individual.\r\n\r\n**Warning:** If you listen for the error event and do not log errors, you will not see when an error occurs. This expected behaviour, listening to the error event overrides & disables the built-in one.\r\n\r\n```python\r\n\r\n@client.on(\"error\")\r\nasync def on_connect(error: Exception):\r\n # Handle the error\r\n if isinstance(error, SomeRandomError):\r\n print(\"Handle some error!\")\r\n return\r\n\r\n # Otherwise, log the error\r\n # You can use the internal method, but ideally your own\r\n client._log_error(error)\r\n\r\n```\r\n\r\n## Contributors\r\n\r\n* **Isaac Kogan** - *Creator, Primary Maintainer, and Reverse-Engineering* - [isaackogan](https://github.com/isaackogan)\r\n* **Zerody** - *Initial Reverse-Engineering Protobuf & Support* - [Zerody](https://github.com/zerodytrash/)\r\n* **Davincible** - *Reverse-Engineering Stream Downloads* - [davincible](https://github.com/davincible)\r\n* **David Teather** - *TikTokLive Introduction Tutorial* - [davidteather](https://github.com/davidteather)\r\n\r\nSee also the full list of [contributors](https://github.com/isaackogan/TikTokLive/contributors) who have participated in this project.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "TikTok Live Connection Client Clone",
"version": "1.0.1",
"project_urls": {
"Download": "https://github.com/aviongeno/TikTokLiveClone/releases/tag/v1.0.0",
"Homepage": "https://github.com/aviongeno/TikTokLiveClone"
},
"split_keywords": [
"tiktok",
"tiktok live",
"python3",
"api",
"unofficial"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "434d1eac8878be1544764cd57bbb72b00428c72f2887bbe238352a02c689cb07",
"md5": "7d9b31ed55cbc3e40b20dd9c4a3cd615",
"sha256": "cd72851792cd6b3b7ca9e80d20563a8ec3466ea1432805551c210ec6ee7d7bf1"
},
"downloads": -1,
"filename": "TikTokLiveClone-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d9b31ed55cbc3e40b20dd9c4a3cd615",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 74464,
"upload_time": "2023-08-21T16:57:55",
"upload_time_iso_8601": "2023-08-21T16:57:55.138315Z",
"url": "https://files.pythonhosted.org/packages/43/4d/1eac8878be1544764cd57bbb72b00428c72f2887bbe238352a02c689cb07/TikTokLiveClone-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9caf63eb144dffb923318affbb7917d8a48ce2cb8c2dab1d7dc09b4e77381eea",
"md5": "3320185ca7d6ceabf5dc8c710d2b4ff6",
"sha256": "5de677afa7f26d1fbc5dcb291b08b97ff729cf60d98f622de727f822dba0d436"
},
"downloads": -1,
"filename": "TikTokLiveClone-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "3320185ca7d6ceabf5dc8c710d2b4ff6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 44400,
"upload_time": "2023-08-21T16:57:58",
"upload_time_iso_8601": "2023-08-21T16:57:58.037245Z",
"url": "https://files.pythonhosted.org/packages/9c/af/63eb144dffb923318affbb7917d8a48ce2cb8c2dab1d7dc09b4e77381eea/TikTokLiveClone-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-21 16:57:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aviongeno",
"github_project": "TikTokLiveClone",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tiktokliveclone"
}
JSON
