0
# Core Device Control
1

2
The main Chromecast class provides comprehensive device connection management, app launching, volume control, and status monitoring. It handles connection lifecycle, error recovery, and provides access to specialized controllers for extended functionality.
3

4
## Capabilities
5

6
### Chromecast Device Interface
7

8
Main class for interacting with a specific Chromecast device, handling all aspects of device communication and control.
9

10
```python { .api }
11
class Chromecast:
12
    """
13
    Class to interface with a ChromeCast device.
14

15
    Parameters:
16
    - cast_info: CastInfo, Information for the device
17
    - tries: int | None, Number of retries if connection fails. None for infinite retries.
18
    - timeout: float | None, Socket timeout in seconds. None for default (30 seconds).
19
    - retry_wait: float | None, Seconds to wait between retries. None for default (5 seconds).
20
    - zconf: zeroconf.Zeroconf | None, Zeroconf instance for mDNS services.
21
    """
22
    def __init__(self, cast_info, *, tries=None, timeout=None, retry_wait=None, zconf=None): ...
23
```
24

25
### Connection Management
26

27
Control the connection lifecycle and wait for device readiness.
28

29
```python { .api }
30
def wait(self, timeout=None):
31
    """
32
    Waits until the cast device is ready for communication.
33
    
34
    If the worker thread is not already running, it will be started.
35
    If the status has already been received then the method returns immediately.
36

37
    Parameters:
38
    - timeout: float | None, Timeout for the operation in seconds. None to block forever.
39
    
40
    Raises:
41
    - RequestTimeout: If timeout expires before device is ready
42
    """
43

44
def start(self):
45
    """Start the chromecast connection's worker thread."""
46

47
def disconnect(self, timeout=None):
48
    """
49
    Disconnects the chromecast and waits for it to terminate.
50

51
    Parameters:
52
    - timeout: float | None, Timeout for the operation in seconds. None to block forever.
53
                              Set to 0 to not block.
54
    """
55

56
def join(self, timeout=None):
57
    """
58
    Blocks the thread of the caller until the chromecast connection is stopped.
59

60
    Parameters:
61
    - timeout: float | None, Timeout for the operation in seconds. None to block forever.
62
    
63
    Raises:
64
    - TimeoutError: If timeout expires before connection stops
65
    """
66
```
67

68
**Usage Example:**
69

70
```python
71
import pychromecast
72

73
# Get a device
74
chromecasts, browser = pychromecast.get_chromecasts()
75
cast = chromecasts[0]
76

77
# Wait for device to be ready
78
try:
79
    cast.wait(timeout=10.0)
80
    print("Device is ready for communication")
81
except pychromecast.RequestTimeout:
82
    print("Device did not become ready within timeout")
83

84
# Use the device...
85

86
# Disconnect when done
87
cast.disconnect(timeout=5.0)
88
browser.stop_discovery()
89
```
90

91
### Application Management
92

93
Launch and quit applications on the Chromecast device.
94

95
```python { .api }
96
def start_app(self, app_id, force_launch=False, timeout=REQUEST_TIMEOUT):
97
    """
98
    Start an app on the Chromecast.
99

100
    Parameters:
101
    - app_id: str, Application ID to launch
102
    - force_launch: bool, Force launch even if app is already running
103
    - timeout: float, Request timeout in seconds
104

105
    Raises:
106
    - RequestTimeout: If app launch times out
107
    - RequestFailed: If app launch fails
108
    """
109

110
def quit_app(self, timeout=REQUEST_TIMEOUT):
111
    """
112
    Tells the Chromecast to quit current app.
113

114
    Parameters:
115
    - timeout: float, Request timeout in seconds
116

117
    Raises:
118
    - RequestTimeout: If quit request times out
119
    - RequestFailed: If quit request fails
120
    """
121
```
122

123
**Usage Example:**
124

125
```python
126
# Launch YouTube app
127
cast.start_app(pychromecast.APP_YOUTUBE)
128

129
# Wait for app to start
130
cast.wait()
131

132
# Check what's running
133
print(f"Current app: {cast.app_display_name} (ID: {cast.app_id})")
134

135
# Quit the current app
136
cast.quit_app()
137

138
# Launch with force (stops current app first)
139
cast.start_app(pychromecast.APP_MEDIA_RECEIVER, force_launch=True)
140
```
141

