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
```