tessl/pypi-pychromecast

Python module to talk to Google Chromecast.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Device Discovery

Name: tessl/pypi-pychromecast
Author: tessl

Comprehensive network discovery of Chromecast devices using mDNS/Zeroconf protocol. PyChromecast provides multiple discovery methods for different use cases, from simple one-time discovery to continuous monitoring with callbacks.

Capabilities

Discover All Devices

Discovers all Chromecast devices on the local network, with both blocking and non-blocking modes.

def get_chromecasts(tries=None, retry_wait=None, timeout=None, blocking=True, 
                   callback=None, zeroconf_instance=None, known_hosts=None):
    """
    Searches the network for chromecast devices and creates a Chromecast object
    for each discovered device.

    Parameters:
    - tries: int | None, Number of retries to perform if connection fails. None for infinite retries.
    - retry_wait: float | None, Seconds to wait between each retry. None for default (5 seconds).
    - timeout: float | None, Socket timeout in seconds. None for default (30 seconds).
    - blocking: bool, If True returns list of devices. If False triggers callback for each device.
    - callback: callable, Callback function triggered for each discovered chromecast when blocking=False.
    - zeroconf_instance: zeroconf.Zeroconf | None, Existing zeroconf instance to use.
    - known_hosts: list[str] | None, List of known host IPs to check directly.

    Returns:
    When blocking=True: tuple[list[Chromecast], CastBrowser]
    When blocking=False: CastBrowser
    """

Usage Example:

import pychromecast

# Blocking discovery - get all devices at once
chromecasts, browser = pychromecast.get_chromecasts()
print(f"Found {len(chromecasts)} Chromecast devices")

for cast in chromecasts:
    print(f"- {cast.name} ({cast.model_name}) at {cast.uri}")

# Clean up
browser.stop_discovery()

# Non-blocking discovery with callback
def device_callback(chromecast):
    print(f"Discovered: {chromecast.name}")
    # Handle each device as it's discovered

browser = pychromecast.get_chromecasts(blocking=False, callback=device_callback)
# Discovery continues in background until stopped
browser.stop_discovery()

Discover Specific Devices

Discovers Chromecast devices matching specific friendly names or UUIDs.

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):
    """
    Searches the network for chromecast devices matching a list of friendly
    names or a list of UUIDs.

    Parameters:
    - friendly_names: list[str] | None, List of wanted friendly names
    - uuids: list[UUID] | None, List of wanted UUIDs
    - tries: int | None, Number of retries for connection
    - retry_wait: float | None, Seconds between retries
    - timeout: float | None, Socket timeout in seconds
    - discovery_timeout: float, Time to wait for devices matching criteria (default 5)
    - zeroconf_instance: zeroconf.Zeroconf | None, Existing zeroconf instance
    - known_hosts: list[str] | None, List of known host IPs to check

    Returns:
    tuple[list[Chromecast], CastBrowser]: List of matching Chromecast objects and browser
    """

Usage Example:

from uuid import UUID

# Find devices by friendly name
target_names = ["Living Room TV", "Kitchen Speaker"]
chromecasts, browser = pychromecast.get_listed_chromecasts(friendly_names=target_names)

# Find devices by UUID
target_uuids = [UUID("12345678-1234-5678-9012-123456789012")]
chromecasts, browser = pychromecast.get_listed_chromecasts(uuids=target_uuids)

# Mixed search with custom timeout
chromecasts, browser = pychromecast.get_listed_chromecasts(
    friendly_names=["Living Room TV"],
    uuids=[UUID("12345678-1234-5678-9012-123456789012")],
    discovery_timeout=10.0
)

browser.stop_discovery()

Discovery Without Connection

Discovers devices without establishing connections, useful for device enumeration.

def discover_chromecasts(max_devices=None, timeout=5, zeroconf_instance=None, known_hosts=None):
    """
    Discover chromecast devices without connecting to them.
    
    DEPRECATED: This function is deprecated as of February 2021 and will be removed.
    Use CastBrowser instead.

    Parameters:
    - max_devices: int | None, Maximum number of devices to discover before stopping
    - timeout: float, Time to wait for discovery (default 5 seconds)
    - zeroconf_instance: zeroconf.Zeroconf | None, Existing zeroconf instance
    - known_hosts: list[str] | None, List of known host IPs to check directly

    Returns:
    tuple[list[CastInfo], CastBrowser]: List of discovered device info and browser
    """

Usage Example:

# Discover without connecting
devices, browser = pychromecast.discover_chromecasts()

for device in devices:
    print(f"Found: {device.friendly_name}")
    print(f"  Model: {device.model_name}")
    print(f"  UUID: {device.uuid}")
    print(f"  Host: {device.host}:{device.port}")
    print(f"  Type: {device.cast_type}")

