piratetok-live-py

Connect to any TikTok Live stream and receive real-time events in Python. No signing server, no API keys, no authentication required.

import asyncio
from piratetok_live import TikTokLiveClient, EventType

async def main():
    # Create client — no API key, no signing server, just a username
    client = TikTokLiveClient("username_here")

    # Register handlers with decorators — events carry decoded protobuf data
    @client.on(EventType.chat)
    def on_chat(evt):
        nick = evt.data.get("user", {}).get("nickname", "?")
        print(f"[chat] {nick}: {evt.data.get('content')}")

    @client.on(EventType.gift)
    def on_gift(evt):
        nick = evt.data.get("user", {}).get("nickname", "?")
        gift = evt.data.get("gift", {})
        print(f"[gift] {nick} sent {gift.get('name')} x{evt.data.get('repeatCount')} ({gift.get('diamondCount', 0)} diamonds)")

    @client.on(EventType.like)
    def on_like(evt):
        nick = evt.data.get("user", {}).get("nickname", "?")
        print(f"[like] {nick} ({evt.data.get('total')} total)")

    # Runs the whole session — auth, room resolution, WSS, heartbeat, reconnection.
    # Returns after client.disconnect() or once max_retries consecutive attempts failed.
    # Need to do other work meanwhile? asyncio.create_task(client.connect())
    await client.connect()

asyncio.run(main())

Install

pip install piratetok-live-py

Requires Python >= 3.11.

Other languages

Features

• Zero signing dependency — no API keys, no signing server, no external auth
• 64 decoded event types — hand-written betterproto dataclasses, no codegen
• Auto-reconnection — stale detection, exponential backoff, ttwid retry + reuse, rotation on DEVICE_BLOCKED, retry budget resets after a healthy (30 s+) session
• Proxy support — .proxy(url) builder, HTTP/HTTPS/SOCKS5 for both HTTP and WSS
• Enriched User data — badges, gifter level, moderator status, follow info, fan club
• Sub-routed convenience events — follow, share, join, live_ended
• Gift helpers — is_combo, is_streak_over, diamond_total on every gift event
• Runtime deps — betterproto, websockets, curl_cffi, python-socks

Configuration

client = (TikTokLiveClient("username_here")
    .cdn_eu()
    .timeout(15)
    .max_retries(10)
    .stale_timeout(90)
    .heartbeat_interval(10)
    .proxy("socks5://127.0.0.1:1080")
    .user_agent("Mozilla/5.0 ...")
    .cookies("sessionid=abc; sid_tt=abc")
    .language("pt")
    .region("BR")
    .compress(False))

Room info (optional, separate call)

from piratetok_live import check_online, fetch_room_info

result = check_online("username_here")
info = fetch_room_info(result.room_id)

# 18+ rooms
info = fetch_room_info(result.room_id, cookies="sessionid=abc; sid_tt=abc")

Viewers

The top-viewers box (usually top 3) rides the WSS feed — no cookies:

from piratetok_live import top_viewers

@client.on(EventType.room_user_seq)
def on_seq(evt):
    for c in top_viewers(evt.data):
        print(c["rank"], c["user"].get("nickname"), c["score"])

The full roster (the web viewer panel) is a separate HTTP call. TikTok requires session cookies for this one call — without them it raises SessionRequiredError:

from piratetok_live import check_online, fetch_room_audience

room = check_online("username_here")
audience = fetch_room_audience(room.room_id, room.anchor_id, cookies="sessionid=abc; sid_tt=abc")
# audience.total, audience.anonymous, audience.viewers[i].username / nickname / rank / ...

Pass anchor_id=None to resolve it from room info (one extra request).

Examples

python examples/basic_chat.py <username>       # connect + print chat events
python examples/online_check.py <username>     # check if user is live
python examples/stream_info.py <username>      # fetch room metadata + stream URLs
python examples/gift_tracker.py <username>     # track gifts with diamond totals
python examples/gift_streak.py <username>      # track gifts with GiftStreakTracker deltas
python examples/profile_lookup.py [username]   # fetch profile via SIGI scrape with caching
python examples/audience.py <username> <cookies>  # full viewer roster (needs session cookies)

Tests

pip install -e ".[test]"
pytest -m "not integration"          # offline: replay, ttwid retry, reconnect loop, WSS, proxy, parsing

Replay tests read testdata/ (gitignored, captures/*.bin + manifests/*.json) or a live-testdata checkout:

git clone https://github.com/PirateTok/live-testdata ../live-testdata
PIRATETOK_TESTDATA=../live-testdata pytest tests/test_replay.py

Missing testdata fails the replay tests — they never pass vacuously.

License

0BSD