If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/librespot-org/librespot shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3mo ago
• 34+ active contributors
• Distributed ownership (top contributor 36% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live librespot-org/librespot repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/librespot-org/librespot.

What it runs against: a local clone of librespot-org/librespot — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in librespot-org/librespot | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | Last commit ≤ 117 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of librespot-org/librespot. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/librespot-org/librespot.git
#   cd librespot
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of librespot-org/librespot and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "librespot-org/librespot(\\.git)?\\b" \\
  && ok "origin remote is librespot-org/librespot" \\
  || miss "origin remote is not librespot-org/librespot (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 117 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~87d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/librespot-org/librespot"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

librespot is an open-source Rust implementation of a Spotify client library that enables applications to play music via Spotify and act as a Spotify Connect receiver—essentially a drop-in replacement for the deprecated closed-source libspotify. It allows building Spotify-enabled applications with multiple audio backends (rodio, ALSA, PulseAudio) and TLS options (native-tls, rustls), and can run as a standalone speaker via the CLI (e.g., librespot -n "Speaker" -b 160). Monorepo structure with core protocol logic in core/, audio streaming in audio/, Spotify Connect support in connect/, OAuth authentication in oauth/, metadata fetching in metadata/, and playback engine in playback/. Each module is a separate Cargo crate with its own Cargo.toml. The main librespot crate at the root aggregates these via workspace dependencies, with examples/ containing runnable demos and protocol/ holding Spotify's protobuf definitions.

Audio developers and Raspberry Pi enthusiasts building Spotify Connect speakers or smart home audio systems that need a lightweight, self-hosted alternative to official Spotify SDKs. Also relevant to Linux audio application developers who want Spotify integration without proprietary dependencies.

Actively maintained and production-ready. The project has regular CI/CD workflows (build.yml, cross-compile.yml, release.yml), comprehensive test coverage in protocol buffers, and organized changelog (CHANGELOG.md). It's version 0.8.0 on crates.io with clear versioning and release automation. Not bleeding-edge but stable and actively developed by the librespot-org team after being forked from the original plietar repository which is no longer maintained.

Moderate risk: depends on Spotify's proprietary protocol (reverse-engineered and documented in /docs), so breaking Spotify API changes could require quick fixes. Single/small maintainer team for a critical streaming library. Requires Spotify Premium (a business/licensing constraint, not a technical one). However, extensive CI/CD and cross-compilation support (Alpine, musl targets) mitigate some deployment risks.

The repo shows active maintenance with CI workflows for building, cross-compiling to multiple architectures, quality checks, and automated release pipelines. Recent focus areas include TLS backend flexibility (rustls vs native-tls compile-time selection per COMPILING.md), Docker multi-platform support (.devcontainer/Dockerfile.alpine for musl), and dependency management (dependabot.yml). The workspace is at Rust 1.85 minimum version.

Clone and compile: git clone https://github.com/librespot-org/librespot && cd librespot && cargo build --release. Install directly from crates.io: cargo install librespot. Then run: librespot -n "My Speaker" -b 160 -u your_spotify_username. See COMPILING.md for environment setup details and audio backend configuration.

Daily commands: Local development: cargo run --bin librespot -- -n "Librespot Dev" -u your_username (requires Spotify Premium account and interactive login). Run tests: cargo test --workspace. Run specific examples from examples/: cargo run --example playback. Multi-platform: use cross (Cross.toml configured) for musl/Alpine builds: cross build --target x86_64-unknown-linux-musl --release.

• connect/src/spirc.rs: Implements the SPIRC protocol for Spotify Connect state synchronization—the core of speaker functionality
• audio/src/decrypt.rs: Handles AES decryption of Spotify's audio streams fetched from CDN
• playback/src/lib.rs: Main playback engine coordinating audio backends, seeking, and volume control
• oauth/src/lib.rs: OAuth2 authentication flow including TLS backend feature validation (critical for compile-time checks)
• protocol/src/lib.rs: Protobuf message definitions and Spotify protocol constants—the bridge to Spotify's wire format
• core/src/lib.rs: Session management, cache, and network layer for Spotify API communication
• COMPILING.md: Essential for understanding TLS backend selection, audio backend compilation flags, and environment setup

Start in core/src/lib.rs for protocol fundamentals. For Connect/playback features, see connect/src/spirc.rs and playback/src/lib.rs. Audio decoding changes go in audio/src/. New backends added to playback/src/ via trait implementations. Authentication changes in oauth/src/. Protocol updates: regenerate from .proto files in protocol/ (uses prost). Always consult CONTRIBUTING.md and run cargo fmt + cargo clippy before submitting.

TLS backends are mutually exclusive and validated at compile time in oauth/src/lib.rs—you cannot mix rustls and native-tls in one build. Audio backend selection (rodio, ALSA, PulseAudio) is a compile-time feature flag, not runtime switchable. The cache/ directory is git-ignored and auto-created on first run. Spotify Premium is strictly required; free accounts will not authenticate. OAuth flow requires interactive login (not suitable for headless CI). Cross-compilation requires the cross tool (not just standard Rust cross targets) due to audio backend dependencies.

• Spotify SPIRC Protocol — This is the proprietary state synchronization protocol that makes Spotify Connect work; understanding it is essential for any Connect feature work in connect/src/spirc.rs
• Protobuf Code Generation (prost) — Spotify's wire protocol is defined as .proto files in protocol/ and compiled to Rust at build time; modifying protocol support requires understanding protobuf semantics
• AES Decryption (Spotify Audio Encryption) — Audio streams from Spotify's CDN arrive encrypted; audio/src/decrypt.rs implements AES decryption which is non-negotiable for playback
• Tokio Async Runtime — The entire librespot codebase is async-first using tokio for non-blocking I/O to Spotify APIs and audio hardware
• Feature Flag Compilation (Cargo Features) — Audio backends and TLS stacks are compile-time features (not runtime switches); understanding Cargo feature resolution is critical for debug builds
• Range-Based HTTP Seeking — Audio streams use HTTP Range requests to seek without re-downloading; see audio/src/range_set.rs and audio/src/fetch/receive.rs for the implementation
• Workspace Crates (Cargo Workspaces) — librespot is a monorepo split across core/, audio/, connect/, oauth/, playback/, etc. Understanding workspace dependencies and feature propagation is essential for builds

• spotifyd/spotifyd — A lightweight Spotify daemon built on librespot, adding systemd integration and local HTTP API—common consumer of this library
• Mopidy/Mopidy — Music server that uses librespot as one of several backends for Spotify playback integration
• raspotify/raspotify — Preconfigured Debian package wrapping librespot for Raspberry Pi—demonstrates typical deployment pattern
• plietar/librespot — Original predecessor repository by plietar, now archived—shows the fork origin and evolution

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for audio/src/fetch/receive.rs and audio/src/decrypt.rs

The audio module handles critical streaming functionality (decryption and HTTP range request handling) but lacks visible unit tests. These modules are core to playback reliability and security. Adding tests would catch regressions in audio fetching logic, decryption correctness, and range_set.rs boundary conditions. This directly improves stability for a library used by multiple downstream projects.

• [ ] Review audio/src/fetch/receive.rs for untested error paths (connection drops, partial reads, retry logic)
• [ ] Review audio/src/decrypt.rs for untested crypto operations and edge cases
• [ ] Review audio/src/range_set.rs for overlap/merge logic tests
• [ ] Add #[cfg(test)] modules with unit tests covering: valid decryption, corrupt data handling, range request merging, and HTTP 206 partial content scenarios
• [ ] Run tests locally and in CI via .github/workflows/quality.yml

Complete the incomplete TLS backend documentation in Cargo.toml and add feature validation tests

The Cargo.toml features section for TLS backends is truncated mid-sentence ('rustls-tl...'). The comment references COMPILING.md for validation logic in oauth/src/lib.rs, but this feature validation should be tested. New contributors need clear examples of how to compile with different TLS backends and understand mutual exclusivity constraints. This prevents misconfiguration issues.

• [ ] Complete the truncated rustls-tls feature documentation in Cargo.toml (root level and librespot-oauth/Cargo.toml)
• [ ] Document both certificate store options (native-tls, rustls-webpki, rustls-native-roots) with use cases
• [ ] Review oauth/src/lib.rs for feature validation logic and document it in COMPILING.md with concrete examples
• [ ] Add a compile-time test in .github/workflows/quality.yml or cross-compile.yml that validates TLS feature combinations (e.g., ensure native-tls + rustls-tls compilation fails with clear error)

Add integration tests for connect/src/spirc.rs state machine using mock Spotify protocol messages

The connect module (Spotify Connect support) contains complex state management (spirc.rs, state/*.rs) for handling device control, context resolution, and playback state transitions. This is critical for Spotify Connect functionality but lacks visible integration tests. Adding protocol-level tests would validate state transitions, context switching, and shuffle/repeat handling without requiring a real Spotify account.

• [ ] Analyze connect/src/spirc.rs and connect/src/state/*.rs to identify key state transitions (play, pause, next, context changes, shuffle toggles)
• [ ] Create tests/integration_spirc.rs or similar with mock protobuf message builders (using the protocol/ module)
• [ ] Add tests covering: device frame handling, context resolution (context_resolver.rs), state transitions, and metadata updates
• [ ] Ensure tests run in .github/workflows/quality.yml without requiring external Spotify credentials
• [ ] Reference contrib/event_handler_example.py as a model for expected state change outputs

• Add integration tests for the audio decryption flow in audio/src/decrypt.rs—currently only unit tests exist. Would involve setting up mock HTTP servers to simulate CDN responses and verify end-to-end decryption.
• Document the SPIRC protocol state machine in connect/src/state/ with inline examples. The connect/README.md exists but the state flow (context.rs, handle.rs, metadata.rs) lacks concrete examples of transitions.
• Add Dockerfile examples for common platforms (Raspberry Pi Armv7, Alpine musl) to .devcontainer/ beyond the existing Dockerfile and Dockerfile.alpine—would help adoption for embedded use cases.

The librespot codebase demonstrates a reasonable security posture with organized structure and published security policy. However, there are notable issues: (1) a critical configuration error with the Rust edition field ('2024' instead of valid '2021'), (2) incomplete TLS backend documentation that could lead to misconfiguration, and (3) limited security documentation for end users. The project appears to follow security best practices with a published SECURITY.md and vulnerability reporting process, but could benefit from expanded documentation of cryptographic practices, authentication security, and library-specific security considerations. The presence of multiple TLS backend options suggests awareness of security trade-offs, but the truncated documentation needs completion.

• Medium · Incomplete TLS Configuration Documentation — Cargo.toml - features section, lines with rustls-tls documentation. The Cargo.toml file shows TLS backend feature configuration is incomplete. The rustls-tls feature description is truncated mid-sentence, and the documentation mentions 'two certificate store options' but doesn't fully document them. This could lead to misconfiguration by users unaware of the implications. Fix: Complete the TLS feature documentation with full descriptions of all certificate store options and their security implications. Ensure users understand the differences between native-tls and rustls-tls backends.
• Medium · Rust Edition Configuration Anomaly — Cargo.toml - [workspace.package] section, edition field. The workspace specifies edition = '2024' which does not exist. The latest Rust edition is 2021. This is likely a configuration error that could cause build failures or use of undefined behavior. Fix: Change edition to '2021' (or the appropriate supported edition). Verify the intended Rust edition and update accordingly. Run 'cargo check' to validate the configuration.
• Low · Minimal Security Policy Disclosure — SECURITY.md. The SECURITY.md file provides only basic vulnerability reporting instructions. It lacks details on security practices, known limitations, or security considerations for users integrating this library. Fix: Expand the security policy to include: security considerations for library users, known security limitations, cryptographic practices, authentication/authorization models, and timeline for security updates.
• Low · Limited README Security Context — README.md. The README does not include security warnings or considerations for users. Given that librespot works with Spotify Premium and handles authentication/streaming, users should be informed of relevant security implications. Fix: Add a security section to the README documenting: authentication security practices, data protection measures, certificate validation, and any known security limitations or considerations.
• Low · Missing Dependency Lock Details — Cargo.toml - dependencies section (not provided in full), potential CI/CD configuration. While Cargo.lock is present (good practice), the provided Cargo.toml snippet doesn't show explicit dependency versions or security audit integration via tools like cargo-audit or cargo-deny. Fix: Ensure cargo-audit or similar security scanning is integrated into the CI/CD pipeline (check .github/workflows/quality.yml). Document dependency update and security review procedures.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.