TikTokLive.types package

Submodules

TikTokLive.types.errors module

exception TikTokLive.types.errors.AlreadyConnected

Bases: RuntimeError

Error that is raised when attempting to connect to a livestream whilst already connected.

exception TikTokLive.types.errors.AlreadyConnecting

Bases: RuntimeError

Error that is raised when attempting to connect to a livestream whilst already attempting to connect.

exception TikTokLive.types.errors.AlreadyDownloadingStream

Bases: DownloadStreamError

Error raised when already downloading a livestream and one attempts to start a second download

exception TikTokLive.types.errors.ChatMessageRepeat

Bases: ChatMessageSendFailure

Error raised when someone repeats a chat message

exception TikTokLive.types.errors.ChatMessageSendFailure

Bases: RuntimeError

Error raised when a TikTok chat message fails to send

exception TikTokLive.types.errors.DownloadProcessNotFound

Bases: DownloadStreamError

Error raised when stopping a download and the process is not found. Usually, you’re stopping it before the process spawns

exception TikTokLive.types.errors.DownloadStreamError

Bases: RuntimeError

Error raised broadly for anything relating to downloading streams

exception TikTokLive.types.errors.FailedConnection

Bases: RuntimeError

Error that is raised when the connection to a livestream fails (generic).

exception TikTokLive.types.errors.FailedFetchGifts

Bases: FailedHTTPRequest

Error raised when fetching gifts encounters an exception

exception TikTokLive.types.errors.FailedFetchRoomInfo

Bases: FailedHTTPRequest

Error raised when failing to fetch room info

exception TikTokLive.types.errors.FailedHTTPRequest

Bases: RuntimeError

Error raised whenever a request fails to HTTP [Generic]

exception TikTokLive.types.errors.FailedParseUserHTML

Bases: FailedFetchRoomInfo

Error raised when failing to parse room html to retrieve the Room ID of the stream

exception TikTokLive.types.errors.FailedRoomPolling

Bases: FailedHTTPRequest

Error raised when room polling encounters an exception

exception TikTokLive.types.errors.InitialCursorMissing

Bases: FailedConnection

Error that is raised when the initial cursor is missing

exception TikTokLive.types.errors.InvalidSessionId

Bases: RuntimeError

Error raised when a session ID is expired or missing

exception TikTokLive.types.errors.LiveNotFound

Bases: RuntimeError

Error that is raised when the livestream you are trying to connect to is offline/does-not-exist.

exception TikTokLive.types.errors.NotDownloadingStream

Bases: DownloadStreamError

Error raised when trying to stop downloading a livestream you are not currently downloading

exception TikTokLive.types.errors.SignatureRateLimitReached

Bases: FailedHTTPRequest

When a user hits the signature rate limit

exception TikTokLive.types.errors.SignatureSigningError

Bases: FailedHTTPRequest

When the sign server fails to return a valid payload

exception TikTokLive.types.errors.WebsocketConnectionFailed

Bases: RuntimeError

Raised when a connection to the TikTok Webcast websocket fails

TikTokLive.types.events module

class TikTokLive.types.events.AbstractEvent(data: dict = {})

Bases: object

Abstract Event

property as_dict: dict

Return a copy of the object as a dictionary

Returns:

A copy of the raw payload

name: str = 'event'
set_as_dict(data: dict)

Set that _as_dict attribute

Parameters:

data – The data to set it to

Returns:

None

class TikTokLive.types.events.CommentEvent(user: Optional[User], comment: Optional[str], name: str = 'comment')

Bases: AbstractEvent

Event that fires when someone comments on the livestream

comment: Optional[str]

The UTF-8 text comment that was sent

name: str = 'comment'
user: Optional[User]

The user that sent the comment

class TikTokLive.types.events.ConnectEvent(name: str = 'connect')

Bases: AbstractEvent

Event that fires when the client connect to a livestream

name: str = 'connect'
class TikTokLive.types.events.DisconnectEvent(name: str = 'disconnect')

Bases: AbstractEvent

Event that fires when the client disconnects from a livestream

name: str = 'disconnect'
class TikTokLive.types.events.EmoteEvent(user: Optional[User], emote: Optional[Emote], name: str = 'emote')

Bases: AbstractEvent

Event that fires when someone sends a subscriber emote

