0
# Mopidy
1

2
Mopidy is an extensible music server written in Python that enables users to play music from various sources including local files, Spotify, SoundCloud, and other cloud services through extensions. It provides a Python-based server architecture with HTTP and MPD protocol support, allowing control from multiple client types (web browsers, MPD clients, mobile apps) across different devices.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import mopidy
14
```
15

16
For models and data structures:
17

18
```python
19
from mopidy.models import (
20
    Track, Album, Artist, Playlist, Ref, SearchResult, TlTrack, Image,
21
    ValidatedImmutableObject, ImmutableObject, ModelJSONEncoder, model_json_decoder
22
)
23
```
24

25
For extension development:
26

27
```python
28
from mopidy.ext import Extension
29
from mopidy.backend import Backend, LibraryProvider, PlaybackProvider, PlaylistsProvider
30
from mopidy.config.schemas import ConfigSchema
31
from mopidy.config.types import String, Integer, Boolean, Secret
32
```
33

34
For core functionality:
35

36
```python
37
from mopidy.core import (
38
    Core, PlaybackController, LibraryController, TracklistController, 
39
    PlaylistsController, MixerController, HistoryController, CoreListener, PlaybackState
40
)
41
```
42

43
For audio system:
44

45
```python
46
from mopidy.audio import Audio, AudioListener
47
from mopidy.mixer import Mixer, MixerListener
48
```
49

50
For exception handling:
51

52
```python
53
from mopidy.exceptions import (
54
    MopidyException, BackendError, CoreError, ExtensionError, 
55
    FrontendError, MixerError, ScannerError, AudioException,
56
    ValidationError, TracklistFull
57
)
58
```
59

60
## Basic Usage
61

62
```python
63
import mopidy
64
from mopidy.models import Track, Artist, Album
65
from mopidy.ext import Extension
66
from mopidy.config.schemas import ConfigSchema
67
from mopidy.config.types import String
68

69
# Create basic music metadata
70
artist = Artist(uri="local:artist:example", name="Example Artist")
71
album = Album(uri="local:album:example", name="Example Album", artists=frozenset([artist]))
72
track = Track(
73
    uri="local:track:example.mp3",
74
    name="Example Track",
75
    artists=frozenset([artist]),
76
    album=album,
77
    length=180000  # 3 minutes in milliseconds
78
)
79

80
# Define a simple extension
81
class MyExtension(Extension):
82
    dist_name = "My-Extension"
83
    ext_name = "my_extension"
84
    version = "1.0.0"
85
    
86
    def get_default_config(self):
87
        config = super().get_default_config()
88
        config["my_setting"] = "default_value"
89
        return config
90
    
91
    def get_config_schema(self):
92
        schema = super().get_config_schema()
93
        schema["my_setting"] = String()
94
        return schema
95

96
print(f"Mopidy Version: {mopidy.__version__}")
97
print(f"Track: {track.name} by {track.artists.pop().name}")
98
```
99

100
## Architecture
101

102
Mopidy follows a modular architecture built around these core components:
103

104
- **Core**: Central controllers for playback, library, playlists, tracklist, mixer, and history management
105
- **Models**: Immutable data structures representing music metadata (tracks, albums, artists, playlists)
106
- **Backend System**: Pluggable providers for different music sources (local files, streaming services)
107
- **Extension System**: Plugin architecture allowing third-party extensions for new music sources and frontends 
108
- **Audio System**: GStreamer-based audio pipeline with mixer support
109
- **Configuration System**: Schema-based configuration with validation and type safety
110
- **Event System**: Listener pattern for system events and state changes
111

112
This architecture enables maximum extensibility for home music server setups, multi-room audio systems, and custom music streaming solutions.
113

114
## Capabilities
115

116
### Core Models and Data Structures
117

118
Immutable data models for representing music metadata including tracks, albums, artists, playlists, and search results. These models form the foundation of Mopidy's data layer.
119

120
```python { .api }
121
class Track(ValidatedImmutableObject):
122
    uri: str
123
    name: str
124
    artists: frozenset[Artist]
125
    album: Album
126
    length: int  # milliseconds
127

128
class Artist(ValidatedImmutableObject):
129
    uri: str
130
    name: str
131
    sortname: str
132
    musicbrainz_id: str
133

134
class Album(ValidatedImmutableObject):
135
    uri: str
136
    name: str
137
    artists: frozenset[Artist]
138
    num_tracks: int
139
    date: str
140
```
141

142
[Models and Data Structures](./models.md)
143

144
### Core System Controllers
145

146
Central business logic controllers for managing playback, library browsing, playlist management, tracklist operations, and audio mixing.
147

148
```python { .api }
149
class Core(pykka.ThreadingActor):
150
    def __init__(self, config, mixer, backends, audio): ...
151
    
152
class PlaybackController:
153
    def play(self, tl_track=None): ...
154
    def pause(self): ...
155
    def stop(self): ...
156
    def get_state(self): ...
157

158
class LibraryController:
159
    def browse(self, uri, **kwargs): ...
160
    def search(self, query=None, uris=None, exact=False): ...
161
    def lookup(self, uris=None): ...
162
```
163

164
[Core Controllers](./core-controllers.md)
165

166
### Backend System and Providers
167

168
Base classes and interfaces for implementing music source backends including library browsing, playback control, and playlist management providers.
169

170
```python { .api }
171
class Backend:
172
    def __init__(self, config, audio): ...
173
    uri_schemes: list[str]
