YouTube Data Types

class ayt_api.types.UseExisting[source]

Bases: object

A dummy class that is used to indicate when updating an object to use the previous existing values

Added in version 0.4.0.

class ayt_api.types.YoutubeThumbnail(url: str | None, _call_data: Any, width: int | None = None, height: int | None = None)[source]

Bases: object

Data for an individual YouTube thumbnail.

url

The file url for the thumbnail.

Type:

Optional[str]

width

The amount of horizontal pixels in the thumbnail.

Type:

Optional[int]

height

The amount of vertical pixels in the thumbnail.

Type:

Optional[int]

resolution

The Width x Height of the thumbnail.

Type:

str

size

An alias of resolution

Type:

str

async download() → bytes[source]

Downloads the thumbnail and stores it as a bytes object

Returns:

The image as a bytes object

Return type:

bytes

Raises:
async save(fp: str | PathLike | None = None)[source]

Downloads the thumbnail and saves it to a specified location

Parameters:

fp (os.PathLike | str) – The path and/or filename to save the file to. Defaults to current working directory with the filename format: {video_id}-{quality}.png

Raises:
class ayt_api.types.YoutubeBanner(url: str | None, _call_data: Any)[source]

Bases: object

Data for an individual YouTube banner.

url

The file url for the banner.

Type:

Optional[str]

async download(width: int | None = None) → tuple[bytes, str][source]

Downloads the banner and stores it as a bytes object

Parameters:

width (Optional[int]) – The width or number of horizontal pixels the downloaded image should have.

Returns:

A list containing the image as a bytes object and the file extension of

the image

Return type:

tuple[bytes, str]

Raises:
async save(fp: str | PathLike | None = None, width: int = None)[source]

Downloads the banner specified and saves it to a specified location

Parameters:

  • fp (os.PathLike | str) – The path and/or filename to save the file to. Defaults to current working directory with the filename format: {banner_id}.{extension}

  • width (Optional[int]) – The width or number of horizontal pixels the downloaded image should have.

Raises:
sized_url(width: int) → str[source]

Return a URL which will give the size specified.

Parameters:

width (int) – The width or number of horizontal pixels the downloaded image should have.

Returns:

The url with the width argument.

Return type:

str

class ayt_api.types.YoutubeThumbnailMetadata(thumbnail_metadata: dict, call_data, etag: str | None = None)[source]

Bases: object

Data for the available thumbnails of a video.

metadata

The raw thumbnail metadata to construct the class.

Type:

dict

etag
Type:

Optional[str]

available

Tells what thumbnails are available with the video

Type:

tuple[str]

highest_available() → str | None[source]

Helper function to get the highest resolution out of the thumbnails available

Returns:

The name of the highest available thumbnail format

Return type:

Optional[str]

property highest: YoutubeThumbnail | None

Helper property that provided the highest resolution out of the thumbnails available

Returns:

The thumbnail with the highest resolution available

Return type:

Optional[YoutubeThumbnail]

property default: YoutubeThumbnail | None

The default video thumbnail. The value is not guaranteed and could be None.

This is the most guaranteed to actually return a thumbnail.

Returns:

A YouTube thumbnail object. Could be None.

Return type:

Optional[YoutubeThumbnail]

property medium: YoutubeThumbnail | None

The medium video thumbnail. The value is not guaranteed and could be None.

Returns:

A YouTube thumbnail object. Could be None.

Return type:

Optional[YoutubeThumbnail]

property high: YoutubeThumbnail | None

The high video thumbnail. The value is not guaranteed and could be None.

Returns:

A YouTube thumbnail object. Could be None.

Return type:

Optional[YoutubeThumbnail]

property standard: YoutubeThumbnail | None

The standard video thumbnail. The value is not guaranteed and could be None.

Returns:

A YouTube thumbnail object. Could be None.

Return type:

Optional[YoutubeThumbnail]

property maxres: YoutubeThumbnail | None

The maximum resolution video thumbnail. The value is not guaranteed and could be None.

Returns:

A YouTube thumbnail object. Could be None.

Return type:

Optional[YoutubeThumbnail]

class ayt_api.types.LocalName(title: str, description: str = None, language: str = None)[source]

Bases: object

Represents the video title and description in a local language if available.

language

The language code.

Type:

Optional[str]

title

The title in a local language.

Type:

str

description

The description in a local language.

Type:

Optional[str]

class ayt_api.types.RegionRestrictions(allowed: list[str] = None, blocked: list[str] = None)[source]

Bases: object

Represents information about the countries where a video is (or is not) viewable.

allowed

The countries that are allowed to view the video. Could be None.

Type:

Optional[list[str]]

blocked

The countries that are blocked from viewing the video. Could be None.

Type:

Optional[list[str]]

class ayt_api.types.ContentRating(data: dict)[source]

Bases: object

Specifies the ratings that the video received under various rating schemes.

There are many attributes for each rating system, only 1 or 2 (if there is a reason) will be available, the rest will be None or all if there is no restrictions set. The attributes documented below are non-exhaustive.

acb

The video’s Australian Classification Board (ACB) or Australian Communications and Media Authority (ACMA) rating. ACMA ratings are used to classify children’s television programming.

Type:

Optional[AcbRating]

youtube

A rating that YouTube uses to identify age-restricted content.

Type:

Optional[str]

class ayt_api.types.RecordingLocation(latitude: float, longitude: float, altitude: float)[source]

Bases: object

The geolocation information associated with the video. if specified by the video uploader.

latitude

Latitude in degrees.

Type:

float

longitude

Longitude in degrees.

Type:

float

altitude

Altitude above the reference ellipsoid, in meters.

Type:

float

class ayt_api.types.RecordingDetails(data: dict)[source]

Bases: object

Contains details of the location and date of the video recording if specified by the video uploader.

data

The raw information about the location, date and address where the video was recorded.

Type:

dict

description

The text description of the location where the video was recorded.

Type:

Optional[str]

location

The geolocation information associated with the video.

Type:

Optional[RecordingLocation]

date

The date and time when the video was recorded.

Type:

Optional[datetime.datetime]

class ayt_api.types.VideoStream(data: dict)[source]

Bases: object

Metadata about a video stream for a YouTube video.

data

The raw video stream data used to construct this class.

Type:

dict

width

The encoded video content’s width in pixels.

Type:

int

height

The encoded video content’s height in pixels.

Type:

int

resolution

width x height.

Type:

str

frame_rate

The video stream’s frame rate, in frames per second.

Type:

float

aspect_ratio

The video content’s display aspect ratio.

Type:

float

codec

The video codec that the stream uses.

Type:

str

bitrate

The video stream’s bitrate, in bits per second.

Type:

int

rotation

The amount that YouTube needs to rotate the original source content to properly display the video.

Type:

Optional[str]

vendor

A value that uniquely identifies a video vendor. Typically, the value is a four-letter vendor code.

Type:

Optional[str]

class ayt_api.types.AudioStream(data: dict)[source]

Bases: object

Metadata about an audio stream for a YouTube video.

data

The raw audio stream data used to construct this class.

Type:

dict

channel_count

The number of audio channels that the stream contains.

Type:

int

codec

The audio codec that the stream uses.

Type:

str

bitrate

The audio stream’s bitrate, in bits per second.

Type:

int

vendor

A value that uniquely identifies a video vendor. Typically, the value is a four-letter vendor code.

Type:

Optional[str]

class ayt_api.types.ProcessingProgress(data: dict)[source]

Bases: object

Contains information about the progress YouTube has made in processing the video.

data

The raw processing progress data used to construct this class.

