
[TikTokLive](https://github.com/isaackogan/TikTokLive) is a Python library for connecting to TikTok LIVE streams.
It provides an async, event-driven API using decorators or manual listeners.

<Callout type="info">
  View the full source on [GitHub](https://github.com/isaackogan/TikTokLive).
</Callout>

## Quickstart

<Steps>
<Step>

### Install the package

```bash
pip install TikTokLive
```

</Step>
<Step>

### Set your API key

```python
from TikTokLive.client.web.web_settings import WebDefaults

WebDefaults.tiktok_sign_api_key = "YOUR_API_KEY"
```

</Step>
<Step>

### Connect and listen to events

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

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

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

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

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

</Step>
</Steps>

## Blocking vs Non-Blocking

```python
# Blocking (runs the event loop)
client.run()

# Non-blocking (use inside an async function)
await client.start()
```

## Common Events

| Event | Description |
|-------|-------------|
| `ConnectEvent` | Successfully connected to the stream |
| `CommentEvent` | A viewer sent a chat message |
| `GiftEvent` | A viewer sent a gift |
| `LikeEvent` | A viewer liked the stream |
| `JoinEvent` | A viewer joined the stream |
| `ShareEvent` | A viewer shared the stream |
| `FollowEvent` | A viewer followed the creator |
| `DisconnectEvent` | Disconnected from the stream |

See the [API Key Usage](/docs/api-key-usage/python) guide for more configuration options.
