Skip to content
Projects

thekivashyn/tiktok-live-rust has 7 GitHub stars and 0 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 20:54 UTC. Last push 2026-11-11.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Unofficial TikTok LIVE event engine in Rust. Direct guest connections, typed events, bounded queues, automatic reconnects, and an NDJSON CLI.

Developer Tools

README.md

Original

tiktok-live-rust

tiktok-live-rust: Rust core, LIVE events, your app

CI License: MIT Rust 2024

TikTok LIVE → typed Rust events → JSON for your app, overlay or agent.

A standalone Rust library and CLI that receives public LIVE events, supervises the connection and makes delivery uncertainty visible. Embed the library in Rust, or consume the CLI from any language that can launch a process.

Built by Tri Nguyen · engine 0.9.0 · MIT

Try the offline demo · Connect LIVE · Integrate · Architecture · Agent guide

Unofficial TikTok client. The runtime obtains an anonymous guest identity and needs no account-session input, API key, signing service, Node.js or browser. TikTok can change or refuse this route; access and event completeness are not guaranteed.

Why this engine exists

A live event connection is only one part of an integration. A usable engine also needs to recover from interruptions, stay within finite resource limits and tell the consumer when its view of the stream may be incomplete.

That is the focus here: a supervised Rust connection, bounded state and an explicit event contract. UI, storage, game rules and agent actions belong to the application built around it.

Design choice What your application gets
Direct guest transport A local runtime without an external signing-service dependency
Typed Rust events + NDJSON Native integration or a process boundary for Python and other languages
Backoff, cooldowns and readiness watchdogs Recovery from transient failures with observable connection state
Bounded decoder, queue and per-room state Explicit resource limits and an error when a consumer cannot keep up
Connection epochs and nullable gift deltas A way to preserve uncertainty instead of inventing complete delivery/totals
Offline fixtures and comparative oracles Reproducible checks independent of whether a particular creator is LIVE

Try it without a LIVE room

Install stable Rust with Cargo, then:

git clone https://github.com/thekivashyn/tiktok-live-rust.git
cd tiktok-live-rust
cargo run --locked --example offline_demo

The example feeds synthetic Protobuf bytes through the real bounded batch decoder and event processor, then writes six NDJSON events. It opens no socket and uses no real profiles or chats. Cargo may download dependencies during a first build.

Output What it demonstrates
1 chat from demo_creator A large sender ID stays a string; a duplicate input emits no second chat
2 gift updates Cumulative counts 1 → 3 become quantity deltas 1 and 2
1 like update Per-update and cumulative counts stay distinct
1 viewer snapshot Audience count uses the same event envelope
1 stream-end event An explicit end event is represented in the output

This demo exercises wire decoding and normalization. It does not simulate the network supervisor. See offline_demo.rs.

Build prerequisites

Use a current stable Rust toolchain; no minimum Rust version is claimed yet. Windows needs the linker tools for the chosen Rust toolchain. Linux native TLS builds need OpenSSL development headers and pkg-config; on Ubuntu/Debian:

sudo apt-get install pkg-config libssl-dev

The CI workflow checks Windows, Linux and macOS. Node.js is optional and used only by the comparative benchmark project. Python examples require Python 3.11+.

Connect a LIVE room

Replace USERNAME with a public channel that is currently LIVE:

cargo build --release --locked
cargo run --release --locked -- --user USERNAME --seconds 60 --events --status --lifecycle
  • stdout: one event JSON object per line.
  • stderr: tagged lifecycle notifications, health snapshots and the final aggregate report.
  • Ctrl+C: cancel the session. The default duration is 60 seconds.

For an aggregate report only, omit --events --status. To target a known room, use --room ROOM_ID instead of --user. An offline channel stops explicitly.

Need a longer bounded session? Add --seconds 14400 --retry-until-deadline for a four-hour budget across transient outages. Backoff and Retry-After still apply; terminal failures stop. See the complete CLI contract.

Build on it

You are building… Start here
A Rust desktop/backend application Rust consumer: bounded events, reconnect lifecycle, health and cancellation
A Python integration Python consumer: concurrent pipe reads, host deadline and child cleanup
An agent that observes LIVE activity Agent integration guide: machine output, stop conditions and trust boundaries
An overlay, game or dashboard Handle normalized events, then apply your own rendering, rules and storage

Python: a working process integration

Build the CLI and demo, then try the same consumer offline or against a LIVE room:

cargo build --release --locked --bins --example offline_demo
python examples/consume.py --demo
python examples/consume.py --user USERNAME --seconds 60

The example uses only Python's standard library. It drains both output pipes, keeps aggregate counts, bounds input buffers and terminates its owned child on failure or a host deadline. Extend the event handler for your application; raw chat and profile data are not printed by default.

Rust: embed the engine

A reproducible Git dependency for the v0.9.0 engine:

[dependencies]
tiktok-live-rust = { git = "https://github.com/thekivashyn/tiktok-live-rust", tag = "v0.9.0" }

