rspotify

The library provides enum wrappers to treat different kinds of IDs generically when an endpoint accepts multiple types.

PlayableId<'a>

Used for items that can be played. It wraps:

• TrackId<'a>
• EpisodeId<'a>

LibraryId<'a>

A comprehensive wrapper for all major library items. It wraps:

• TrackId<'a>, AlbumId<'a>, EpisodeId<'a>, ShowId<'a>, ArtistId<'a>, UserId<'a>, and PlaylistId<'a>.

PlayContextId<'a>

Used for context-based playback. It wraps:

• ArtistId<'a>, AlbumId<'a>, PlaylistId<'a>, and ShowId<'a>.

All these enums implement the Id trait and provide .as_ref(), .into_static(), and .clone_static() methods to manage lifetimes.

use rspotify_model::{TrackId, EpisodeId, PlayableId};

fn add_to_queue(id: &[PlayableId]) { /* ... */ }

let tracks = [
    PlayableId::Track(TrackId::from_id("track_id_1").unwrap()),
    PlayableId::Track(TrackId::from_id("track_id_2").unwrap()),
];
let episodes = [
    PlayableId::Episode(EpisodeId::from_id("ep_id_1").unwrap()),
];

// Combine different types into a single vector of PlayableId
let playable: Vec<PlayableId> = tracks.into_iter().chain(episodes.into_iter()).collect();

add_to_queue(&playable);

The AuthCodeSpotify client implements the Spotify Authorization Code Flow, which allows access to user private data. The flow follows these steps:

1. Generate Authorization URL: Use get_authorize_url to create the URL where the user will log in.
2. User Authorization: The user logs in via the generated URL and is redirected to your specified redirect_uri with a code parameter in the URL.
3. Parse Code: Extract the code from the redirect URL (the client provides parse_response_code for this).
4. Exchange Code for Token: Call request_token(code) to exchange the code for an access token. This token is stored internally.
5. Refresh Token: When the access token expires, use refetch_token() to obtain a new one using the stored refresh_token without requiring user re-login.

Note for CLI developers: If you enable the cli feature, you can use prompt_for_token to automate these steps via user interaction in the terminal.

// Conceptual flow summary:
// 1. let url = client.get_authorize_url(false)?;
// 2. // User visits url, gets redirected to callback with ?code=...
// 3. client.request_token("the_code_from_url").await?;
// 4. // Later, when expired:
// 5. client.refetch_token().await?;

The rspotify-model crate provides type-safe wrappers for various Spotify identifiers. Instead of using raw strings, you use specific types like TrackId, ArtistId, or AlbumId. This prevents logic errors, such as passing an EpisodeId to a function expecting a TrackId, which are caught at compile-time.

Supported ID Types

• ArtistId (Type::Artist)
• AlbumId (Type::Album)
• TrackId (Type::Track)
• PlaylistId (Type::Playlist)
• UserId (Type::User)
• ShowId (Type::Show)
• EpisodeId (Type::Episode)

Key Concepts

• The Id Trait: The central interface for all ID types. You must import this trait (e.g., use rspotify::prelude::*) to access methods like .id(), .uri(), and .url().
• Ownership and Lifetimes: ID types are wrappers around Cow<str>. They can hold borrowed data (Id<'a>) or owned data (Id<'static>). Use .into_static() or .clone_static() to convert a borrowed ID into an owned one with a 'static lifetime.
• Parsing: You can create IDs from raw strings (using .from_id()) or from full Spotify URIs (using .from_uri()).

use rspotify_model::{TrackId, EpisodeId};

fn pause_track(id: TrackId<'_>) { /* ... */ }

// Success: Correct type
let id = TrackId::from_id("4iV5W9uYEdYUVa79Axb7Rh").unwrap();
pause_track(id);

// Compile-time error: Wrong type
// let id = EpisodeId::from_id("4iV5W9uYEdYUVa79Axb7Rh").unwrap();
// pause_track(id); // This would fail to compile

// Runtime panic: URI type mismatch
// let id = TrackId::from_uri("spotify:album:6akEvsycLGftJxYudPjmqK").unwrap();
// pause_track(id); // This would panic because the URI is an album, not a track