librespot-org/librespot

This system is a Rust-based implementation of the Spotify Connect protocol, functioning as a headless Spotify client that allows devices to stream audio and control playback. It handles authentication via OAuth, manages device discovery and state synchronization, and supports both remote streaming and local file playback with configurable audio backends. The architecture is modular, separating core protocol communication, metadata handling, and playback logic into distinct components.

14 changes.

The project underwent a major architectural overhaul, migrating from a monolithic synchronous structure to a modular, tokio-based async runtime. This period focused on replacing legacy protocol definitions with pure Rust protobuf generation, expanding telemetry capabilities, and introducing new crates for metadata and audio playback infrastructure.

12 changes.

This period focused on a comprehensive refactoring of the project's core infrastructure, introducing a new WebSocket-based Dealer client and restructuring the Connect protocol for better state management. Significant improvements were made to the playback engine, including a new decoder architecture using Symphonia, support for local file playback, and unified error handling across audio backends. The work also enhanced reliability and usability through redesigned audio fetching with CDN fallbacks, expanded discovery capabilities, and refined metadata models.

5 changes.

This period focused on establishing developer tooling with VS Code devcontainers and building the core infrastructure for the OAuth authentication library. It also involved significant refactoring of Connect playback state management and defining the Dealer protocol structures to support playback and device transfer commands.

Developers can now use VS Code Dev Containers to work in a pre-configured Rust environment. The change introduces a new \.devcontainer\ directory containing \devcontainer.json\ (defaulting to the Alpine image) and two Dockerfiles (\Dockerfile\ for Debian Bookworm and \Dockerfile.alpine\ for Alpine 3.20). Both images are based on Rust 1.85.0 and include necessary build dependencies (such as OpenSSL, PulseAudio, PortAudio, SDL2, GStreamer, and Avahi), development tools (git, nano, openssh-server), and Rust tooling (rustfmt, clippy, cargo-hack). The configuration also sets up VS Code extensions like rust-analyzer and GitLens, and configures environment variables for sparse crate registry protocol and backtrace.

.devcontainer · high confidence

New example programs have been added to the discovery crate to demonstrate how to initialize and run the discovery service. The \discovery\ example shows how to set up a device with the 'Computer' type, while \discovery\_group\ demonstrates configuring a device as a group member using the 'Speaker' type and the new \is\_group\ builder method, allowing users to see how to advertise different device roles.

discovery/examples · high confidence

The discovery module has been refactored to support multiple zeroconf backends, introducing a new Avahi (DBus) backend alongside existing DNS-SD and libmdns options, allowing the service to bind to specific IPs and improving stability by avoiding crashes when Avahi is unavailable. Additionally, the device information exposed to Spotify clients now includes an 'aliases' field, enabling the device to be discovered under multiple names, and the 'activeUser' field in the device info response is now correctly populated.

discovery/src · high confidence

The \core/src/dealer\ module now implements a WebSocket-based client to communicate with Spotify's Dealer service. This change adds a new \DealerManager\ to handle connection lifecycle (start/close), URL resolution, and reconnection logic, alongside a \Dealer\ struct that manages subscriptions and request handlers using a hierarchical map structure. The module includes a \protocol\ layer to parse and serialize WebSocket messages, handling JSON and gzip-compressed payloads, enabling features like listening for context updates and sending requests to the Dealer service.

core/src/dealer · high confidence

The \core/src/dealer/protocol/request.rs\ file now defines the data structures for the Dealer protocol's request handling, including the \Request\ envelope and a \Command\ enum that covers playback actions (Play, Pause, SeekTo, SkipNext, Resume), context management (SetShufflingContext, SetRepeatingContext, UpdateContext), queue operations (AddToQueue, SetQueue), and device transfer (Transfer). This change establishes the schema for parsing incoming commands such as \play\, \transfer\, and \seek\_to\, supporting features like transfer playback initiation and context updates within the Dealer protocol layer.

core/src/dealer/protocol · high confidence

The core module now includes a new Mercury API client (\core/src/mercury\) that enables interaction with Spotify's Mercury service. This addition provides a \MercuryManager\ for sending requests (GET, SEND) and managing subscriptions (SUB, UNSUB) via URIs, along with a \MercurySender\ for buffered, sequential data transmission. The implementation uses \tokio\ for asynchronous operations and \protobuf\ for encoding protocol messages, exposing a structured API for retrieving user attributes, connection details, and other service data.

core/src/mercury · high confidence

