search

isaackogan / TikTokLive

Python library to receive live stream events (comments, gifts, etc.) in realtime from TikTok LIVE.
https://isaackogan.github.io/TikTokLive/
MIT License
880 stars 175 forks source link
api chat-reader connector printer python scraper stream tiktok tiktok-api tiktok-live tiktok-printer tiktok-scraper

readme

TikTokLive API

This is an unofficial API wrapper for TikTok LIVE written in Python. With this API you can connect to any TikTok livestream and fetch all data available to users in a stream using just a creator's @username.

LinkedIn LinkedIn Connections Downloads Stars Forks Issues

This API is designed to retrieve information from TikTok. It cannot be used to post/upload LIVE content or comments, to simulate user interaction, or otherwise generate fake traffic. This API does not count towards viewers in a stream. It has no support for any user-authenticated routes.

Enterprise Solutions




 Euler Stream is a paid TikTok LIVE service providing managed TikTok LIVE WebSocket connections, increased access, TikTok LIVE alerts, JWT authentication and more.

Table of Contents

Community

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

Getting Started

  1. Install the module via pip from the PyPi repository
pip install TikTokLive
  1. 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.

Other Languages

TikTokLive is available in several alternate programming languages:

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_ws_params dict The URL parameters added to the URI when connecting to TikTok's Webcast WebSocket server.
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

Proto Events

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

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

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.