0
# App Controllers
1

2
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.
3

4
## Capabilities
5

6
### YouTube Controller
7

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

10
```python { .api }
11
class YouTubeController:
12
    """Controller for YouTube Chromecast app"""
13
    
14
    def play_video(self, video_id, **kwargs):
15
        """
16
        Play a YouTube video.
17

18
        Parameters:
19
        - video_id: str, YouTube video ID
20
        - **kwargs: Additional parameters for playback
21
        """
22
        
23
    def add_to_queue(self, video_id):
24
        """Add video to YouTube queue"""
25
        
26
    def play_next(self):
27
        """Play next video in queue"""
28
        
29
    def play_previous(self):
30
        """Play previous video in queue"""
31
```
32

33
**Usage Example:**
34

35
```python
36
from pychromecast.controllers.youtube import YouTubeController
37

38
# Create and register controller
39
yt = YouTubeController()
40
cast.register_handler(yt)
41

42
# Launch YouTube app
43
yt.launch()
44

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

48
# Add more videos to queue
49
yt.add_to_queue("jNQXAC9IVRw")  # Another video
50
```
51

52
### Plex Controller
53

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

56
```python { .api }
57
class PlexController:
58
    """Controller for Plex Chromecast app"""
59
    
60
    def play_media(self, media_type, **kwargs):
61
        """
62
        Play Plex media content.
63

64
        Parameters:
65
        - media_type: str, Type of media ('video', 'music', 'photo')
66
        - **kwargs: Plex-specific parameters
67
        """
68
        
69
    def set_credentials(self, token):
70
        """Set Plex authentication token"""
71
```
72

73
**Usage Example:**
74

75
```python
76
from pychromecast.controllers.plex import PlexController
77

78
# Create and register controller
79
plex = PlexController()
80
cast.register_handler(plex)
81

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

85
# Launch Plex app
86
plex.launch()
87

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

92
### Home Assistant Controllers
93

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

96
```python { .api }
97
class HomeAssistantController:
98
    """Controller for Home Assistant Lovelace"""
99
    
100
    def show_lovelace_view(self, view_path=None, url_path=None):
101
        """
102
        Show a Lovelace view on the Chromecast.
103

104
        Parameters:
105
        - view_path: str | None, Path to Lovelace view
106
        - url_path: str | None, Custom URL path
107
        """
108

109
class HomeAssistantMediaController:
110
    """Controller for Home Assistant Media"""
111
    
112
    def quick_play(self, *, media_id, timeout=30, **kwargs):
113
        """
114
        Quick play media through Home Assistant.
115

116
        Parameters:
117
        - media_id: str, Media ID to play
118
        - timeout: float, Request timeout
119
        - **kwargs: Additional parameters
120
        """
121
```
122

123
**Usage Example:**
124

125
```python
126
from pychromecast.controllers.homeassistant import HomeAssistantController
127
from pychromecast.controllers.homeassistant_media import HomeAssistantMediaController
128

129
# Home Assistant Lovelace
130
ha = HomeAssistantController()
131
cast.register_handler(ha)
132
ha.launch()
133
ha.show_lovelace_view(view_path="lovelace/living-room")
134

135
# Home Assistant Media
136
ha_media = HomeAssistantMediaController()
137
cast.register_handler(ha_media)
138
ha_media.launch()
139
ha_media.quick_play(media_id="media_player.spotify")
140
```
141

142
### BBC Controllers
143

144
Controllers for BBC services including iPlayer and Sounds.
145

146
```python { .api }
147
class BbcIplayerController:
148
    """Controller for BBC iPlayer"""
149
    
150
    def quick_play(self, *, media_id, timeout=30, **kwargs):
151
        """Play BBC iPlayer content"""
152

153
class BbcSoundsController:
154
    """Controller for BBC Sounds"""
155
    
156
    def quick_play(self, *, media_id, timeout=30, **kwargs):
157
        """Play BBC Sounds content"""
158
```
159

160
**Usage Example:**
161

162
```python
163
from pychromecast.controllers.bbciplayer import BbcIplayerController
164
from pychromecast.controllers.bbcsounds import BbcSoundsController
165

166
# BBC iPlayer
167
iplayer = BbcIplayerController()
168
cast.register_handler(iplayer)
169
iplayer.quick_play(media_id="programme_id")
170

171
# BBC Sounds
172
sounds = BbcSoundsController()
173
cast.register_handler(sounds)
174
sounds.quick_play(media_id="episode_id")
175
```
176

177
### Media-Specific Controllers
178

179
Controllers for specialized media applications and services.
180

181
```python { .api }
182
class BubbleUPNPController:
183
    """Controller for BubbleUPNP media server"""
184
    
185
    def quick_play(self, *, media_id, timeout=30, **kwargs):
186
        """Play media through BubbleUPNP"""
187

188
class DashCastController:
189
    """Controller for DashCast"""
190
    
191
    def load_url(self, url, force=False, reload_seconds=None):
192
        """Load a URL in DashCast"""
193

194
class SuplaController:
195
    """Controller for Supla home automation"""
196
    
197
    def quick_play(self, *, media_id, timeout=30, **kwargs):
198
        """Control Supla devices"""
199
```
200

201
**Usage Example:**
202

203
```python
204
from pychromecast.controllers.bubbleupnp import BubbleUPNPController
205
from pychromecast.controllers.dashcast import DashCastController
206

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

