tessl/pypi-mopidy
Mopidy is an extensible music server written in Python
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Securityby
Pending
The risk profile of this skill
core-controllers.mddocs/
Core Controllers
Mopidy's core system provides centralized business logic controllers for managing all aspects of music playback, library access, playlist management, and audio control. These controllers form the main API surface for interacting with Mopidy programmatically.
Capabilities
Core Actor System
The main Core actor coordinates all system components and provides the primary interface for Mopidy functionality.
class Core(pykka.ThreadingActor):
"""
Main core actor that coordinates all Mopidy functionality.
Parameters:
- config: Mopidy configuration
- mixer: Audio mixer instance
- backends: List of configured backends
- audio: Audio actor instance
"""
def __init__(self, config, mixer, backends, audio): ...
# Controller properties
@property
def playback(self) -> PlaybackController: ...
@property
def library(self) -> LibraryController: ...
@property
def tracklist(self) -> TracklistController: ...
@property
def playlists(self) -> PlaylistsController: ...
@property
def mixer(self) -> MixerController: ...
@property
def history(self) -> HistoryController: ...Playback Control
Comprehensive playback control including play/pause/stop, seeking, volume, and playback state management.
class PlaybackController:
"""Controls music playback including play, pause, stop, and seeking."""
def play(self, tl_track=None, tlid=None):
"""
Start playback.
Parameters:
- tl_track (TlTrack, optional): Track to play (deprecated, use tlid)
- tlid (int, optional): TLID of track to play, or None for current
Returns:
- TlTrack or None: The track that was played
"""
...
def pause(self):
"""
Pause playback.
Returns:
- bool: True if successful
"""
...
def stop(self):
"""
Stop playback and clear current track.
Returns:
- bool: True if successful
"""
...
def resume(self):
"""
Resume playback from paused state.
Returns:
- bool: True if successful
"""
...
def seek(self, time_position):
"""
Seek to specific position in current track.
Parameters:
- time_position (int): Position in milliseconds
Returns:
- bool: True if successful
"""
...
def get_time_position(self):
"""
Get current playback position.
Returns:
- int: Position in milliseconds
"""
...
def get_state(self):
"""
Get current playback state.
Returns:
- PlaybackState: Current state (playing, paused, stopped)
"""
...
def set_state(self, new_state):
"""
Set the playback state.
Parameters:
- new_state (PlaybackState): Must be PLAYING, PAUSED, or STOPPED
Note: This is primarily for internal use and testing
"""
...
def next(self):
"""
Change to next track in tracklist.
Returns:
- TlTrack or None: Next track that was switched to
"""
...
def previous(self):
"""
Change to previous track in tracklist.
Returns:
- TlTrack or None: Previous track that was switched to
"""
...
def get_current_tl_track(self):
"""
Get currently playing or paused track.
Returns:
- TlTrack or None: Current track
"""
...
def get_current_track(self):
"""
Get currently playing or paused track.
Returns:
- Track or None: Current track
"""
...
def get_current_tlid(self):
"""
Get TLID of currently playing or paused track.
Returns:
- int or None: Current track TLID
"""
...
def get_stream_title(self):
"""
Get stream title for radio streams.
Returns:
- str or None: Stream title if available
"""
...
class PlaybackState:
"""Playback state constants."""
STOPPED = "stopped"
PLAYING = "playing"
PAUSED = "paused"Usage example:
from mopidy.core import Core
# Assume core is a Core instance
core.playback.play() # Start playback
core.playback.pause() # Pause
core.playback.seek(30000) # Seek to 30 seconds
state = core.playback.get_state() # Get current stateLibrary Access
Library browsing, searching, and track lookup across all configured backends.
class LibraryController:
"""Provides library browsing and searching across backends."""
def browse(self, uri, **kwargs):
"""
Browse library at given URI.
Parameters:
- uri (str): URI to browse
- **kwargs: Backend-specific options
Returns:
- list[Ref]: List of references at the URI
"""
...
def search(self, query=None, uris=None, exact=False):
"""
Search library across backends.
Parameters:
- query (dict, optional): Search query by field
- uris (list[str], optional): URIs to search within
- exact (bool): Whether to match exactly
Returns:
- list[SearchResult]: Search results from backends
"""
...
def lookup(self, uris=None):
"""
Lookup tracks by URI.
Parameters:
- uris (list[str]): URIs to lookup
Returns:
- dict[str, list[Track]]: Mapping of URI to tracks
"""
...
def refresh(self, uri=None):
"""
Refresh library cache.
Parameters:
- uri (str, optional): Specific URI to refresh
Returns:
- bool: True if successful
"""
...
def get_distinct(self, field, query=None):
"""
Get distinct values for a field.
Parameters:
- field (str): Field name ('artist', 'album', etc.)
- query (dict, optional): Query to filter by
Returns:
- set[str]: Distinct values
"""
...
def get_images(self, uris):
"""
Get images for given URIs.
Parameters:
- uris (list[str]): URIs to get images for
Returns:
- dict[str, list[Image]]: Mapping of URI to images
"""
...Usage example:
# Browse root directory
refs = core.library.browse("file:///")
# Search for tracks
results = core.library.search({"artist": ["Beatles"], "album": ["Abbey Road"]})
# Lookup specific tracks
tracks = core.library.lookup(["spotify:track:123", "local:track:song.mp3"])Tracklist Management
Manage the current tracklist including adding, removing, and reordering tracks.
class TracklistController:
"""Manages the current tracklist of tracks to be played."""
def add(self, tracks=None, at_position=None, uris=None):
"""
Add tracks to tracklist.
Parameters:
- tracks (list[Track], optional): Tracks to add
- at_position (int, optional): Position to insert at
- uris (list[str], optional): URIs to add (alternative to tracks)
Returns:
- list[TlTrack]: Added tracklist tracks
"""
...
def remove(self, criteria):
"""
Remove tracks from tracklist.
Parameters:
- criteria (dict): Removal criteria (tlid, uri, etc.)
Returns:
- list[TlTrack]: Removed tracks
"""
...
def clear(self):
"""
Clear all tracks from tracklist.
Returns:
- bool: True if successful
"""
...
def move(self, start, end, to_position):
"""
Move tracks within tracklist.
Parameters:
- start (int): Start position
- end (int): End position
- to_position (int): Destination position
Returns:
- bool: True if successful
"""
...
def shuffle(self, start=None, end=None):
"""
Shuffle tracks in tracklist.
Parameters:
- start (int, optional): Start position
- end (int, optional): End position
Returns:
- bool: True if successful
"""
...
def get_tl_tracks(self):
"""
Get all tracklist tracks.
Returns:
- list[TlTrack]: All tracklist tracks
"""
...
def get_tracks(self):
"""
Get all tracks.
Returns:
- list[Track]: All tracks
"""
...
def get_length(self):
"""
Get tracklist length.
Returns:
- int: Number of tracks
"""
...
def get_version(self):
"""
Get tracklist version (increments on changes).
Returns:
- int: Version number
"""
...
def index(self, tl_track=None, tlid=None):
"""
Get index of tracklist track.
Parameters:
- tl_track (TlTrack, optional): Track to find
- tlid (int, optional): TLID to find (alternative to tl_track)
Returns:
- int or None: Index of track
"""
...
def filter(self, criteria):
"""
Filter the tracklist by the given criteria.
Each rule in the criteria consists of a model field and a list of
values to compare it against. If the model field matches any of the
values, it may be returned.
Parameters:
- criteria (dict): Filter criteria (uri, name, etc.)
Returns:
- list[TlTrack]: Filtered tracks
"""
...
def get_consume(self):
"""
Get consume mode status.
Returns:
- bool: True if consume mode is enabled
"""
...
def set_consume(self, value):
"""
Set consume mode.
Parameters:
- value (bool): Enable/disable consume mode
Returns:
- bool: True if successful
"""
...
def get_random(self):
"""
Get random mode status.
Returns:
- bool: True if random mode is enabled
"""
...
def set_random(self, value):
"""
Set random mode.
Parameters:
- value (bool): Enable/disable random mode
Returns:
- bool: True if successful
"""
...
def get_repeat(self):
"""
Get repeat mode status.
Returns:
- bool: True if repeat mode is enabled
"""
...
def set_repeat(self, value):
"""
Set repeat mode.
Parameters:
- value (bool): Enable/disable repeat mode
Returns:
- bool: True if successful
"""
...
def get_single(self):
"""
Get single mode status.
Returns:
- bool: True if single mode is enabled
"""
...
def set_single(self, value):
"""
Set single mode.
Parameters:
- value (bool): Enable/disable single mode
Returns:
- bool: True if successful
"""
...
def get_eot_tlid(self):
"""
The TLID of the track that will be played after the current track.
Not necessarily the same TLID as returned by get_next_tlid.
Returns:
- int or None: TLID of end-of-track track
"""
...
def eot_track(self, tl_track):
"""
The track that will be played after the given track.
Not necessarily the same track as next_track.
Note: This method is deprecated in favor of get_eot_tlid.
Parameters:
- tl_track (TlTrack or None): The reference track
Returns:
- TlTrack or None: End-of-track track
"""
...
def get_next_tlid(self):
"""
The TLID of the track that will be played if calling next().
For normal playback this is the next track in the tracklist. If repeat
is enabled the next track can loop around the tracklist. When random is
enabled this should be a random track.
Returns:
- int or None: TLID of next track
"""
...
def next_track(self, tl_track):
"""
The track that will be played if calling next().
Note: This method is deprecated in favor of get_next_tlid.
Parameters:
- tl_track (TlTrack or None): The reference track
Returns:
- TlTrack or None: Next track
"""
...
def get_previous_tlid(self):
"""
Returns the TLID of the track that will be played if calling previous().
For normal playback this is the previous track in the tracklist. If
random and/or consume is enabled it should return the current track.
Returns:
- int or None: TLID of previous track
"""
...
def previous_track(self, tl_track):
"""
Returns the track that will be played if calling previous().
Note: This method is deprecated in favor of get_previous_tlid.
Parameters:
- tl_track (TlTrack or None): The reference track
Returns:
- TlTrack or None: Previous track
"""
...
def slice(self, start, end):
"""
Get slice of tracklist.
Parameters:
- start (int): Start index
- end (int): End index
Returns:
- list[TlTrack]: Slice of tracks
"""
...
# Playback options
def get_consume(self):
"""Get consume mode state."""
...
def set_consume(self, value):
"""Set consume mode."""
...
def get_random(self):
"""Get random mode state."""
...
def set_random(self, value):
"""Set random mode."""
...
def get_repeat(self):
"""Get repeat mode state."""
...
def set_repeat(self, value):
"""Set repeat mode."""
...
def get_single(self):
"""Get single mode state."""
...
def set_single(self, value):
"""Set single mode."""
...Usage example:
# Add tracks to tracklist
tl_tracks = core.tracklist.add([track1, track2, track3])
# Set playback modes
core.tracklist.set_random(True)
core.tracklist.set_repeat(True)
# Get current tracklist
all_tracks = core.tracklist.get_tl_tracks()Playlist Management
Manage stored playlists including creation, modification, and deletion across backends.
class PlaylistsController:
"""Manages stored playlists across backends."""
def as_list(self):
"""
Get all playlists.
Returns:
- list[Playlist]: All available playlists
"""
...
def get_items(self, uri):
"""
Get playlist items.
Parameters:
- uri (str): Playlist URI
Returns:
- list[Ref]: Playlist items
"""
...
def create(self, name, uri_scheme=None):
"""
Create new playlist.
Parameters:
- name (str): Playlist name
- uri_scheme (str, optional): URI scheme to use
Returns:
- Playlist or None: Created playlist
"""
...
def save(self, playlist):
"""
Save playlist changes.
Parameters:
- playlist (Playlist): Playlist to save
Returns:
- Playlist or None: Saved playlist
"""
...
def delete(self, uri):
"""
Delete playlist.
Parameters:
- uri (str): Playlist URI
Returns:
- bool: True if successful
"""
...
def lookup(self, uri):
"""
Lookup playlist by URI.
Parameters:
- uri (str): Playlist URI
Returns:
- Playlist or None: Found playlist
"""
...
def refresh(self, uri_scheme=None):
"""
Refresh playlists cache.
Parameters:
- uri_scheme (str, optional): Specific scheme to refresh
Returns:
- bool: True if successful
"""
...
def get_uri_schemes(self):
"""
Get available playlist URI schemes.
Returns:
- list[str]: Available URI schemes
"""
...Usage example:
# List all playlists
playlists = core.playlists.as_list()
# Create new playlist
playlist = core.playlists.create("My New Playlist")
# Add tracks and save
updated_playlist = playlist.replace(tracks=(track1, track2))
core.playlists.save(updated_playlist)Audio Mixer Control
Control audio volume and muting across the system.
class MixerController:
"""Controls audio volume and muting."""
def get_volume(self):
"""
Get current volume level.
Returns:
- int or None: Volume level (0-100)
"""
...
def set_volume(self, volume):
"""
Set volume level.
Parameters:
- volume (int): Volume level (0-100)
Returns:
- bool: True if successful
"""
...
def get_mute(self):
"""
Get mute state.
Returns:
- bool or None: True if muted
"""
...
def set_mute(self, mute):
"""
Set mute state.
Parameters:
- mute (bool): True to mute
Returns:
- bool: True if successful
"""
...Playback History
Track and manage playback history for recently played tracks.
class HistoryController:
"""Manages playback history of recently played tracks."""
def get_length(self):
"""
Get history length.
Returns:
- int: Number of history entries
"""
...
def get_history(self):
"""
Get playback history.
Returns:
- list[tuple[int, Ref]]: History entries (timestamp, track_ref)
"""
...Event Listener
Base class for receiving notifications about system events and state changes.
class CoreListener:
"""Base class for receiving core system events."""
def track_playback_paused(self, tl_track, time_position):
"""Called when track playback is paused."""
...
def track_playback_resumed(self, tl_track, time_position):
"""Called when track playback is resumed."""
...
def track_playback_started(self, tl_track):
"""Called when track playback starts."""
...
def track_playback_ended(self, tl_track, time_position):
"""Called when track playback ends."""
...
def playback_state_changed(self, old_state, new_state):
"""Called when playback state changes."""
...
def tracklist_changed(self):
"""Called when tracklist is modified."""
...
def playlists_loaded(self):
"""Called when playlists are loaded."""
...
def volume_changed(self, volume):
"""Called when volume changes."""
...
def mute_changed(self, mute):
"""Called when mute state changes."""
...Usage example:
class MyListener(CoreListener):
def track_playback_started(self, tl_track):
print(f"Now playing: {tl_track.track.name}")
def volume_changed(self, volume):
print(f"Volume changed to: {volume}")
# Register listener (implementation depends on setup)
listener = MyListener()