A new \librespot-metadata\ crate has been added to provide structured, type-safe models for Spotify content. This includes dedicated structs for Albums, Artists, Tracks, Episodes, and Shows, along with supporting types for images, availability, restrictions, and lyrics. The crate implements a unified \Metadata\ trait that handles fetching and parsing protobuf responses from the Spotify client API, allowing other parts of the application to access rich metadata in a consistent manner.

metadata/src · high confidence

The playback engine now supports playing local audio files (MP3, MP4, M4P, FLAC) by scanning specified directories and mapping them to Spotify URIs. Additionally, users can configure the audio output format via the \PlayerConfig\, supporting F64, F32, S32, S24, S24\_3, and S16, with S16 as the default. The system also includes a new dithering module offering Triangular, Gaussian, and High-Pass dithering options to improve audio quality when converting between bit depths.

playback/src · high confidence

Users can now control volume via the system's ALSA hardware mixer instead of only the software mixer. This change introduces a new \AlsaMixer\ implementation that detects hardware capabilities (such as mute switches and dB ranges), corrects ALSA rounding errors, and applies linear mapping for small hardware ranges. It also adds configurable volume control mappings (logarithmic, cubic, linear) via the \mappings\ module to ensure consistent loudness perception across different hardware controls.

playback/src/mixer · high confidence

The oauth module now provides a new library for obtaining Spotify access tokens, supporting both the standard authorization code flow (with PKCE) and the device authorization flow. Users can authenticate interactively via a web browser or, for headless environments, by entering a code at spotify.com/pair. The library exposes builders for both flows and includes example programs demonstrating synchronous and asynchronous usage.

oauth · high confidence

The audio module has been restructured to introduce a new file downloading mechanism and support for encrypted audio streams. A new \AudioDecrypt\ component handles AES-128-CTR decryption for protected content, while a \RangeSet\ utility manages buffered audio data ranges. This change also includes a new \AudioFetchParams\ configuration for tuning fetch parameters and moves decoder logic into the playback crate, laying the groundwork for improved audio handling and prefetching.

audio/src · high confidence

The contrib directory now includes Dockerfiles and build scripts to facilitate cross-compiling librespot for multiple architectures, including x86\_64, aarch64, armhf, armel, and a specific armv6hf target for Raspberry Pi 1. These files provide pre-configured environments with necessary toolchains and dependencies. Additionally, systemd service unit files (both system and user scopes) are added to simplify running librespot as a background service with appropriate restart policies and audio group permissions.

contrib · high confidence

The playback module now uses a new decoder abstraction located in \playback/src/decoder\. This introduces \SymphoniaDecoder\ for decoding audio formats (such as FLAC and MP3) using the Symphonia library, and a feature-gated \PassthroughDecoder\ for handling Ogg Vorbis streams directly. The new system supports seeking in milliseconds, extracts local file metadata (title, artist, album, etc.) from tags, and handles replay gain information for normalization.

playback/src/decoder · high confidence

Added a set of new examples to demonstrate core library usage: \get\_token.rs\ and \get\_creds.rs\ show how to obtain and store OAuth access tokens; \play.rs\ demonstrates direct track playback; \play\_connect.rs\ illustrates connecting a device via Spirc with automatic credential handling; and \playlist\_tracks.rs\ shows how to retrieve and list tracks from a playlist. A README.md has also been added to explain how to run these examples and acquire the necessary access tokens.

examples · high confidence

The project now enforces consistent code formatting and linting by introducing a \.pre-commit-config.yaml\ that automatically runs \rustfmt\ and \clippy\ before commits, alongside a \rustfmt.toml\ to define the 2024 edition style. A \rust-toolchain.toml\ file explicitly registers the required \rustfmt\ and \clippy\ components, ensuring the build environment is correctly configured. Additionally, a \test.sh\ script was added to streamline local testing by synchronizing the checks performed in CI, and the manual \build.rs\ protobuf compilation script has been removed in favor of pre-generated protocol files.

(repo-wide) · high confidence

The core library has been restructured into distinct modules to improve maintainability and separation of concerns. A new \apresolve\ module now handles the resolution of Spotify access points (including fallback logic and proxy support), while \cdn\_url\ manages the parsing and expiration of CDN audio URLs. Authentication logic is now isolated in \authentication.rs\ with dedicated credential types, and \audio\_key.rs\ manages the asynchronous retrieval of audio decryption keys. Additionally, \channel.rs\ implements a new channel-based packet dispatch system, and \cache.rs\ provides a robust file-size limiter for managing local cache storage.

core/src · high confidence

