The idea
Most interactive stream systems rely on paid third-party APIs that abstract everything away — you pay per event, you get a black box, and you learn almost nothing. I wanted the opposite: full control, zero cost, and a project that would genuinely teach me how real-time systems work under the hood.
So I set myself a challenge: listen to a live TikTok stream and turn every interaction into a game event — using only Python and raw WebSockets.
Understanding the protocol
TikTok live streams communicate over a WebSocket connection. The tricky part is that the data isn't plain JSON — it's a binary envelope that wraps protobuf-encoded payloads. To read it, I had to:
- Establish the WebSocket handshake with the correct headers and room ID.
- Parse the binary packet structure — frame length, payload type, and body.
- Decode protobuf messages to extract events like likes, gifts, and follows.
The architecture
The system is split into three clean layers, so any part can be swapped without touching the rest:
listener (captures raw events)
│
▼
event bus (normalizes → clean Python objects)
│
▼
WebSocket server (broadcasts JSON to any client)Games subscribe to the WebSocket server and react to events. The listener never cares what's listening — it just feeds the bus. That separation turned a hacky reverse-engineering project into something genuinely reusable.
The hard parts
1. Keeping the connection alive
TikTok sends periodic heartbeat requests. If you don't answer correctly, you're dropped within seconds. I had to replicate the exact ping/pong cadence and payload format.
2. Parsing binary packets
A single frame can contain multiple nested messages. Getting the byte offsets right — and handling endianness — took the longest. This is where I learned to read hex dumps like a language.
3. Graceful reconnects
Streams end, networks hiccup, rooms rotate. The listener had to detect a drop, back off, and reconnect without losing the event stream. A simple state machine solved it.
// lesson
Reverse engineering is just debugging with extra steps. Every protocol can be understood if you're willing to read bytes, form hypotheses, and test them one at a time.
Where it landed
The final system does exactly what I set out to do — and more than I expected:
- Likes spawn monsters in the game.
- Gifts trigger boss waves.
- Follows & shares broadcast live announcements.
Everything streams over WebSocket to any connected client in real time, with zero API costs. More importantly, the project gave me a working understanding of WebSockets, protobuf, binary parsing, and state machines — fundamentals that show up in every real-time system I'll ever build.
What I'd do differently
I'd add proper logging and metrics from day one, and containerize the listener so it can run anywhere. I'd also publish it as a library — the event bus pattern is genuinely reusable. But honestly? I'm glad I built it the hard way first.