tiktok-live-api 1.0.0__tar.gz

tiktok_live_api-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+*.whl
+.env
+.venv/
+venv/
+env/

tiktok_live_api-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TikTool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tiktok_live_api-1.0.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: tiktok-live-api
+Version: 1.0.0
+Summary: TikTok LIVE API Client — Real-time chat, gifts, viewers, battles, and live captions from any TikTok livestream. Production-ready managed API.
+Project-URL: Homepage, https://tik.tools
+Project-URL: Documentation, https://tik.tools/docs
+Project-URL: Repository, https://github.com/tiktool/live-python
+Project-URL: Issues, https://github.com/tiktool/live-python/issues
+Project-URL: Changelog, https://github.com/tiktool/live-python/releases
+Author-email: TikTool <support@tik.tools>
+License: MIT
+License-File: LICENSE
+Keywords: captions,chat,euler-stream,gifts,live-chat,live-streaming,real-time,speech-to-text,tiktok,tiktok-api,tiktok-bot,tiktok-data,tiktok-live,tiktok-live-api,tiktok-live-connector,tiktok-live-python,tiktok-live-sdk,tiktok-tools,transcription,translation,webcast,websocket
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: websockets>=11.0
+Description-Content-Type: text/markdown
+
+# tiktok-live-api
+
+**TikTok LIVE API Client for Python** — Connect to any TikTok LIVE stream and receive real-time chat messages, gifts, likes, follows, viewer counts, battles, and more.
+
+[![PyPI](https://img.shields.io/pypi/v/tiktok-live-api)](https://pypi.org/project/tiktok-live-api/)
+[![Python](https://img.shields.io/pypi/pyversions/tiktok-live-api)](https://pypi.org/project/tiktok-live-api/)
+[![License](https://img.shields.io/pypi/l/tiktok-live-api)](https://github.com/tiktool/live-python/blob/main/LICENSE)
+
+> **Production-ready alternative to the `TikTokLive` library.** Unlike `TikTokLive` which reverse-engineers TikTok's internal protocol and breaks frequently, `tiktok-live-api` connects to TikTool Live's managed API service — 99.9% uptime, zero maintenance. Also available for Node.js: `npm install @tiktool/live`.
+
+## Install
+
+```bash
+pip install tiktok-live-api
+```
+
+## Quick Start
+
+```python
+from tiktok_live_api import TikTokLive
+
+client = TikTokLive("streamer_username", api_key="YOUR_API_KEY")
+
+@client.on("chat")
+def on_chat(event):
+    print(f"{event['user']['uniqueId']}: {event['comment']}")
+
+@client.on("gift")
+def on_gift(event):
+    print(f"{event['user']['uniqueId']} sent {event['giftName']} ({event['diamondCount']} 💎)")
+
+@client.on("like")
+def on_like(event):
+    print(f"{event['user']['uniqueId']} liked (total: {event['totalLikes']})")
+
+@client.on("follow")
+def on_follow(event):
+    print(f"{event['user']['uniqueId']} followed!")
+
+@client.on("roomUserSeq")
+def on_viewers(event):
+    print(f"{event['viewerCount']} viewers watching")
+
+client.run()
+```
+
+That's it. No complex setup, no protobuf, no reverse engineering.
+
+## Get a Free API Key
+
+1. Go to [tik.tools](https://tik.tools)
+2. Sign up (no credit card required)
+3. Copy your API key
+
+The free Sandbox tier gives you 50 requests/day and 1 WebSocket connection.
+
+## Environment Variable
+
+Instead of passing `api_key` directly, you can set it as an environment variable:
+
+```bash
+# Linux / macOS
+export TIKTOOL_API_KEY=your_api_key_here
+
+# Windows (CMD)
+set TIKTOOL_API_KEY=your_api_key_here
+
+# Windows (PowerShell)
+$env:TIKTOOL_API_KEY="your_api_key_here"
+```
+
+```bash
+python my_bot.py
+```
+
+```python
+from tiktok_live_api import TikTokLive
+
+# Automatically reads TIKTOOL_API_KEY from environment
+client = TikTokLive("streamer_username")
+client.on("chat", lambda e: print(e["comment"]))
+client.run()
+```
+
+## Events
+
+| Event | Description | Key Fields |
+|-------|-------------|------------|
+| `chat` | Chat message | `user`, `comment`, `emotes` |
+| `gift` | Virtual gift | `user`, `giftName`, `diamondCount`, `repeatCount` |
+| `like` | Like event | `user`, `likeCount`, `totalLikes` |
+| `follow` | New follower | `user` |
+| `share` | Stream share | `user` |
+| `member` | Viewer joined | `user` |
+| `subscribe` | New subscriber | `user` |
+| `roomUserSeq` | Viewer count | `viewerCount`, `topViewers` |
+| `battle` | Battle event | `type`, `teams`, `scores` |
+| `envelope` | Treasure chest | `diamonds`, `user` |
+| `streamEnd` | Stream ended | `reason` |
+| `connected` | Connected | `uniqueId` |
+| `disconnected` | Disconnected | `uniqueId` |
+| `error` | Error occurred | `error` |
+| `event` | Catch-all | Full raw event |
+
+## Live Captions (Speech-to-Text)
+
+Transcribe and translate any TikTok LIVE stream in real-time. **This feature is unique to TikTool Live — no other service offers it.**
+
+```python
+from tiktok_live_api import TikTokCaptions
+
+captions = TikTokCaptions(
+    "streamer_username",
+    api_key="YOUR_API_KEY",
+    translate="en",       # translate to English
+    diarization=True,     # identify who is speaking
+)
+
+@captions.on("caption")
+def on_caption(event):
+    speaker = event.get("speaker", "")
+    text = event["text"]
+    is_final = event.get("isFinal", False)
+    print(f"[{speaker}] {text}{'  ✓' if is_final else '...'}")
+
+@captions.on("translation")
+def on_translation(event):
+    print(f"  → {event['text']}")
+
+captions.run()
+```
+
+## Async Usage
+
+For integration with async frameworks (FastAPI, aiohttp, etc.):
+
+```python
+import asyncio
+from tiktok_live_api import TikTokLive
+
+async def main():
+    client = TikTokLive("streamer_username", api_key="YOUR_API_KEY")
+
+    @client.on("chat")
+    async def on_chat(event):
+        print(f"{event['user']['uniqueId']}: {event['comment']}")
+
+    await client.connect()
+
+asyncio.run(main())
+```
+
+## Chat Bot Example
+
+```python
+from tiktok_live_api import TikTokLive
+
+client = TikTokLive("streamer_username", api_key="YOUR_API_KEY")
+gift_leaderboard = {}
+message_count = 0
+
+@client.on("chat")
+def on_chat(event):
+    global message_count
+    message_count += 1
+    msg = event["comment"].lower().strip()
+    user = event["user"]["uniqueId"]
+
+    if msg == "!hello":
+        print(f">> BOT: Welcome {user}! 👋")
+    elif msg == "!stats":
+        print(f">> BOT: {message_count} messages, {len(gift_leaderboard)} gifters")
+    elif msg == "!top":
+        top = sorted(gift_leaderboard.items(), key=lambda x: -x[1])[:5]
+        for i, (name, diamonds) in enumerate(top):
+            print(f"  {i+1}. {name} — {diamonds} 💎")
+
+@client.on("gift")
+def on_gift(event):
+    user = event["user"]["uniqueId"]
+    diamonds = event.get("diamondCount", 0)
+    gift_leaderboard[user] = gift_leaderboard.get(user, 0) + diamonds
+
+client.run()
+```
+
+## Why tiktok-live-api?
+
+| | tiktok-live-api | TikTokLive (Python) | tiktok-live-connector (Node.js) |
+|---|---|---|---|
+| **Stability** | ✓ Managed API, 99.9% uptime | ✗ Breaks on TikTok updates | ✗ Breaks on TikTok updates |
+| **Live Captions** | ✓ AI speech-to-text | ✗ | ✗ |
+| **Maintenance** | ✓ Zero — we handle it | ✗ You fix breakages | ✗ You fix breakages |
+| **CAPTCHA Solving** | ✓ Built-in (Pro+) | ✗ | ✗ |
+| **Feed Discovery** | ✓ See who's live | ✗ | ✗ |
+| **Free Tier** | ✓ 50 requests/day | ✓ Free (unreliable) | ✓ Free (unreliable) |
+
+## Pricing
+
+| Tier | Requests/Day | WebSocket Connections | Price |
+|------|-------------|----------------------|-------|
+| Sandbox | 50 | 1 (60s) | Free |
+| Basic | 10,000 | 3 (8h) | $7/week |
+| Pro | 75,000 | 50 (8h) | $15/week |
+| Ultra | 300,000 | 500 (8h) | $45/week |
+
+## Also Available
+
+- **Node.js/TypeScript**: [`npm install @tiktool/live`](https://www.npmjs.com/package/@tiktool/live)
+- **Any language**: Connect via WebSocket: `wss://api.tik.tools?uniqueId=USERNAME&apiKey=KEY`
+- **Unreal Engine**: Native C++/Blueprint plugin
+
+## Links
+
+- **Website**: [tik.tools](https://tik.tools)
+- **Documentation**: [tik.tools/docs](https://tik.tools/docs)
+- **Python Guide**: [tik.tools/guides/python-tiktok-live](https://tik.tools/guides/python-tiktok-live)
+- **GitHub**: [github.com/tiktool/live-python](https://github.com/tiktool/live-python)
+- **npm (Node.js)**: [@tiktool/live](https://www.npmjs.com/package/@tiktool/live)
+
+## License
+
+MIT

tiktok_live_api-1.0.0/README.md

@@ -0,0 +1,223 @@
+# tiktok-live-api
+
+**TikTok LIVE API Client for Python** — Connect to any TikTok LIVE stream and receive real-time chat messages, gifts, likes, follows, viewer counts, battles, and more.
+
+[![PyPI](https://img.shields.io/pypi/v/tiktok-live-api)](https://pypi.org/project/tiktok-live-api/)
+[![Python](https://img.shields.io/pypi/pyversions/tiktok-live-api)](https://pypi.org/project/tiktok-live-api/)
+[![License](https://img.shields.io/pypi/l/tiktok-live-api)](https://github.com/tiktool/live-python/blob/main/LICENSE)
+
+> **Production-ready alternative to the `TikTokLive` library.** Unlike `TikTokLive` which reverse-engineers TikTok's internal protocol and breaks frequently, `tiktok-live-api` connects to TikTool Live's managed API service — 99.9% uptime, zero maintenance. Also available for Node.js: `npm install @tiktool/live`.
+
+## Install
+
+```bash
+pip install tiktok-live-api
+```
+
+## Quick Start
+
+```python
+from tiktok_live_api import TikTokLive
+
+client = TikTokLive("streamer_username", api_key="YOUR_API_KEY")
+
+@client.on("chat")
+def on_chat(event):
+    print(f"{event['user']['uniqueId']}: {event['comment']}")
+
+@client.on("gift")
+def on_gift(event):
+    print(f"{event['user']['uniqueId']} sent {event['giftName']} ({event['diamondCount']} 💎)")
+
+@client.on("like")
+def on_like(event):
+    print(f"{event['user']['uniqueId']} liked (total: {event['totalLikes']})")
+
+@client.on("follow")
+def on_follow(event):
+    print(f"{event['user']['uniqueId']} followed!")
+
+@client.on("roomUserSeq")
+def on_viewers(event):
+    print(f"{event['viewerCount']} viewers watching")
+
+client.run()
+```
+
+That's it. No complex setup, no protobuf, no reverse engineering.
+
+## Get a Free API Key
+
+1. Go to [tik.tools](https://tik.tools)
+2. Sign up (no credit card required)
+3. Copy your API key
+
+The free Sandbox tier gives you 50 requests/day and 1 WebSocket connection.
+
+## Environment Variable
+
+Instead of passing `api_key` directly, you can set it as an environment variable:
+
+```bash
+# Linux / macOS
+export TIKTOOL_API_KEY=your_api_key_here
+
+# Windows (CMD)
+set TIKTOOL_API_KEY=your_api_key_here
+
+# Windows (PowerShell)
+$env:TIKTOOL_API_KEY="your_api_key_here"
+```
+
+```bash
+python my_bot.py
+```
+
+```python
+from tiktok_live_api import TikTokLive
+
+# Automatically reads TIKTOOL_API_KEY from environment
+client = TikTokLive("streamer_username")
+client.on("chat", lambda e: print(e["comment"]))
+client.run()
+```
+
+## Events
+
+| Event | Description | Key Fields |
+|-------|-------------|------------|
+| `chat` | Chat message | `user`, `comment`, `emotes` |
+| `gift` | Virtual gift | `user`, `giftName`, `diamondCount`, `repeatCount` |
+| `like` | Like event | `user`, `likeCount`, `totalLikes` |
+| `follow` | New follower | `user` |
+| `share` | Stream share | `user` |
+| `member` | Viewer joined | `user` |
+| `subscribe` | New subscriber | `user` |
+| `roomUserSeq` | Viewer count | `viewerCount`, `topViewers` |
+| `battle` | Battle event | `type`, `teams`, `scores` |
+| `envelope` | Treasure chest | `diamonds`, `user` |
+| `streamEnd` | Stream ended | `reason` |
+| `connected` | Connected | `uniqueId` |
+| `disconnected` | Disconnected | `uniqueId` |
+| `error` | Error occurred | `error` |
+| `event` | Catch-all | Full raw event |
+
+## Live Captions (Speech-to-Text)
+
+Transcribe and translate any TikTok LIVE stream in real-time. **This feature is unique to TikTool Live — no other service offers it.**
+
+```python
+from tiktok_live_api import TikTokCaptions
+
+captions = TikTokCaptions(
+    "streamer_username",
+    api_key="YOUR_API_KEY",
+    translate="en",       # translate to English
+    diarization=True,     # identify who is speaking
+)
+
+@captions.on("caption")
+def on_caption(event):
+    speaker = event.get("speaker", "")
+    text = event["text"]
+    is_final = event.get("isFinal", False)
+    print(f"[{speaker}] {text}{'  ✓' if is_final else '...'}")
+
+@captions.on("translation")
+def on_translation(event):
+    print(f"  → {event['text']}")
+
+captions.run()
+```
+
+## Async Usage
+
+For integration with async frameworks (FastAPI, aiohttp, etc.):
+
+```python
+import asyncio
+from tiktok_live_api import TikTokLive
+
+async def main():
+    client = TikTokLive("streamer_username", api_key="YOUR_API_KEY")
+
+    @client.on("chat")
+    async def on_chat(event):
+        print(f"{event['user']['uniqueId']}: {event['comment']}")
+
+    await client.connect()
+
+asyncio.run(main())
+```
+
+## Chat Bot Example
+
+```python
+from tiktok_live_api import TikTokLive
+
+client = TikTokLive("streamer_username", api_key="YOUR_API_KEY")
+gift_leaderboard = {}
+message_count = 0
+
+@client.on("chat")
+def on_chat(event):
+    global message_count
+    message_count += 1
+    msg = event["comment"].lower().strip()
+    user = event["user"]["uniqueId"]
+
+    if msg == "!hello":
+        print(f">> BOT: Welcome {user}! 👋")
+    elif msg == "!stats":
+        print(f">> BOT: {message_count} messages, {len(gift_leaderboard)} gifters")
+    elif msg == "!top":
+        top = sorted(gift_leaderboard.items(), key=lambda x: -x[1])[:5]
+        for i, (name, diamonds) in enumerate(top):
+            print(f"  {i+1}. {name} — {diamonds} 💎")
+
+@client.on("gift")
+def on_gift(event):
+    user = event["user"]["uniqueId"]
+    diamonds = event.get("diamondCount", 0)
+    gift_leaderboard[user] = gift_leaderboard.get(user, 0) + diamonds
+
+client.run()
+```
+
+## Why tiktok-live-api?
+
+| | tiktok-live-api | TikTokLive (Python) | tiktok-live-connector (Node.js) |
+|---|---|---|---|
+| **Stability** | ✓ Managed API, 99.9% uptime | ✗ Breaks on TikTok updates | ✗ Breaks on TikTok updates |
+| **Live Captions** | ✓ AI speech-to-text | ✗ | ✗ |
+| **Maintenance** | ✓ Zero — we handle it | ✗ You fix breakages | ✗ You fix breakages |
+| **CAPTCHA Solving** | ✓ Built-in (Pro+) | ✗ | ✗ |
+| **Feed Discovery** | ✓ See who's live | ✗ | ✗ |
+| **Free Tier** | ✓ 50 requests/day | ✓ Free (unreliable) | ✓ Free (unreliable) |
+
+## Pricing
+
+| Tier | Requests/Day | WebSocket Connections | Price |
+|------|-------------|----------------------|-------|
+| Sandbox | 50 | 1 (60s) | Free |
+| Basic | 10,000 | 3 (8h) | $7/week |
+| Pro | 75,000 | 50 (8h) | $15/week |
+| Ultra | 300,000 | 500 (8h) | $45/week |
+
+## Also Available
+
+- **Node.js/TypeScript**: [`npm install @tiktool/live`](https://www.npmjs.com/package/@tiktool/live)
+- **Any language**: Connect via WebSocket: `wss://api.tik.tools?uniqueId=USERNAME&apiKey=KEY`
+- **Unreal Engine**: Native C++/Blueprint plugin
+
+## Links
+
+- **Website**: [tik.tools](https://tik.tools)
+- **Documentation**: [tik.tools/docs](https://tik.tools/docs)
+- **Python Guide**: [tik.tools/guides/python-tiktok-live](https://tik.tools/guides/python-tiktok-live)
+- **GitHub**: [github.com/tiktool/live-python](https://github.com/tiktool/live-python)
+- **npm (Node.js)**: [@tiktool/live](https://www.npmjs.com/package/@tiktool/live)
+
+## License
+
+MIT

tiktok_live_api-1.0.0/examples/basic.py

@@ -0,0 +1,61 @@
+"""Basic example — connect to a TikTok LIVE stream and print all events.
+
+Usage:
+    # Set environment variables first:
+    # Linux/macOS:  export TIKTOOL_API_KEY=your_key  TIKTOK_USERNAME=streamer
+    # Windows CMD:  set TIKTOOL_API_KEY=your_key  & set TIKTOK_USERNAME=streamer
+    # PowerShell:   $env:TIKTOOL_API_KEY="your_key"; $env:TIKTOK_USERNAME="streamer"
+
+    python basic.py
+"""
+
+import os
+import sys
+
+from tiktok_live_api import TikTokLive
+
+USERNAME = os.environ.get("TIKTOK_USERNAME", "")
+if not USERNAME:
+    print("Set TIKTOK_USERNAME environment variable to the streamer's username.")
+    sys.exit(1)
+
+client = TikTokLive(USERNAME)
+
+
+@client.on("connected")
+def on_connected(event):
+    print(f"Connected to @{event['uniqueId']}")
+
+
+@client.on("chat")
+def on_chat(event):
+    print(f"[chat] {event['user']['uniqueId']}: {event['comment']}")
+
+
+@client.on("gift")
+def on_gift(event):
+    diamonds = event.get("diamondCount", 0)
+    print(f"[gift] {event['user']['uniqueId']} sent {event['giftName']} ({diamonds} diamonds)")
+
+
+@client.on("like")
+def on_like(event):
+    print(f"[like] {event['user']['uniqueId']} liked (total: {event['totalLikes']})")
+
+
+@client.on("follow")
+def on_follow(event):
+    print(f"[follow] {event['user']['uniqueId']} followed")
+
+
+@client.on("roomUserSeq")
+def on_viewers(event):
+    print(f"[viewers] {event['viewerCount']} watching")
+
+
+@client.on("streamEnd")
+def on_stream_end(event):
+    print("[stream] Stream has ended.")
+
+
+client.run()

tiktok_live_api-1.0.0/examples/captions.py

@@ -0,0 +1,48 @@
+"""Live Captions example — transcribe and translate a TikTok LIVE stream.
+
+Usage:
+    # Set environment variables first:
+    # Linux/macOS:  export TIKTOOL_API_KEY=your_key  TIKTOK_USERNAME=streamer
+    # Windows CMD:  set TIKTOOL_API_KEY=your_key  & set TIKTOK_USERNAME=streamer
+    # PowerShell:   $env:TIKTOOL_API_KEY="your_key"; $env:TIKTOK_USERNAME="streamer"
+
+    python captions.py
+"""
+
+import os
+import sys
+
+from tiktok_live_api import TikTokCaptions
+
+USERNAME = os.environ.get("TIKTOK_USERNAME", "")
+if not USERNAME:
+    print("Set TIKTOK_USERNAME environment variable to the streamer's username.")
+    sys.exit(1)
+
+captions = TikTokCaptions(
+    USERNAME,
+    translate="en",
+    diarization=True,
+)
+
+
+@captions.on("connected")
+def on_connected(event):
+    print(f"Listening to @{event['uniqueId']}")
+
+
+@captions.on("caption")
+def on_caption(event):
+    speaker = event.get("speaker", "")
+    text = event["text"]
+    is_final = event.get("isFinal", False)
+    status = "FINAL" if is_final else "partial"
+    print(f"[{status}] [{speaker}] {text}")
+
+
+@captions.on("translation")
+def on_translation(event):
+    print(f"  -> {event['text']}")
+
+
+captions.run()

tiktok_live_api-1.0.0/examples/chat_bot.py

@@ -0,0 +1,54 @@
+"""Chat bot example — respond to commands and track a gift leaderboard.
+
+Usage:
+    # Set environment variables first:
+    # Linux/macOS:  export TIKTOOL_API_KEY=your_key  TIKTOK_USERNAME=streamer
+    # Windows CMD:  set TIKTOOL_API_KEY=your_key  & set TIKTOK_USERNAME=streamer
+    # PowerShell:   $env:TIKTOOL_API_KEY="your_key"; $env:TIKTOK_USERNAME="streamer"
+
+    python chat_bot.py
+"""
+
+import os
+import sys
+from typing import Dict
+
+from tiktok_live_api import TikTokLive
+
+USERNAME = os.environ.get("TIKTOK_USERNAME", "")
+if not USERNAME:
+    print("Set TIKTOK_USERNAME environment variable to the streamer's username.")
+    sys.exit(1)
+
+client = TikTokLive(USERNAME)
+
+gift_leaderboard: Dict[str, int] = {}
+message_count = 0
+
+
+@client.on("chat")
+def on_chat(event):
+    global message_count
+    message_count += 1
+    msg = event["comment"].lower().strip()
+    user = event["user"]["uniqueId"]
+
+    if msg == "!hello":
+        print(f">> BOT: Welcome {user}!")
+    elif msg == "!stats":
+        print(f">> BOT: {message_count} messages, {len(gift_leaderboard)} gifters")
+    elif msg == "!top":
+        top = sorted(gift_leaderboard.items(), key=lambda x: -x[1])[:5]
+        for rank, (name, diamonds) in enumerate(top, start=1):
+            print(f"  {rank}. {name} - {diamonds} diamonds")
+
+
+@client.on("gift")
+def on_gift(event):
+    user = event["user"]["uniqueId"]
+    diamonds = event.get("diamondCount", 0)
+    gift_leaderboard[user] = gift_leaderboard.get(user, 0) + diamonds
+    print(f"[gift] {user} sent {event['giftName']} ({diamonds} diamonds)")
+
+
+client.run()

tiktok_live_api-1.0.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tiktok-live-api"
+version = "1.0.0"
+description = "TikTok LIVE API Client — Real-time chat, gifts, viewers, battles, and live captions from any TikTok livestream. Production-ready managed API."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "TikTool", email = "support@tik.tools"}
+]
+keywords = [
+    "tiktok",
+    "tiktok-live",
+    "tiktok-api",
+    "tiktok-live-api",
+    "tiktok-live-connector",
+    "live-streaming",
+    "websocket",
+    "chat",
+    "gifts",
+    "webcast",
+    "real-time",
+    "speech-to-text",
+    "captions",
+    "transcription",
+    "translation",
+    "tiktok-data",
+    "tiktok-bot",
+    "live-chat",
+    "tiktok-live-python",
+    "tiktok-tools",
+    "euler-stream",
+    "tiktok-live-sdk"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Typing :: Typed",
+]
+dependencies = [
+    "websockets>=11.0",
+]
+
+[project.urls]
+Homepage = "https://tik.tools"
+Documentation = "https://tik.tools/docs"
+Repository = "https://github.com/tiktool/live-python"
+Issues = "https://github.com/tiktool/live-python/issues"
+Changelog = "https://github.com/tiktool/live-python/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tiktok_live_api"]

tiktok_live_api-1.0.0/tiktok_live_api/__init__.py

@@ -0,0 +1,50 @@
+"""TikTok Live API — TikTok LIVE stream data client for Python.
+
+Connect to any TikTok LIVE stream and receive real-time events:
+chat messages, gifts, likes, follows, viewer counts, battles, and more.
+
+Usage::
+
+    from tiktok_live_api import TikTokLive
+
+    client = TikTokLive("streamer_username", api_key="YOUR_KEY")
+
+    @client.on("chat")
+    def on_chat(event):
+        print(f"{event['user']['uniqueId']}: {event['comment']}")
+
+    client.run()
+
+See https://tik.tools/docs for full documentation.
+"""
+
+from tiktok_live_api.client import TikTokLive
+from tiktok_live_api.captions import TikTokCaptions
+from tiktok_live_api.types import (
+    TikTokUser,
+    ChatEvent,
+    GiftEvent,
+    LikeEvent,
+    MemberEvent,
+    SocialEvent,
+    RoomUserSeqEvent,
+    BattleEvent,
+    CaptionEvent,
+    TranslationEvent,
+)
+
+__all__ = [
+    "TikTokLive",
+    "TikTokCaptions",
+    "TikTokUser",
+    "ChatEvent",
+    "GiftEvent",
+    "LikeEvent",
+    "MemberEvent",
+    "SocialEvent",
+    "RoomUserSeqEvent",
+    "BattleEvent",
+    "CaptionEvent",
+    "TranslationEvent",
+]
+__version__ = "1.0.0"

tiktok_live_api-1.0.0/tiktok_live_api/captions.py

@@ -0,0 +1,203 @@
+"""TikTokCaptions — Real-time AI speech-to-text for TikTok LIVE streams."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import signal
+from typing import Any, Callable, Dict, List, Optional, Union
+
+import websockets
+import websockets.client
+
+logger = logging.getLogger("tiktok_live_api.captions")
+
+EventHandler = Callable[[Dict[str, Any]], None]
+AsyncEventHandler = Callable[[Dict[str, Any]], Any]
+AnyHandler = Union[EventHandler, AsyncEventHandler]
+
+CAPTIONS_BASE = "wss://api.tik.tools/captions"
+_VERSION = "1.0.0"
+
+
+class TikTokCaptions:
+    """Real-time AI speech-to-text transcription for TikTok LIVE streams.
+
+    This is a unique feature not available in any other TikTok LIVE library.
+
+    Args:
+        unique_id: TikTok username (without @).
+        api_key: Your TikTool API key. Get one at https://tik.tools
+        translate: Target language code for real-time translation (e.g. ``"en"``, ``"es"``).
+        diarization: Enable speaker identification (default ``True``).
+
+    Example::
+
+        from tiktok_live_api import TikTokCaptions
+
+        captions = TikTokCaptions("streamer", api_key="KEY", translate="en")
+
+        @captions.on("caption")
+        def on_caption(event):
+            print(f"[{event.get('speaker', '')}] {event['text']}")
+
+        captions.run()
+    """
+
+    def __init__(
+        self,
+        unique_id: str,
+        *,
+        api_key: Optional[str] = None,
+        translate: Optional[str] = None,
+        diarization: bool = True,
+    ) -> None:
+        self.unique_id = unique_id.lstrip("@")
+        self.api_key = api_key or os.environ.get("TIKTOOL_API_KEY", "")
+        if not self.api_key:
+            raise ValueError(
+                "api_key is required. Get a free key at https://tik.tools"
+            )
+        self.translate = translate
+        self.diarization = diarization
+
+        self._handlers: Dict[str, List[AnyHandler]] = {}
+        self._ws: Optional[websockets.client.WebSocketClientProtocol] = None
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._connected = False
+        self._intentional_close = False
+
+    @property
+    def connected(self) -> bool:
+        """Whether the captions client is currently connected."""
+        return self._connected
+
+    def on(
+        self, event: str, handler: Optional[AnyHandler] = None
+    ) -> Any:
+        """Register an event handler. Can be used as a decorator or called directly.
+
+        Supported events:
+            caption, translation, credits, status, error, connected, disconnected
+
+        Usage as decorator::
+
+            @captions.on("caption")
+            def on_caption(event):
+                print(event["text"])
+
+        Usage as method::
+
+            captions.on("translation", lambda e: print(e["text"]))
+        """
+        if handler is not None:
+            self._handlers.setdefault(event, []).append(handler)
+            return handler
+
+        def decorator(fn: AnyHandler) -> AnyHandler:
+            self._handlers.setdefault(event, []).append(fn)
+            return fn
+
+        return decorator
+
+    def _emit(self, event: str, data: Any = None) -> None:
+        for handler in self._handlers.get(event, []):
+            try:
+                result = handler(data)
+                if asyncio.iscoroutine(result):
+                    loop = self._loop or asyncio.get_event_loop()
+                    loop.create_task(result)
+            except Exception as exc:
+                logger.error("Error in '%s' handler: %s", event, exc)
+
+    async def start(self) -> None:
+        """Start receiving captions from the stream.
+
+        For most use cases, prefer :meth:`run` which handles the event loop
+        automatically. Use ``start`` when integrating with an existing
+        async application.
+        """
+        self._intentional_close = False
+        self._loop = asyncio.get_event_loop()
+        params = f"uniqueId={self.unique_id}&apiKey={self.api_key}"
+        if self.translate:
+            params += f"&translate={self.translate}"
+        if self.diarization:
+            params += "&diarization=true"
+
+        uri = f"{CAPTIONS_BASE}?{params}"
+
+        try:
+            self._ws = await websockets.connect(
+                uri,
+                additional_headers={"User-Agent": f"tiktok-live-api-python/{_VERSION}"},
+                ping_interval=10,
+                ping_timeout=30,
+            )
+        except Exception as exc:
+            self._emit("error", {"error": str(exc)})
+            raise
+
+        self._connected = True
+        self._emit("connected", {"uniqueId": self.unique_id})
+
+        try:
+            async for raw in self._ws:
+                try:
+                    event = json.loads(raw)
+                except (json.JSONDecodeError, TypeError):
+                    continue
+
+                msg_type = event.get("type", "unknown")
+                self._emit(msg_type, event)
+        except websockets.ConnectionClosed:
+            pass
+        except Exception as exc:
+            self._emit("error", {"error": str(exc)})
+        finally:
+            self._connected = False
+            self._emit("disconnected", {"uniqueId": self.unique_id})
+
+    def stop(self) -> None:
+        """Stop receiving captions."""
+        self._intentional_close = True
+        if self._ws is not None:
+            if self._loop is not None and self._loop.is_running():
+                self._loop.create_task(self._ws.close())
+            else:
+                try:
+                    asyncio.get_event_loop().run_until_complete(self._ws.close())
+                except RuntimeError:
+                    pass
+        self._connected = False
+
+    def run(self) -> None:
+        """Start receiving captions and block until stopped.
+
+        Creates an event loop, connects to the captions stream, and blocks
+        until the stream ends or :meth:`stop` is called::
+
+            from tiktok_live_api import TikTokCaptions
+
+            captions = TikTokCaptions("streamer", api_key="KEY", translate="en")
+            captions.on("caption", lambda e: print(e["text"]))
+            captions.run()
+        """
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        self._loop = loop
+
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                loop.add_signal_handler(sig, self.stop)
+            except (NotImplementedError, ValueError, OSError):
+                pass
+
+        try:
+            loop.run_until_complete(self.start())
+        except KeyboardInterrupt:
+            self.stop()
+        finally:
+            loop.close()

tiktok_live_api-1.0.0/tiktok_live_api/client.py

@@ -0,0 +1,238 @@
+"""TikTokLive client — connect to any TikTok LIVE stream via WebSocket."""
+# ruff: noqa: E402
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import signal
+from typing import Any, Callable, Dict, List, Optional, Union
+
+import websockets
+import websockets.client
+
+logger = logging.getLogger("tiktok_live_api")
+
+EventHandler = Callable[[Dict[str, Any]], None]
+AsyncEventHandler = Callable[[Dict[str, Any]], Any]
+AnyHandler = Union[EventHandler, AsyncEventHandler]
+
+WS_BASE = "wss://api.tik.tools"
+_VERSION = "1.0.0"
+
+
+class TikTokLive:
+    """Connect to a TikTok LIVE stream and receive real-time events.
+
+    Args:
+        unique_id: TikTok username (without @).
+        api_key: Your TikTool API key. Get one free at https://tik.tools
+        auto_reconnect: Auto-reconnect on disconnect (default True).
+        max_reconnect_attempts: Max reconnection attempts (default 5).
+
+    Example::
+
+        from tiktok_live_api import TikTokLive
+
+        client = TikTokLive("streamer_username", api_key="YOUR_KEY")
+
+        @client.on("chat")
+        def on_chat(event):
+            print(f"{event['user']['uniqueId']}: {event['comment']}")
+
+        client.run()
+    """
+
+    def __init__(
+        self,
+        unique_id: str,
+        *,
+        api_key: Optional[str] = None,
+        auto_reconnect: bool = True,
+        max_reconnect_attempts: int = 5,
+    ) -> None:
+        self.unique_id = unique_id.lstrip("@")
+        self.api_key = api_key or os.environ.get("TIKTOOL_API_KEY", "")
+        if not self.api_key:
+            raise ValueError(
+                "api_key is required. Get a free key at https://tik.tools"
+            )
+        self.auto_reconnect = auto_reconnect
+        self.max_reconnect_attempts = max_reconnect_attempts
+
+        self._handlers: Dict[str, List[AnyHandler]] = {}
+        self._ws: Optional[websockets.client.WebSocketClientProtocol] = None
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._connected = False
+        self._intentional_close = False
+        self._reconnect_attempts = 0
+        self._event_count = 0
+
+    @property
+    def connected(self) -> bool:
+        """Whether the client is currently connected."""
+        return self._connected
+
+    @property
+    def event_count(self) -> int:
+        """Total number of events received."""
+        return self._event_count
+
+    def on(
+        self, event: str, handler: Optional[AnyHandler] = None
+    ) -> Any:
+        """Register an event handler. Can be used as a decorator or called directly.
+
+        Supported events:
+            connected, chat, gift, like, follow, share, member, subscribe,
+            roomUserSeq, roomInfo, battle, envelope, streamEnd, error,
+            disconnected, event (catch-all)
+
+        Usage as decorator::
+
+            @client.on("chat")
+            def on_chat(event):
+                print(event["comment"])
+
+        Usage as method::
+
+            client.on("gift", lambda e: print(e["giftName"]))
+        """
+        if handler is not None:
+            self._handlers.setdefault(event, []).append(handler)
+            return handler
+
+        def decorator(fn: AnyHandler) -> AnyHandler:
+            self._handlers.setdefault(event, []).append(fn)
+            return fn
+
+        return decorator
+
+    def _emit(self, event: str, data: Any = None) -> None:
+        for handler in self._handlers.get(event, []):
+            try:
+                result = handler(data)
+                if asyncio.iscoroutine(result):
+                    loop = self._loop or asyncio.get_event_loop()
+                    loop.create_task(result)
+            except Exception as exc:
+                logger.error("Error in '%s' handler: %s", event, exc)
+
+    async def connect(self) -> None:
+        """Connect to the TikTok LIVE stream.
+
+        For most use cases, prefer :meth:`run` which handles the event loop
+        setup automatically. Use ``connect`` directly when integrating with
+        an existing async application (FastAPI, aiohttp, etc.)::
+
+            import asyncio
+            from tiktok_live_api import TikTokLive
+
+            async def main():
+                client = TikTokLive("username", api_key="KEY")
+                client.on("chat", lambda e: print(e["comment"]))
+                await client.connect()
+
+            asyncio.run(main())
+        """
+        self._intentional_close = False
+        self._loop = asyncio.get_event_loop()
+        uri = f"{WS_BASE}?uniqueId={self.unique_id}&apiKey={self.api_key}"
+
+        try:
+            self._ws = await websockets.connect(
+                uri,
+                additional_headers={"User-Agent": f"tiktok-live-api-python/{_VERSION}"},
+                ping_interval=10,
+                ping_timeout=30,
+                close_timeout=5,
+            )
+        except Exception as exc:
+            self._emit("error", {"error": str(exc)})
+            raise
+
+        self._connected = True
+        self._reconnect_attempts = 0
+        self._emit("connected", {"uniqueId": self.unique_id})
+
+        try:
+            async for raw in self._ws:
+                try:
+                    event = json.loads(raw)
+                except (json.JSONDecodeError, TypeError):
+                    continue
+
+                self._event_count += 1
+                event_type = event.get("event", "unknown")
+                data = event.get("data", event)
+
+                self._emit("event", event)
+                self._emit(event_type, data)
+        except websockets.ConnectionClosed:
+            pass
+        except Exception as exc:
+            self._emit("error", {"error": str(exc)})
+        finally:
+            self._connected = False
+            self._emit("disconnected", {"uniqueId": self.unique_id})
+
+            if (
+                not self._intentional_close
+                and self.auto_reconnect
+                and self._reconnect_attempts < self.max_reconnect_attempts
+            ):
+                self._reconnect_attempts += 1
+                delay = min(2 ** (self._reconnect_attempts - 1), 30)
+                logger.info(
+                    "Reconnecting in %ds (attempt %d/%d)...",
+                    delay,
+                    self._reconnect_attempts,
+                    self.max_reconnect_attempts,
+                )
+                await asyncio.sleep(delay)
+                await self.connect()
+
+    def disconnect(self) -> None:
+        """Disconnect from the stream."""
+        self._intentional_close = True
+        if self._ws is not None:
+            if self._loop is not None and self._loop.is_running():
+                self._loop.create_task(self._ws.close())
+            else:
+                try:
+                    asyncio.get_event_loop().run_until_complete(self._ws.close())
+                except RuntimeError:
+                    pass
+        self._connected = False
+
+    def run(self) -> None:
+        """Connect and block until disconnected.
+
+        This is the simplest way to use the client. It creates an event loop,
+        connects to the stream, and blocks until the stream ends or
+        :meth:`disconnect` is called::
+
+            from tiktok_live_api import TikTokLive
+
+            client = TikTokLive("streamer", api_key="KEY")
+            client.on("chat", lambda e: print(e["comment"]))
+            client.run()
+        """
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        self._loop = loop
+
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                loop.add_signal_handler(sig, self.disconnect)
+            except (NotImplementedError, ValueError, OSError):
+                pass
+
+        try:
+            loop.run_until_complete(self.connect())
+        except KeyboardInterrupt:
+            self.disconnect()
+        finally:
+            loop.close()

tiktok_live_api-1.0.0/tiktok_live_api/py.typed

@@ -0,0 +1 @@
+py_typed

tiktok_live_api-1.0.0/tiktok_live_api/types.py

@@ -0,0 +1,113 @@
+"""Type definitions for TikTok LIVE API events.
+
+These types can be used for IDE autocompletion and type checking
+when handling events from :class:`~tiktok_live_api.TikTokLive` and
+:class:`~tiktok_live_api.TikTokCaptions`.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Dict, List
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+__all__ = [
+    "TikTokUser",
+    "ChatEvent",
+    "GiftEvent",
+    "LikeEvent",
+    "MemberEvent",
+    "SocialEvent",
+    "RoomUserSeqEvent",
+    "BattleEvent",
+    "CaptionEvent",
+    "TranslationEvent",
+]
+
+
+class TikTokUser(TypedDict, total=False):
+    """User profile attached to most LIVE events."""
+
+    userId: str
+    uniqueId: str
+    nickname: str
+    profilePictureUrl: str
+    followRole: int
+    isSubscriber: bool
+
+
+class ChatEvent(TypedDict, total=False):
+    """Payload for ``chat`` events."""
+
+    user: TikTokUser
+    comment: str
+    emotes: List[Dict[str, Any]]
+
+
+class GiftEvent(TypedDict, total=False):
+    """Payload for ``gift`` events."""
+
+    user: TikTokUser
+    giftId: int
+    giftName: str
+    diamondCount: int
+    repeatCount: int
+    repeatEnd: bool
+
+
+class LikeEvent(TypedDict, total=False):
+    """Payload for ``like`` events."""
+
+    user: TikTokUser
+    likeCount: int
+    totalLikes: int
+
+
+class MemberEvent(TypedDict, total=False):
+    """Payload for ``member`` (viewer join) events."""
+
+    user: TikTokUser
+    actionId: int
+
+
+class SocialEvent(TypedDict, total=False):
+    """Payload for ``follow`` and ``share`` events."""
+
+    user: TikTokUser
+    eventType: str
+
+
+class RoomUserSeqEvent(TypedDict, total=False):
+    """Payload for ``roomUserSeq`` (viewer count) events."""
+
+    viewerCount: int
+    topViewers: List[TikTokUser]
+
+
+class BattleEvent(TypedDict, total=False):
+    """Payload for ``battle`` events."""
+
+    type: str
+    teams: List[Dict[str, Any]]
+    scores: List[int]
+
+
+class CaptionEvent(TypedDict, total=False):
+    """Payload for ``caption`` events from :class:`~tiktok_live_api.TikTokCaptions`."""
+
+    text: str
+    speaker: str
+    isFinal: bool
+    language: str
+
+
+class TranslationEvent(TypedDict, total=False):
+    """Payload for ``translation`` events from :class:`~tiktok_live_api.TikTokCaptions`."""
+
+    text: str
+    sourceLanguage: str
+    targetLanguage: str