pyytlounge package

Python YouTube Lounge API

class pyytlounge.AdPlayingEvent(data: _AdPlayingData)

Bases: object

Contains information related to ad state

class pyytlounge.AdStateEvent(data: _AdStateData)

Bases: object

Contains information related to ad state

class pyytlounge.AutoplayModeChangedEvent(data: _AutoplayModeChangedData)

Bases: object

Contains auto play mode

class pyytlounge.AutoplayUpNextEvent(data: _AutoplayUpNextData)

Bases: object

Contains information related the next video to be played

class pyytlounge.DisconnectedEvent(data: _DisconnectedData | None)

Bases: object

Contains information related to disconnection

class pyytlounge.EventListener

Bases: ABC

Base class to implement an event listener. You should subclass this and override methods for events you’re interested in.

async ad_playing_changed(event: AdPlayingEvent) → None

Called when ad starts playing

async ad_state_changed(event: AdStateEvent) → None

Called when ad state changes (position, play/pause, skippable)

async autoplay_changed(event: AutoplayModeChangedEvent) → None

Called when auto play mode changes

async autoplay_up_next_changed(event: AutoplayUpNextEvent) → None

Called when up next video changes

async disconnected(event: DisconnectedEvent) → None

Called when the screen is no longer connected

async now_playing_changed(event: NowPlayingEvent) → None

Called when active video changes

async playback_speed_changed(event: PlaybackSpeedEvent) → None

Called when playback speed changes

async playback_state_changed(event: PlaybackStateEvent) → None

Called when playback state changes (position, play/pause)

async subtitles_track_changed(event: SubtitlesTrackEvent) → None

Called when subtitles track changes

async volume_changed(event: VolumeChangedEvent) → None

Called when volume or muted state changes

class pyytlounge.NowPlayingEvent(data: _NowPlayingData)

Bases: object

Contains information related to playback state

get_thumbnail_url(thumbnail_idx: int = 0) → str | None

Returns thumbnail for current video. Use thumbnail idx to get different thumbnails.

class pyytlounge.PlaybackSpeedEvent(data: _PlaybackSpeedData)

Bases: object

Contains information related to playback speed

class pyytlounge.PlaybackStateEvent(data: _PlaybackStateData)

Bases: object

Contains information related to playback state

class pyytlounge.State(*values)

Bases: Enum

Playback state

Advertisement = 1081

Buffering = 0

Paused = 2

Playing = 1

Starting = 3

Stopped = -1

static parse(state: str) → State

Parse a state value to State enum

class pyytlounge.SubtitlesTrackEvent(data: _SubtitlesTrackData)

Bases: object

Contains information related to subtitles track

class pyytlounge.VolumeChangedEvent(data: _VolumeChangedData)

Bases: object

Contains information related to volume

class pyytlounge.YtLoungeApi(device_name: str, event_listener: EventListener | None = None, logger: Logger | None = None)

Bases: object

YouTube Lounge API

async close()

async connect() → bool

Attempt to connect using the previously set tokens.

Raises:

• NotSupportedException – screen does not allow lounge client

• NotLinkedException – client is not yet linked, first pair or refresh authorization

connected() → bool

Returns true if the screen’s session is connected.

async disconnect() → bool

Disconnect from the current session.

Raises:

NotConnectedException – the client is already not connected

async get_now_playing() → bool

Requests a now playing update from the screen.

Raises:

NotConnectedException – the client is not connected to the screen

async is_available() → bool

Asks YouTube API if the screen is available. Must be linked prior to this.

Raises:

NotLinkedException – client is not yet linked, first pair or refresh authorization

linked() → bool

Returns true if paired and lounge id token is known.

load_auth_state(data: dict)

Use deserialized auth parameters

async next() → bool

Sends next command to screen

Raises:

NotConnectedException – the client is not connected to the screen

async pair(pairing_code: str) → bool

Pair with a device using a manual input pairing code

async pair_with_screen_id(screen_id: str, screen_name: str | None = None) → bool