browser.stop_discovery()

Create from Known Information

Create Chromecast objects from known device information without discovery.

def get_chromecast_from_host(host, tries=None, retry_wait=None, timeout=None):
    """
    Creates a Chromecast object from a zeroconf host tuple.

    Parameters:
    - host: tuple[str, int, UUID, str | None, str | None], 
            Tuple of (ip_address, port, uuid, model_name, friendly_name)
    - tries: int | None, Number of connection retries
    - retry_wait: float | None, Seconds between retries  
    - timeout: float | None, Socket timeout in seconds

    Returns:
    Chromecast: Chromecast object for the host
    """

def get_chromecast_from_cast_info(cast_info, zconf, tries=None, retry_wait=None, timeout=None):
    """
    Creates a Chromecast object from a CastInfo object.

    Parameters:
    - cast_info: CastInfo, Cast device information
    - zconf: zeroconf.Zeroconf | None, Zeroconf instance for mDNS services
    - tries: int | None, Number of connection retries
    - retry_wait: float | None, Seconds between retries
    - timeout: float | None, Socket timeout in seconds

    Returns:
    Chromecast: Chromecast object for the cast info
    """

Usage Example:

from uuid import UUID

# Create from known host information
host_info = ("192.168.1.100", 8009, UUID("12345678-1234-5678-9012-123456789012"), 
             "Chromecast", "Living Room TV")
cast = pychromecast.get_chromecast_from_host(host_info)

# Create from CastInfo object
cast_info = pychromecast.CastInfo(
    services={pychromecast.HostServiceInfo("192.168.1.100", 8009)},
    uuid=UUID("12345678-1234-5678-9012-123456789012"),
    model_name="Chromecast",
    friendly_name="Living Room TV",
    host="192.168.1.100",
    port=8009,
    cast_type="cast",
    manufacturer="Google Inc."
)
cast = pychromecast.get_chromecast_from_cast_info(cast_info, None)

Discovery Management

Control discovery processes and monitor device changes.

def start_discovery(cast_browser, zeroconf_instance):
    """
    Start discovering chromecasts on the network.
    
    DEPRECATED: This function is deprecated as of February 2021 and will be removed.
    Call CastBrowser.start_discovery() instead.

    Parameters:
    - cast_browser: CastBrowser, Browser instance to start
    - zeroconf_instance: zeroconf.Zeroconf, Zeroconf instance (required)

    Returns:
    CastBrowser: The same browser instance
    """

def stop_discovery(cast_browser):
    """
    Stop the chromecast discovery threads.
    
    DEPRECATED: This function is deprecated as of February 2021 and will be removed.
    Call CastBrowser.stop_discovery() instead.

    Parameters:
    - cast_browser: CastBrowser, Browser instance to stop
    """

class CastBrowser:
    """Browser for discovering and monitoring cast devices"""
    def start_discovery(self): ...
    def stop_discovery(self): ...
    @property
    def devices(self) -> dict[UUID, CastInfo]: ...

Usage Example:

class MyCastListener(pychromecast.AbstractCastListener):
    def add_cast(self, uuid, service):
        print(f"Device added: {uuid}")
    
    def remove_cast(self, uuid, service, cast_info):
        print(f"Device removed: {uuid}")
    
    def update_cast(self, uuid, service):
        print(f"Device updated: {uuid}")

# Start continuous discovery
listener = MyCastListener()
browser = pychromecast.start_discovery(listener)

# Access discovered devices
for uuid, cast_info in browser.devices.items():
    print(f"Device: {cast_info.friendly_name} ({uuid})")

# Stop discovery
pychromecast.stop_discovery(browser)

Types

class CastInfo:
    """Information about a discovered cast device"""
    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 HostServiceInfo:
    """Host-based service information"""
    host: str
    port: int

class MDNSServiceInfo:
    """mDNS service information"""
    name: str

class AbstractCastListener:
    """Abstract base class for cast discovery listeners"""
    def add_cast(self, uuid: UUID, service: str) -> None: ...
    def remove_cast(self, uuid: UUID, service: str, cast_info: CastInfo) -> None: ...
    def update_cast(self, uuid: UUID, service: str) -> None: ...

class SimpleCastListener(AbstractCastListener):
    """Helper listener with callback functions"""
    def __init__(self, add_callback=None, remove_callback=None, update_callback=None): ...

Constants

DISCOVER_TIMEOUT = 5  # Default discovery timeout in seconds

Install with Tessl CLI

npx tessl i tessl/pypi-pychromecast

docs

app-controllers.md

core-device-control.md

tessl/pypi-pychromecast