TikTokLive Docs#
The following subpackages exist for TikTokLive:
TikTokLive#
The definitive Python library to connect to TikTok LIVE.
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.
Consider Donating <3#
I’m a 2nd-year Biology student in university who likes to program for fun. Please consider supporting development through a small donation at https://www.buymeacoffee.com/isaackogan. Anything you can offer will go towards school & development costs for TikTokLive, which has taken hundreds of hours of time to build.
Other Languages#
TikTokLive is available in several alternate programming languages:
Table of Contents#
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 |
web_proxy |
No |
|
TikTokLive supports proxying HTTP requests. This parameter accepts an |
ws_proxy |
No |
|
TikTokLive supports proxying the websocket connection. This parameter accepts an |
web_kwargs |
No |
|
Under the scenes, the TikTokLive HTTP client uses the |
ws_kwargs |
No |
|
Under the scenes, TikTokLive uses the |
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 |
connect |
|
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 |
|
Connects to the live chat without blocking the main thread. This returns an |
disconnect |
|
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 |
room_info |
Room information that is retrieved from TikTok when you use a connection method (e.g. |
gift_info |
Extra gift information that is retrieved from TikTok when you use a connection method (e.g. |
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 |
|
The TikTok app URL ( |
tiktok_sign_url |
|
The signature server used to generate tokens to connect to TikTokLive. |
tiktok_webcast_url |
|
The TikTok livestream URL ( |
client_params |
|
The URL parameters added on to TikTok requests from the HTTP client. |
client_headers |
|
The headers added on to TikTok requests from the HTTP client. |
tiktok_sign_api_key |
|
A global way of setting the |
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 initiatedDisconnectEvent
- Triggered when the Webcast connection closes (including the livestream ending)LiveEndEvent
- Triggered when the livestream endsLivePauseEvent
- Triggered when the livestream is pausedLiveUnpauseEvent
- Triggered when the livestream is unpausedFollowEvent
- Triggered when a user in the livestream follows the streamerShareEvent
- Triggered when a user shares the livestreamWebsocketResponseEvent
- Triggered when any event is received (contains the event)UnknownEvent
- An instance ofWebsocketResponseEvent
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 streamerGoalUpdateEvent
- Triggered when the subscriber goal is updatedControlEvent
- Triggered when a stream action occurs (e.g. Livestream start, end)LikeEvent
- Triggered when the stream receives a likeSubscribeEvent
- Triggered when someone subscribes to the TikTok creatorPollEvent
- Triggered when the creator launches a new pollCommentEvent
- Triggered when a comment is sent in the streamRoomEvent
- Messages broadcasted to all users in the room (e.g. “Welcome to TikTok LIVE!”)EmoteChatEvent
- Triggered when a custom emote is sent in the chatEnvelopeEvent
- Triggered every time someone sends a treasure chestSocialEvent
- Triggered when a user shares the stream or follows the hostQuestionNewEvent
- Triggered every time someone asks a new question via the question feature.LiveIntroEvent
- Triggered when a live intro message appearsLinkMicArmiesEvent
- Triggered when a TikTok battle user receives pointsLinkMicBattleEvent
- Triggered when a TikTok battle is startedJoinEvent
- Triggered when a user joins the livestreamLinkMicFanTicketMethodEvent
LinkMicMethodEvent
BarrageEvent
CaptionEvent
ImDeleteEvent
RoomUserSeqEvent
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 increasedevent.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 withevent.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.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}\"")
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.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}\"")
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
David Teather - TikTokLive Introduction Tutorial - davidteather
See also the full list of contributors who have participated in this project.
License#
This project is licensed under the MIT License - see the LICENSE file for details.