Overview TikTokLive allows you to fetch detailed information about a live room and available gifts. This data includes stream details, broadcaster information, viewer statistics, and the complete gift catalog.
Fetching Room Info Basic Usage Enable room info fetching when starting your client:
from TikTokLive import TikTokLiveClient from TikTokLive.events import ConnectEvent client = TikTokLiveClient( unique_id = "@username" ) @client.on (ConnectEvent) async def on_connect ( event : ConnectEvent): if client.room_info: print ( f "Room ID: { client.room_info[ 'room_id' ] } " ) print ( f "Title: { client.room_info.get( 'title' , 'No title' ) } " ) print ( f "Viewer Count: { client.room_info.get( 'user_count' , 0 ) } " ) if __name__ == '__main__' : # Enable room info fetching client.run( fetch_room_info = True )
Using room_info Property Access room information through the room_info property:
from TikTokLive import TikTokLiveClient client = TikTokLiveClient( unique_id = "@username" ) # Start with room info fetching await client.start( fetch_room_info = True ) # Access room info if client.room_info: room_data = client.room_info # Extract useful information owner = room_data.get( 'owner' , {}) stats = room_data.get( 'stats' , {}) print ( f "Broadcaster: { owner.get( 'display_id' ) } " ) print ( f "Nickname: { owner.get( 'nickname' ) } " ) print ( f "Follower Count: { owner.get( 'follower_count' , 0 ) } " ) print ( f "Room Status: { room_data.get( 'status' , 'unknown' ) } " )
Room Info Structure The room_info dictionary contains comprehensive stream information:
{ 'room_id' : '7123456789' , 'title' : 'Stream Title' , 'status' : 2 , # 2 = live, 4 = ended 'user_count' : 1234 , 'owner' : { 'id' : '123456' , 'display_id' : 'username' , 'nickname' : 'Display Name' , 'avatar_thumb' : { 'url_list' : [ ... ]}, 'follower_count' : 50000 , 'following_count' : 123 }, 'stats' : { 'total_user' : 5678 , 'like_count' : 123456 , 'total_user_str' : '5.6K' }, 'stream_url' : { 'rtmp_pull_url' : 'rtmp://...' , 'live_core_sdk_data' : { ... } }, 'create_time' : 1234567890 , 'finish_time' : 0 }
The exact structure may vary depending on the TikTok API version. Always check if keys exist before accessing them.
Fetching Gift Info Basic Usage Enable gift info fetching to get the complete gift catalog:
from TikTokLive import TikTokLiveClient from TikTokLive.events import ConnectEvent client = TikTokLiveClient( unique_id = "@username" ) @client.on (ConnectEvent) async def on_connect ( event : ConnectEvent): if client.gift_info: print ( f "Total gifts available: { len (client.gift_info.get( 'gifts' , [])) } " ) # List all gifts for gift in client.gift_info.get( 'gifts' , []): print ( f "Gift: { gift[ 'name' ] } - Cost: { gift[ 'diamond_count' ] } diamonds" ) if __name__ == '__main__' : # Enable gift info fetching client.run( fetch_gift_info = True )
Using gift_info Property Access gift information through the gift_info property:
from TikTokLive import TikTokLiveClient client = TikTokLiveClient( unique_id = "@username" ) # Start with gift info fetching await client.start( fetch_gift_info = True ) # Access gift info if client.gift_info: gifts = client.gift_info.get( 'gifts' , []) # Find a specific gift rose_gift = next ( (g for g in gifts if g[ 'name' ].lower() == 'rose' ), None ) if rose_gift: print ( f "Rose costs { rose_gift[ 'diamond_count' ] } diamonds" ) print ( f "Gift ID: { rose_gift[ 'id' ] } " )
Gift Info Structure The gift_info dictionary contains details about all available gifts:
{ 'gifts' : [ { 'id' : 5655 , 'name' : 'Rose' , 'diamond_count' : 1 , 'type' : 1 , 'icon' : { 'url_list' : [ ... ]}, 'image' : { 'url_list' : [ ... ]}, 'describe' : 'Send a rose' , 'is_displayed' : True , 'is_effect_befview' : False , 'is_random_gift' : False , 'is_broadcast_gift' : False , 'combo' : True }, # ... more gifts ] }
Combining Room and Gift Info Fetch both room and gift information simultaneously:
from TikTokLive import TikTokLiveClient from TikTokLive.events import ConnectEvent, GiftEvent client = TikTokLiveClient( unique_id = "@username" ) @client.on (ConnectEvent) async def on_connect ( event : ConnectEvent): print ( f "Connected to { event.unique_id } " ) # Display room info if client.room_info: owner = client.room_info.get( 'owner' , {}) print ( f "Broadcaster: { owner.get( 'nickname' ) } " ) print ( f "Viewers: { client.room_info.get( 'user_count' , 0 ) } " ) # Display gift catalog if client.gift_info: gifts = client.gift_info.get( 'gifts' , []) print ( f " \n Available gifts: { len (gifts) } " ) @client.on (GiftEvent) async def on_gift ( event : GiftEvent): # Cross-reference with gift catalog if client.gift_info: gift_id = event.gift.id gift_details = next ( (g for g in client.gift_info.get( 'gifts' , []) if g[ 'id' ] == gift_id), None ) if gift_details: print ( f " { event.user.nickname } sent { gift_details[ 'name' ] } " ) print ( f "Value: { gift_details[ 'diamond_count' ] } diamonds" ) if __name__ == '__main__' : # Enable both client.run( fetch_room_info = True , fetch_gift_info = True )
Recording Streams Use room info to record live streams:
from TikTokLive import TikTokLiveClient from TikTokLive.events import ConnectEvent import httpx import asyncio client = TikTokLiveClient( unique_id = "@username" ) @client.on (ConnectEvent) async def on_connect ( event : ConnectEvent): if not client.room_info: return # Extract stream URL stream_url_data = client.room_info.get( 'stream_url' , {}) rtmp_url = stream_url_data.get( 'rtmp_pull_url' ) if rtmp_url: print ( f "Stream URL: { rtmp_url } " ) # Use ffmpeg or similar to record # ffmpeg -i {rtmp_url} -c copy output.mp4 if __name__ == '__main__' : client.run( fetch_room_info = True )
Recording streams may violate TikTok’s Terms of Service. Always respect creator rights and platform policies.
Gift Analytics Track gift statistics using the gift catalog:
from TikTokLive import TikTokLiveClient from TikTokLive.events import ConnectEvent, GiftEvent from collections import defaultdict client = TikTokLiveClient( unique_id = "@username" ) gift_stats = defaultdict( int ) total_diamonds = 0 @client.on (ConnectEvent) async def on_connect ( event : ConnectEvent): print ( "Connected! Tracking gifts..." ) @client.on (GiftEvent) async def on_gift ( event : GiftEvent): global total_diamonds if client.gift_info and event.gift: # Find gift details gift_details = next ( (g for g in client.gift_info.get( 'gifts' , []) if g[ 'id' ] == event.gift.id), None ) if gift_details: gift_name = gift_details[ 'name' ] diamonds = gift_details[ 'diamond_count' ] # Track statistics gift_stats[gift_name] += 1 total_diamonds += diamonds print ( f " \n { event.user.nickname } sent { gift_name } " ) print ( f "Session total: { total_diamonds } diamonds" ) print ( f "Top gifts: { dict ( sorted (gift_stats.items(), key = lambda x : x[ 1 ], reverse = True )[: 5 ]) } " ) if __name__ == '__main__' : client.run( fetch_gift_info = True )
Checking Stream Status Use room info to monitor stream status:
from TikTokLive import TikTokLiveClient from TikTokLive.events import ConnectEvent import asyncio async def check_stream_status ( username : str ): client = TikTokLiveClient( unique_id = username) try : await client.start( fetch_room_info = True ) if client.room_info: status = client.room_info.get( 'status' ) if status == 2 : print ( f " { username } is LIVE" ) print ( f "Viewers: { client.room_info.get( 'user_count' , 0 ) } " ) print ( f "Title: { client.room_info.get( 'title' , 'No title' ) } " ) elif status == 4 : print ( f " { username } stream has ended" ) else : print ( f " { username } stream status: { status } " ) await client.disconnect() except Exception as e: print ( f "Error: { e } " ) if __name__ == '__main__' : asyncio.run(check_stream_status( "@username" ))
Complete Example from TikTokLive import TikTokLiveClient from TikTokLive.events import ConnectEvent, GiftEvent from TikTokLive.client.logger import LogLevel client = TikTokLiveClient( unique_id = "@username" , debug = True ) @client.on (ConnectEvent) async def on_connect ( event : ConnectEvent): print ( "=" * 50 ) print ( "CONNECTED TO STREAM" ) print ( "=" * 50 ) # Display room information if client.room_info: owner = client.room_info.get( 'owner' , {}) stats = client.room_info.get( 'stats' , {}) print ( f " \n Broadcaster: { owner.get( 'nickname' ) } (@ { owner.get( 'display_id' ) } )" ) print ( f "Room ID: { client.room_info.get( 'room_id' ) } " ) print ( f "Title: { client.room_info.get( 'title' , 'No title' ) } " ) print ( f "Current Viewers: { client.room_info.get( 'user_count' , 0 ) } " ) print ( f "Total Viewers: { stats.get( 'total_user_str' , '0' ) } " ) print ( f "Likes: { stats.get( 'like_count' , 0 ) } " ) print ( f "Followers: { owner.get( 'follower_count' , 0 ) } " ) # Display gift catalog summary if client.gift_info: gifts = client.gift_info.get( 'gifts' , []) print ( f " \n Gift Catalog: { len (gifts) } gifts available" ) # Show most expensive gifts expensive_gifts = sorted ( gifts, key = lambda g : g.get( 'diamond_count' , 0 ), reverse = True )[: 5 ] print ( " \n Top 5 Most Expensive Gifts:" ) for gift in expensive_gifts: print ( f " - { gift[ 'name' ] } : { gift[ 'diamond_count' ] } diamonds" ) print ( "=" * 50 ) @client.on (GiftEvent) async def on_gift ( event : GiftEvent): if client.gift_info: gift_details = next ( (g for g in client.gift_info.get( 'gifts' , []) if g[ 'id' ] == event.gift.id), None ) if gift_details: print ( f "🎁 { event.user.nickname } sent { gift_details[ 'name' ] } ( { gift_details[ 'diamond_count' ] } diamonds)" ) if __name__ == '__main__' : client.run( fetch_room_info = True , fetch_gift_info = True )
Best Practices
Error Handling Always check if room_info and gift_info are not None before accessing them.
Data Validation Use .get() with default values when accessing dictionary keys to avoid KeyErrors.
Performance Only fetch room/gift info when needed - it adds overhead to the connection process.
Caching Gift info rarely changes - consider caching it instead of fetching every time.
Room and gift info are only available after calling client.run() or client.start() with the respective fetch parameters set to True. They will be None otherwise.