Use engine::run, engine::run_with_status or engine::run_observed with DirectSource, Config, Target, a CancellationToken and a bounded event channel. The complete consume.rs example runs reception, consumption and health observation concurrently:

cargo run --locked --example consume -- USERNAME

The crate import is tiktok_live_rust. The package is not on crates.io (publish = false); pin a release tag or commit and update it intentionally. There is no C ABI, language-specific SDK or MCP server bundled with this engine.

Reconnects your consumer can handle

v0.9.0: keep the same event subscription through transient reconnects, and observe connecting → connected → ready, interruptions, retry waits and terminal stops independently of application events. Rust uses run_observed with lifecycle::channel(); CLI users add --lifecycle for tagged stderr records.

The lifecycle ring retains 64 notifications and explicitly reports a slow reader's lag. A connected socket is not yet ready, and reconnecting does not recover missed upstream events. The updated Rust/Python examples flag incomplete views rather than silently resetting totals. Delivery, ordering and recovery guide.

Thanks to @Rhytera on X for the feedback behind this improvement (issue #1).

Events that your app can understand

Supported kinds: chat · gift · like · follow · share · social · join · viewers · stream_end.

A synthetic chat envelope, with optional profile metadata omitted for readability:

{"sequence":1,"connection_epoch":1,"kind":"chat","room_id":"42","message_id":"101","user_id":"9007199254740993","data":{"text":"Hello from the offline demo!"}}
Field Meaning
kind + data Normalized event type and typed payload
user Optional selected sender profile; no separate profile request
like_details Optional detailed like metadata from the same received payload
sequence Processing order within this run
connection_epoch Connection boundary; a change may mean source events are missing
metadata_incomplete Optional metadata failed validation; the core event survived

Large IDs are strings. Gift quantity_delta: null means unknown, never a known total. Treat text and URLs as untrusted data, including when passing events to an agent. See USAGE.md for fields, units, output counters and limits.

Under the hood

Public username / room ID
           |
TikTok lookup + anonymous guest bootstrap
           |
Verified TLS WebSocket / room entry / heartbeat / ACK
           |
Bounded gzip + Protobuf decoder
           |
Per-room normalization / dedupe / gift-combo state
           |
Bounded event channel ------> Rust consumer / NDJSON stdout

Connection supervisor -----> Coalesced health snapshots / final report

The engineering details are in ARCHITECTURE.md: shared batch buffers, small-frame scheduling, joined decoder cleanup, a watchdog race and the tradeoff between bounded gift history and exact quantity accounting.

Evidence, with its scope attached

For v0.9.0, CI run 43033800758 passed 100 Rust tests and 11 Python tests per OS on Windows, Linux and macOS (Apple Silicon), plus source-manifest/document links, Clippy, formatting, release builds and CLI/demo integration. These checks do not contact TikTok.

Recorded experiment Result What it establishes
0.8.0 historical LIVE observation 10 minutes, 990 events, zero decode errors, 3 forced recoveries Behavior of those received samples on Windows
0.7.1 matched loopback comparison 120,218 events/s Rust vs 75,683 for Connector 2.5.0 + adapter Median of three pairs for the specified synthetic local receive path
Same 0.7.1 comparison Peak receiver working set: 6.76 MiB vs 135.70 MiB Process memory for that workload, including the respective consumer/adapter

The benchmark numbers belong to 0.7.1, not a fresh 0.9.0 performance run. Original 0.7.1 binaries/raw reports are not included in this checkout; rerunning the harness measures the current source, rather than recreating those artifacts. The adapter supplies equivalent application policies; these are not claims about upstream built-ins. They do not predict TikTok latency or a universal speed/RAM ratio. Methodology and reproduction · Versioned evidence · Follow-up audit.

Boundaries to design around

  • Guest access is unofficial and can change or be refused.
  • Reconnects do not replay events TikTok never delivered during an outage.
  • Dedupe (8,192 IDs) and gift history (4,096 keys) are finite; state is lost on restart.
  • Profiles expose selected fields, not the full upstream User schema. Avatar URLs expire.
  • TikTok may aggregate or omit likes; not every viewer action is observable.
  • One run targets one room, with a maximum 24-hour duration budget. Finite tests do not prove 24/7 uptime, many-room capacity or exactly-once accounting.
  • Posting comments, sending gifts, account management, storage, UI, OBS, battle and commerce integration are outside the current engine scope.

Contribute a concrete improvement

Useful next work: real-world Linux/macOS LIVE observations, small integration examples, targeted synthetic protocol regressions and longer reliability studies. Bring a reproducible case and preserve unknown values instead of guessing them.

Contribution guide · Development workflow · Report a bug · Security reporting

License and credits

Copyright © 2026 Tri Nguyen. MIT License. Protocol/transport provenance and the retained upstream MIT notice are in THIRD_PARTY_NOTICES.md. Optional benchmark dependencies retain their own licenses and are not production runtime dependencies.

Independent project; not affiliated with or endorsed by TikTok.