0
# Device Discovery
1

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

4
## Capabilities
5

6
### Discover All Devices
7

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

10
```python { .api }
11
def get_chromecasts(tries=None, retry_wait=None, timeout=None, blocking=True, 
12
                   callback=None, zeroconf_instance=None, known_hosts=None):
13
    """
14
    Searches the network for chromecast devices and creates a Chromecast object
15
    for each discovered device.
16

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

26
    Returns:
27
    When blocking=True: tuple[list[Chromecast], CastBrowser]
28
    When blocking=False: CastBrowser
29
    """
30
```
31

32
**Usage Example:**
33

34
```python
35
import pychromecast
36

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

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

44
# Clean up
45
browser.stop_discovery()
46

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

52
browser = pychromecast.get_chromecasts(blocking=False, callback=device_callback)
53
# Discovery continues in background until stopped
54
browser.stop_discovery()
55
```
56

57
### Discover Specific Devices
58

59
Discovers Chromecast devices matching specific friendly names or UUIDs.
60

61
```python { .api }
62
def get_listed_chromecasts(friendly_names=None, uuids=None, tries=None, 
63
                          retry_wait=None, timeout=None, discovery_timeout=5, 
64
                          zeroconf_instance=None, known_hosts=None):
65
    """
66
    Searches the network for chromecast devices matching a list of friendly
67
    names or a list of UUIDs.
68

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

79
    Returns:
80
    tuple[list[Chromecast], CastBrowser]: List of matching Chromecast objects and browser
81
    """
82
```
83

84
**Usage Example:**
85

86
```python
87
from uuid import UUID
88

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

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

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

104
browser.stop_discovery()
105
```
106

107
### Discovery Without Connection
108

109
Discovers devices without establishing connections, useful for device enumeration.
110

111
```python { .api }
112
def discover_chromecasts(max_devices=None, timeout=5, zeroconf_instance=None, known_hosts=None):
113
    """
114
    Discover chromecast devices without connecting to them.
115
    
116
    DEPRECATED: This function is deprecated as of February 2021 and will be removed.
117
    Use CastBrowser instead.
118

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

125
    Returns:
126
    tuple[list[CastInfo], CastBrowser]: List of discovered device info and browser
127
    """
128
```
129

130
**Usage Example:**
131

132
```python
133
# Discover without connecting
134
devices, browser = pychromecast.discover_chromecasts()
135

136
for device in devices:
137
    print(f"Found: {device.friendly_name}")
138
    print(f"  Model: {device.model_name}")
139
    print(f"  UUID: {device.uuid}")
140
    print(f"  Host: {device.host}:{device.port}")
141
    print(f"  Type: {device.cast_type}")
142

143
browser.stop_discovery()
144
```
145

146
### Create from Known Information
147

148
Create Chromecast objects from known device information without discovery.
149

150
```python { .api }
151
def get_chromecast_from_host(host, tries=None, retry_wait=None, timeout=None):
152
    """
153
    Creates a Chromecast object from a zeroconf host tuple.
154

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

162
    Returns:
163
    Chromecast: Chromecast object for the host
164
    """
165

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

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

177
    Returns:
178
    Chromecast: Chromecast object for the cast info
179
    """
180
```
181

182
**Usage Example:**
183

184
```python
185
from uuid import UUID
186

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

192
# Create from CastInfo object
193
cast_info = pychromecast.CastInfo(
194
    services={pychromecast.HostServiceInfo("192.168.1.100", 8009)},
195
    uuid=UUID("12345678-1234-5678-9012-123456789012"),
196
    model_name="Chromecast",
197
    friendly_name="Living Room TV",
198
    host="192.168.1.100",
199
    port=8009,
200
    cast_type="cast",
201
    manufacturer="Google Inc."
202
)
203
cast = pychromecast.get_chromecast_from_cast_info(cast_info, None)
204
```
205

206
### Discovery Management
207

208
Control discovery processes and monitor device changes.
209

210
```python { .api }
211
def start_discovery(cast_browser, zeroconf_instance):
212
    """
213
    Start discovering chromecasts on the network.
214
    
215
    DEPRECATED: This function is deprecated as of February 2021 and will be removed.
216
    Call CastBrowser.start_discovery() instead.
217

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

222
    Returns:
223
    CastBrowser: The same browser instance
224
    """
225

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

233
    Parameters:
234
    - cast_browser: CastBrowser, Browser instance to stop
235
    """
236

237
class CastBrowser:
238
    """Browser for discovering and monitoring cast devices"""
239
    def start_discovery(self): ...
240
    def stop_discovery(self): ...
241
    @property
242
    def devices(self) -> dict[UUID, CastInfo]: ...
243
```
244

245
**Usage Example:**
246

247
```python
248
class MyCastListener(pychromecast.AbstractCastListener):
249
    def add_cast(self, uuid, service):
250
        print(f"Device added: {uuid}")
251
    
252
    def remove_cast(self, uuid, service, cast_info):
253
        print(f"Device removed: {uuid}")
254
    
255
    def update_cast(self, uuid, service):
256
        print(f"Device updated: {uuid}")
257

258
# Start continuous discovery
259
listener = MyCastListener()
260
browser = pychromecast.start_discovery(listener)
261

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

266
# Stop discovery
267
pychromecast.stop_discovery(browser)
268
```
269

270
## Types
271

272
```python { .api }
273
class CastInfo:
274
    """Information about a discovered cast device"""
275
    services: set[HostServiceInfo | MDNSServiceInfo]
276
    uuid: UUID
277
    model_name: str | None
278
    friendly_name: str | None
279
    host: str
280
    port: int
281
    cast_type: str | None
282
    manufacturer: str | None
283

284
class HostServiceInfo:
285
    """Host-based service information"""
286
    host: str
287
    port: int
288

289
class MDNSServiceInfo:
290
    """mDNS service information"""
291
    name: str
292

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

299
class SimpleCastListener(AbstractCastListener):
300
    """Helper listener with callback functions"""
301
    def __init__(self, add_callback=None, remove_callback=None, update_callback=None): ...
302
```
303

304
## Constants
305

306
```python { .api }
307
DISCOVER_TIMEOUT = 5  # Default discovery timeout in seconds
308
```