Metadata-Version: 2.4
Name: TikTokLive
Version: 7.0.0
Summary: Unofficial TikTok LIVE API for Python: real-time chat, gift, like, follow and viewer events from any TikTok livestream.
Author-email: Isaac Kogan <info@isaackogan.com>
License: Modified AGPL-3.0
Project-URL: Homepage, https://github.com/isaackogan/TikTokLive
Project-URL: Documentation, https://isaackogan.github.io/TikTokLive/
Project-URL: Source, https://github.com/isaackogan/TikTokLive
Project-URL: Issues, https://github.com/isaackogan/TikTokLive/issues
Project-URL: Changelog, https://github.com/isaackogan/TikTokLive/releases
Project-URL: Discord, https://discord.gg/e2XwPNTBBr
Project-URL: Production API, https://www.eulerstream.com/
Keywords: tiktok live api,tiktok api,tiktoklive,euler stream,tiktool,tiktok live,python3,api,unofficial
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: English
Classifier: Framework :: AsyncIO
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: pyee==13.0.1
Requires-Dist: ffmpy>=0.3.0
Requires-Dist: websockets_proxy==0.1.3
Requires-Dist: betterproto2==0.9.1
Requires-Dist: async-timeout>=4.0.3
Requires-Dist: mashumaro>=3.5
Requires-Dist: protobuf3-to-dict>=0.1.5
Requires-Dist: protobuf>=3.19.4
Requires-Dist: TikTokLiveProto==0.2.2
Requires-Dist: EulerApiSdk==0.1.0
Provides-Extra: test
Requires-Dist: pytest>=8.3; extra == "test"
Requires-Dist: pytest-asyncio>=0.24; extra == "test"
Dynamic: license-file

# TikTok LIVE API for Python: Real-Time Livestream Events (Unofficial)

TikTok LIVE API (TikTokLive) is the #1 TikTok LIVE client for **Python**. Connect to any [TikTok LIVE](https://www.tiktok.com/live) stream and receive **real-time chat messages, gifts, likes, follows, shares, viewer counts, battles, and more** using just a creator's `@unique_id`. No login, no credentials or app are required.

TikTokLive is the definitive third-party Python library for reading the TikTok LIVE websocket, building TikTok chat bots, gift trackers, live stream overlays, alerts, and analytics tools.