Type:

dict

parts_total

An estimate of the total number of parts that need to be processed for the video.

Type:

int

parts_processed

The number of parts of the video that YouTube has already processed.

Type:

int

time_left

An estimate of the amount of time, in milliseconds, that YouTube needs to finish processing the video.

Type:

Optional[datetime.timedelta]

percentage

The percentage of the video that has been processed.

Type:

int

class ayt_api.types.TagSuggestion(data: dict)[source]

Bases: object

A list of keyword tags that could be added to the video’s metadata to increase the likelihood that users will

locate your video when searching or browsing on YouTube.

data

The raw tag suggestions data used to construct this class.

Type:

dict

tag

The keyword tag suggested for the video.

Type:

str

category_restricts

A set of video categories for which the tag is relevant.

Type:

Optional[list[str]]

class ayt_api.types.VideoChapter(start: timedelta, duration: timedelta, name: str)[source]

Bases: object

The start time, duration and name of a YouTube video chapter.

start

The start time of the chapter in seconds.

Type:

int

duration

(int): The length of the chapter in seconds.

Type:

datetime.timedelta

name

The name of the chapter.

Type:

str

class ayt_api.types.BaseVideo(metadata: dict, call_url: str, etag: str, id: str, url: str, title: str, description: str, visibility: PrivacyStatus)[source]

Bases: object

The base class that all video related objects are inherited from.

metadata

The raw metadata from the API response used to construct this class. Intended use is for debugging purposes.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

etag

The Etag of this resource.

Type:

str

id

The ID of the video. Example: “dQw4w9WgXcQ” from the url: “https://www.youtube.com/watch?v=dQw4w9WgXcQ”. Look familiar?

Type:

str

url

The URL of the video.

Type:

str

title

The title of the video.

Type:

str

description

The description of the video.

Type:

str

thumbnails

The available thumbnails the video has.

Type:

YoutubeThumbnailMetadata

visibility

The video’s privacy status. Can be PrivacyStatus.private, PrivacyStatus.public or PrivacyStatus.unlisted.

Type:

PrivacyStatus

thumbnails

alias of YoutubeThumbnailMetadata

class ayt_api.types.DummyObject(metadata: dict, call_url: str, call_data)[source]

Bases: object

This is used for debugging only.

class ayt_api.types.YoutubeVideo(metadata: dict, call_url: str, call_data)[source]

Bases: BaseVideo

A data class containing video data such as the title, id, description, channel, etc.

metadata

The raw metadata from the API response used to construct this class. Intended use is for debugging purposes.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

etag

The Etag of this resource.

Type:

str

id

The ID of the video. Example: “dQw4w9WgXcQ” from the url: “https://www.youtube.com/watch?v=dQw4w9WgXcQ”. Look familiar?

Type:

str

snippet

The raw snippet data used to construct part this class.

Type:

dict

content_details

The raw content details data used to construct part of this class.

Type:

dict

status

The raw status data used to construct part of this class.

Type:

dict

statistics

The raw statistics data used to construct part of this class.

Type:

dict

player

The raw player data used to construct part of this class.

Type:

dict

topic_details

The raw topic details used to construct part of this class.

Type:

Optional[dict]

raw_recording_details

The raw recording details used to construct part of this class.

Type:

dict

raw_localisations

The raw localisation data used to construct part of this class.

Type:

Optional[dict]

paid_product_placement_details

The paid product placement details data used to construct part of this class.

Type:

dict

url

The URL of the video.

Type:

str

title

The title of the video.

Type:

str

description

The description of the video.

Type:

str

published_at

The date and time the video was published.

Type:

datetime.datetime

thumbnails

The available thumbnails the video has.

Type:

YoutubeThumbnailMetadata

channel_title

The name of the channel that the video belongs to.

Type:

Optional[str]

channel_id

The id of the channel that the video belongs to.

Type:

Optional[str]

channel_url

The url of the channel that the video belongs to.

Type:

Optional[str]

tags

The tags the uploaded has provided to make the video appear in search results relating to it.

Type:

Optional[list[str]]

category_id

The id of the category that was set for the video.

Changed in version 0.4.0: category_id is now a str rather than an int

Type:

str

live_broadcast_content

Indicates if the video is a livestream and if it is live.

Type:

LiveBroadcastContent

default_language

The default language the video is set in. The value is a BCP-47 language code.

Type:

Optional[str]

localised

The localised language of the title and description of the video.

Type:

Optional[LocalName]

localized

an alias of localised.

Type:

Optional[LocalName]

default_audio_language

The default audio language the video is set in. The value is a BCP-47 language code.

Type:

Optional[str]

duration

The length of the video.

Type:

Union[isodate.Duration, datetime.timedelta, _NotImplementedType]

dimension

Indicates whether the video is available in 3D or in 2D.

Type:

str

definition

Indicates whether the video is available in high definition (HD) or only in standard definition.

Type:

VideoDefinition

has_captions

Indicates whether captions are available for the video.

Type:

bool

licensed_content

Indicates whether the video represents licensed content, which means that the content was uploaded to a channel linked to a YouTube content partner and then claimed by that partner.

Type:

bool

region_restrictions

contains information about the countries where a video is (or is not) viewable. Can be None.

Type:

Optional[RegionRestrictions]

content_rating

Specifies the ratings that the video received under various rating schemes.

Type:

ContentRating

age_restricted

Whether the video is age restricted or not.

Type:

bool

projection

Specifies the projection format of the video (example: 360 or rectangular).

Type:

Optional[VideoProjection]

upload_status

The status of the uploaded video.

Type:

Optional[UploadStatus]

failure_reason

Explains why a video failed to upload. This attribute is only present if the upload_status attribute is set to UploadStatus.failed.

Type:

Optional[UploadFailureReason]

rejection_reason

Explains why YouTube rejected an uploaded video. This attribute is only present if the upload_status attribute is set to UploadStatus.rejected.

Type:

Optional[UploadRejectionReason]

visibility

The video’s privacy status. Can be PrivacyStatus.private, PrivacyStatus.public or PrivacyStatus.unlisted.

Type:

PrivacyStatus

publish_set_at

The date and time when the video is scheduled to publish if any.

Type:

Optional[datetime.datetime]

license

The video’s license. valid values for this attribute is License.creative_common and License.youtube.

Type:

Optional[License]

embeddable

Indicates whether the video can be embedded on another website.

Type:

bool

public_stats_viewable

Indicates whether the extended video statistics on the video’s watch page are publicly viewable.

Type:

bool

made_for_kids

Indicates whether the video is designated as child-directed, and it contains the current “made for kids” status of the video.

Type:

Optional[bool]

contains_synthetic_media

If the video contain realistic Altered or Synthetic (A/S) content.

Note

This attribute will not be set unless setting the value via updating this class.

Type:

Optional[bool]

view_count

The number of times the video has been viewed.

Type:

int

like_count

The number of users who have indicated that they liked the video.

Type:

Optional[int]

comment_count

The number of comments on the video. This attribute is None if disabled

Type:

Optional[int]

embed_html

An <iframe> tag that embeds a player that plays the video.

Type:

Optional[str]

embed_height

The height of the embedded player returned to the embed_html attribute. Is None unless the height and aspect ratio is known.

Type:

Optional[str]

embed_width

The width of the embedded player returned to the embed_html attribute. Is None unless the width and aspect ratio is known.

Type:

Optional[str]

topic_categories

A list of Wikipedia URLs that provide a high-level description of the video’s content.

Type:

Optional[list[str]]

recording_details

Encapsulates information about the location, date and address where the video was recorded.

