SpotifyService

Status of this project

This project is currently under development, and breaking changes are expected to be introduced frequently.

The goal of this project

To create a high-level Spotify API for FOSS Blazor WebAssembly projects, providing services such as Spotify playback in the browser, managing OAuth authorization, access to the Spotify Web API, IndexedDB caching and more.

Areas currently implemented

• Authentication & authorization: OAuth 2.0

  • Implicit grant flow: authenticate without any backend involvement. Users will have to re-authorize your app every hour.

  • Authorization code flow: configure and deploy the ASP.NET Core SpotifyAuthServer. Users will only have to authorize your Blazor webapp once, SpotifyService and the supporting server will take care of the rest.

• Playback: in the browser, using the Spotify Web Playback SDK.

• Web API: a high-level wrapper around JohnnyCrazy's SpotifyAPI-NET.

  • Playback

    • Read and manage the current playback context, including the currently playing track and the state of the playback (e.g. paused or playing, shuffle and repeat status, (interpolated) progression, etc.).

    • Use automatic track relinking.

  • Context

    • Get the currently playing album, artist or playlist.

  • User

    • Get information about the current user.

  • Library

    • Get the user's saved tracks and playlists.

    • See whether a song is in the user's library.

  • Insights

    • Get a detailed audio analysis of each of the user's saved tracks.

  • Extensions

    • Extension methods for displaying SpotifyAPI-NET.Web.Model entities with ease and in a human-readable format.

Demo

Most of SpotifyService's functionality was originally implemented for use in Cærostris, a Blazor WebAssembly Spotify client. The latest version of Cærostris can be accessed here.

Requirements

Your application should use .NET 5.0.0 or higher.

How to use

• Include the SpotifyService project in your solution and run dotnet restore.

• Include the lines marked with '<--' in your Program.cs:

  using Caerostris.Services.Spotify;                      // <--
  
  // ...
  
  public class Program
  {
      public static async Task Main(string[] args)
          {
              var builder = WebAssemblyHostBuilder.CreateDefault(args);
              builder.RootComponents.Add<App>("#app");
  
              builder.Services
                  .AddSpotify(new() // <-- 
                  {
                      // If you supply a non-null value, the Authorization Code Grant workflow will be used.
                      // (Use https!)
                      // Otherwise, the Implicit Grant workflow will be used instead.
                      AuthServerApiBase = "https://caerostrisauthserver.azurewebsites.net/auth",
                      PlayerDeviceName = "Your Spotify player device name here",
                      // Issued by Spotify, register your app and view its ID at
                      // https://developer.spotify.com/dashboard/
                      ClientId = "0123456789abcdef0123456789abcdef",
                      // All permissions SpotifyService currently uses
                      PermissionScopes = new[]
                      {
                          "user-read-private",
                          "user-read-email",
                          "user-read-playback-state",
                          "user-modify-playback-state",
                          "user-library-read",
                          "user-library-modify",
                          "user-read-currently-playing",
                          "playlist-read-private",
                          "playlist-read-collaborative",
                          "playlist-modify-private",
                          "playlist-modify-public",
                          "streaming"
                      }
                  });
  
              var host = builder.Build();
  
              await host.Services.InitializeSpotify(); // <--
          
              await host.RunAsync();
          }
      }
  }

• Include the JavaScript and mock audio files needed for SpotifyService's functionality in your index.html:

  <audio id="mediasession-mock-audio" src="_content/Caerostris.Services.Spotify/media/mediasession-mock-audio.mp3" autoplay loop></audio>
  <script src="_content/Caerostris.Services.Spotify/blazor.extensions.storage.js"></script>
  <script src="_content/Caerostris.Services.Spotify.IndexedDB/indexedDb.Blazor.js"></script>
  <script src="_content/Caerostris.Services.Spotify/spotifyservice-web-playback.js"></script>
  <script src="https://sdk.scdn.co/spotify-player.js"></script>

• See some examples for using SpotifyService in your Blazor components in the Examples section below.

Design considerations

• SpotifyService publishes several events, including:

  • Spotify authorization events;

  • UI update suggestions;

  • loading progress updates;

  • playback context changes.

• SpotifyService provides stateful services (caching, automatic track relinking, etc.), and uses the singleton dependency injection mode.

Examples

Fetching all of the user's saved tracks:

@inject SpotifyService Spotify

@code
{
    private IEnumerable<SavedTrack>? tracks;

    protected override async Task OnInitializedAsync()
    {
        if (await Spotify.Auth.IsUserLoggedIn())
            tracks = await Spotify.Library.GetSavedTracks();
    }
}