174
    library: LibraryProvider
175
    playback: PlaybackProvider
176
    playlists: PlaylistsProvider
177

178
class LibraryProvider:
179
    def browse(self, uri): ...
180
    def search(self, query=None, uris=None, exact=False): ...
181
    def lookup(self, uris): ...
182
```
183

184
[Backend System](./backend-system.md)
185

186
### Extension System
187

188
Plugin architecture for creating Mopidy extensions including configuration schemas, lifecycle management, and integration points.
189

190
```python { .api }
191
class Extension:
192
    dist_name: str
193
    ext_name: str
194
    version: str
195
    
196
    def get_default_config(self): ...
197
    def get_config_schema(self): ...
198
    def setup(self, registry): ...
199
    def validate_environment(self): ...
200
```
201

202
[Extension Development](./extension-system.md)
203

204
### Configuration System
205

206
Schema-based configuration management with validation, type safety, and support for multiple configuration sources.
207

208
```python { .api }
209
class ConfigSchema:
210
    def __init__(self, name): ...
211
    def __setitem__(self, key, value): ...
212

213
class ConfigValue:
214
    def deserialize(self, value): ...
215
    def serialize(self, value, display=False): ...
216

217
def load(files, ext_schemas, ext_defaults, overrides): ...
218
def format(config, ext_schemas, comments=None, display=True): ...
219
```
220

221
[Configuration System](./configuration.md)
222

223
### Audio System
224

225
GStreamer-based audio pipeline with playback control, volume management, and audio format support.
226

227
```python { .api }
228
class Audio(pykka.ThreadingActor):
229
    def __init__(self, config, mixer): ...
230
    def set_uri(self, uri): ...
231
    def start_playback(self): ...
232
    def pause_playback(self): ...
233
    def stop_playback(self): ...
234

235
def supported_uri_schemes(): ...
236
def calculate_duration(num_samples, sample_rate): ...
237
```
238

239
[Audio System](./audio-system.md)
240

241
### Exception Handling
242

243
Mopidy provides comprehensive exception types for error handling across all system components.
244

245
```python { .api }
246
from mopidy.exceptions import (
247
    MopidyException, BackendError, CoreError, ExtensionError, 
248
    FrontendError, MixerError, ScannerError, TracklistFull, 
249
    AudioException, ValidationError
250
)
251

252
class MopidyException(Exception):
253
    """
254
    Base exception for all Mopidy errors.
255
    
256
    All Mopidy-specific exceptions inherit from this base class.
257
    Provides a message property for error details.
258
    
259
    Parameters:
260
    - message (str): Error message
261
    """
262
    def __init__(self, message, *args, **kwargs): ...
263
    
264
    @property
265
    def message(self): ...
266

267
class BackendError(MopidyException):
268
    """
269
    Backend-related errors.
270
    
271
    Raised when backend operations fail, such as music source
272
    connection issues or playback provider errors.
273
    """
274
    ...
275

276
class CoreError(MopidyException):
277
    """
278
    Core system errors.
279
    
280
    Raised when core Mopidy functionality fails.
281
    
282
    Parameters:
283
    - message (str): Error message  
284
    - errno (int, optional): Error code
285
    """
286
    def __init__(self, message, errno=None): ...
287

288
class ExtensionError(MopidyException):
289
    """
290
    Extension-related errors.
291
    
292
    Raised during extension loading, setup, or validation failures.
293
    """
294
    ...
295

296
class FrontendError(MopidyException):
297
    """
298
    Frontend-related errors.
299
    
300
    Raised when frontend components fail to initialize or operate.
301
    """
302
    ...
303

304
class MixerError(MopidyException):
305
    """
306
    Audio mixer errors.
307
    
308
    Raised when mixer operations fail, such as volume control issues.
309
    """
310
    ...
311

312
class ScannerError(MopidyException):
313
    """
314
    Library scanning errors.
315
    
316
    Raised when media library scanning fails.
317
    """
318
    ...
319

320
class TracklistFull(CoreError):
321
    """
322
    Tracklist capacity exceeded error.
323
    
324
    Raised when attempting to add tracks to a full tracklist.
325
    
326
    Parameters:
327
    - message (str): Error message
328
    - errno (int, optional): Error code
329
    """
330
    def __init__(self, message, errno=None): ...
331

332
class AudioException(MopidyException):
333
    """
334
    Audio subsystem errors.
335
    
336
    Raised when GStreamer audio pipeline operations fail.
337
    """
338
    ...
339

340
class ValidationError(ValueError):
341
    """
342
    Data validation errors.
343
    
344
    Raised when data validation fails, such as invalid model field values.
345
    Note: Inherits from ValueError rather than MopidyException.
346
    """
347
    ...
348
```
349

350
### Event System
351

352
Event listener pattern for receiving notifications about system state changes and events.
353

354
```python { .api }
355
from mopidy.core import CoreListener
356
from mopidy.audio import AudioListener
357
from mopidy.listener import Listener, send
358

359
class CoreListener:
360
    def track_playback_started(self, tl_track): ...
361
    def track_playback_paused(self, tl_track, time_position): ...
362
    def track_playback_ended(self, tl_track, time_position): ...
363
    def playback_state_changed(self, old_state, new_state): ...
364
    def tracklist_changed(self): ...
365
    def volume_changed(self, volume): ...
366

367
def send(event, **kwargs):
368
    """Send events to registered listeners."""
369
    ...
370
```