Type:

RecordingDetails

stream_actual_start_time

The time that the broadcast actually started.

Type:

Optional[datetime.datetime]

stream_scheduled_start_time

The time that the broadcast is scheduled to begin.

Type:

Optional[datetime.datetime]

stream_actual_end_time

The time that the broadcast actually ended.

Type:

Optional[datetime.datetime]

stream_scheduled_end_time

The time that the broadcast is scheduled to end.

Type:

Optional[datetime.datetime]

stream_concurrent_viewers

The number of viewers currently watching the broadcast.

Type:

Optional[int]

stream_active_live_chat_id

The ID of the currently active live chat attached to this video.

Type:

Optional[str]

localisations

Contains translations of the video’s metadata.

Type:

Optional[list[LocalName]]

localizations

An alias of localisations.

Type:

Optional[list[LocalName]]

has_paid_product_placement

Set to True if the content uses paid product placement. Defaults to False.

Type:

bool

async fetch_channel() → YoutubeChannel | None[source]

Fetches the channel associated with the video.

This ia an api call which then returns a YoutubeChannel object.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The channel object containing data of the channel.

Return type:

Optional[YoutubeChannel]

Raises:
async fetch_comments(max_comments: int | None = 50) → list[YoutubeCommentThread][source]

Fetches a list of comments on the video.

This ia an api call which then returns a list[YoutubeCommentThread] object.

Quota Impact

A call to this method has a quota cost of 1 unit per call or per 50 comments fetched.

Returns:

A list of comments on the video.

Return type:

list[YoutubeCommentThread]

Raises:
async fetch_captions() → list[VideoCaption][source]

Fetches a list of captions on the video.

This ia an api call which then returns a list[VideoCaption] object.

Quota Impact

A call to this method has a quota cost of 50 units per call or per 50 captions fetched.

Returns:

A list of captions on the video.

Return type:

list[VideoCaption]

Raises:
async fetch_category() → YoutubeVideoCategory[source]

Fetches the category that has been or could be associated with the video.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Added in version 0.4.0.

Returns:

The video category

Return type:

YoutubeVideoCategory

Raises:
property chapters: list[VideoChapter] | None

A list of chapters the video has if any otherwise just an empty list.

Returns:

A list of chapters the video has if any otherwise None.

Return type:

chapters (list[VideoChapter])

current_chapter(position: timedelta) → VideoChapter | None[source]

Gets the current chapter based on the position provided.

Parameters:

position (datetime.timedelta) – The position of the video to get the current chapter from.

Returns:

The current video chapter at that position of the video. Returns None if either

the video doesn’t have any chapters or the position is greater than the duration of the video or is negative.

Return type:

Optional[VideoChapter]

class ayt_api.types.PlaylistItem(metadata: dict, call_url: str, call_data)[source]

Bases: BaseVideo

A data class for videos in a playlist.

metadata

The raw metadata from the API call used to construct this class.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

etag

The Etag of this resource.

Type:

str

id

The id that represents the playlist item resource.

Type:

str

resource_id

Contains information that can be used to uniquely identify the resource that is included in the playlist as the playlist item.

Type:

dict

video_id

The ID of the video in the playlist. Example: “dQw4w9WgXcQ” from the url: “https://www.youtube.com/watch?v=dQw4w9WgXcQ”. Look familiar?

Type:

str

position

The position in the playlist the video is in.

Type:

int

url

The URL of the video.

Type:

str

title

The title of the video.

Type:

str

description

The description of the video.

Type:

str

added_at

The date and time the video was added to the playlist.

Type:

datetime.datetime

thumbnails

The available thumbnails the video has.

Type:

YoutubeThumbnailMetadata

channel_title

The name of the channel that the video belongs to.

Type:

Optional[str]

channel_id

The id of the channel that the video belongs to.

Type:

Optional[str]

channel_url

The url of the channel that the video belongs to.

Type:

Optional[str]

playlist_id

The ID of the playlist the video is in.

Type:

str

playlist_url

The URL of the playlist the video is in.

Type:

str

published_at

The date and time the video was published.

Type:

datetime.datetime

available

Whether the video in the playlist is playable hasn’t been deleted or made private. This is determined by checking if the video has an upload date.

Type:

bool

note

A user-generated note for this item.

Type:

Optional[str]

visibility

The playlist item’s privacy status. Can be PrivacyStatus.private, PrivacyStatus.public or PrivacyStatus.unlisted.

Type:

PrivacyStatus

async expand() → YoutubeVideo[source]

Fetches extended information on the video in the playlist.

This ia an api call which then returns a YoutubeVideo object.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The video object containing data of the video.

Return type:

YoutubeVideo

Raises:
async fetch_playlist() → YoutubePlaylist[source]

Fetches the playlist associated with the video.

This ia an api call which then returns a YoutubePlaylist object.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The playlist object containing data of the playlist.

Return type:

YoutubePlaylist

Raises:
async fetch_channel() → YoutubeChannel | None[source]

Fetches the channel associated with the video.

This ia an api call which then returns a YoutubeChannel object.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The channel object containing data of the channel.

Return type:

Optional[YoutubeChannel]

Raises:
async fetch_comments(max_comments: int | None = 50) → list[YoutubeCommentThread][source]

Fetches a list of comments on the video.

This ia an api call which then returns a list[YoutubeCommentThread] object.

Quota Impact

A call to this method has a quota cost of 1 unit per call or per 50 comments fetched.

Returns:

A list of comments on the video.

Return type:

list[YoutubeCommentThread]

Raises:
async fetch_captions() → list[VideoCaption][source]

Fetches a list of comments on the video.

This ia an api call which then returns a list[VideoCaption] object.

Quota Impact

A call to this method has a quota cost of 50 units per call or per 50 captions fetched.

Returns:

A list of comments on the video.

Return type:

list[VideoCaption]

Raises:
async update(*, position: int | EXISTING | None = EXISTING, note: str | EXISTING | None = EXISTING) → PlaylistItem[source]

Update the metadata for an item in a playlist.

Added in version 0.4.0.

Values default to a special constant called EXISTING which is from the class ayt_api.types.UseExisting. Specify any other value in order to edit the property you want.

Quota Impact

A call to this method has a quota cost of 50 units per call.

Important

Specifying None for a parameter will wipe it or set it to YouTube’s default value.

Note

This method requires OAuth2 authentication with at least the default scope.

Parameters:

  • position (Union[int, EXISTING, None]) – The position in the playlist the item should be.

  • note (Union[str, EXISTING, None]) – A user-generated note for this item. The note has a maximum character limit of 280 and the API will throw a 400 error if this limit is exceeded.

Returns:

The updated metadata for the item in the playlist related to the video.

Return type:

PlaylistItem

Raises:

  • HTTPException – Editing the item in the playlist failed or an invalid playlist position or note was set.

  • ResourceNotFound – The playlist item does not exist or is not accessible.

  • aiohttp.ClientError – There was a problem sending the request to the api.

  • APITimeout – The YouTube api did not respond within the timeout period set.

class ayt_api.types.PlaylistImageMetadata(metadata: dict, call_url: str, call_data)[source]

Bases: object

Represents metadata about a custom image for a playlist.

Added in version 0.4.0.

metadata

The raw API response used to construct this class.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

id

The ID that YouTube uses to uniquely identify the playlist image.

Type:

str

snippet

The raw snippet data used to construct this class.

Type:

dict

playlist_id

The playlist ID of the playlist this image is associated with.

Type:

str

type

The image type.

Type:

str

width

The amount of horizontal pixels in the image.