emote: Optional[Emote]

The emote the person sent

name: str = 'emote'
user: Optional[User]

Person who sent the emote message

class TikTokLive.types.events.EnvelopeEvent(treasureBoxData: Optional[TreasureBoxData], treasureBoxUser: Optional[User], name: str = 'envelope')

Bases: AbstractEvent

Event that fire when someone sends an envelope

name: str = 'envelope'
treasureBoxData: Optional[TreasureBoxData]

Data about the enclosed Treasure Box in the envelope

treasureBoxUser: Optional[User]

Data about the user that sent the treasure box

class TikTokLive.types.events.FollowEvent(user: Optional[User], displayType: Optional[str], label: Optional[str], name: str = 'follow')

Bases: AbstractEvent

Event that fires when a user follows the livestream

displayType: Optional[str]
label: Optional[str]
name: str = 'follow'
user: Optional[User]

The user that followed the streamer

class TikTokLive.types.events.GiftEvent(user: Optional[User], gift: Optional[Gift], name: str = 'gift')

Bases: AbstractEvent

Event that fires when a gift is received

gift: Optional[Gift]

Object containing gift data

name: str = 'gift'
user: Optional[User]

The user that sent the gift

class TikTokLive.types.events.JoinEvent(user: Optional[User], displayType: Optional[str], label: Optional[str], name: str = 'join')

Bases: AbstractEvent

Event that fires when a user joins the livestream

displayType: Optional[str]

The type of event

label: Optional[str]

Label for event in live chat

name: str = 'join'
property through_share: bool

Whether they joined through a link vs. the TikTok App

Returns:

Returns True if they joined through a share link

user: Optional[User]

The user that joined the stream

class TikTokLive.types.events.LikeEvent(user: Optional[User], likeCount: Optional[int], totalLikeCount: Optional[int], displayType: Optional[str], label: Optional[str], name: str = 'like')

Bases: AbstractEvent

Event that fires when a user likes the livestream

displayType: Optional[str]
label: Optional[str]
likeCount: Optional[int]

The number of likes they sent (I think?)

name: str = 'like'
totalLikeCount: Optional[int]

The total number of likes on the stream

user: Optional[User]

The user that liked the stream

class TikTokLive.types.events.LiveEndEvent(name: str = 'live_end')

Bases: AbstractEvent

Event that fires when the livestream ends

name: str = 'live_end'
class TikTokLive.types.events.MicArmiesEvent(battleStatus: ~typing.Optional[int], battleUsers: ~typing.List[~TikTokLive.types.objects.MicArmiesUser] = <factory>, name: str = 'mic_armies')

Bases: AbstractEvent

Event that fires during a Mic Battle to update its progress

battleStatus: Optional[int]

The status of the current Battle

battleUsers: List[MicArmiesUser]

Information about the users engaged in the Mic Battle

name: str = 'mic_armies'
class TikTokLive.types.events.MicBattleEvent(battleUsers: ~typing.List[~TikTokLive.types.objects.MicBattleUser] = <factory>, name: str = 'mic_battle')

Bases: AbstractEvent

Event that fires when a Mic Battle starts

battleUsers: List[MicBattleUser]

Information about the users engaged in the Mic Battle

name: str = 'mic_battle'
class TikTokLive.types.events.MoreShareEvent(user: Optional[User], displayType: Optional[str], label: Optional[str], name: str = 'more_share')

Bases: ShareEvent

Event that fires when a user shared the livestream more than 5 users or more than 10 users

“user123 has shared to more than 10 people!”

property amount: Optional[int]

The number of people that have joined the stream off the user

Returns:

The number of people that have joined

name: str = 'more_share'
class TikTokLive.types.events.QuestionEvent(questionText: Optional[str], user: Optional[User], name: str = 'question')

Bases: AbstractEvent

Event that fires when someone asks a Q&A question

name: str = 'question'
questionText: Optional[str]

The question that was asked

user: Optional[User]

User who asked the question

class TikTokLive.types.events.ShareEvent(user: Optional[User], displayType: Optional[str], label: Optional[str], name: str = 'share')

Bases: AbstractEvent

Event that fires when a user shares the livestream

displayType: Optional[str]

Type of event

label: Optional[str]

Internal Webcast Label

name: str = 'share'
user: Optional[User]