[![Discord](https://img.shields.io/discord/977648006063091742?logo=discord&label=TikTokLive%20Discord&labelColor=%23171717&color=%231877af)](https://discord.gg/N3KSxzvDX8)
![Live TikTok LIVE API connections](https://api.eulerstream.com/analytics/pips)
![TikTokLive PyPI downloads](https://pepy.tech/badge/tiktoklive)
![TikTokLive GitHub stars](https://img.shields.io/github/stars/isaackogan/TikTokLive?style=flat&color=0274b5)
![TikTokLive GitHub forks](https://img.shields.io/github/forks/isaackogan/TikTokLive?style=flat&color=0274b5)
![TikTokLive open issues](https://img.shields.io/github/issues/isaackogan/TikTokLive)

> **Note:** This is <strong>not</strong> a production-ready API. It is a reverse engineering project. Use the [WebSocket API](https://www.eulerstream.com/websockets) for production by [Euler Stream](https://www.eulerstream.com/).

## What Can You Build With the TikTok LIVE API?

- **TikTok live chat readers** and chat bots that respond to comments in real time
- **Gift trackers and donation alerts** for TikTok LIVE streamers (with streak handling)
- **OBS overlays and stream widgets** driven by live TikTok events
- **TikTok LIVE analytics**: viewer counts, likes, follows, battle (PK) scores
- **Moderation tools** that react to deleted messages and room events
- **Text-to-speech (TTS) readers** and interactive livestream games

## TikTok LIVE API for Production

<table>
<tr>
    <td><br/><img width="180px" style="border-radius: 10px" alt="Euler Stream TikTok LIVE API logo" src="https://raw.githubusercontent.com/isaackogan/TikTokLive/master/.github/SquareLogo.png"><br/><br/></td>
    <td>
        <a href="https://www.eulerstream.com/">
            <strong>Euler Stream</strong> offers a comprehensive TikTok LIVE API, WebSocket Server, CAPTCHA Solutions and much more!
        </a>
    </td>
</tr>
</table>

## Table of Contents

- [Getting Started](#getting-started)
    - [Parameters](#parameters)
    - [Methods](#methods)
    - [Properties](#properties)
    - [WebDefaults](#webdefaults)
- [Events](#events)
- [Documentation](https://isaackogan.github.io/TikTokLive/)
- [Other Languages](#tiktok-live-api-in-other-languages-nodejs-java-c-go-rust)
- [Community](#community)
- [Examples](https://github.com/isaackogan/TikTokLive/tree/master/examples)
- [FAQ](#frequently-asked-questions)
- [Licensing](#license)
- [Star History](#star-history)
- [Contributors](#contributors)

## Community

Join the [TikTokLive discord](https://discord.gg/e2XwPNTBBr) and visit
the [`#py-support`](https://discord.gg/uja6SajDxd)
channel for questions, contributions and ideas.

## Getting Started

Install the TikTok LIVE API client for Python via pip from the [PyPi](https://pypi.org/project/TikTokLive/) repository:

```shell script
pip install TikTokLive
```

Then create your first real-time TikTok LIVE chat connection:

```python
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, including a TikTok live chat reader, gift tracker, and live status checker, see the [examples folder](https://github.com/isaackogan/TikTokLive/tree/master/examples) provided in the source tree.

## TikTok LIVE API in Other Languages: Node.js, Java, C#, Go, Rust

The TikTokLive TikTok LIVE API is available in several alternate programming languages:

- **Node.JS / JavaScript / TypeScript:** [TikTok-Live-Connector](https://github.com/zerodytrash/TikTok-Live-Connector)
- **Java:** [TikTok-Live-Java](https://github.com/jwdeveloper/TikTok-Live-Java)
- **C# / Unity:** [TikTokLiveSharp](https://github.com/frankvHoof93/TikTokLiveSharp)
- **Go:** [gotiktoklive](https://github.com/steampoweredtaco/gotiktoklive)
- **Rust:** [TikTokLiveRust](https://github.com/jwdeveloper/TikTokLiveRust)

## 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`](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`](https://github.com/encode/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`](https://github.com/python-websockets/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 methods worth mentioning:

| 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(Type[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](https://github.com/isaackogan/TikTokLive/blob/master/examples/web_defaults.py) example.

| Parameter                   | Type   | Description                                                                                                                                                                   |
|-----------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| tiktok_sign_api_key         | `str`  | A [Euler Stream](https://www.eulerstream.com/) API key used to increase rate limits.                                                                                          |
| tiktok_app_url              | `str`  | The TikTok app URL (`https://www.tiktok.com`) used to scrape the room.                                                                                                        |
| tiktok_sign_url             | `str`  | The [signature server](https://www.eulerstream.com/) used to generate tokens to connect to TikTokLive. By default, this is Euler Stream, but you can swap your own with ease. |
| tiktok_webcast_url          | `str`  | The TikTok livestream URL (`https://webcast.tiktok.com`) where livestreams can be accessed from.                                                                              |
| web_client_params           | `dict` | The URL parameters added on to TikTok requests from the HTTP client.                                                                                                          |
| web_client_headers          | `dict` | The headers added on to TikTok requests from the HTTP client.                                                                                                                 |
| web_client_cookies          | `dict` | Custom cookies to initialize the http client with.                                                                                                                            |
| ws_client_params            | `dict` | The URL parameters added to the URI when connecting to TikTok's Webcast WebSocket server.                                                                                     |
| ws_client_params_append_str | `dict` | Extra string data to append to the TikTokLive WebSocket connection URI.                                                                                                       |
| ws_client_headers           | `dict` | Extra headers to append to the TikTokLive WebSocket client.                                                                                                                   |

## Events

The TikTok LIVE API emits real-time events for everything happening in a livestream: comments, gifts, likes, joins, follows, shares, battles (PK), polls, captions, subscriptions, and moderation actions. Events can be listened to using a decorator or non-decorator method call. The following examples illustrate how you can listen to an event:

```python
@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`](https://github.com/isaackogan/TikTokLive/blob/master/TikTokLive/events/custom_events.py)
events and [`ProtoEvent`](https://github.com/isaackogan/TikTokLive/blob/master/TikTokLive/events/proto_events.py) 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
- `SuperFanEvent` - Triggered when a viewer becomes a super fan of the streamer
- `SuperFanJoinEvent` - Triggered when an existing super fan joins the live (distinct from `SuperFanEvent`)
- `SuperFanBoxEvent` - Triggered when a super-fan envelope (gift box) is delivered
- `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

These events are auto-generated from the
[TikTokLiveProto](https://pypi.org/project/TikTokLiveProto/) v3 schema. Only
events whose proto messages are present in v3 are emitted; if you don't see
one you used to rely on, it's because TikTok removed it from the schema.

If you know what an event does that's missing a description below,
[make a pull request](https://github.com/isaackogan/TikTokLive/pulls) and add it.

<ul>
<li><code>BarrageEvent</code> - A "VIP" viewer (based on gifting level) joins the chat room</li>
<li><code>CaptionEvent</code> - Auto-caption update from the host's audio</li>
<li><code>CommentEvent</code> - A viewer sent a chat comment</li>
<li><code>ControlEvent</code> - Stream action (e.g. start, end, pause, unpause)</li>
<li><code>EmoteChatEvent</code> - A custom emote was sent in chat</li>
<li><code>EnvelopeEvent</code> - A treasure chest / envelope was sent</li>
<li><code>GiftEvent</code> - A gift was sent (see <a href="#giftevent">Gift handling</a> below)</li>
<li><code>GoalUpdateEvent</code> - Subscriber/follow goal updated</li>
<li><code>HourlyRankRewardEvent</code> - Hourly rank reward delivered</li>
<li><code>ImDeleteEvent</code> - A viewer's messages were deleted by a moderator</li>
<li><code>InRoomBannerEvent</code> - In-room banner notice</li>
<li><code>JoinEvent</code> - A viewer joined the livestream</li>
<li><code>LikeEvent</code> - The stream received likes</li>
<li><code>LinkEvent</code> - Generic link-mic event</li>
<li><code>LinkLayerEvent</code> - Link-mic layer/visibility change</li>
<li><code>LinkMicArmiesEvent</code> - A battle user received points</li>
<li><code>LinkMicBattleEvent</code> - A battle was started</li>
<li><code>LinkMicBattlePunishFinishEvent</code> - A battle's punishment phase ended</li>
<li><code>LinkMicFanTicketMethodEvent</code></li>
<li><code>LinkMicMethodEvent</code></li>
<li><code>LinkmicBattleTaskEvent</code></li>
<li><code>LiveIntroEvent</code> - Live-intro message appears</li>
<li><code>MessageDetectEvent</code></li>
<li><code>OecLiveShoppingEvent</code> - Live-shopping signal</li>
<li><code>PollEvent</code> - The creator launched / updated a poll</li>
<li><code>QuestionNewEvent</code> - Someone asked a new question via the question feature</li>
<li><code>RankTextEvent</code> - Gift count made a viewer enter the top three</li>
<li><code>RankUpdateEvent</code></li>
<li><code>RoomEvent</code> - Broadcast message to all room users (e.g. "Welcome to TikTok LIVE!")</li>
<li><code>RoomPinEvent</code> - A message was pinned</li>
<li><code>RoomUserSeqEvent</code> - Current viewer count information</li>
<li><code>SocialEvent</code> - A viewer shared or followed the host (also surfaced as <code>FollowEvent</code> / <code>ShareEvent</code> custom events)</li>
<li><code>SystemEvent</code></li>
<li><code>UnauthorizedMemberEvent</code></li>
</ul>

#### New in 7.X.X

<ul>
<li><code>AccessControlEvent</code> - Access-control update for the room (e.g. CAPTCHA challenge issued to a viewer)</li>
<li><code>AccessRecallEvent</code> - Access restriction lifted / recalled for a viewer</li>
<li><code>BoostCardEvent</code> - Boost cards delivered to the room</li>
<li><code>BottomEvent</code> - Bottom-of-screen notice (often a punishment or violation banner)</li>
<li><code>CapsuleEvent</code> - In-room capsule / promotional pill notice</li>
<li><code>GameRankNotifyEvent</code> - Game-rank notification</li>
<li><code>GiftBroadcastEvent</code> - Big gift broadcast notice across rooms</li>
<li><code>GiftDynamicRestrictionEvent</code> - Dynamic gift restriction update</li>
<li><code>GiftPanelUpdateEvent</code> - Gift panel content update</li>
<li><code>GiftPromptEvent</code> - Anti-addiction / spending-limit prompt before gifting</li>
<li><code>GuideEvent</code> - In-room guide / tooltip prompt</li>
<li><code>LinkMicLayoutStateEvent</code> - Link-mic layout state update</li>
<li><code>LinkStateEvent</code> - Link-mic channel state update</li>
<li><code>LiveGameIntroEvent</code> - Live-game intro message</li>
<li><code>MarqueeAnnouncementEvent</code> - Marquee announcement scrolling across the room</li>
<li><code>NoticeEvent</code> - Generic notice / system tip in the room</li>
<li><code>PartnershipDropsUpdateEvent</code> - Partnership drops campaign update</li>
<li><code>PartnershipGameOfflineEvent</code> - Partnership game taken offline</li>
<li><code>PartnershipPunishEvent</code> - Partnership punishment notice</li>
<li><code>PerceptionEvent</code> - Perception dialog (warning / violation surfaced to a viewer)</li>
<li><code>RoomNotifyEvent</code> - Room-wide notification banner</li>
<li><code>RoomVerifyEvent</code> - Room verification action (e.g. forced verify / close)</li>
<li><code>SpeakerEvent</code> - Active speaker update (link-mic audio)</li>
<li><code>SubNotifyEvent</code> - Subscription notification (subscribe / renew / gift sub)</li>
<li><code>SubPinEventEvent</code> - Subscription pin card action</li>
<li><code>ToastEvent</code> - Transient toast notification</li>
<li><code>ViewerPicksUpdateEvent</code> - Viewer-picks (audience-driven prompt) update</li>
</ul>

### `GiftEvent`

Fires every time a gift is sent. Extra static metadata for every gift type
in the room can be fetched once on connect by passing
`fetch_gift_info=True` to `client.run()` / `client.start()`; the result is
cached on `client.gift_info`.

> **Streaks**: streakable gifts trigger multiple `GiftEvent`s as the viewer
> ramps up the streak, with `event.repeat_count` incrementing each time.
> The final gift in a streak carries `event.repeat_end == 1`. Use the
> `event.streaking` helper to filter intermediate events out and only act
> on the final one.

```python
@client.on(GiftEvent)
async def on_gift(event: GiftEvent):
    gift = event.gift
    if gift is None:
        return

    # Streakable gift & streak is over
    if not event.streaking and gift.type == 1:  # ``type == 1`` is streakable
        print(f"{event.user.unique_id} sent {event.repeat_count}x \"{gift.name}\"")

    # Non-streakable gift
    elif gift.type != 1:
        print(f"{event.user.unique_id} sent \"{gift.name}\"")
```

In v3 the canonical `Gift` field names are `name`, `type`, and `image`. The
v2-era prefixed names (`gift_name`, `gift_type`, `gift_image`) remain
available as read-only aliases on `ExtendedGift` for backwards compatibility.
Wrap a `Gift` in `ExtendedGift(...)` if you want the `.streakable` helper.

## 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](https://github.com/isaackogan/TikTokLive/blob/master/examples/check_live.py) of how to do this in the [examples](https://github.com/isaackogan/TikTokLive/tree/master/examples) folder.

## Frequently Asked Questions

### Is there an official TikTok LIVE API?

TikTok does not offer a public official API for reading livestream events. TikTokLive is an unofficial, open-source TikTok LIVE API client that reads the same Webcast websocket data available to any viewer of a stream.

### How do I get TikTok LIVE chat messages in Python?

Install with `pip install TikTokLive`, create a `TikTokLiveClient` with the streamer's `@unique_id`, and listen for `CommentEvent`. See the [Getting Started](#getting-started) example above; it takes about ten lines of code.

### Is the TikTok LIVE API free?

Yes. TikTokLive is free and open source under a modified AGPL license. Signing is handled by a third-party signature server ([Euler Stream](https://www.eulerstream.com/)) with free community rate limits; an API key raises those limits.

### Can I track TikTok gifts, likes, and viewer counts in real time?

Yes. `GiftEvent` (with streak handling), `LikeEvent`, and `RoomUserSeqEvent` deliver gifts, likes, and live viewer counts as they happen, alongside 50+ other event types including battles, polls, captions, and subscriptions.

### Does this work with Node.js, Java, C#, Go, or Rust?

Yes, sister libraries exist for each. See [Other Languages](#tiktok-live-api-in-other-languages-nodejs-java-c-go-rust).

## Star History

<p align="center">
    <img alt="TikTokLive GitHub star history chart: growth of the TikTok LIVE API for Python" src="https://star-history.dera.page/svg?repos=isaackogan/TikTokLive&type=Date&theme=dark" onerror="this.src='https://star-history.dera.page/svg?repos=isaackogan/TikTokLive&type=Date'" />
</p>

## License

This project is licensed under a modified AGPL license - see the [LICENSE](LICENSE) file for details.

## Contributors

* **Isaac Kogan** - *Creator, Primary Maintainer, and Reverse-Engineering* - [isaackogan](https://github.com/isaackogan)
* **Zerody** - *Creator of the NodeJS library, introduced me to scraping TikTok LIVE* - [Zerody](https://github.com/zerodytrash/)

See also the full list of secondary [contributors](https://github.com/isaackogan/TikTokLive/contributors) who have participated in
this project.
