TikTokLive Python API for Real-Time Livestream Events

What TikTokLive Reads from a TikTok Broadcast

TikTokLive targets developers who need to consume a TikTok LIVE room without asking viewers or creators to install an application. Its central input is a broadcaster's `unique_id`, which the README identifies as the username found in the TikTok profile URL. For example, the profile `https://www.tiktok.com/@isaackogz` has the `unique_id` `isaackogz`. The client is intended for chat bots, comment readers, gift and donation alerts, OBS overlays, stream widgets, moderation helpers, analytics, text-to-speech readers, and interactive livestream games.

The documented event surface includes comments, gifts, likes, follows, shares, viewer counts, battles, and other room events. The repository also lists examples for gifts, images, live status, proxying, recording, logged-in operation, and a web UI. That scope is broader than a simple chat API, although the README excerpt does not define the full event model or guarantee that every event is available for every room.

The package is explicitly unofficial. No login, credentials, or application is required for the basic connection shown in the README. That convenience matters for experiments and small tools, but it also means the library depends on a reverse-engineered service interface rather than a supported public API contract.

HTTP Requests and WebSocket Events Inside TikTokLive

The documented architecture has two network paths. Before receiving live events, the library uses an internal `httpx` HTTP client to obtain or prepare the TikTok LIVE connection. It then uses the `websockets` library to connect to TikTok and receive room events. The README exposes separate controls for these paths: `web_proxy`, `ws_proxy`, `web_kwargs`, and `ws_kwargs`.

`web_proxy` accepts an `httpx.Proxy` for HTTP requests. The documentation warns that proxy users may face reduced connection limits during periods of high load. `ws_proxy` also accepts an `httpx.Proxy`, but the README says that this WebSocket proxy is never subject to those reduced limits. The dictionaries `web_kwargs` and `ws_kwargs` are forwarded to the underlying `httpx` and `websockets` clients respectively. This gives callers a documented extension point when they need lower-level client options.

The public client uses event listeners. The quickstart registers a decorator for `ConnectEvent`, then adds a listener manually for `CommentEvent`. `client.run()` blocks the main thread, while `await client.start()` is documented as the non-blocking form. This is an asynchronous event model with a synchronous convenience entry point. It fits scripts that should keep receiving events until stopped and applications that need to integrate the client with other asyncio tasks.

The repository's `pyproject.toml` names `TikTokLiveProto`, `betterproto2`, `protobuf3-to-dict`, `pyee`, `httpx`, `websockets_proxy`, `async-timeout`, `ffmpy`, `mashumaro`, and `EulerApiSdk` as dependencies. Those package names point to protocol decoding and an asynchronous client design, although the README does not expose the complete internal parser flow.

Installing TikTokLive and Connecting to the First Stream

The README directs users to install the client from PyPI. This is the documented installation command:

```shell script pip install TikTokLive

After installation, create a client with the broadcaster's unique ID. The following example prints connection information through `ConnectEvent` and then prints incoming comments. The listener receives each `CommentEvent` and prints the user's nickname followed by the comment text.

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

client: TikTokLiveClient = TikTokLiveClient(unique_id="@isaackogz")

@client.on(ConnectEvent) async def on_connect(event: ConnectEvent): print(f"Connected to @{event.unique_id} (Room ID: {client.room_id}")

async def on_comment(event: CommentEvent) -> None: print(f"{event.user.nickname} -> {event.comment}")

client.add_listener(CommentEvent, on_comment)

if __name__ == '__main__': client.run() ```

The example uses `client.run()` to block the main thread. A program that already manages an asyncio event loop can use the documented `await client.start()` form instead. The repository's `examples/README.md` and `examples/comments.py` are the stated places for additional quickstarts, including a chat reader. The README does not document a credential setup step for the basic client.

Listener Registration and Proxy Configuration Choices

The client supports two listener styles. The decorator form is convenient for event classes with dedicated handlers, while `client.add_listener()` registers a callback by event type. The quickstart uses both styles, showing that the two approaches can coexist in one client. This is useful when a project needs a small connection-status message alongside a larger comment or gift-processing path.

