DOCSEARCHbyAlgolia
Submit Docs

Music Assistant Server

repository·dev·Indexed 25 days ago

https://github.com/music-assistant/server

An open-source media library manager that connects streaming services to connected speakers. The server acts as the core engine, featuring a MusicController for library orchestration, a MetaDataController for image resolution and enrichment, a PlayerQueuesController for playback synchronization, and a CacheController for SQLite-backed data storage.

Tokens
27.3K
Snippets
20
Records
163
Agent score
84%

What's inside music-assistant-server

  1. Overview of the AirPlay Provider

    dev

    The AirPlay provider allows Music Assistant to stream audio to AirPlay-enabled devices on your local network. It supports both RAOP (AirPlay 1) and AirPlay 2 protocols, making it compatible with Apple HomePods, Apple TVs, Macs, and various third-party AirPlay speakers.

    Key Capabilities

    • Dual Protocol Support: Automatically selects the best route (RAOP, AirPlay 2 RAOP-compatible, or native AirPlay 2) using the cliairplay binary.
    • Multi-Room Audio: Synchronizes playback across multiple devices using a shared PTP clock.
    • Hi-Res Audio: Supports 24-bit playback (44.1/48 kHz) over AirPlay 2 for compatible receivers.
    • Metadata: Sends rich metadata (title, artist, album, artwork, progress) via DMAP or MediaRemote.
    • Remote Control: Supports DACP remote control commands (play/pause, volume, etc.).

  2. Overview of Music Assistant Webserver Architecture

    dev

    The Music Assistant webserver is a core controller providing real-time communication and API access. It runs on port 8095 by default and includes:

    • WebSocket API: Located at /ws for bidirectional, real-time communication.
    • HTTP/JSON-RPC API: Located at /api for standard request-response interactions.
    • Frontend Hosting: Serves the Vue-based Progressive Web App (PWA).
    • Authentication: Manages users, roles, and tokens.
    • Remote Access: Uses WebRTC for external connectivity without port forwarding.
    • Home Assistant Integration: Supports Ingress for seamless use within Home Assistant.

  3. Overview of the Smart Fades Provider

    dev

    The Smart Fades Provider is an audio analysis provider for Music Assistant that enables intelligent crossfading in the playback queue. It performs real-time analysis of audio streams to detect:

    • Beats and Downbeats: Timestamps for rhythmic alignment.
    • Musical Key: Detection of pitch class and mode (major/minor).
    • RMS Energy: Volume/intensity levels.
    • Spectral Centroid: Timbral characteristics.
    • Vocal Activity: Detection of speech or singing.

    This information is used to position smart crossfades based on the musical structure of the tracks.

  4. Understand the Music Controller architecture

    dev

    The MusicController is the central orchestrator for the Music Assistant library. It aggregates and normalizes media items from various providers (streaming services, local files, etc.) into an internal SQLite database. It serves as the primary entry point for:

    • Searching the library
    • Browsing media
    • Accessing recommendations
    • Performing library edits
    • Playback bookkeeping

    Key Components

    • MusicController (controller.py): The main orchestrator that composes per-media-type sub-controllers.
    • MusicDatabaseSetupMixin (database.py): Manages the library database lifecycle, including connection setup, schema creation, and maintenance.
    • Media Sub-controllers (media/): Specialized controllers for specific media types (e.g., AlbumsController, ArtistsController, TracksController, PlaylistController, etc.) that inherit from MediaControllerBase.
    • Migrations (migrations.py): Handles versioned, step-by-step schema migrations via migrate_database.

  5. Understand Sync Group Player Provider

    dev
    The Sync Group Player provider allows you to create permanent, persistent groups of compatible speakers that play audio in perfect synchronization. Unlike manual/temporary syncing, sync groups act as independent player entities with their own dedicated playback queue and configuration. They persist across system restarts and appear as regular players in the UI.

  6. Understand the Streams Controller Architecture

    dev

    The Streams Controller manages all audio streaming to players. It operates on a dedicated HTTP-only webserver on a separate port (default 8097) to isolate audio traffic from the main API. This design ensures compatibility with resource-constrained embedded devices by avoiding SSL/TLS and authentication, instead using session IDs in stream URLs for security.

    Core Capabilities:

    • HTTP streaming endpoints for local network players.
    • Audio buffering with configurable memory usage.
    • Volume normalization (dynamic, measurement-based, and fixed gain).
    • Smart crossfading and continuous flow mode.
    • Audio overlay (e.g., looping ambient sounds like rain).
    • Ahead-of-time audio analysis (loudness and beat detection).

  7. Understand the Universal Player Provider

    dev
    The Universal Player provider automatically merges multiple protocol players (such as AirPlay, Chromecast, DLNA, Squeezelite, and SendSpin) that belong to the same physical device into a single unified virtual player. This prevents the system from showing multiple separate players for a single device (e.g., a receiver that supports both Chromecast and AirPlay).

  8. Use the Background Tasks Controller for long-running work

    dev

    The Background Tasks Controller is used to manage long-running, user-visible background work such as library syncs, playlist mutations, and scheduled system jobs.

    Important Distinction:

    • Use this controller for long-running tasks that require progress reporting, logging, or scheduling.
    • Do not use this controller for short-lived internal jobs; instead, use mass.create_task or mass.call_later for those purposes.

  9. Understand the Metadata Controller architecture

    dev

    The MetaDataController manages metadata enrichment, image resolution, and radio artwork lookup. It is implemented as a single controller instance composed of several specialized mixins to organize its large API surface:

    • controller.py: The main MetaDataController handling lifecycle, configuration, preferred-language handling, and scheduled maintenance.
    • images.py (ImageProxyMixin): Handles image resolution, the opaque image-id system, thumbnail rendering/caching, the /imageproxy endpoint, and palette extraction.
    • radio.py (RadioArtworkMixin): Resolves radio-stream artwork by matching station metadata against the library or MusicBrainz.
    • enrichment.py (MetadataEnrichmentMixin): Contains routines for merging provider metadata into library items based on media type.
    • helpers.py: Pure functions independent of the controller instance.
    • constants.py: Shared constants including config keys, cache categories, and imageproxy tunables.

  10. Understand Spotify Connect provider architecture and audio flow

    dev

    The Spotify Connect provider works by wrapping a go-librespot subprocess, which acts as a reverse-engineered Spotify Connect client.

    How it works

    1. Discovery: The Spotify app discovers the Music Assistant player via mDNS.
    2. Audio Stream: go-librespot decodes the Ogg Vorbis stream from Spotify and writes raw s16le PCM to stdout.
    3. Processing: Music Assistant reads this stream via a custom get_audio_stream function, which paces the read to match the native rate to prevent buffer overflow.
    4. Output: The PCM stream is passed through ffmpeg (using -fflags nobuffer for low latency) and sent to the Music Assistant player.

    Key Components

    • go-librespot subprocess: Managed by _daemon_runner. It exposes a local HTTP + WebSocket API for control and events.
    • GoLibrespotClient: Handles REST control commands (resume, pause, seek, volume) and listens to the /events WebSocket for state changes.
    • AudioSource MediaItem: The provider presents a single live item under the global "Live Inputs" node. It is configured with exclusive=True and allow_external_trigger=True.

  11. Understand the Player Queues Controller Architecture

    dev

    The PlayerQueuesController is a core component responsible for converting media playback requests into actual playback on players. It manages the lifecycle of a player's queue, handles transport commands (play, pause, stop, etc.), and reconciles the in-memory queue state with the real-time state reported by the physical player.

    Key responsibilities include:

    • Accepting and applying enqueue requests.
    • Driving playback transport.
    • Maintaining synchronization between the server's queue model and the player's actual state.
    • Broadcasting queue lifecycle events (e.g., queue added/updated, items changed, elapsed-time progress, item played) to clients.

  12. Key features of the Background Tasks Controller

    dev

    The controller provides the following capabilities for managing background work:

    • Task Scheduling: Register recurring tasks that remain visible even when idle. Runtime state (like last_run, pause/enable state) is persisted in the tasks core config to survive restarts.
    • Ad Hoc Task Execution: Queue and execute long-running tasks with bounded concurrency. A limited history of completed ad hoc tasks is retained in memory.
    • Progress and Logging: Captures per-task in-memory log output for UI inspection and export. It provides a task execution context so code can report progress and non-fatal issues.
    • State Monitoring: Publishes task state changes via EventType.TASKS_UPDATED.