or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

app-controllers.mdcore-device-control.mddevice-discovery.mderror-handling.mdindex.mdmedia-control.md
tile.json

tessl/pypi-pychromecast

Python module to talk to Google Chromecast.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pychromecast@14.0.x

To install, run

npx @tessl/cli install tessl/pypi-pychromecast@14.0.0

index.mddocs/

PyChromecast

A comprehensive Python library that enables developers to communicate with Google Chromecast devices over the network. PyChromecast provides automatic discovery of Chromecast devices using mDNS/Zeroconf, implements the Google Cast protocol v2 for device communication, and offers full control over media playback and device management.

Package Information

  • Package Name: PyChromecast
  • Language: Python
  • Installation: pip install PyChromecast

Core Imports

import pychromecast

Main functions and classes:

from pychromecast import get_chromecasts, Chromecast

Specific components:

from pychromecast.controllers.media import MediaController
from pychromecast.error import ChromecastConnectionError, NotConnected
from pychromecast import CAST_TYPE_CHROMECAST, CAST_TYPE_AUDIO, CAST_TYPE_GROUP

Basic Usage

import pychromecast
import time

# Discover all Chromecast devices on the network
chromecasts, browser = pychromecast.get_chromecasts()

if chromecasts:
    # Select the first device
    cast = chromecasts[0]
    
    # Wait for the device to be ready
    cast.wait()
    
    print(f"Connected to: {cast.name}")
    print(f"Device model: {cast.model_name}")
    print(f"Cast type: {cast.cast_type}")
    
    # Play a media file
    media_url = "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
    cast.media_controller.play_media(media_url, 'video/mp4')
    
    # Wait for media to start
    cast.media_controller.block_until_active()
    
    # Control playback
    time.sleep(10)
    cast.media_controller.pause()
    time.sleep(5)
    cast.media_controller.play()
    
    # Disconnect when done
    cast.disconnect()

# Stop discovery
browser.stop_discovery()

Architecture

PyChromecast uses a layered architecture for flexible device communication:

  • Discovery Layer: mDNS/Zeroconf-based device discovery with automatic service monitoring
  • Connection Layer: Socket-based communication implementing Google Cast protocol v2
  • Controller Layer: Modular controllers for different apps and namespaces
  • Public API: High-level interfaces for device and media control

The controller architecture enables extensibility through app-specific controllers while maintaining a consistent interface pattern.

Capabilities

Device Discovery

Comprehensive network discovery of Chromecast devices using mDNS/Zeroconf. Supports both blocking and callback-based discovery, device filtering by name or UUID, and continuous service monitoring for dynamic device management.

def get_chromecasts(tries=None, retry_wait=None, timeout=None, blocking=True, 
                   callback=None, zeroconf_instance=None, known_hosts=None):
    """Discover all Chromecast devices on network"""

def get_listed_chromecasts(friendly_names=None, uuids=None, tries=None, 
                          retry_wait=None, timeout=None, discovery_timeout=5, 
                          zeroconf_instance=None, known_hosts=None):  
    """Discover specific Chromecast devices by name or UUID"""

def discover_chromecasts(max_devices=None, timeout=5, zeroconf_instance=None, known_hosts=None):
    """Discover devices without connecting (DEPRECATED)"""

Device Discovery

Core Device Control

Main Chromecast class providing device connection management, app launching, volume control, and status monitoring. Handles connection lifecycle, error recovery, and provides access to specialized controllers.

class Chromecast:
    def __init__(self, cast_info, *, tries=None, timeout=None, retry_wait=None, zconf=None): ...
    def wait(self, timeout=None): ...
    def start_app(self, app_id, force_launch=False, timeout=REQUEST_TIMEOUT): ...
    def quit_app(self, timeout=REQUEST_TIMEOUT): ...
    def volume_up(self, delta=0.1, timeout=REQUEST_TIMEOUT): ...
    def volume_down(self, delta=0.1, timeout=REQUEST_TIMEOUT): ...
    def disconnect(self, timeout=None): ...

Core Device Control

Media Control

Comprehensive media playback control supporting various content types, streaming protocols, and playback states. Provides queue management, seek operations, subtitle control, and detailed status monitoring.

class MediaController:
    def play_media(self, url, content_type, title=None, thumb=None, 
                  current_time=0, autoplay=True, stream_type=None, 
                  subtitles=None, subtitles_lang=None, subtitles_mime=None,
                  metadata=None, enqueue=False): ...
    def pause(self): ...
    def play(self): ...
    def stop(self): ...
    def seek(self, position): ...

Media Control

App-Specific Controllers

Specialized controllers for popular Chromecast applications including YouTube, Plex, BBC iPlayer, Home Assistant, and others. Each controller provides app-specific functionality while maintaining consistent patterns.

class YouTubeController:
    def play_video(self, video_id, **kwargs): ...

class PlexController:
    def play_media(self, media_type, **kwargs): ...

class HomeAssistantMediaController:
    def quick_play(self, *, media_id, timeout, **kwargs): ...

App Controllers

Error Handling

Comprehensive exception hierarchy for different error conditions including connection failures, protocol errors, timeout situations, and controller registration issues.

class PyChromecastError(Exception): ...
class ChromecastConnectionError(PyChromecastError): ...
class NotConnected(PyChromecastError): ...
class RequestTimeout(PyChromecastError): ...
class UnsupportedNamespace(PyChromecastError): ...

Error Handling

Types

class CastInfo:
    """Cast device information container"""
    services: set[HostServiceInfo | MDNSServiceInfo]
    uuid: UUID
    model_name: str | None
    friendly_name: str | None
    host: str
    port: int
    cast_type: str | None
    manufacturer: str | None

class CastStatus:
    """Current cast device status"""
    is_active_input: bool | None
    is_stand_by: bool | None
    volume_level: float
    volume_muted: bool
    app_id: str | None
    display_name: str | None
    namespaces: list[str]
    session_id: str | None
    transport_id: str | None
    status_text: str
    icon_url: str | None

class MediaStatus:
    """Current media playback status"""
    current_time: float
    content_id: str | None
    content_type: str | None
    duration: float | None
    stream_type: str
    idle_reason: str | None
    media_session_id: int | None
    playback_rate: float
    player_state: str
    supported_media_commands: int
    volume_level: float
    volume_muted: bool
    media_custom_data: dict
    media_metadata: dict
    subtitle_tracks: dict
    current_subtitle_tracks: list
    last_updated: datetime.datetime | None

Constants

# Cast Types
CAST_TYPE_CHROMECAST = "cast"
CAST_TYPE_AUDIO = "audio"
CAST_TYPE_GROUP = "group"

# Media Player States
MEDIA_PLAYER_STATE_PLAYING = "PLAYING"
MEDIA_PLAYER_STATE_PAUSED = "PAUSED"
MEDIA_PLAYER_STATE_IDLE = "IDLE"
MEDIA_PLAYER_STATE_BUFFERING = "BUFFERING"

# Stream Types
STREAM_TYPE_BUFFERED = "BUFFERED"
STREAM_TYPE_LIVE = "LIVE"

# Timeouts
REQUEST_TIMEOUT = 10.0
DISCOVER_TIMEOUT = 5.0