PyYTLounge

3.2.0 verified Fri May 01 auth: no python

A Python wrapper for the YouTube Lounge API, enabling remote control of YouTube on connected screens (e.g., TV, Chromecast). Current version 3.2.0, requires Python >=3.9. Released on GitHub with active maintenance, roughly monthly release cadence.

pip install pyytlounge

Common errors

error AttributeError: 'YtLoungeApi' object has no attribute 'subscribe' ↓

cause subscribe() removed in v3.0.0 in favor of EventListener.

fix

Use api.set_event_listener(YourListener()) instead of api.subscribe(callback).

error TypeError: disconnected() takes 1 positional argument but 2 were given ↓

cause disconnected() signature changed in v3.2.0; now expects a DisconnectedEvent argument.

fix

Change method to async def disconnected(self, event: DisconnectedEvent).

error ModuleNotFoundError: No module named 'pyytlounge.api' ↓

cause User tries to import from submodule that doesn't exist at top level.

fix

Use from pyytlounge import YtLoungeApi (not pyytlounge.api).

error pyytlounge.exceptions.NotSupportedException: YouTube TV Kids not supported ↓

cause The screen is using YouTube TV Kids, which is not supported.

fix

Use a standard YouTube screen (not Kids mode).

Warnings

breaking In v3.0.0, the event system changed from subscribe(callback) to EventListener class. Old subscribe() no longer works. ↓

fix Subclass EventListener and pass instance to set_event_listener(). See migration guide.

breaking In v3.2.0, EventListener.disconnected() signature changed: now takes DisconnectedEvent instead of plain self. ↓

fix Update method signature: async def disconnected(self, event: DisconnectedEvent)

gotcha Pairing code is required; screen device name alone will not work. Use create_credentials(screen_name, code). ↓

fix Ensure you have a valid pairing code from the YouTube screen (Settings -> Link with TV code).

gotcha Connecting to a screen without any video playing may raise an exception or hang. v3.0.1 fixed some cases. ↓

fix Upgrade to >=3.0.1 and ensure screen has content playing.

gotcha Python 3.9+ required. v2.2.1 added 3.9 support, but newer versions require >=3.9. ↓

fix Upgrade Python to 3.9+ or use pyytlounge 2.2.1.

Imports

YtLoungeApi
wrong
```
from pyytlounge.api import YtLoungeApi
```
correct
```
from pyytlounge import YtLoungeApi
```
Incorrect submodule path; common mistake from older versions.
EventListener
```
from pyytlounge import EventListener
```
Listener base class for v3.x event system.
DisconnectedEvent
```
from pyytlounge import DisconnectedEvent
```
Event object for disconnected callback.

create_credentials

wrong

from pyytlounge.api import create_credentials

correct

from pyytlounge import create_credentials

create_credentials is top-level, not under api.

Quickstart

Basic example of connecting to a YouTube screen and playing a video.

import asyncio
from pyytlounge import YtLoungeApi, create_credentials, EventListener

class MyListener(EventListener):
    async def disconnected(self, event):
        print(f"Disconnected: {event.reason}")

async def main():
    credentials = create_credentials("YOUR_SCREEN_NAME", "YOUR_PAIRING_CODE")
    api = YtLoungeApi(credentials)
    api.set_event_listener(MyListener())
    await api.connect()
    await api.play_video("dQw4w9WgXcQ")
    await asyncio.sleep(10)
    await api.disconnect()

asyncio.run(main())