Type:

int

height

The amount of vertical pixels in the image.

Type:

int

resolution

The Width x Height of the image.

Type:

str

size

An alias of resolution.

Type:

str

async fetch_playlist() → YoutubePlaylist[source]

Fetches the playlist associated with the image.

This ia an api call which then returns a YoutubePlaylist object.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The playlist object containing data of the playlist.

Return type:

YoutubePlaylist

Raises:
class ayt_api.types.YoutubePlaylist(metadata: dict, call_url: str, call_data)[source]

Bases: object

Data class for YouTube playlists.

metadata

The raw API response used to construct this class.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

etag

The Etag of this resource.

Type:

str

id

The ID of the playlist. Example: “PLwZcI0zn-Jhemx2m_gpYqQfnc3l4xA4fp” from the url: “https://www.youtube.com/playlist?list=PLwZcI0zn-Jhemx2m_gpYqQfnc3l4xA4fp”.

Type:

str

url

The URL of the playlist.

Type:

str

snippet

The raw snippet data used to construct this class.

Type:

dict

status

The raw status data used to construct part of this class.

Type:

dict

content_details

The raw content details data used to construct part of this class.

Type:

dict

player

The raw player data used to construct part of this class.

Type:

dict

raw_localisations

The raw localisation data used to construct part of this class.

Type:

Optional[dict]

published_at

The date and time the playlist was published.

Type:

datetime.datetime

channel_id

The id of the channel that created the playlist.

Type:

Optional[str]

channel_url

The url of the channel that created the playlist.

Type:

Optional[str]

title

The title of the playlist.

Type:

str

description

The description of the playlist.

Type:

str

thumbnails

The available thumbnails the playlist has.

Type:

YoutubeThumbnailMetadata

channel_title

The name of the channel that created the playlist.

Type:

Optional[str]

default_language

The default language the video is set in. Can be None.

Type:

Optional[str]

localised

The localised language of the title and description of the video.

Type:

Optional[LocalName]

localized

an alias of localised.

Type:

Optional[LocalName]

visibility

The video’s privacy status. Can be PrivacyStatus.private, PrivacyStatus.public or PrivacyStatus.unlisted.

Type:

Optional[PrivacyStatus]

podcast_status

The playlist’s podcast status.

Added in version 0.4.0.

Type:

Optional[PodcastStatus]

item_count

The number of items in the playlist.

Type:

Optional[int]

embed_html

An <iframe> tag that embeds a player that plays the video.

Type:

Optional[str]

localisations

contains translations of the video’s metadata.

Type:

Optional[list[LocalName]]

localizations

an alias of localisations.

Type:

Optional[list[LocalName]]

async fetch_items() → list[PlaylistItem][source]

Fetches a list of the videos in the playlist.

This is an api call which returns a list of PlaylistItem objects.

Quota Impact

A call to this method has a quota cost of 1 unit per call or per 50 items fetched.

Returns:

A list containing playlist video objects.

Return type:

list[PlaylistItem]

Raises:
async fetch_videos(exclude: list[str] = None, ignore_not_found=False) → list[YoutubeVideo] | list[source]

Fetches a list of the videos in the playlist.

This is an api call which returns a list of YoutubeVideo objects.

Quota Impact

A call to this method has a quota cost of 2 units per call or per 50 videos fetched.

Parameters:

  • exclude (Optional[list[str]]) –

    A list of videos to not fetch in the playlist.

    Deprecated since version 0.4.0: Use ignore_not_found instead.

  • ignore_not_found (bool) –

    Ignore any videos that were not returned by this method.

    Added in version 0.4.0.

Returns:

A list containing videos from the playlist.

Return type:

Union[list[YoutubeVideo], list]

Raises:
async fetch_channel() → YoutubeChannel | None[source]

Fetches the channel associated with the playlist.

This ia an api call which then returns a YoutubeChannel object.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The channel object containing data of the channel.

Return type:

Optional[YoutubeChannel]

Raises:
async fetch_image_metadata() → PlaylistImageMetadata | None[source]

Fetches metadata on the custom cover images if the current playlist has one.

Added in version 0.4.0.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Important

The API endpoint for playlist images is still in early stages and its own documentation currently has bits missing and contains a few errors and inconsistencies. Not everything may work as expected or may change and break this method.

Note

This method will not fetch the actual image asset due to YouTube limitations.

Returns:

The metadata of the custom playlist image. Returns None if the playlist has no custom image set.

Return type:

Optional[PlaylistImageMetadata]

Raises:
async add_video(video: BaseVideo | str, *, position: int = None, note: str = None) → PlaylistItem[source]

Add a video to the playlist.

Added in version 0.4.0.

Quota Impact

A call to this method has a quota cost of 50 units per call.

Note

This method requires OAuth2 authentication with at least the default scope.

Parameters:

  • video (Union[BaseVideo, str]) – The video or video ID to add to the playlist.

  • position (Optional[int]) – The position in the playlist to add the video. Defaults to the end.

  • note (Optional[str]) –

    A user-generated note for this item. The note has a maximum character limit of 280 and the API is meant to throw a 400 error if this limit is exceeded.

    Important

    This property might be deprecated by the API as it seems to ignore any set value even if it is over the said character limit in its documentation.

Returns:

The metadata for the item in the playlist related to the video.

Return type:

PlaylistItem

Raises:

  • HTTPException – Adding the video to the playlist failed or an invalid playlist position was set.

  • PlaylistNotFound – The playlist does not exist or is not accessable.

  • VideoNotFound – The video does not exist or is not accessable.

  • aiohttp.ClientError – There was a problem sending the request to the api.

  • InvalidInput – The input is not a playlist id.

  • APITimeout – The YouTube api did not respond within the timeout period set.

async update(*, title: str | EXISTING = EXISTING, description: str | EXISTING | None = EXISTING, default_language: str | EXISTING | None = EXISTING, visibility: PrivacyStatus | EXISTING | None = EXISTING, podcast_status: PodcastStatus | EXISTING | None = EXISTING, localisations: list[LocalName] | EXISTING | None = EXISTING) → YoutubePlaylist[source]

Updates metadata for the playlist.

Added in version 0.4.0.

Values default to a special constant called EXISTING which is from the class ayt_api.types.UseExisting. Specify any other value in order to edit the property you want.

Quota Impact

A call to this method has a quota cost of 50 units per call.

Important

Specifying None for a parameter will wipe it or set it to YouTube’s default value.

Note

This method requires OAuth2 authentication with at least the default scope.

Parameters:

  • title (Union[str, EXISTING]) –

    The title of the playlist to set.

    Note

    This value cannot be set to None or an empty string as YouTube forbids this.

  • default_language (Union[str, EXISTING, None]) – The default language the playlist should be set in. The value should be a BCP-47 language code.

  • description (Union[str, EXISTING, None]) – The description of the playlist to set.

  • visibility (Union[PrivacyStatus, EXISTING, None]) – Set the playlist’s privacy status.

  • podcast_status (Union[PodcastStatus, EXISTING, None]) – Set the playlist’s podcast status.

  • localisations (Union[list[LocalName], EXISTING, None]) – Specify translations of the playlist’s metadata.

Returns:

The updated playlist object.

Return type:

YoutubePlaylist

Raises:
class ayt_api.types.AuthorisedYoutubeVideo(metadata, call_url, call_data)[source]

Bases: YoutubeVideo

A data class containing owner only information video data such as the file and processing information.

This class is used if authorisation is provided that you are the owner of the video. It contains attributes only accessible by the video owner as well as attributes inherited from YoutubeVideo.