The user that shared the stream

class TikTokLive.types.events.SubscribeEvent(user: Optional[User], exhibitionType: Optional[int], subscribeType: Optional[int], oldSubScribeStatus: Optional[int], subscribingStatus: Optional[int], name: str = 'subscribe')

Bases: AbstractEvent

Event that fires when someone subscribes to the streamer

exhibitionType: Optional[int]

Unknown

name: str = 'subscribe'
oldSubScribeStatus: Optional[int]

Whether they were subscribed before

subscribeType: Optional[int]

Unknown

subscribingStatus: Optional[int]

Whether they are subscribing now

user: Optional[User]

The user that subscribed to the streamer

class TikTokLive.types.events.UnknownEvent(name: str = 'unknown')

Bases: AbstractEvent

Event that fires when an event is received that is not handled by other events in the library.

name: str = 'unknown'
class TikTokLive.types.events.ViewerCountUpdateEvent(viewerCount: Optional[int], name: str = 'viewer_count_update')

Bases: AbstractEvent

Event that fires when the viewer count for the livestream updates

name: str = 'viewer_count_update'
viewerCount: Optional[int]

The number of people viewing the stream currently

class TikTokLive.types.events.WeeklyRankingEvent(data: Optional[RankContainer], name: str = 'weekly_ranking')

Bases: AbstractEvent

Event that fires when the weekly rankings are updated

data: Optional[RankContainer]

Weekly ranking data

name: str = 'weekly_ranking'

TikTokLive.types.objects module

class TikTokLive.types.objects.AbstractObject

Bases: object

Abstract Object

class TikTokLive.types.objects.Avatar(urls: List[str])

Bases: AbstractObject

The URLs to the avatar of a TikTok User

property avatar_url

The last (highest quality) avatar URL supplied

urls: List[str]
class TikTokLive.types.objects.Badge(type: Optional[str], name: Optional[str])

Bases: AbstractObject

User badges (e.g moderator)

name: Optional[str]

The name for the badge

type: Optional[str]

The type of badge

class TikTokLive.types.objects.BadgeContainer(imageBadges: ~typing.List[~TikTokLive.types.objects.ImageBadge] = <factory>, badges: ~typing.List[~TikTokLive.types.objects.Badge] = <factory>)

Bases: AbstractObject

Badge container housing a list of user badges

badges: List[Badge]

A list of text badges the user has (e.g. Moderator/Friend badge)

imageBadges: List[ImageBadge]

A list of image badges the user has (e.g. Subscriber badge)

class TikTokLive.types.objects.Emote(emoteId: Optional[str], image: Optional[EmoteImage])

Bases: object

The Emote a user sent in the chat

emoteId: Optional[str]

ID of the TikTok Emote

image: Optional[EmoteImage]

Container encapsulating the image URL for the sent Emote

class TikTokLive.types.objects.EmoteImage(imageUrl: Optional[str])

Bases: object

Container encapsulating the image URL for the Emote

imageUrl: Optional[str]

TikTok CDN link to the given Emote for the streamer

class TikTokLive.types.objects.ExtendedGift(id: Optional[int], name: Optional[str], type: Optional[int], diamond_count: Optional[int], describe: Optional[str], duration: Optional[int], event_name: Optional[str], icon: Optional[GiftIcon], image: Optional[GiftIcon], notify: Optional[bool], is_broadcast_gift: Optional[bool], is_displayed_on_panel: Optional[bool], is_effect_befview: Optional[bool], is_random_gift: Optional[bool], is_gray: Optional[bool])

Bases: AbstractObject

Extended gift data for a gift including a whole lotta extra properties.

describe: Optional[str]
diamond_count: Optional[int]

The currency (Diamond) value of the item

duration: Optional[int]
event_name: Optional[str]
icon: Optional[GiftIcon]
id: Optional[int]

The ID of the gift

image: Optional[GiftIcon]
is_broadcast_gift: Optional[bool]
is_displayed_on_panel: Optional[bool]
is_effect_befview: Optional[bool]
is_gray: Optional[bool]
is_random_gift: Optional[bool]
name: Optional[str]

The name of the gift

notify: Optional[bool]
type: Optional[int]

The type of gift

class TikTokLive.types.objects.ExtraAttributes(followRole: ~typing.Optional[int] = <factory>)