142
### Volume Control
143

144
Control device volume level and mute state.
145

146
```python { .api }
147
def volume_up(self, delta=0.1, timeout=REQUEST_TIMEOUT):
148
    """
149
    Increment volume by delta unless it is already maxed.
150

151
    Parameters:
152
    - delta: float, Volume increase amount (must be > 0)
153
    - timeout: float, Request timeout in seconds
154

155
    Returns:
156
    float: New volume level
157

158
    Raises:
159
    - ValueError: If delta <= 0
160
    - NotConnected: If not connected to device
161
    - RequestTimeout: If request times out
162
    """
163

164
def volume_down(self, delta=0.1, timeout=REQUEST_TIMEOUT):
165
    """
166
    Decrement the volume by delta unless it is already 0.
167

168
    Parameters:
169
    - delta: float, Volume decrease amount (must be > 0)  
170
    - timeout: float, Request timeout in seconds
171

172
    Returns:
173
    float: New volume level
174

175
    Raises:
176
    - ValueError: If delta <= 0
177
    - NotConnected: If not connected to device
178
    - RequestTimeout: If request times out
179
    """
180

181
def set_volume(self, volume, timeout=REQUEST_TIMEOUT):
182
    """
183
    Set the volume level (forwarded from receiver controller).
184

185
    Parameters:
186
    - volume: float, Volume level (0.0 to 1.0)
187
    - timeout: float, Request timeout in seconds
188

189
    Returns:
190
    float: New volume level
191
    """
192

193
def set_volume_muted(self, muted, timeout=REQUEST_TIMEOUT):
194
    """
195
    Set the mute state (forwarded from receiver controller).
196

197
    Parameters:
198
    - muted: bool, True to mute, False to unmute
199
    - timeout: float, Request timeout in seconds
200
    """
201
```
202

203
**Usage Example:**
204

205
```python
206
# Check current volume
207
print(f"Current volume: {cast.status.volume_level}")
208
print(f"Muted: {cast.status.volume_muted}")
209

210
# Adjust volume
211
new_volume = cast.volume_up(0.2)  # Increase by 20%
212
print(f"New volume: {new_volume}")
213

214
cast.volume_down(0.1)  # Decrease by 10%
215

216
# Set specific volume
217
cast.set_volume(0.5)  # Set to 50%
218

219
# Mute/unmute
220
cast.set_volume_muted(True)   # Mute
221
cast.set_volume_muted(False)  # Unmute
222
```
223

224
### Device Properties
225

226
Access device information and current status.
227

228
```python { .api }
229
@property
230
def uuid(self) -> UUID:
231
    """Returns the unique UUID of the Chromecast device."""
232

233
@property  
234
def name(self) -> str | None:
235
    """
236
    Returns the friendly name set for the Chromecast device.
237
    This is the name that the end-user chooses for the cast device.
238
    """
239

240
@property
241
def uri(self) -> str:
242
    """Returns the device URI (ip:port)"""
243

244
@property
245
def model_name(self) -> str:
246
    """Returns the model name of the Chromecast device."""
247

248
@property
249
def cast_type(self) -> str:
250
    """
251
    Returns the type of the Chromecast device.
252
    One of CAST_TYPE_CHROMECAST, CAST_TYPE_AUDIO, or CAST_TYPE_GROUP.
253
    """
254

255
@property
256
def app_id(self) -> str | None:
257
    """Returns the current app_id."""
258

259
@property
260
def app_display_name(self) -> str | None:
261
    """Returns the name of the current running app."""
262

263
@property
264
def status(self) -> CastStatus | None:
265
    """Returns the current cast status."""
266

267
@property
268
def is_idle(self) -> bool:
269
    """Returns if there is currently an app running."""
270

271
@property
272
def ignore_cec(self) -> bool:
273
    """Returns whether the CEC data should be ignored."""
274

275
@property
276
def media_controller(self) -> MediaController:
277
    """Returns the media controller."""
278
```
279

280
**Usage Example:**
281