file_details

The raw file details used to construct this class.

Type:

dict

has_custom_thumbnail

Indicates whether the video uploader has provided a custom thumbnail image for the video.

Type:

bool

self_declared_made_for_kids

This Attribute allows the channel owner to designate the video as being child-directed.

Type:

bool

dislike_count

The number of users who have indicated that they disliked the video.

Type:

Optional[int]

file_name

The uploaded file’s name.

Type:

Optional[str]

file_size

The uploaded file’s size in bytes.

Type:

Optional[int]

file_type

The uploaded file’s type as detected by YouTube’s video processing engine.

Type:

Optional[UploadFileType]

file_container

The uploaded video file’s container format.

Type:

Optional[str]

video_streams

A list of video streams contained in the uploaded video file.

Type:

Optional[list[VideoStream]]

audio_streams

A list of audio streams contained in the uploaded video file.

Type:

Optional[list[AudioStream]]

file_duration

The length of the uploaded video millisecond accurate.

Type:

Optional[datetime.timedelta]

file_bitrate

The uploaded video file’s combined (video and audio) bitrate in bits per second.

Type:

Optional[int]

file_creation_time

The date and time when the uploaded video file was created.

Type:

Optional[datetime.datetime]

processing_status

The video’s processing status.

Type:

Optional[ProcessingStatus]

processing_progress

contains information about the progress YouTube has made in processing the video

Type:

Optional[ProcessingProgress]

processing_failure_reason

The reason that YouTube failed to process the video.

Type:

Optional[ProcessingFailureReason]

file_details_availability

This value indicates whether file details are available for the uploaded video.

Type:

Optional[str]

processing_issues_availability

indicates whether the video processing engine has generated suggestions that might improve YouTube’s ability to process the video, warnings that explain video processing problems, or errors that cause video processing problems.

Type:

Optional[str]

tag_suggestions_availability

This value indicates whether keyword (tag) suggestions are available for the video.

Type:

Optional[str]

editor_suggestions_availability

This value indicates whether video editing suggestions, which might improve video quality or the playback experience, are available for the video.

Type:

Optional[str]

thumbnails_availability

This value indicates whether thumbnail images have been generated for the video.

Type:

Optional[str]

processing_errors

A list of errors that will prevent YouTube from successfully processing the uploaded video.

Type:

Optional[list[ProcessingError]]

processing_warnings

A list of reasons why YouTube may have difficulty transcoding the uploaded video or that might result in an erroneous transcoding.

Type:

Optional[list[ProcessingWarning]]

processing_hints

A list of suggestions that may improve YouTube’s ability to process the video.

Type:

Optional[list[ProcessingHint]]

tag_suggestions

A list of keyword tags that could be added to the video’s metadata to increase the likelihood that users will locate your video when searching or browsing on YouTube.

Type:

Optional[list[TagSuggestion]]

editor_suggestions

A list of video editing operations that might improve the video quality or playback experience of the uploaded video.

Type:

Optional[list[EditorSuggestion]]

async update(*, title: str | EXISTING = EXISTING, category_id: str | EXISTING = EXISTING, default_language: str | EXISTING | None = EXISTING, description: str | EXISTING | None = EXISTING, tags: list[str] | EXISTING | None = EXISTING, embeddable: bool | EXISTING | None = EXISTING, video_license: License | EXISTING | None = EXISTING, visibility: PrivacyStatus | EXISTING | None = EXISTING, public_stats_viewable: bool | EXISTING | None = EXISTING, publish_at: datetime | EXISTING | None = EXISTING, made_for_kids: bool | EXISTING | None = EXISTING, contains_synthetic_media: bool | EXISTING | None = EXISTING, recording_date: datetime | EXISTING | None = EXISTING, localisations: list[LocalName] | EXISTING | None = EXISTING)[source]

Updates metadata for the video.

Added in version 0.4.0.

Values default to a special constant called EXISTING which is from the class ayt_api.types.UseExisting. Specify any other value in order to edit the property you want.

Quota Impact

A call to this method has a quota cost of 50 units per call.

Important

Specifying None for a parameter will wipe it or set it to YouTube’s default value.

Parameters:

  • title (Union[str, EXISTING]) –

    The title of the video to set.

    Note

    This value cannot be set to None or an empty string as YouTube forbids this.

  • category_id (Union[str, EXISTING]) –

    The category id to set for the video.

    Note

    This value cannot be set to None or an empty string as YouTube forbids this.

  • default_language (Union[str, EXISTING, None]) – The default language the video should be set in. The value should be a BCP-47 language code.

  • description (Union[str, EXISTING, None]) – The description of the video to set.

  • tags (Union[list[str], EXISTING, None]) – The tags the to set to make the video appear in search results relating to it.

  • embeddable (Union[bool, EXISTING, None]) – Set whether the video can be embedded on another website.

  • video_license (Union[License, EXISTING, None]) – The YouTube license to set for the video.

  • visibility (Union[PrivacyStatus, EXISTING, None]) – Set the video’s privacy status.

  • public_stats_viewable (Union[bool, EXISTING, None]) – Set whether the extended video statistics on the video’s watch page are publicly viewable.

  • publish_at (Union[datetime.datetime, EXISTING, None]) –

    Set the date and time when the video is scheduled to publish.

    Note

    If you set a value for this property, you must also set the visibility property to ayt_api.enums.PrivacyStatus.private.

  • made_for_kids (Union[bool, EXISTING, None]) – Designate the video as being child-directed.

  • contains_synthetic_media (Union[bool, EXISTING, None]) – Tell YouTube if the video contain realistic Altered or Synthetic (A/S) content.

  • recording_date (Union[datetime.datetime, EXISTING, None]) – Set the date and time when the video was recorded.

  • localisations (Union[list[LocalName], EXISTING, None]) – Specify translations of the video’s metadata.

Returns:

The updated instance of this class.

Return type:

AuthorisedYoutubeVideo

Raises:
async set_thumbnail(image: bytes)[source]

Upload and set the video’s thumbnail.

Added in version 0.4.0.

Quota Impact

A call to this method has a quota cost of 50 units per call.

Parameters:

image (bytes) – The thumbnail image to upload.

Raises:
class ayt_api.types.YoutubeChannel(metadata: dict, call_url: str, call_data, partial=False)[source]

Bases: object

A class representing metadata from a YouTube channel.

metadata

The raw API response used to construct this class.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

etag

The Etag of this resource.

Type:

str

branding_settings

encapsulates information about the branding of the channel.

Type:

dict

content_details

encapsulates information about the channel’s content.

Type:

dict

content_owner_details

encapsulates channel data that is visible only to the YouTube Partner that has linked the channel to their Content Manager.

Type:

dict

id

The ID that YouTube uses to uniquely identify the channel.

Type:

str

url

The URL of the channel.

Type:

str

raw_localisations

encapsulates translations of the channel’s metadata.

Type:

Optional[dict]

snippet

contains basic details about the channel, such as its title, description, and thumbnail images.

Type:

dict

statistics

encapsulates statistics for the channel.

Type:

dict

status

encapsulates information about the privacy status of the channel.

Type:

dict

topic_details

encapsulates information about topics associated with the channel.

Type:

Optional[dict]

title

The channel’s title.

Type:

str

description

The channel’s description. The property’s value has a maximum length of 1000 characters.

Type:

Optional[str]

custom_url

The channel’s custom URL.

Type:

Optional[str]

username

Alias for custom_url.

Type:

Optional[str]

handle

Alias for custom_url.

Type:

Optional[str]

published_at

