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

App Controllers

Name: tessl/pypi-pychromecast
Author: tessl

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 for launching, controlling, and interacting with their respective applications.

Capabilities

YouTube Controller

Control YouTube videos on Chromecast devices with support for video playback, playlists, and YouTube-specific features.

class YouTubeController:
    """Controller for YouTube Chromecast app"""
    
    def play_video(self, video_id, **kwargs):
        """
        Play a YouTube video.

        Parameters:
        - video_id: str, YouTube video ID
        - **kwargs: Additional parameters for playback
        """
        
    def add_to_queue(self, video_id):
        """Add video to YouTube queue"""
        
    def play_next(self):
        """Play next video in queue"""
        
    def play_previous(self):
        """Play previous video in queue"""

Usage Example:

from pychromecast.controllers.youtube import YouTubeController

# Create and register controller
yt = YouTubeController()
cast.register_handler(yt)

# Launch YouTube app
yt.launch()

# Play a video (using video ID from URL)
yt.play_video("dQw4w9WgXcQ")  # Rick Roll video ID

# Add more videos to queue
yt.add_to_queue("jNQXAC9IVRw")  # Another video

Plex Controller

Control Plex media server content with support for movies, TV shows, music, and Plex-specific features.

class PlexController:
    """Controller for Plex Chromecast app"""
    
    def play_media(self, media_type, **kwargs):
        """
        Play Plex media content.

        Parameters:
        - media_type: str, Type of media ('video', 'music', 'photo')
        - **kwargs: Plex-specific parameters
        """
        
    def set_credentials(self, token):
        """Set Plex authentication token"""

Usage Example:

from pychromecast.controllers.plex import PlexController

# Create and register controller
plex = PlexController()
cast.register_handler(plex)

# Set authentication
plex.set_credentials("your-plex-token")

# Launch Plex app
plex.launch()

# Play media (requires Plex server setup)
plex.play_media('video', server_url='http://plex-server:32400', key='/library/metadata/12345')

Home Assistant Controllers

Controllers for Home Assistant integration, supporting both Lovelace dashboards and media playback.

class HomeAssistantController:
    """Controller for Home Assistant Lovelace"""
    
    def show_lovelace_view(self, view_path=None, url_path=None):
        """
        Show a Lovelace view on the Chromecast.

        Parameters:
        - view_path: str | None, Path to Lovelace view
        - url_path: str | None, Custom URL path
        """

class HomeAssistantMediaController:
    """Controller for Home Assistant Media"""
    
    def quick_play(self, *, media_id, timeout=30, **kwargs):
        """
        Quick play media through Home Assistant.

        Parameters:
        - media_id: str, Media ID to play
        - timeout: float, Request timeout
        - **kwargs: Additional parameters
        """

Usage Example:

from pychromecast.controllers.homeassistant import HomeAssistantController
from pychromecast.controllers.homeassistant_media import HomeAssistantMediaController

# Home Assistant Lovelace
ha = HomeAssistantController()
cast.register_handler(ha)
ha.launch()
ha.show_lovelace_view(view_path="lovelace/living-room")

# Home Assistant Media
ha_media = HomeAssistantMediaController()
cast.register_handler(ha_media)
ha_media.launch()
ha_media.quick_play(media_id="media_player.spotify")

BBC Controllers

Controllers for BBC services including iPlayer and Sounds.

class BbcIplayerController:
    """Controller for BBC iPlayer"""
    
    def quick_play(self, *, media_id, timeout=30, **kwargs):
        """Play BBC iPlayer content"""

class BbcSoundsController:
    """Controller for BBC Sounds"""
    
    def quick_play(self, *, media_id, timeout=30, **kwargs):
        """Play BBC Sounds content"""

Usage Example:

from pychromecast.controllers.bbciplayer import BbcIplayerController
from pychromecast.controllers.bbcsounds import BbcSoundsController

# BBC iPlayer
iplayer = BbcIplayerController()
cast.register_handler(iplayer)
iplayer.quick_play(media_id="programme_id")

# BBC Sounds
sounds = BbcSoundsController()
cast.register_handler(sounds)
sounds.quick_play(media_id="episode_id")

Media-Specific Controllers

Controllers for specialized media applications and services.

class BubbleUPNPController:
    """Controller for BubbleUPNP media server"""
    
    def quick_play(self, *, media_id, timeout=30, **kwargs):
        """Play media through BubbleUPNP"""

class DashCastController:
    """Controller for DashCast"""
    
    def load_url(self, url, force=False, reload_seconds=None):
        """Load a URL in DashCast"""

class SuplaController:
    """Controller for Supla home automation"""
    
    def quick_play(self, *, media_id, timeout=30, **kwargs):
        """Control Supla devices"""

Usage Example:

from pychromecast.controllers.bubbleupnp import BubbleUPNPController
from pychromecast.controllers.dashcast import DashCastController

# BubbleUPNP for media serving
bubble = BubbleUPNPController()
cast.register_handler(bubble)
bubble.quick_play(media_id="media_file.mp4", media_type="video/mp4")

