0
# PyChromecast
1

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

4
## Package Information
5

6
- **Package Name**: PyChromecast
7
- **Language**: Python
8
- **Installation**: `pip install PyChromecast`
9

10
## Core Imports
11

12
```python
13
import pychromecast
14
```
15

16
Main functions and classes:
17

18
```python
19
from pychromecast import get_chromecasts, Chromecast
20
```
21

22
Specific components:
23

24
```python
25
from pychromecast.controllers.media import MediaController
26
from pychromecast.error import ChromecastConnectionError, NotConnected
27
from pychromecast import CAST_TYPE_CHROMECAST, CAST_TYPE_AUDIO, CAST_TYPE_GROUP
28
```
29

30
## Basic Usage
31

32
```python
33
import pychromecast
34
import time
35

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

39
if chromecasts:
40
    # Select the first device
41
    cast = chromecasts[0]
42
    
43
    # Wait for the device to be ready
44
    cast.wait()
45
    
46
    print(f"Connected to: {cast.name}")
47
    print(f"Device model: {cast.model_name}")
48
    print(f"Cast type: {cast.cast_type}")
49
    
50
    # Play a media file
51
    media_url = "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
52
    cast.media_controller.play_media(media_url, 'video/mp4')
53
    
54
    # Wait for media to start
55
    cast.media_controller.block_until_active()
56
    
57
    # Control playback
58
    time.sleep(10)
59
    cast.media_controller.pause()
60
    time.sleep(5)
61
    cast.media_controller.play()
62
    
63
    # Disconnect when done
64
    cast.disconnect()
65

66
# Stop discovery
67
browser.stop_discovery()
68
```
69

70
## Architecture
71

72
PyChromecast uses a layered architecture for flexible device communication:
73

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

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

81
## Capabilities
82

83
### Device Discovery
84

85
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.
86

87
```python { .api }
88
def get_chromecasts(tries=None, retry_wait=None, timeout=None, blocking=True, 
89
                   callback=None, zeroconf_instance=None, known_hosts=None):
90
    """Discover all Chromecast devices on network"""
91

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

97
def discover_chromecasts(max_devices=None, timeout=5, zeroconf_instance=None, known_hosts=None):
98
    """Discover devices without connecting (DEPRECATED)"""
99
```
100

101
[Device Discovery](./device-discovery.md)
102

103
### Core Device Control
104

105
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.
106

107
```python { .api }
108
class Chromecast:
109
    def __init__(self, cast_info, *, tries=None, timeout=None, retry_wait=None, zconf=None): ...
110
    def wait(self, timeout=None): ...
111
    def start_app(self, app_id, force_launch=False, timeout=REQUEST_TIMEOUT): ...
112
    def quit_app(self, timeout=REQUEST_TIMEOUT): ...
113
    def volume_up(self, delta=0.1, timeout=REQUEST_TIMEOUT): ...
114
    def volume_down(self, delta=0.1, timeout=REQUEST_TIMEOUT): ...
115
    def disconnect(self, timeout=None): ...
116
```
117

118
[Core Device Control](./core-device-control.md)
119

120
### Media Control
121

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

124
```python { .api }
125
class MediaController:
126
    def play_media(self, url, content_type, title=None, thumb=None, 
127
                  current_time=0, autoplay=True, stream_type=None, 
128
                  subtitles=None, subtitles_lang=None, subtitles_mime=None,
129
                  metadata=None, enqueue=False): ...
130
    def pause(self): ...
131
    def play(self): ...
132
    def stop(self): ...
133
    def seek(self, position): ...
134
```
135

136
[Media Control](./media-control.md)
137

138
### App-Specific Controllers
139

140
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.
141

142
```python { .api }
143
class YouTubeController:
144
    def play_video(self, video_id, **kwargs): ...
145

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

149
class HomeAssistantMediaController:
150
    def quick_play(self, *, media_id, timeout, **kwargs): ...
151
```
152

153
[App Controllers](./app-controllers.md)
154

155
### Error Handling
156

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

159
```python { .api }
160
class PyChromecastError(Exception): ...
161
class ChromecastConnectionError(PyChromecastError): ...
162
class NotConnected(PyChromecastError): ...
163
class RequestTimeout(PyChromecastError): ...
164
class UnsupportedNamespace(PyChromecastError): ...
165
```
166

167
[Error Handling](./error-handling.md)
168

169
## Types
170

171
```python { .api }
172
class CastInfo:
173
    """Cast device information container"""
174
    services: set[HostServiceInfo | MDNSServiceInfo]
175
    uuid: UUID
176
    model_name: str | None
177
    friendly_name: str | None
178
    host: str
179
    port: int
180
    cast_type: str | None
181
    manufacturer: str | None
182

183
class CastStatus:
184
    """Current cast device status"""
185
    is_active_input: bool | None
186
    is_stand_by: bool | None
187
    volume_level: float
188
    volume_muted: bool
189
    app_id: str | None
190
    display_name: str | None
191
    namespaces: list[str]
192
    session_id: str | None
193
    transport_id: str | None
194
    status_text: str
195
    icon_url: str | None
196

197
class MediaStatus:
198
    """Current media playback status"""
199
    current_time: float
200
    content_id: str | None
201
    content_type: str | None
202
    duration: float | None
203
    stream_type: str
204
    idle_reason: str | None
205
    media_session_id: int | None
206
    playback_rate: float
207
    player_state: str
208
    supported_media_commands: int
209
    volume_level: float
210
    volume_muted: bool
211
    media_custom_data: dict
212
    media_metadata: dict
213
    subtitle_tracks: dict
214
    current_subtitle_tracks: list
215
    last_updated: datetime.datetime | None
216
```
217

218
## Constants
219

220
```python { .api }
221
# Cast Types
222
CAST_TYPE_CHROMECAST = "cast"
223
CAST_TYPE_AUDIO = "audio"
224
CAST_TYPE_GROUP = "group"
225

226
# Media Player States
227
MEDIA_PLAYER_STATE_PLAYING = "PLAYING"
228
MEDIA_PLAYER_STATE_PAUSED = "PAUSED"
229
MEDIA_PLAYER_STATE_IDLE = "IDLE"
230
MEDIA_PLAYER_STATE_BUFFERING = "BUFFERING"
231

232
# Stream Types
233
STREAM_TYPE_BUFFERED = "BUFFERED"
234
STREAM_TYPE_LIVE = "LIVE"
235

236
# Timeouts
237
REQUEST_TIMEOUT = 10.0
238
DISCOVER_TIMEOUT = 5.0
239
```