Spotify API

Annie Mei uses the Spotify Web API to add Spotify track links to opening and ending themes from MyAnimeList.

Authentication

The bot uses Spotify’s client credentials flow for server-to-server authentication. Set:

SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

Create these credentials in the Spotify Developer Dashboard.

fn get_spotify_client() -> ClientCredsSpotify {
    let client_id = env::var(SPOTIFY_CLIENT_ID)
        .expect("Expected a spotify client id in the environment");
    let client_secret = env::var(SPOTIFY_CLIENT_SECRET)
        .expect("Expected a spotify client secret in the environment");
    let credentials = Credentials {
        id: client_id,
        secret: Some(client_secret),
    };

    ClientCredsSpotify::new(credentials)
}

Implementation: src/utils/spotify.rs

Batch enrichment

The /songs command parses up to 10 opening and 10 ending themes, combines both sections for enrichment, and passes the complete batch to enrich_songs_with_spotify. For each song with an artist, the integration:

Checks Redis for a cached positive or negative result.
Authenticates only when an uncached song needs a Spotify request.
Reuses the authenticated Spotify client and access token for the remaining uncached songs in the batch.
Makes at most one later authentication retry after a transient token failure.
Restores the enriched songs to their opening and ending sections.

pub fn enrich_songs_with_spotify(songs: &mut [ParsedSong]) {
    enrich_songs_with_backend(songs, &mut DefaultSpotifyBackend::default());
}

This avoids requesting a new access token for every theme song.

Search strategy

Annie Mei searches for the track and artist together:

track:{song_name} artist:{artist_name}

The request uses the United States market and asks for up to five results. Annie Mei links the first track result. For each uncached song:

Search with the romaji title.
If Spotify returns no track and a kana title is available, search with the kana title using the same authenticated client.
Use the first matching track URL, or display the song without a link.

match backend.search(romaji_name, artist_name) {
    SearchOutcome::Found(url) => Some(url),
    SearchOutcome::NotFound => match kana_name {
        Some(kana_name) => match backend.search(kana_name, artist_name) {
            SearchOutcome::Found(url) => Some(url),
            SearchOutcome::NotFound | SearchOutcome::Failed => None,
        },
        None => None,
    },
    SearchOutcome::Failed => None,
}

The blocking Spotify and Redis work runs inside tokio::task::spawn_blocking so it does not block Tokio’s async worker threads.

Redis caching

Spotify lookups share the bot’s Redis cache. The cache key remains compatible with earlier releases:

{romaji_name}:{kana_name_debug}:{artist_name}

The integration stores:

the Spotify URL for a successful match
None when an authenticated search produces no usable URL

Cache entries expire after 18,000 seconds (5 hours). A failed token request does not create a negative cache entry, so a later song or command can retry authentication. The Redis client uses a reusable pool with at most eight connections. Pool waits, connection establishment, reads, and writes use a two-second bound. Connections that encounter I/O failures are discarded rather than returned to the pool.

Failure behavior

Spotify enrichment is optional. If Spotify cannot authenticate, times out, or returns no track, Annie Mei still displays the MyAnimeList song title, artist, and episode range when those fields are available.

A missing Spotify link does not mean the theme song lookup failed. It means Annie Mei did not obtain a usable Spotify match for that song.

Dependency

The integration uses rspotify with its blocking ureq client and Rustls:

rspotify = { version = "0.16.1", default-features = false, features = [
  "client-ureq",
  "ureq-rustls-tls",
] }

Getting Started

Self-hosting

Commands

Legal

Development

Deployment

API Reference

Authentication

Batch enrichment

Search strategy

Redis caching

Failure behavior

Dependency

​Authentication

​Batch enrichment

​Search strategy

​Redis caching

​Failure behavior

​Dependency

Authentication

Batch enrichment

Search strategy

Redis caching

Failure behavior

Dependency