Pair with a device using a known screen id Optionally specify the screen name if already known

paired() → bool

Returns true if screen id is known.

async pause() → bool

Sends pause command to screen

Raises:

NotConnectedException – the client is not connected to the screen

async play() → bool

Sends play command to screen

async play_video(video_id: str) → bool

Sends setPlaylist command to screen to play a specific video

Raises:

NotConnectedException – the client is not connected to the screen

async previous() → bool

Sends previous command to screen

Raises:

NotConnectedException – the client is not connected to the screen

async refresh_auth() → bool

Refresh lounge token using stored refresh token.

Raises:

NotPairedException – the screen is not yet known, pair first

property screen_device_name: str | None

Returns device name built from device info returned by YouTube. Returns None if not yet initialized or information was not sent.

Raises:

NotConnectedException – screen is not yet connected

property screen_name: str | None

Returns screen name as returned by YouTube.

Raises:

NotLinkedException – there is no screen linked yet

async seek_to(time: float) → bool

Seek to given time (seconds)

Raises:

NotConnectedException – the client is not connected to the screen

async send_dpad_command(button_input: DpadCommand) → bool

Sends a dpad command like a remote.

Raises:

NotConnectedException – the client is not connected to the screen

async set_auto_play_mode(enabled: bool) → bool

Set auto play mode enabled/disabled

Raises:

NotConnectedException – the client is not connected to the screen

async set_closed_captions(language_code: str | None, video_id: str)

Sets the closed captions to the provided BCP-47 language_code if available. Provide the language_code as None to toggle closed captions to off. video_id is always required.

Raises:

NotConnectedException – the client is not connected to the screen

async set_playback_speed(speed: float) → bool

Sets the playback speed to given value (0.25-2)

Raises:

NotConnectedException – the client is not connected to the screen

async set_volume(volume: int) → bool

Sets volume to given value (0-100)

Raises:

NotConnectedException – the client is not connected to the screen

async skip_ad() → bool

Skips ad if possible

Raises:

NotConnectedException – the client is not connected to the screen

store_auth_state() → dict

Return auth parameters as dict which can be serialized for later use

async subscribe() → None

Start listening for events. Updates will be sent to the event_listener passed when creating this object.

Raises:

• NotSupportedException – screen does not allow lounge client

• NotConnectedException – the client is not yet connected to the screen

async pyytlounge.get_available_captions(api_key: str, video_id: str)

Uses the traditional YouTube API to enumerate available subtitle tracks.

pyytlounge.get_thumbnail_url(video_id: str, thumbnail_idx=0) → str

Returns thumbnail for given video. Use thumbnail idx to get different thumbnails.

Submodules

pyytlounge.api module

async pyytlounge.api.get_available_captions(api_key: str, video_id: str)

Uses the traditional YouTube API to enumerate available subtitle tracks.

pyytlounge.api.get_thumbnail_url(video_id: str, thumbnail_idx=0) → str

Returns thumbnail for given video. Use thumbnail idx to get different thumbnails.

pyytlounge.dial module

Helper functions for discovering YouTube Lounge through DIAL

class pyytlounge.dial.DialResult(screen_name: str, screen_id: str)

Bases: object

YouTube screen obtained using DIAL

screen_id: str

screen_name: str

async pyytlounge.dial.get_screen_id_from_dial(url: str) → DialResult | None

Tries to get YouTube screen id from a DIAL endpoint

pyytlounge.event_listener module

class pyytlounge.event_listener.EventListener

Bases: ABC

Base class to implement an event listener. You should subclass this and override methods for events you’re interested in.

async ad_playing_changed(event: AdPlayingEvent) → None

Called when ad starts playing

async ad_state_changed(event: AdStateEvent) → None

Called when ad state changes (position, play/pause, skippable)

async autoplay_changed(event: AutoplayModeChangedEvent) → None

Called when auto play mode changes

async autoplay_up_next_changed(event: AutoplayUpNextEvent) → None

Called when up next video changes

async disconnected(event: DisconnectedEvent) → None