# DashCast for web content
dash = DashCastController()
cast.register_handler(dash)
dash.launch()
dash.load_url("https://dashboard.example.com")

International Controllers

Controllers for international streaming services.

class YleAreenaController:
    """Controller for Yle Areena (Finnish broadcasting)"""
    
    def quick_play(self, *, media_id, timeout=30, **kwargs):
        """Play Yle Areena content"""

class NrkTvController:
    """Controller for NRK TV (Norwegian broadcasting)"""
    
    def quick_play(self, *, media_id, timeout=30, **kwargs):
        """Play NRK TV content"""

class NrkRadioController:
    """Controller for NRK Radio (Norwegian broadcasting)"""
    
    def quick_play(self, *, media_id, timeout=30, **kwargs):
        """Play NRK Radio content"""

Advanced Controllers

Controllers for specialized playback and multi-room features.

class ShakaController:
    """Controller for Shaka Player (adaptive streaming)"""
    
    def quick_play(self, *, media_id, timeout=30, **kwargs):
        """Play adaptive streaming content"""

class MultizoneController:
    """Controller for multi-room audio groups"""
    
    def get_multizone_status(self):
        """Get multi-room audio status"""
        
    def set_multizone_config(self, config):
        """Configure multi-room audio setup"""

Quick Play Interface

Universal quick play interface for compatible controllers.

def quick_play(cast, app_name, data, timeout=30.0):
    """
    Given a Chromecast connection, launch the app and start playing media
    based on parameters defined in data.

    Parameters:
    - cast: Chromecast, Chromecast connection to cast to
    - app_name: str, App name "slug" to cast
    - data: dict[str, Any], Data to send to the app controller
    - timeout: float, Request timeout

    Required in data:
    - media_id: str, Primary identifier of the media

    Optional in data:
    - media_type: str, Type of media identified by media_id
    - enqueue: bool, Enqueue the media to current playlist
    - index: str, Play index x of matching media
    - audio_lang: str, Audio language preference
    - subtitle_lang: str, Subtitle language preference
    """

Usage Example:

import pychromecast.quick_play as quick_play

# Quick play YouTube video
quick_play.quick_play(
    cast=cast,
    app_name="youtube", 
    data={"media_id": "dQw4w9WgXcQ"},
    timeout=30.0
)

# Quick play with options
quick_play.quick_play(
    cast=cast,
    app_name="bubbleupnp",
    data={
        "media_id": "http://example.com/video.mp4",
        "media_type": "video/mp4",
        "enqueue": False
    }
)

Base Controller Pattern

All app controllers follow a consistent pattern based on the BaseController class.

class BaseController:
    """ABC for namespace controllers"""
    
    def __init__(self, namespace, supporting_app_id=None, 
                 target_platform=False, app_must_match=False): ...
                 
    def launch(self, *, callback_function=None, force_launch=False):
        """Launch the associated app"""
        
    def send_message(self, data, *, inc_session_id=False, 
                    callback_function=None, no_add_request_id=False):
        """Send a message on this namespace to the Chromecast"""
        
    @property
    def is_active(self) -> bool:
        """True if controller is active and namespace is supported"""

class QuickPlayController(BaseController):
    """ABC for controller which supports quick play"""
    
    def quick_play(self, *, media_id, timeout, **kwargs):
        """Quick Play support for a controller"""

App ID Constants

# From pychromecast.config
APP_BACKDROP = "E8C28D3C"           # Default backdrop/idle app
APP_YOUTUBE = "233637DE"            # YouTube
APP_MEDIA_RECEIVER = "CC1AD845"    # Default media receiver
APP_PLEX = "06ee44ee-e7e3-4249-83b6-f5d0b6f07f34_1"  # Plex
APP_DASHCAST = "84912283"           # DashCast
APP_HOMEASSISTANT_LOVELACE = "A078F6B0"  # Home Assistant Lovelace
APP_HOMEASSISTANT_MEDIA = "B45F4572"     # Home Assistant Media
APP_SUPLA = "A41B766D"              # Supla
APP_YLEAREENA = "A9BCCB7C"          # Yle Areena
APP_BUBBLEUPNP = "3927FA74"         # BubbleUPNP
APP_BBCSOUNDS = "D350F6A9"          # BBC Sounds
APP_BBCIPLAYER = "5E81F6DB"         # BBC iPlayer
APP_SHAKA = "07AEE832"              # Shaka Player
APP_NRKTV = "3AEDF8D1"              # NRK TV
APP_NRKRADIO = "A49874B1"           # NRK Radio
APP_AUDIBLE = "25456794"            # Audible

Controller Registration Pattern

All controllers follow the same registration pattern:

# Create controller instance
controller = SomeController()

# Register with Chromecast
cast.register_handler(controller)

# Launch the app
controller.launch()

# Use controller-specific methods
controller.some_method()

# Unregister when done
cast.unregister_handler(controller)

Install with Tessl CLI