The date and time that the channel was created.

Type:

datetime.datetime

created_at

Alias for published_at.

Type:

datetime.datetime

thumbnails

The thumbnail images associated with the channel.

Type:

YoutubeThumbnailMetadata

icon

Alias of thumbnails.

Type:

YoutubeThumbnailMetadata

pfp

Alias of thumbnails.

Type:

YoutubeThumbnailMetadata

avatar

Alias of thumbnails.

Type:

YoutubeThumbnailMetadata

default_language

The language of the text in the YoutubeChannel class’s title and description properties.

Type:

Optional[str]

localised

The localized title and description for the channel or title and description in the default_language.

Type:

Optional[LocalName]

localized

Alias for localised.

Type:

Optional[LocalName]

country

The country with which the channel is associated.

Type:

Optional[str]

related_playlists

The playlists associated with the channel, such as the channel’s uploaded videos or liked videos.

Type:

dict

likes_id

The ID of the playlist that contains the channel’s liked videos.

Type:

Optional[str]

likes_url

The URL of the playlist that contains the channel’s liked videos.

Type:

Optional[str]

uploads_id

The ID of the playlist that contains the channel’s uploaded videos.

Type:

Optional[str]

uploads_url

The URL of the playlist that contains the channel’s uploaded videos.

Type:

Optional[str]

view_count

The number of times the channel has been viewed.

Type:

int

subscriber_count

The number of subscribers that the channel has. This is rounded to 3 significant figures.

Type:

int

hidden_subscriber_count

Whether the channel’s subscriber count is publicly visible.

Type:

bool

video_count

The number of public videos uploaded to the channel.

Type:

int

topic_categories

A list of Wikipedia URLs that describe the channel’s content.

Type:

Optional[list[str]]

topic_ids

A list of topic IDs associated with the channel.

Type:

Optional[list[str]]

visibility

The channel’s privacy status. Can be PrivacyStatus.private, PrivacyStatus.public or PrivacyStatus.unlisted.

Type:

PrivacyStatus

is_linked

Whether the channel data identifies a user that is already linked to either a YouTube username or a Google+ account.

Type:

bool

long_upload_status

whether the channel is eligible to upload videos that are more than 15 minutes long.

Type:

LongUploadsStatus

made_for_kids

Whether the channel is designated as child-directed, and it contains the current “made for kids” status of the channel.

Type:

Optional[bool]

self_declared_made_for_kids

Designates the channel as child-directed.

Type:

Optional[bool]

keywords

Keywords associated with your channel.

Type:

Optional[list[str]]

tracking_analytics_account_id

The ID for a Google Analytics account used to track and measure traffic to the channel.

Type:

Optional[str]

moderate_comments

Determines whether user-submitted comments left on the channel page need to be approved by the channel owner to be publicly visible.

Type:

Optional[bool]

unsubscribed_trailer_id

The ID of the video that should play in the featured video module in the channel page’s browse view for unsubscribed viewers.

Type:

Optional[str]

unsubscribed_trailer_url

The URL of the video that should play in the featured video module in the channel page’s browse view for unsubscribed viewers.

Type:

Optional[str]

banner_external

The banner image that YouTube uses to generate the various banner image sizes for a channel.

Type:

Optional[YoutubeBanner]

content_owner

The ID of the content owner linked to the channel.

Type:

Optional[str]

time_linked

The date and time of when the channel was linked to the content owner.

Type:

Optional[datetime.datetime]

localisations

Encapsulates translations of the channel’s metadata.

Type:

Optional[list[LocalName]]

localizations

Alias for localisations.

Type:

Optional[list[LocalName]]

async fetch_uploads() → list[PlaylistItem] | None[source]

Fetches the playlist containing all public uploads associated with the channel.

This ia an api call which then returns a PlaylistItem object.

Quota Impact

A call to this method has a quota cost of 1 unit per call or per 50 items fetched.

Returns:

A list containing playlist video objects of the channel’s public uploads.

Return type:

Optional[list[PlaylistItem]]

Raises:
async fetch_likes(max_items: int = None) → list[PlaylistItem] | None[source]

Fetches the playlist containing all videos the channel has liked if public.

This ia an api call which then returns a PlaylistItem object if public, otherwise None.

Quota Impact

A call to this method has a quota cost of 1 unit per call or per 50 items fetched.

Parameters:

max_items (Optional[int]) –

The maximum number of playlist items to fetch. Defaults to None which fetches every item in a playlist.

Added in version 0.4.0.

Warning

If a specified playlist has a lot of videos, not specifying a value to max_items could hammer the api too much causing you to get rate limited so do this with caution.

Returns:

A list containing playlist video objects of the channel’s public likes.

Return type:

Optional[list[PlaylistItem]]

Raises:
async fetch_unsubscribed_trailer() → YoutubeVideo | None[source]

Fetches the channel trailer video if any.

This ia an api call which then returns a YoutubeVideo object if the channel has a trailer, otherwise None.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The video object containing data of the channel trailer.

Return type:

Optional[YoutubeVideo]

Raises:
async fetch_comments(max_comments: int | None = 50) → list[YoutubeCommentThread][source]

Fetches a list of related to the channel.

This ia an api call which then returns a list[YoutubeCommentThread] object.

Quota Impact

A call to this method has a quota cost of 1 unit per call or per 50 comments fetched.

Parameters:

max_comments (Optional[int]) –

The maximum number of comments to fetch. Defaults to 50.

Warning

If a specified video has a lot of comments, not specifying a value to max_comments could hammer the api too much causing you to get rate limited so do this with caution.

Returns:

A list of comments related to the channel.

Return type:

list[YoutubeCommentThread]

Raises:
async update(*, country: str | EXISTING | None = EXISTING, description: str | EXISTING | None = EXISTING, default_language: str | EXISTING | None = EXISTING, keywords: list[str] | EXISTING | None = EXISTING, tracking_analytics_account_id: str | EXISTING | None = EXISTING, unsubscribed_trailer: str | BaseVideo | EXISTING | None = EXISTING, localisations: list[LocalName] | EXISTING | None = EXISTING, made_for_kids: bool | EXISTING = EXISTING) → YoutubeChannel[source]

Updates metadata for the channel.

Added in version 0.4.0.

Values default to a special constant called EXISTING which is from the class ayt_api.types.UseExisting. Specify any other value in order to edit the property you want.

Quota Impact

A call to this method has a quota cost of between 0-150 units. As updating localisations and made_for_kids cost an extra 50 units each and not updating anything costs nothing as no API call is actually made.

Note

If no arguments are specified or are all set to EXISTING, no API call is made and hence no quota units will be used. The function will just return the YoutubeChannel as it is.

Important

Specifying None for a parameter will wipe it or set it to YouTube’s default value.

Note

This method requires OAuth2 authentication with at least the default scope.

Parameters:

  • country (Union[str, EXISTING, None]) – The country to set which the channel is associated.

  • description (Union[str, EXISTING, None]) – The description of the channel to set.

  • default_language (Union[str, EXISTING, None]) – The default language the video should be set in. The value should be a BCP-47 language code.

  • keywords (Union[list[str], EXISTING, None]) – Keywords to set associated with your channel.

  • tracking_analytics_account_id (Union[str, EXISTING, None]) – The ID to set for a Google Analytics account used to track and measure traffic to the channel.

  • unsubscribed_trailer (Union[str, BaseVideo, EXISTING, None]) – The ID or BaseVideo to set of the video that should play in the featured video module in the channel page’s browse view for unsubscribed viewers.

  • localisations (Union[list[LocalName], EXISTING, None]) –

    Specify translations of the video’s metadata.

    Note

    This value cannot be set to None or an empty list as YouTube forbids this.

  • made_for_kids (Union[bool, EXISTING]) –

    Designate the channel as being child-directed.

    Note

    This value cannot be set to None as YouTube forbids this.