Called when the screen is no longer connected

async now_playing_changed(event: NowPlayingEvent) → None

Called when active video changes

async playback_speed_changed(event: PlaybackSpeedEvent) → None

Called when playback speed changes

async playback_state_changed(event: PlaybackStateEvent) → None

Called when playback state changes (position, play/pause)

async subtitles_track_changed(event: SubtitlesTrackEvent) → None

Called when subtitles track changes

async volume_changed(event: VolumeChangedEvent) → None

Called when volume or muted state changes

pyytlounge.events module

class pyytlounge.events.AdPlayingEvent(data: _AdPlayingData)

Bases: object

Contains information related to ad state

class pyytlounge.events.AdStateEvent(data: _AdStateData)

Bases: object

Contains information related to ad state

class pyytlounge.events.AutoplayModeChangedEvent(data: _AutoplayModeChangedData)

Bases: object

Contains auto play mode

class pyytlounge.events.AutoplayUpNextEvent(data: _AutoplayUpNextData)

Bases: object

Contains information related the next video to be played

class pyytlounge.events.DisconnectedEvent(data: _DisconnectedData | None)

Bases: object

Contains information related to disconnection

class pyytlounge.events.NowPlayingEvent(data: _NowPlayingData)

Bases: object

Contains information related to playback state

get_thumbnail_url(thumbnail_idx: int = 0) → str | None

Returns thumbnail for current video. Use thumbnail idx to get different thumbnails.

class pyytlounge.events.PlaybackSpeedEvent(data: _PlaybackSpeedData)

Bases: object

Contains information related to playback speed

class pyytlounge.events.PlaybackStateEvent(data: _PlaybackStateData)

Bases: object

Contains information related to playback state

class pyytlounge.events.SubtitlesTrackEvent(data: _SubtitlesTrackData)

Bases: object

Contains information related to subtitles track

class pyytlounge.events.VolumeChangedEvent(data: _VolumeChangedData)

Bases: object

Contains information related to volume

pyytlounge.exceptions module

Possible exceptions thrown by this library

exception pyytlounge.exceptions.NotConnectedException

Bases: Exception

This exception indicates an operation that failed due to an incorrect state. The operation requires that there is an active connection to the API. Use the connected() and connect() functions on YtLoungeApi.

exception pyytlounge.exceptions.NotLinkedException

Bases: Exception

This exception indicates an operation that failed due to an incorrect state. The operation requires that the API has been linked with a screen. Use the linked(), pair() and refresh_auth() functions on YtLoungeApi.

exception pyytlounge.exceptions.NotPairedException

Bases: Exception

This exception indicates an operation that failed due to an incorrect state. The operation requires that the API has been paired with a screen. Use the paired() and pair() functions on YtLoungeApi.

exception pyytlounge.exceptions.NotSupportedException

Bases: Exception

This exception indicates an operation that failed due to connecting to an unsupported client. Some YouTube clients (currently YouTube TV for Kids) are not supported by this library and will raise this exception when attempting to connect to them.

pyytlounge.lounge_models module

pyytlounge.models module

class pyytlounge.models.AuthState

Bases: object

Stores information used to authenticate with YouTube. Can be serialized and deserialized for reuse.

deserialize(data: dict)

Deserializes state from a dictionary into this object.

expiry: int

lounge_id_token: str

refresh_token: str

screen_id: str

serialize() → AuthStateData

Serializes the current state into a dictionary.

version: int

class pyytlounge.models.AuthStateData

Bases: TypedDict

Auth state in serialized state

expiry: int

loungeIdToken: str

refreshToken: str

screenId: str

version: int

class pyytlounge.models.DpadCommand(*values)

Bases: str, Enum

BACK = 'BACK'

DOWN = 'DOWN'

ENTER = 'ENTER'

LEFT = 'LEFT'

RIGHT = 'RIGHT'

UP = 'UP'

class pyytlounge.models.State(*values)

Bases: Enum

Playback state

Advertisement = 1081

Buffering = 0