212
# DashCast for web content
213
dash = DashCastController()
214
cast.register_handler(dash)
215
dash.launch()
216
dash.load_url("https://dashboard.example.com")
217
```
218

219
### International Controllers
220

221
Controllers for international streaming services.
222

223
```python { .api }
224
class YleAreenaController:
225
    """Controller for Yle Areena (Finnish broadcasting)"""
226
    
227
    def quick_play(self, *, media_id, timeout=30, **kwargs):
228
        """Play Yle Areena content"""
229

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

236
class NrkRadioController:
237
    """Controller for NRK Radio (Norwegian broadcasting)"""
238
    
239
    def quick_play(self, *, media_id, timeout=30, **kwargs):
240
        """Play NRK Radio content"""
241
```
242

243
### Advanced Controllers
244

245
Controllers for specialized playback and multi-room features.
246

247
```python { .api }
248
class ShakaController:
249
    """Controller for Shaka Player (adaptive streaming)"""
250
    
251
    def quick_play(self, *, media_id, timeout=30, **kwargs):
252
        """Play adaptive streaming content"""
253

254
class MultizoneController:
255
    """Controller for multi-room audio groups"""
256
    
257
    def get_multizone_status(self):
258
        """Get multi-room audio status"""
259
        
260
    def set_multizone_config(self, config):
261
        """Configure multi-room audio setup"""
262
```
263

264
### Quick Play Interface
265

266
Universal quick play interface for compatible controllers.
267

268
```python { .api }
269
def quick_play(cast, app_name, data, timeout=30.0):
270
    """
271
    Given a Chromecast connection, launch the app and start playing media
272
    based on parameters defined in data.
273

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

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

283
    Optional in data:
284
    - media_type: str, Type of media identified by media_id
285
    - enqueue: bool, Enqueue the media to current playlist
286
    - index: str, Play index x of matching media
287
    - audio_lang: str, Audio language preference
288
    - subtitle_lang: str, Subtitle language preference
289
    """
290
```
291

292
**Usage Example:**
293

294
```python
295
import pychromecast.quick_play as quick_play
296

297
# Quick play YouTube video
298
quick_play.quick_play(
299
    cast=cast,
300
    app_name="youtube", 
301
    data={"media_id": "dQw4w9WgXcQ"},
302
    timeout=30.0
303
)
304

305
# Quick play with options
306
quick_play.quick_play(
307
    cast=cast,
308
    app_name="bubbleupnp",
309
    data={
310
        "media_id": "http://example.com/video.mp4",
311
        "media_type": "video/mp4",
312
        "enqueue": False
313
    }
314
)
315
```
316

317
## Base Controller Pattern
318

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

321
```python { .api }
322
class BaseController:
323
    """ABC for namespace controllers"""
324
    
325
    def __init__(self, namespace, supporting_app_id=None, 
326
                 target_platform=False, app_must_match=False): ...
327
                 
328
    def launch(self, *, callback_function=None, force_launch=False):
329
        """Launch the associated app"""
330
        
331
    def send_message(self, data, *, inc_session_id=False, 
332
                    callback_function=None, no_add_request_id=False):
333
        """Send a message on this namespace to the Chromecast"""
334
        
335
    @property
336
    def is_active(self) -> bool:
337
        """True if controller is active and namespace is supported"""
338

339
class QuickPlayController(BaseController):
340
    """ABC for controller which supports quick play"""
341
    
342
    def quick_play(self, *, media_id, timeout, **kwargs):
343
        """Quick Play support for a controller"""
344
```
345

346
## App ID Constants
347

348
```python { .api }
349
# From pychromecast.config
350
APP_BACKDROP = "E8C28D3C"           # Default backdrop/idle app
351
APP_YOUTUBE = "233637DE"            # YouTube
352
APP_MEDIA_RECEIVER = "CC1AD845"    # Default media receiver
353
APP_PLEX = "06ee44ee-e7e3-4249-83b6-f5d0b6f07f34_1"  # Plex
354
APP_DASHCAST = "84912283"           # DashCast
355
APP_HOMEASSISTANT_LOVELACE = "A078F6B0"  # Home Assistant Lovelace
356
APP_HOMEASSISTANT_MEDIA = "B45F4572"     # Home Assistant Media
357
APP_SUPLA = "A41B766D"              # Supla
358
APP_YLEAREENA = "A9BCCB7C"          # Yle Areena
359
APP_BUBBLEUPNP = "3927FA74"         # BubbleUPNP
360
APP_BBCSOUNDS = "D350F6A9"          # BBC Sounds
361
APP_BBCIPLAYER = "5E81F6DB"         # BBC iPlayer
362
APP_SHAKA = "07AEE832"              # Shaka Player
363
APP_NRKTV = "3AEDF8D1"              # NRK TV
364
APP_NRKRADIO = "A49874B1"           # NRK Radio
365
APP_AUDIBLE = "25456794"            # Audible
366
```
367

368
## Controller Registration Pattern
369

370
All controllers follow the same registration pattern:
371

372
```python
373
# Create controller instance
374
controller = SomeController()
375

376
# Register with Chromecast
377
cast.register_handler(controller)
378

379
# Launch the app
380
controller.launch()
381

382
# Use controller-specific methods
383
controller.some_method()
384

385
# Unregister when done
386
cast.unregister_handler(controller)
387
```