Bases: AbstractObject

Extra attributes on the User Object (e.g. following status)

followRole: Optional[int]
class TikTokLive.types.objects.FFmpegWrapper(runtime: Optional[str], thread: Thread, ffmpeg: FFmpeg, verbose: bool, path: str, started_at: int = -1)

Bases: object

A wrapper for the FFmpeg Stream Download utility in the TikTokLive Package

ffmpeg: FFmpeg

The ffmpy FFmpeg object in which a subprocess is spawned to download

path: str

The path to download the video to

runtime: Optional[str]

FFMpeg argument for how long to download for

started_at: int = -1

The time at which the download began

thread: Thread

The thread object in which a download is occuring

verbose: bool

Whether to include logging messages about the status of the download

class TikTokLive.types.objects.Gift(giftId: Optional[int], repeatCount: Optional[int], repeatEnd: Optional[int], giftDetails: Optional[GiftDetails], giftExtra: Optional[GiftExtra], extended_gift: Optional[ExtendedGift])

Bases: AbstractObject

Gift object containing information about a given gift

extended_gift: Optional[ExtendedGift]

Extended gift including extra data (not very important as of april 2022)

giftDetails: Optional[GiftDetails]

Details about the specific Gift sent

giftExtra: Optional[GiftExtra]

Details like who the gift was sent to (multi-user streams)

giftId: Optional[int]

The Internal TikTok ID of the gift

property gift_type: int

Alias for the giftDetails.giftType for backwards compatibility

Returns:

giftType Value

repeatCount: Optional[int]

Number of times the gift has repeated

repeatEnd: Optional[int]

Whether or not the repetition is over

property repeat_count: int

Alias for repeatCount for backwards compatibility

Returns:

repeatCount Value

property repeat_end: int

Alias for repeatEnd for backwards compatibility

Returns:

repeatEnd Value

property streakable: bool

Whether a given gift can have a streak

Returns:

True if it is type 1, otherwise False

property streaking: bool

Whether the streak is over

Returns:

True if currently streaking, False if not

class TikTokLive.types.objects.GiftDetailImage(giftPictureUrl: Optional[str])

Bases: AbstractObject

Gift image

giftPictureUrl: Optional[str]

Icon URL for the Gift

class TikTokLive.types.objects.GiftDetails(giftImage: Optional[GiftDetailImage], describe: Optional[str], giftType: Optional[int], diamondCount: Optional[int], giftName: Optional[str])

Bases: AbstractObject

Details about a given gift

describe: Optional[str]

Describes the gift

diamondCount: Optional[int]

Diamond value of 1 of the gift

giftImage: Optional[GiftDetailImage]

Image container for the Gift

giftName: Optional[str]

Name of the gift

giftType: Optional[int]

The type of gift. Type 1 are repeatable, any other type are not.

class TikTokLive.types.objects.GiftExtra(timestamp: Optional[int], receiverUserId: Optional[int])

Bases: object

Gift object containing information about the gift recipient

receiverUserId: Optional[int]

The user that received the gift

timestamp: Optional[int]

The time the gift was sent

class TikTokLive.types.objects.GiftIcon(avg_color: Optional[str], uri: Optional[str], is_animated: Optional[bool], url_list: Optional[List[str]])

Bases: AbstractObject

Icon data for a given gift (such as its image URL)

avg_color: Optional[str]
is_animated: Optional[bool]

Whether or not it is an animated icon

uri: Optional[str]
url_list: Optional[List[str]]

A list of URLs containing various sizes of the gift’s icon

class TikTokLive.types.objects.ImageBadge(displayType: Optional[int], image: Optional[ImageBadgeImage])

Bases: object

” Image Badge object containing an image badge for a TikTok User

displayType: Optional[int]

The displayType of the badge

image: Optional[ImageBadgeImage]

Container for the image badge

class TikTokLive.types.objects.ImageBadgeImage(url: Optional[str])

Bases: object

Image container with the URL of the user badge

url: Optional[str]

The TikTok CDN Image URL for the badge

class TikTokLive.types.objects.LinkUser(userId: Optional[int], nickname: Optional[str], profilePicture: Optional[Avatar], uniqueId: Optional[str])

Bases: object

