TikTokLive

The definitive Python library to connect to TikTok LIVE.

Connections Stars Forks Issues

TikTokLive is a Python library designed to connect to TikTok LIVE and receive realtime events such as comments, gifts, and likes through a websocket connection to TikTok's internal Webcast service. This library allows you to connect directly to TikTok with just a username (@unique_id). No credentials are required to use TikTokLive.

Join the TikTokLive discord and visit the #py-support channel for questions, contributions and ideas.

Enterprise Access

Eulerstream offers paid plans for enterprises for increased TikTokLive access & TikTok API tokens for data collection

Other Languages

TikTokLive is available in several alternate programming languages:

Node.JS: https://github.com/zerodytrash/TikTok-Live-Connector
Java: https://github.com/jwdeveloper/TikTok-Live-Java
C#/Unity: https://github.com/frankvHoof93/TikTokLiveSharp
Go: https://github.com/Davincible/gotiktoklive
Rust: https://github.com/jwdeveloper/TikTokLiveRust

Getting Started

Install the module via pip from the PyPi repository

pip install TikTokLive

Create your first chat connection

from TikTokLive import TikTokLiveClient
from TikTokLive.events import ConnectEvent, CommentEvent

# Create the client
client: TikTokLiveClient = TikTokLiveClient(unique_id="@isaackogz")


# Listen to an event with a decorator!
@client.on(ConnectEvent)
async def on_connect(event: ConnectEvent):
    print(f"Connected to @{event.unique_id} (Room ID: {client.room_id}")


# Or, add it manually via "client.add_listener()"
async def on_comment(event: CommentEvent) -> None:
    print(f"{event.user.nickname} -> {event.comment}")


client.add_listener(CommentEvent, on_comment)

if __name__ == '__main__':
    # Run the client and block the main thread
    # await client.start() to run non-blocking
    client.run()

For more quickstart examples, see the examples folder provided in the source tree.

Parameters

Param Name	Required	Default	Description
unique_id	Yes	N/A	The unique username of the broadcaster. You can find this name in the URL of the user. For example, the `unique_id` for `https://www.tiktok.com/@isaackogz` would be `isaackogz`.
web_proxy	No	`None`	TikTokLive supports proxying HTTP requests. This parameter accepts an `httpx.Proxy`. Note that if you do use a proxy you may be subject to reduced connection limits at times of high load.
ws_proxy	No	`None`	TikTokLive supports proxying the websocket connection. This parameter accepts an `httpx.Proxy`. Using this proxy will never be subject to reduced connection limits.
web_kwargs	No	`{}`	Under the scenes, the TikTokLive HTTP client uses the `httpx` library. Arguments passed to `web_kwargs` will be forward the the underlying HTTP client.
ws_kwargs	No	`{}`	Under the scenes, TikTokLive uses the `websockets` library to connect to TikTok. Arguments passed to `ws_kwargs` will be forwarded to the underlying WebSocket client.

Methods

A TikTokLiveClient object contains the following important methods:

Method Name	Notes	Description
run	N/A	Connect to the livestream and block the main thread. This is best for small scripts.
add_listener	N/A	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
connect	`async`	Connects to the tiktok live chat while blocking the current future. When the connection ends (e.g. livestream is over), the future is released.
start	`async`	Connects to the live chat without blocking the main thread. This returns an `asyncio.Task` object with the client loop.
disconnect	`async`	Disconnects the client from the websocket gracefully, processing remaining events before ending the client loop.

Properties

A TikTokLiveClient object contains the following important properties:

Attribute Name	Description
room_id	The Room ID of the livestream room the client is currently connected to.
web	The TikTok HTTP client. This client has a lot of useful routes you should explore!
connected	Whether you are currently connected to the livestream.
logger	The internal logger used by TikTokLive. You can use `client.logger.setLevel(...)` method to enable client debug.
room_info	Room information that is retrieved from TikTok when you use a connection method (e.g. `client.connect`) with the keyword argument `fetch_room_info=True` .
gift_info	Extra gift information that is retrieved from TikTok when you use a connection method (e.g. `client.run`) with the keyword argument `fetch_gift_info=True`.

WebDefaults

TikTokLive has a series of global defaults used to create the HTTP client which you can customize. For info on how to set these parameters, see the web_defaults.py example.

Parameter	Type	Description
tiktok_app_url	`str`	The TikTok app URL (`https://www.tiktok.com`) used to scrape the room.
tiktok_sign_url	`str`	The signature server used to generate tokens to connect to TikTokLive.
tiktok_webcast_url	`str`	The TikTok livestream URL (`https://webcast.tiktok.com`) where livestreams can be accessed from.
client_params	`dict`	The URL parameters added on to TikTok requests from the HTTP client.
client_headers	`dict`	The headers added on to TikTok requests from the HTTP client.
tiktok_sign_api_key	`str`	A global way of setting the `sign_api_key` parameter.