This change introduces new implementation traits in the protocol layer to handle conversions between internal domain types and protobuf-based player context structures. Specifically, it adds \Hash\ and \Eq\ implementations for \Context\, and \From\ conversions for \ContextPage\ (from string URIs and track lists), as well as extensive bidirectional conversions between internal restriction, mode, and suppression types and their protobuf equivalents (\PlayerRestrictions\, \PlayerModeRestrictions\, etc.). This enables the application to properly serialize and deserialize playback context and restriction data for the player service.

_protocol/src/impl\trait · high confidence

The audio backend implementations (ALSA, GStreamer, JACK, PortAudio, PulseAudio, Rodio, SDL, pipe, and subprocess) have been reorganized into the \playback/src/audio\_backend\ module. This change introduces a standardized \SinkError\ enum and \SinkResult\ type across all backends, replacing previous ad-hoc error handling with consistent, structured error reporting for connection issues, write failures, and invalid parameters.

_playback/src/audio\backend · high confidence

The build process for the core library has been updated to allow overriding the generated build ID via the SOURCE\_DATE\_EPOCH environment variable. When this variable is set, the build ID becomes deterministic, enabling reproducible builds; otherwise, a random alphanumeric string is generated as before.

core · high confidence

The protocol definitions in this location have been updated with a large set of new Protobuf message types extracted from Spotify client versions 1.1.61.583 and 1.1.73.517. These changes introduce detailed telemetry schemas for ad delivery and tracking (AdContext, AdDecisionEvent, AdError, AdEvent, AdRequestEvent, AdSlotEvent, EndAd), comprehensive audio settings and streaming reports (AudioDriverError, AudioDriverInfo, AudioFileSelection, AudioOffliningSettingsReport, AudioRateLimit, AudioSessionEvent, AudioSettingsReport, AudioStreamingSettingsReport), and extensive desktop performance monitoring (DesktopDeviceInformation, DesktopGPUAccelerationInfo, DesktopHighMemoryUsage, DesktopPerformanceIssue). Additionally, new messages cover cache management (CacheError, CachePruningReport, CacheRealmPruningReport, CacheRealmReport, CacheReport), configuration fetching (ConfigurationApplied, ConfigurationFetched, ConfigurationFetchedNonAuth, DefaultConfigurationApplied), Connect device discovery and transfer results, connection state changes, and local file import errors. These definitions enable more granular reporting of user interactions, system health, and playback quality.

protocol/proto · high confidence

The application has been completely refactored from a monolithic structure into a modular crate-based architecture (librespot-core, playback, connect, etc.), replacing the legacy synchronous connection and cryptographic modules with a modern tokio-based async runtime. A new event-driven playback system has been introduced, allowing external scripts to react to player state changes via the --onstart/--onstop flags and environment variables, while authentication has been updated to support OAuth device flows and the audio backend system has been made configurable at runtime.

src · high confidence

The playlist metadata handling has been refactored into a new module structure (annotation, attribute, diff, item, list, operation, permission) that parses playlist data from updated protobuf messages. This change introduces support for playlist annotations (including abuse reporting), granular permission capabilities, and playlist diff operations, while also fixing timestamp parsing to correctly handle microsecond precision for certain playlist types.

metadata/src/playlist · high confidence

The build system now uses \protobuf\_codegen\ in pure Rust mode to generate protocol buffer bindings at build time, eliminating the external \protoc\ dependency. This change also removes several legacy protocol definition files (including \authentication.proto\, \keyexchange.proto\, \mercury.proto\, \metadata.proto\, \spirc.proto\, and \spotify.proto\) from the source tree, as they are no longer part of the active build inputs defined in the new \build.rs\ script.

protocol · high confidence

The core connection module has been rewritten to use a new \ApCodec\ for encrypted framing and a dedicated \handshake\ module that performs Diffie-Hellman key exchange and RSA signature verification to prevent man-in-the-middle attacks. This change introduces a 5-second timeout for the access-point handshake, adds retry logic for connection failures, and improves platform identification (e.g., correctly handling Windows ARM and Android as Linux) to ensure compatibility with Spotify's access points. Authentication now sends detailed system info and uses specific packet types for login and welcome responses, mapping errors to user-friendly messages.

core/src/connection · high confidence

The audio metadata layer has been refactored to introduce a new \AudioItem\ structure that unifies tracks and episodes, alongside a dedicated \AudioFileFormat\ enum that explicitly maps protocol format codes (including MP3, OGG Vorbis, FLAC, and AAC variants) to internal types. This change adds support for local file paths via the \UniqueFields::Local\ variant and ensures that explicit content filtering is applied consistently when retrieving audio items, while also handling unknown audio formats gracefully by ignoring them rather than failing.

metadata/src/audio · high confidence