Paused = 2

Playing = 1

Starting = 3

Stopped = -1

static parse(state: str) → State

Parse a state value to State enum

pyytlounge.util module

async pyytlounge.util.as_aiter(iterator)

Turns a synchronous iterator into an asynchronous iterator

async pyytlounge.util.iter_response_lines(resp: StreamReader)

Enumerate lines in response one at a time.

pyytlounge.wrapper module

Wrapper class for YouTube Lounge API

class pyytlounge.wrapper.YtLoungeApi(device_name: str, event_listener: EventListener | None = None, logger: Logger | None = None)

Bases: object

YouTube Lounge API

async close()

async connect() → bool

Attempt to connect using the previously set tokens.

Raises:

• NotSupportedException – screen does not allow lounge client

• NotLinkedException – client is not yet linked, first pair or refresh authorization

connected() → bool

Returns true if the screen’s session is connected.

async disconnect() → bool

Disconnect from the current session.

Raises:

NotConnectedException – the client is already not connected

async get_now_playing() → bool

Requests a now playing update from the screen.

Raises:

NotConnectedException – the client is not connected to the screen

async is_available() → bool

Asks YouTube API if the screen is available. Must be linked prior to this.

Raises:

NotLinkedException – client is not yet linked, first pair or refresh authorization

linked() → bool

Returns true if paired and lounge id token is known.

load_auth_state(data: dict)

Use deserialized auth parameters

async next() → bool

Sends next command to screen

Raises:

NotConnectedException – the client is not connected to the screen

async pair(pairing_code: str) → bool

Pair with a device using a manual input pairing code

async pair_with_screen_id(screen_id: str, screen_name: str | None = None) → bool

Pair with a device using a known screen id Optionally specify the screen name if already known

paired() → bool

Returns true if screen id is known.

async pause() → bool

Sends pause command to screen

Raises:

NotConnectedException – the client is not connected to the screen

async play() → bool

Sends play command to screen

async play_video(video_id: str) → bool

Sends setPlaylist command to screen to play a specific video

Raises:

NotConnectedException – the client is not connected to the screen

async previous() → bool

Sends previous command to screen

Raises:

NotConnectedException – the client is not connected to the screen

async refresh_auth() → bool

Refresh lounge token using stored refresh token.

Raises:

NotPairedException – the screen is not yet known, pair first

property screen_device_name: str | None

Returns device name built from device info returned by YouTube. Returns None if not yet initialized or information was not sent.

Raises:

NotConnectedException – screen is not yet connected

property screen_name: str | None

Returns screen name as returned by YouTube.

Raises:

NotLinkedException – there is no screen linked yet

async seek_to(time: float) → bool

Seek to given time (seconds)

Raises:

NotConnectedException – the client is not connected to the screen

async send_dpad_command(button_input: DpadCommand) → bool

Sends a dpad command like a remote.

Raises:

NotConnectedException – the client is not connected to the screen

async set_auto_play_mode(enabled: bool) → bool

Set auto play mode enabled/disabled

Raises:

NotConnectedException – the client is not connected to the screen

async set_closed_captions(language_code: str | None, video_id: str)

Sets the closed captions to the provided BCP-47 language_code if available. Provide the language_code as None to toggle closed captions to off. video_id is always required.

Raises:

NotConnectedException – the client is not connected to the screen

async set_playback_speed(speed: float) → bool

Sets the playback speed to given value (0.25-2)

Raises:

NotConnectedException – the client is not connected to the screen

async set_volume(volume: int) → bool

Sets volume to given value (0-100)

Raises:

NotConnectedException – the client is not connected to the screen

async skip_ad() → bool

Skips ad if possible

Raises:

NotConnectedException – the client is not connected to the screen

store_auth_state() → dict

Return auth parameters as dict which can be serialized for later use

async subscribe() → None

Start listening for events. Updates will be sent to the event_listener passed when creating this object.

Raises:

• NotSupportedException – screen does not allow lounge client

• NotConnectedException – the client is not yet connected to the screen