Events

Events can be listened to using a decorator or non-decorator method call. The following examples illustrate how you can listen to an event:

@client.on(LikeEvent)
async def on_like(event: LikeEvent) -> None:
    ...

async def on_comment(event: CommentEvent) -> None:
    ...

client.add_listener(CommentEvent, on_comment)

There are two types of events, CustomEvent events and ProtoEvent events. Both belong to the TikTokLive Event type and can be listened to. The following events are available:

Custom Events

ConnectEvent - Triggered when the Webcast connection is initiated
DisconnectEvent - Triggered when the Webcast connection closes (including the livestream ending)
LiveEndEvent - Triggered when the livestream ends
LivePauseEvent - Triggered when the livestream is paused
LiveUnpauseEvent - Triggered when the livestream is unpaused
FollowEvent - Triggered when a user in the livestream follows the streamer
ShareEvent - Triggered when a user shares the livestream
WebsocketResponseEvent - Triggered when any event is received (contains the event)
UnknownEvent - An instance of WebsocketResponseEvent thrown whenever an event does not have an existing definition, useful for debugging

Proto Events

If you know what an event does, make a pull request and add the description.

GiftEvent - Triggered when a gift is sent to the streamer
GoalUpdateEvent - Triggered when the subscriber goal is updated
ControlEvent - Triggered when a stream action occurs (e.g. Livestream start, end)
LikeEvent - Triggered when the stream receives a like
SubscribeEvent - Triggered when someone subscribes to the TikTok creator
PollEvent - Triggered when the creator launches a new poll
CommentEvent - Triggered when a comment is sent in the stream
RoomEvent - Messages broadcasted to all users in the room (e.g. "Welcome to TikTok LIVE!")
EmoteChatEvent - Triggered when a custom emote is sent in the chat
EnvelopeEvent - Triggered every time someone sends a treasure chest
SocialEvent - Triggered when a user shares the stream or follows the host
QuestionNewEvent - Triggered every time someone asks a new question via the question feature.
LiveIntroEvent - Triggered when a live intro message appears
LinkMicArmiesEvent - Triggered when a TikTok battle user receives points
LinkMicBattleEvent - Triggered when a TikTok battle is started
JoinEvent - Triggered when a user joins the livestream
LinkMicFanTicketMethodEvent
LinkMicMethodEvent
BarrageEvent
CaptionEvent
ImDeleteEvent
RoomUserSeqEvent - Current viewer count information
RankUpdateEvent
RankTextEvent
HourlyRankEvent
UnauthorizedMemberEvent
MessageDetectEvent
OecLiveShoppingEvent
RoomPinEvent
SystemEvent
LinkEvent
LinkLayerEvent

Special Events

`GiftEvent`

Triggered every time a gift arrives. Extra information can be gleamed from the available_gifts client attribute.

NOTE: Users have the capability to send gifts in a streak. This increases the event.gift.repeat_count value until the user terminates the streak. During this time new gift events are triggered again and again with an increased event.gift.repeat_count value. It should be noted that after the end of a streak, a final gift event is triggered, which signals the end of the streak with event.repeat_end:1. The following handlers show how you can deal with this in your code.

Using the low-level direct proto:

@client.on(GiftEvent)
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.repeat_count}x \"{event.gift.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.name}\"")

Using the TikTokLive extended proto:

@client.on("gift")
async def on_gift(event: GiftEvent):
    # Streakable gift & streak is over
    if event.gift.streakable and not event.streaking:
        print(f"{event.user.unique_id} sent {event.repeat_count}x \"{event.gift.name}\"")

    # Non-streakable gift
    elif not event.gift.streakable:
        print(f"{event.user.unique_id} sent \"{event.gift.name}\"")

`SubscribeEvent`

This event will only fire when a session ID (account login) is passed to the HTTP client before connecting to TikTok LIVE. You can set the session ID with client.web.set_session_id(...).

Checking If A User Is Live

It is considered inefficient to use the connect method to check if a user is live. It is better to use the dedicated await client.is_live() method.

There is a complete example of how to do this in the examples folder.

Contributors

Isaac Kogan - Creator, Primary Maintainer, and Reverse-Engineering - isaackogan
Zerody - Initial Reverse-Engineering Protobuf & Support - Zerody
Davincible - Reverse-Engineering Stream Downloads - davincible

See also the full list of contributors who have participated in this project.