Returns:

The updated channel object.

Return type:

YoutubeChannel

Raises:
async set_banner(image: bytes)[source]

Upload and set the banner for the channel.

Added in version 0.4.0.

Quota Impact

A call to this method has a quota cost of 100 units per call.

Note

This method requires OAuth2 authentication with at least the default scope.

Parameters:

image (bytes) –

The banner image to upload.

Note

The image must have a 16:9 aspect ratio and be at least 2048x1152 pixels. YouTube recommends uploading a 2560px by 1440px image.

Raises:
async set_watermark(image: bytes, timing_type: WatermarkTimingType = None, timing_offset: timedelta = None, duration: timedelta = None)[source]

Upload and set the watermark for a channel.

Added in version 0.4.0.

Quota Impact

A call to this method has a quota cost of 50 units per call.

Note

This method requires OAuth2 authentication with at least the default scope.

Parameters:

  • image (bytes) – The watermark image to upload.

  • timing_type (Optional[WatermarkTimingType]) –

    The timing method that determines when the watermark image is displayed during the video playback.

    Note

    Setting this argument to None will make the watermark appear for the entire video.

  • timing_offset (Optional[datetime.timedelta]) – The time offset that determines when the promoted item appears during video playbacks. timing_type Determines if this offset if from the start or end of a video.

  • duration (Optional[datatime.timedelta]) – The length of time that the watermark image should display.

Raises:
async unset_watermark()[source]

Unset the watermark for a channel.

Added in version 0.4.0.

Quota Impact

A call to this method has a quota cost of 50 units per call.

Warning

If the channel currently has no watermark set, this function will raise WatermarkNotFound as the API throws a 404 error.

Note

This method requires OAuth2 authentication with at least the default scope.

Raises:
async fetch_playlists() → list[YoutubePlaylist][source]

Fetches playlists created by the channel.

Added in version 0.4.0.

Quota Impact

A call to this method has a quota cost of 1 unit per call or per 50 playlists fetched.

Note

Only playlists marked as public will be returned if the request is made without OAuth2 authorisation using the associated channel.

Returns:

The playlists created by the channel.

Return type:

list[YoutubePlaylist]

Raises:
class ayt_api.types.YoutubeComment(metadata: dict, call_url: str, call_data)[source]

Bases: object

Represents information on an individual YouTube command.

Information about the video the comment belongs to will not be available unless this object was access under YoutubeCommentThread.replies

metadata

The raw API response used to construct this class.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

etag

The Etag of this resource.

Type:

str

snippet

The raw snippet data used to construct part this class.

Type:

dict

id

The ID of the comment.

Type:

str

author_display_name

The display name of the author (this is not their handle).

Type:

str

author_profile_image_url

The image URL of the author’s pfp.

Type:

str

author_channel_id

The ID of the author’s channel.

Type:

Optional[str]

author_channel_url

The URL of the author’s channel.

Type:

Optional[str]

channel_id

The id of the channel that the video belongs to.

Type:

Optional[str]

channel_url

The url of the channel that the video belongs to.

Type:

Optional[str]

video_id

The ID of the video that the comments refer to. Will be None unless part of a YoutubeCommentThread.

Type:

Optional[str]

video_url

The URL of the video that the comments refer to. Will be None unless part of a YoutubeCommentThread.

Type:

Optional[str]

highlight_url

The highlight URL of the comment. Will be None unless part of a YoutubeCommentThread.

Type:

Optional[str]

url

Alias of highlight_url

Type:

Optional[str]

text_display

The comment’s text in either plain text or HTML.

Type:

str

text_original

The comment’s raw text.

Type:

Optional[str]

parent_id

The unique ID of the parent comment.

Type:

Optional[str]

can_rate

whether the current viewer can rate the comment.

Type:

bool

viewer_rating

The rating the viewer has given to this comment.

Type:

Optional[str]

like_count

The total number of likes on the comment.

Type:

int

moderation_status

The comment’s moderation status.

Type:

Optional[str]

published_at

The date and time when the comment was originally published.

Type:

datetime.datetime

updated_at

The date and time when the comment was last updated.

Type:

datetime.datetime

async fetch_replies(max_comments: int | None = 50) → list[YoutubeComment][source]

Fetches a list of replies on the comment.

This ia an api call which then returns a list[YoutubeComment] object.

Quota Impact

A call to this method has a quota cost of 1 unit per call or per 50 comments fetched.

Parameters:

max_comments (Optional[int]) –

The maximum number of comments to fetch. Defaults to 50.

Warning

If a specified comment has a lot of replies, not specifying a value to max_comments could hammer the api too much causing you to get rate limited so do this with caution.

Returns:

A list of replies on the comment.

Return type:

list[YoutubeComment]

Raises:
class ayt_api.types.YoutubeCommentThread(metadata: dict, call_url: str, call_data)[source]

Bases: object

Represents the structure of a comment (thread).

metadata

The raw API response used to construct this class.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

etag

The Etag of this resource.

Type:

str

snippet

The raw snippet data used to construct part this class.

Type:

dict

id

The ID of the comment.

Type:

str

channel_id

The id of the channel that the video belongs to.

Type:

Optional[str]

channel_url

The url of the channel that the video belongs to.

Type:

Optional[str]

video_id

The ID of the video that the comments refer to.

Type:

Optional[str]

video_url

The URL of the video that the comments refer to.

Type:

Optional[str]

highlight_url

The highlight URL of the comment.

Type:

Optional[str]

url

Alias of highlight_url

Type:

Optional[str]

top_level_comment

The thread’s top-level comment.

Type:

YoutubeComment

can_reply

Whether the current viewer can reply to the thread.

Type:

bool

total_reply_count

The total number of replies that have been submitted in response to the top-level comment.

Type:

Optional[int]

is_public

Whether the thread, including all of its comments and comment replies, is visible to all YouTube users.

Type:

bool

replies

The replies on the comment if any.

Type:

Optional[list[YoutubeComment]]

class ayt_api.types.YoutubeSearchResult(data: dict, call_url: str, call_data)[source]

Bases: object

Represents individual results from an API search.

data

The raw API response used to construct this class.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

kind_id

The raw kind of the result separated by a #. Could be video, channel or playlist.

Type:

str

kind
Type:

type[Union[YoutubeVideo, YoutubeChannel, YoutubePlaylist]]

id

The ID of the object in the result.

Type:

str

url

The URL of the object in the result.

Type:

str

snippet

The raw snippet data used to construct part this class.

Type:

dict

title

The title of the object in the search result.

Type:

str

description

The description of the object in the search result.

Type:

str

thumbnails

The available thumbnails the object has.

Type:

YoutubeThumbnailMetadata

channel_title

The title of the channel that published the resource that the search result identifies.

Type:

Optional[str]

live_broadcast_content

Indicates if the object is a livestream and if it is live.

Type:

LiveBroadcastContent

async expand() → YoutubeVideo | YoutubeChannel | YoutubePlaylist[source]

Expand the search result into its appropriate type.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The proper object of the search result.

Return type:

Union[YoutubeVideo, YoutubeChannel, YoutubePlaylist]

Raises:
class ayt_api.types.VideoCaption(metadata: dict, call_url: str, call_data)[source]

Bases: object

Represents data of an individual caption track on a video.

etag