A user in a TikTok LinkMicBattle (TikTok Battle Events)

nickname: Optional[str]

User’s Nickname

profilePicture: Optional[Avatar]

User’s Profile Picture

uniqueId: Optional[str]

The uniqueId of the user

userId: Optional[int]

userId of the user

class TikTokLive.types.objects.MemberMessage(eventDetails: Optional[MemberMessageDetails])

Bases: object

Container encapsulating the member message details

eventDetails: Optional[MemberMessageDetails]
class TikTokLive.types.objects.MemberMessageDetails(displayType: Optional[str], label: Optional[str])

Bases: object

Details about a given member message proto event

displayType: Optional[str]

The displayType of the message corresponding to the type of member message

label: Optional[str]

Display Label for the member message

class TikTokLive.types.objects.MicArmiesGroup(points: ~typing.Optional[int], users: ~typing.List[~TikTokLive.types.objects.User] = <factory>)

Bases: object

A group containing

points: Optional[int]

The number of points the person has

users: List[User]

(Presumably) the users involved in the battle

class TikTokLive.types.objects.MicArmiesUser(hostUserId: Optional[int], battleGroups: Optional[MicArmiesGroup])

Bases: object

Information about the Mic Armies User

battleGroups: Optional[MicArmiesGroup]

Information about the users involved in the battle

hostUserId: Optional[int]

The user ID of the TikTok host

class TikTokLive.types.objects.MicBattleGroup(user: LinkUser)

Bases: object

A container encapsulating LinkUser data for TikTok Battles

user: LinkUser

The TikTok battle LinkUser

class TikTokLive.types.objects.MicBattleUser(battleGroup: MicBattleGroup)

Bases: object

A container encapsulating the LinkUser data for TikTok Battles

battleGroup: MicBattleGroup
class TikTokLive.types.objects.RankContainer(rankings: Optional[WeeklyRanking])

Bases: object

Container encapsulating weekly ranking data

rankings: Optional[WeeklyRanking]
class TikTokLive.types.objects.RankItem(colour: Optional[str], id: Optional[int])

Bases: object

Rank Item for the user ranking

colour: Optional[str]

Colour that the rank corresponds to (for the UI)

id: Optional[int]

The rank. If id=400, they are in the Top 400

class TikTokLive.types.objects.TreasureBoxData(coins: Optional[int], canOpen: Optional[int], timestamp: Optional[int])

Bases: object

Information about the gifted treasure box

canOpen: Optional[int]

Whether the treasure box can be opened

coins: Optional[int]

Coins of the treasure box

timestamp: Optional[int]

Timestamp for when the treasure box was sent

class TikTokLive.types.objects.User(userId: ~typing.Optional[int], uniqueId: ~typing.Optional[str], nickname: ~typing.Optional[str], profilePicture: ~typing.Optional[~TikTokLive.types.objects.Avatar], extraAttributes: ~TikTokLive.types.objects.ExtraAttributes = <factory>, badges: ~typing.List[~TikTokLive.types.objects.BadgeContainer] = <factory>)

Bases: AbstractObject

User object containing information on a TikTok User

badges: List[BadgeContainer]

Badges for the user containing information such as if they are a stream moderator

extraAttributes: ExtraAttributes

Extra attributes for the user such as if they are following the streamer

property is_following: bool

Whether they are following the watched streamer

property is_friend: bool

Whether they are a friend of the watched streamer

property is_moderator: bool

Whether they are a moderator for the watched streamer

property is_new_gifter: bool

Whether they are a new gifter in the streamer’s stream

property is_subscriber: bool

Whether they are a subscriber in the watched stream

nickname: Optional[str]

The user’s nickname (e.g Charlie d’Amelio)

profilePicture: Optional[Avatar]

An object containing avatar url information

property top_gifter_rank: Optional[int]

Their top gifter rank if they are a top gifter

uniqueId: Optional[str]

The user’s uniqueId (e.g @charlidamelio)

userId: Optional[int]

The user’s user id

class TikTokLive.types.objects.WeeklyRanking(type: Optional[str], label: Optional[str], rank: Optional[RankItem])

Bases: object

Container with the weekly ranking data

label: Optional[str]

Label for the UI

rank: Optional[RankItem]

The weekly ranking data

type: Optional[str]

Unknown

Module contents