PyChromecast

raw JSON →

14.0.10 verified Mon Apr 27 auth: no python

Python module to talk to Google Chromecast. v14.0.10 requires Python >=3.11. Active development by Home Assistant team.

pip install pychromecast

Common errors

error AttributeError: module 'pychromecast' has no attribute 'Chromecast' ↓

cause Importing directly from pychromecast module without knowing the correct import path.

fix

Use from pychromecast import Chromecast or from pychromecast.controllers import Chromecast

error TypeError: get_chromecasts() got multiple values for argument 'blocking' ↓

cause Passing positional arguments that are now keyword-only in v14.

fix

Use keyword arguments: get_chromecasts(blocking=True, callback=my_callback)

error zeroconf.BadServiceType: Service type '_googlecast._tcp.local.' is not valid ↓

cause Running multiple instances of ZeroConf service or incorrect zeroconf version.

fix

Ensure only one zeroconf instance is active per process. Upgrade zeroconf to >=0.118.0.

Warnings

breaking Breaking change in v14: optional callback arguments are now keyword-only. Passing positional callbacks will raise TypeError. ↓

fix Update calls to use keyword arguments, e.g., cast.register_handler(handler, is_registered=True).

breaking ServiceInfo class replaced with dataclass in v14. Instantiating with positional arguments breaks. ↓

fix Use keyword arguments: ServiceInfo(uuid=..., services=..., etc.).

gotcha get_chromecasts() returns a list and a Browser object. The Browser must be stopped to avoid resource leaks. ↓

fix Always call browser.stop_discovery() when done, or use context manager: with pychromecast.get_chromecasts() as (casts, browser):

gotcha Cast device may not be ready immediately after get_chromecasts(). Accessing properties before wait() can cause AttributeError. ↓

fix Call cast.wait() before using cast.device or other attributes.

Imports

Chromecast

wrong

import pychromecast; Chromecast()

correct

from pychromecast import Chromecast

Not a top-level attribute in the package module.

get_chromecasts

wrong

from pychromecast.discover import get_chromecasts

correct

from pychromecast import get_chromecasts

get_chromecasts moved to top-level in v14.

ChromecastInfo
```
from pychromecast import ChromecastInfo
```

Quickstart

Discovers Chromecasts on the network, connects to the first found, and plays a test video.

import os
import time
import pychromecast

casts, browser = pychromecast.get_chromecasts()
if casts:
    cast = casts[0]
    cast.wait()
    print(cast.device.friendly_name)
    mc = cast.media_controller
    mc.play_media('http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4', 'video/mp4')
    time.sleep(5)
    browser.stop_discovery()