The protocol module now exposes a structured entry point via \lib.rs\ that integrates with the build system to include generated code from \OUT\_DIR\. It defines an \impl\_trait\ module containing \context\ and \player\ sub-modules, establishing the foundational layout for protocol implementations derived from protobuf definitions.

protocol/src · medium confidence

The audio fetching module has been restructured to support configurable network behavior and improved reliability. Users can now tune streaming parameters such as minimum download block size, throughput expectations, and read-ahead buffers via \AudioFetchParams\, which directly impacts initial loading times and performance on slow connections. The implementation introduces a new \receive.rs\ module that handles HTTP range requests, implements rate-limiting retries for 429 responses, and enforces strict validation of HTTP 206 status codes. Additionally, the system now includes logic to fall back to alternative CDN URLs if a fetch fails to return a valid partial content response, enhancing stability when connecting to specific CDN endpoints.

audio/src/fetch · high confidence

The playback state logic in the Connect module has been restructured into a modular set of files (context, handle, metadata, options, provider, restrictions, tracks, and transfer). This refactoring introduces explicit support for autoplay contexts, refines shuffle and repeat behavior with dedicated state tracking, and hardens the device transfer flow to better preserve playback position and queue state when switching devices.

connect/src/state · high confidence

The \connect\ crate has been completely rewritten to overhaul how Spotify Connect devices manage playback state and resolve contexts. A new \ContextResolver\ component now handles the logic for fetching and queuing context data (such as playlists or albums), including retry mechanisms for unavailable contexts. The \Spirc\ module has been refactored to use this resolver and a new \ConnectState\ system, which centralizes device capabilities, volume control, and queue management. Additionally, a new \ShuffleVec\ utility ensures consistent shuffle behavior across state resets, and the \model\ module introduces structured \LoadRequest\ and \PlayingTrack\ types to standardize how playback commands are processed.

connect/src · high confidence

Added a new integration test in core/tests/connect.rs that verifies the Session connection behavior when invalid credentials are provided. The test ensures that authentication correctly fails and returns an error message rather than succeeding unexpectedly.

core/tests · high confidence

This release updates the project to version 0.8.0 and upgrades core dependencies, including Hyper to 1.x, Tokio to 1.x, and Protobuf to 3.x. It introduces configurable TLS backend selection, allowing users to choose between native-tls (default) and rustls (with native or WebPKI roots) via feature flags. The update also includes a new MSRV of Rust 1.85 and updates various audio and system libraries.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 63 → 66 (+3.3)
• Rubric changed (rubric-2026.09.9 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 84 → 84 (+0.0)
• Architecture 100 → 98 (-2.0)
• Maturity 56 → 55 (-0.3)
• Readiness 83 → 79 (-3.5)
• Security 51 → 63 (+12.0)
• Event Sourcing 100 → 100 (+0.0)
• Performance 100 (new)

• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Off-boarding risk: anonymized user #1

• Confusing method naming and intent. resolve_audio sounds like it performs the network resolution, while try_get_url sounds like it retrieves a cached or previously resolved URL. However, try_get_url likely also performs resolution if not cached. The prefix try_ is misleading in Rust where try_ often implies fallibility that is handled via ? or Result, but here it's just a getter. resolve_audio is domain-specific, while try_get_url is generic.
• Documentation: no project overview (README.md)
• Inconsistent builder pattern return types. with_password and with_access_token return Self (allowing method chaining), while with_blob returns Result. This breaks the fluent builder pattern and forces the user to handle errors differently depending on which credential type they are setting.
• Inconsistent setter return types. Most setters return () (unit), but set_user_attribute returns String. This suggests set_user_attribute might be returning the previous value or a new key, which is an unexpected side effect for a setter and inconsistent with the rest of the API.
• Inconsistent volume control API. set_volume takes an absolute u16, while volume_up and volume_down take no arguments (implying a fixed step). This is acceptable, but set_volume returns Result while volume_up/down also return Result. If the volume steps are fixed, the step size is hidden. More importantly, set_volume is the only way to set an absolute value, but the lack of a get_volume method in the public surface (only Cache.volume() exists) makes the API asymmetric.
• Medium vulnerability: RUSTSEC-2026-0285 (Cargo.lock)
• Off the main sequence: librespot-core
• Off the main sequence: librespot-oauth
• Off-boarding risk: anonymized user #1
• Outdated: async-trait
• Outdated: bytes
• Outdated: data-encoding
• Outdated: env_logger
• Outdated: flate2
• Outdated: futures-core
• Outdated: futures-util
• Outdated: governor
• Outdated: http
• Outdated: http-body-util
• Outdated: hyper
• …and 24 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

librespot-org/librespot was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.