282
```python
283
# Device information
284
print(f"Device: {cast.name}")
285
print(f"UUID: {cast.uuid}")
286
print(f"Model: {cast.model_name}")
287
print(f"Type: {cast.cast_type}")
288
print(f"URI: {cast.uri}")
289

290
# Current state
291
print(f"Is idle: {cast.is_idle}")
292
if cast.status:
293
    print(f"Volume: {cast.status.volume_level}")
294
    print(f"Muted: {cast.status.volume_muted}")
295
    
296
if cast.app_id:
297
    print(f"Running app: {cast.app_display_name} ({cast.app_id})")
298

299
# Access controllers
300
media_ctrl = cast.media_controller
301
print(f"Media controller: {media_ctrl}")
302
```
303

304
### Event Listeners
305

306
Register listeners for device status changes and errors.
307

308
```python { .api }
309
def register_status_listener(self, listener):
310
    """
311
    Register a status listener for when a new Chromecast status has been received.
312
    Listeners will be called with listener.new_cast_status(status).
313

314
    Parameters:
315
    - listener: CastStatusListener, Object with new_cast_status method
316
    """
317

318
def register_launch_error_listener(self, listener):
319
    """
320
    Register a listener for when a new launch error message has been received.
321
    Listeners will be called with listener.new_launch_error(launch_failure).
322

323
    Parameters:
324
    - listener: LaunchErrorListener, Object with new_launch_error method
325
    """
326

327
def register_connection_listener(self, listener):
328
    """
329
    Register a connection listener (forwarded from socket client).
330

331
    Parameters:
332
    - listener: ConnectionStatusListener, Object with connection status methods
333
    """
334

335
def new_cast_status(self, status):
336
    """
337
    Called when a new status received from the Chromecast.
338

339
    Parameters:
340
    - status: CastStatus, New status information
341
    """
342
```
343

344
**Usage Example:**
345

346
```python
347
class MyStatusListener:
348
    def new_cast_status(self, status):
349
        print(f"Status update - App: {status.display_name}, Volume: {status.volume_level}")
350

351
class MyLaunchErrorListener:
352
    def new_launch_error(self, launch_failure):
353
        print(f"Launch failed: {launch_failure.reason} for app {launch_failure.app_id}")
354

355
# Register listeners
356
status_listener = MyStatusListener()
357
error_listener = MyLaunchErrorListener()
358

359
cast.register_status_listener(status_listener)
360
cast.register_launch_error_listener(error_listener)
361

362
# Now status changes and launch errors will trigger the listeners
363
```
364

365
### Message Handling
366

367
Register custom message handlers and forward media control methods.
368

369
```python { .api }
370
def register_handler(self, handler):
371
    """Register message handler (forwarded from socket client)."""
372

373
def unregister_handler(self, handler):
374
    """Unregister message handler (forwarded from socket client)."""
375

376
def play_media(self, url, content_type, **kwargs):
377
    """Play media (forwarded from media controller)."""
378
```
379

380
## Types
381

382
```python { .api }
383
class CastStatus:
384
    """Current cast device status"""
385
    is_active_input: bool | None
386
    is_stand_by: bool | None  
387
    volume_level: float
388
    volume_muted: bool
389
    app_id: str | None
390
    display_name: str | None
391
    namespaces: list[str]
392
    session_id: str | None
393
    transport_id: str | None
394
    status_text: str
395
    icon_url: str | None
396
    volume_control_type: str
397

398
class CastStatusListener:
399
    """Abstract listener for cast status events"""
400
    def new_cast_status(self, status: CastStatus) -> None: ...
401

402
class LaunchErrorListener:
403
    """Abstract listener for launch error events"""
404
    def new_launch_error(self, status: LaunchFailure) -> None: ...
405

406
class LaunchFailure:
407
    """Launch failure information"""
408
    reason: str | None
409
    app_id: str | None
410
    request_id: int | None
411
```
412

413
## Constants
414

415
```python { .api }
416
REQUEST_TIMEOUT = 10.0  # Default request timeout in seconds
417
IDLE_APP_ID = "E8C28D3C"  # Backdrop/idle app ID
418

419
# Cast Types  
420
CAST_TYPE_CHROMECAST = "cast"
421
CAST_TYPE_AUDIO = "audio"
422
CAST_TYPE_GROUP = "group"
423

424
# Volume Control Types
425
VOLUME_CONTROL_TYPE_ATTENUATION = "attenuation"
426
VOLUME_CONTROL_TYPE_FIXED = "fixed" 
427
VOLUME_CONTROL_TYPE_MASTER = "master"
428
```