The Etag of this resource.

Type:

str

id

The ID of the caption track.

Type:

str

snippet

The raw snippet data used to construct part this class.

Type:

dict

video_id

The ID of the video that the caption track refer to.

Type:

str

last_updated

The date and time when the caption track was last updated.

Type:

datetime.datetime

track_kind

The caption track’s type.

Type:

CaptionTrackKind

language

The language of the caption track. The value is a BCP-47 language code.

Type:

str

name

The name of the caption track. The name is intended to be visible to the user as an option during playback.

Type:

str

audio_track_type

The type of audio track associated with the caption track.

Type:

AudioTrackType

is_cc

Whether the track contains closed captions. Defaults to False.

Type:

bool

is_large

Whether the caption track uses large text for the vision-impaired. Defaults to False.

Type:

bool

is_easy_reader

Whether the caption track is formatted for “easy reader,” meaning it is at a third-grade level for language learners. Defaults to False.

Type:

bool

is_auto_synced

Whether YouTube synchronized the caption track to the audio track in the video.

Type:

bool

status

The caption track’s status.

Type:

CaptionStatus

failure_reason

The reason that YouTube failed to process the caption track.

Type:

CaptionFailureReason

async download(track_format: CaptionFormat | None = None, language: str | None = None) → bytes[source]

Downloads the caption track and stores it as a bytes object

Added in version 0.4.0.

Quota Impact

A call to this method has a quota cost of 200 units per call.

Note

You must be the owner of the video of the captions and use OAuth authentication to call this method with one of the following scopes:

Parameters:

  • track_format (Optional[CaptionFormat]) – The format YouTube should return the captions in.

  • language (Optional[str]) – The alpha-2 language code to translate the caption track into.

Returns:

The caption track as a bytes object.

Return type:

bytes

Raises:
async save(*, track_format: CaptionFormat | None = None, language: str | None = None, fp: PathLike | str | None = None)[source]

Downloads the caption track and saves it to a specified location

Added in version 0.4.0.

Quota Impact

A call to this method has a quota cost of 200 units per call.

Note

You must be the owner of the video of the captions and use OAuth authentication to call this method with one of the following scopes:

Parameters:

  • track_format (Optional[CaptionFormat]) – The format YouTube should return the captions in.

  • language (Optional[str]) – The alpha-2 language code to translate the caption track into.

  • fp (Union[os.PathLike, str, None]) – The path and/or filename to save the file to. Defaults to current working directory with the filename format: {track_id}.{file_extension (if any)}

Raises:
class ayt_api.types.YoutubeSubscription(metadata: dict, call_url: str, call_data)[source]

Bases: object

A class representing a user’s subscription to a channel on YouTube

Added in version 0.4.0.

metadata

The raw API response used to construct this class.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

etag

The Etag of this resource.

Type:

str

subscription_id

The ID that YouTube uses to uniquely identify the subscription.

Type:

str

id

Alias of subscription_id.

Type:

str

snippet

The raw snippet data used to construct part this class.

Type:

dict

content_details

The raw content details data used to construct part of this class.

Type:

dict

subscriber_snippet

The raw subscriber snippet data used to construct part this class.

Type:

dict

published_at

The date and time the subscriber subscribed to the channel this subscription points to.

Type:

datetime.datetime

subscribed_at

Alias of published_at.

Type:

datetime.datetime

title

The title of the channel the subscription points to.

Type:

str

description

The description of the channel the subscription points to.

Type:

str

resource_id

The raw resource id information used to construct part this class.

Type:

dict

channel_id

The ID of the channel the subscription points to.

Type:

str

channel_url

The URL of the channel the subscription points to.

Type:

str

thumbnails

The thumbnail images associated with the channel the subscription points to.

Type:

YoutubeThumbnailMetadata

icon

Alias of thumbnails.

Type:

YoutubeThumbnailMetadata

pfp

Alias of thumbnails.

Type:

YoutubeThumbnailMetadata

avatar

Alias of thumbnails.

Type:

YoutubeThumbnailMetadata

total_item_count

The approximate number of items that the subscription points to.

Type:

str

new_item_count

The number of new items in the subscription since its content was last read.

Type:

str

activity_type

The type of activity this subscription is for.

Type:

SubscriptionActivityType

subscriber_title

The title of the channel associated with the subscriber.

Type:

str

subscriber_description

The description of the channel associated with the subscriber.

Type:

str

subscriber_id

The ID of the channel associated with the subscriber.

Type:

str

subscriber_url

The URL of the channel associated with the subscriber.

Type:

str

subscriber_thumbnails

The thumbnail images associated with the channel associated with the subscriber.

Type:

YoutubeThumbnailMetadata

subscriber_icon

Alias of subscriber_thumbnails.

Type:

YoutubeThumbnailMetadata

subscriber_pfp

Alias of subscriber_thumbnails.

Type:

YoutubeThumbnailMetadata

subscriber_avatar

Alias of subscriber_thumbnails.

Type:

YoutubeThumbnailMetadata

async fetch_channel() → YoutubeChannel[source]

Fetches the channel the subscription points to.

This ia an api call which then returns a YoutubeChannel object.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The channel object containing data of the channel.

Return type:

YoutubeChannel

Raises:
async fetch_subscriber() → YoutubeChannel[source]

Fetches the channel associated with the subscriber.

This ia an api call which then returns a YoutubeChannel object.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The channel object containing data of the channel.

Return type:

YoutubeChannel

Raises:
class ayt_api.types.YoutubeVideoCategory(metadata: dict, call_url: str, call_data)[source]

Bases: object

Represents a YouTube video category

Added in version 0.4.0.

metadata

The raw API response used to construct this class.

Type:

dict

call_url

The url used to call the API. Intended use is for debugging purposes.

Type:

str

etag

The Etag of this resource.

Type:

str

id

The ID that YouTube uses to uniquely identify the video category.

Type:

str

snippet

The raw snippet data used to construct part this class.

Type:

dict

title

The video category’s title.

Type:

str

channel_id

The ID of the YouTube channel that created the video category.

Type:

str

channel_url

The URL of the YouTube channel that created the video category.

Type:

str

assignable

Indicates whether videos can be associated with the category.

Type:

bool

async fetch_channel() → YoutubeChannel[source]

Fetches the channel that created the video category.

This ia an api call which then returns a YoutubeChannel object.

Quota Impact

A call to this method has a quota cost of 1 unit per call.

Returns:

The channel object containing data of the channel.

Return type:

YoutubeChannel

Raises:
class ayt_api.types.OAuth2Session(access_token: str, expires_in: int, refresh_token: str, scope: str, token_type: str, client_id: str, client_secret: str, http_date: datetime)[source]

Bases: object

Represents an oauth2 session

Added in version 0.4.0.

access_token

The OAuth2 access token used to authorise requests.

Type:

str

refresh_token

The token used to refresh the session.

Type:

str

scope

The scope of the access token.

Type:

str

token_type

The authorisation type.

Type:

str

expiry_length

The total time the token is valid before it expires

Type:

datetime.timedelta

expires_at

The time the token will expire at

Type:

datetime.datetime

client_id

A client id as part of OAuth client credentials created at https://console.cloud.google.com/apis/credentials.

Type:

str

client_secret

The client secret as part of OAuth client credentials created at https://console.cloud.google.com/apis/credentials.

Type:

str

property expires_in: timedelta

The time the token will expire in.

Returns:

The time the token will expire in.

Return type:

datetime.timedelta

is_expired()[source]

A check to see if the access token has expired

Returns:

Has the access token expired?

Return type:

bool