For deployments that cannot connect directly, the documented parameters separate HTTP and WebSocket behavior. `web_proxy` is passed as an `httpx.Proxy` for the HTTP portion of the connection, and `ws_proxy` handles the WebSocket portion. The distinction matters because the README attaches a warning to HTTP proxying under load while saying the WebSocket proxy is not subject to that particular limit. `web_kwargs` and `ws_kwargs` are transparent pass-through dictionaries, so their accepted contents are determined by `httpx` and `websockets`, not by a TikTokLive-specific configuration schema.

The examples directory also includes `proxying.py`, `recording.py`, `logged_in.py`, and a `web-ui` directory. Those filenames indicate optional integrations, but the README does not explain their configuration, recording output format, login behavior, or web UI startup command. An engineer would need to inspect those files before treating an example as a documented deployment pattern.

Version, Dependency, and Licensing Boundaries

The repository is not archived, and the last push was on 2026-09-10. That is a recent maintenance signal in repository terms, but it does not remove the project's central limitation: the README calls it a reverse engineering project and says it is not a production-ready API. Recent releases are listed as `v6.2.0` on 2024-10-21, `v6.1.6` on 2024-09-19, and `v6.1.5` on 2024-09-19. Separately, `pyproject.toml` declares version `7.0.1`. That version discrepancy should be checked against the package actually installed from PyPI.

The package metadata says `requires-python = ">=3.10"`, while the README's installation command does not pin Python or library versions. The dependency list does pin several packages, including `pyee==13.0.1`, `websockets_proxy==0.1.3`, `betterproto2==0.9.1`, and `TikTokLiveProto==0.2.2`. An upgrade review should compare both the project version and the protocol-related dependency versions rather than assuming that every dependency can change independently.

The license is another adoption boundary. The repository identifies the project as AGPL-3.0, while `pyproject.toml` describes it as a modified AGPL-3.0 license with added Sections 18-21, a library-integration exception, a SaaS or relay carve-out, and excepted parties. The metadata avoids a plain SPDX expression because `pyproject.toml` says no SPDX expression describes the modified terms. Engineers must review the repository's `LICENSE` file before incorporating the package into a hosted or redistributed service.

Production APIs and Language-Specific Alternatives

The README itself names Euler Stream's WebSocket API as the production alternative. Euler Stream is described as offering a broad TikTok LIVE API, a WebSocket server, CAPTCHA solutions, and related services. The practical difference is architectural: TikTokLive is a Python package that talks directly to the reverse-engineered interface, while Euler Stream is presented through its WebSocket API and server offering. A team that needs a managed production boundary should compare those operational assumptions rather than treating the two as interchangeable.

The repository also links separate implementations for Node.js and JavaScript or TypeScript, Java, C#, Go, and Rust. For example, the Node.js and TypeScript alternative is `TikTok-Live-Connector`, and the Java alternative is `TikTok-Live-Java`. These links establish different language ecosystems and implementations, but the README does not compare their event coverage, protocol versions, maintenance, or deployment requirements.

TikTokLive is the wrong tool when a project requires a formally supported API contract, contractual service availability, documented backward compatibility, or a production SLA. It also does not fit a Python 3.9 environment because `pyproject.toml` requires Python 3.10 or newer. The documented connection assumes a live TikTok room and a creator unique ID, so it does not address historical event retrieval, analytics backfill, or room discovery. The README also does not document rollback or compatibility procedures for a breaking TikTok protocol change.

Editorial conclusion

Adopt TikTokLive for local experiments, chat readers, gift trackers, overlays, and prototypes where Python and direct WebSocket events are priorities. Do not adopt it as the sole production service, because the README describes it as reverse engineering software and recommends Euler Stream's WebSocket API for production. Verify the installed package version, Python compatibility, expected event behavior, and the modified AGPL-3.0 license terms first.

Frequently asked questions

Official sources

1. isaackogan/TikTokLive on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases