Skip to content

Latest commit

 

History

History
170 lines (125 loc) · 5.91 KB

README.md

File metadata and controls

170 lines (125 loc) · 5.91 KB
Raw

Spotify API .NET Core

Lightweight .NET Core wrapper for the Spotify Web API.

Build status

Build Status

Features

  • Targets .NET Standard 2.0
  • async by default
  • BYO HttpClient
  • Authorization support (App and User flows)
  • MIT license
  • Fully XML documented

Installation

Install the latest version using dotnet CLI:

> dotnet add package SpotifyApi.NetCore

Install using Package Manager Console:

> Install-Package SpotifyApi.NetCore

Version 3

Version 3 of SpotifyApi.NetCore is a major version overhaul with many improvements including:

  • Removal of multi-user authentication in favour of bring-your-own auth
  • Simplification of Authentication services
  • Consistent approach to paging and auth params throughout the library
  • Removal of many overloads in favour of optional params
  • Complete XML comment documentation of public methods including links to Spotify reference docs
  • Separate SpotifyApi.NetCore.Samples repo

It is highly recommended that users upgrade to SpotifyApi.NetCore >= v3.0.1 as soon as possible. Version >= 2.4.7 will be supported until the next major version ships.

Upgrading from v2 to v3

There are breaking changes in v3 but, for most users, upgrading should be straight-forward. Some minor refactoring may be required, e.g.

  • Most Authorization objects have moved from namespace SpotifyApi.NetCore to SpotifyApi.NetCore.Authorization
  • Models.Image.Height and Models.Image.Width have changed from int to int?
  • Models.CurrentPlaybackContext.ProgressMs has changed from long to long?

Basic usage

Set Environment variables:

SpotifyApiClientId=(SpotifyApiClientId)
SpotifyApiClientSecret=(SpotifyApiClientSecret)

// HttpClient and AccountsService can be reused. 
// Tokens are automatically cached and refreshed
var http = new HttpClient();
var accounts = new AccountsService(http);

// Get an artist by Spotify Artist Id
var artists = new ArtistsApi(http, accounts);
Artist artist = await artists.GetArtist("1tpXaFf2F55E7kVJON4j4G");
string artistName = artist.Name;
Trace.WriteLine($"Artist.Name = {artistName}");

// Get recommendations based on seed Artist Ids
var browse = new BrowseApi(http, accounts);
RecommendationsResult result = await browse.GetRecommendations(new[] { "1tpXaFf2F55E7kVJON4j4G", "4Z8W4fKeB5YxbusRsdQVPb" }, null, null);
string firstTrackName = result.Tracks[0].Name;
Trace.WriteLine($"First recommendation = {firstTrackName}");

// Page through a list of tracks in a Playlist
var playlists = new PlaylistsApi(http, accounts);
int limit = 100;
PlaylistPaged playlist = await playlists.GetTracks("4h4urfIy5cyCdFOc1Ff4iN", limit: limit);
int offset = 0;
int j = 0;
// using System.Linq
while (playlist.Items.Any())
{
    for (int i = 0; i < playlist.Items.Length; i++)
    {
        Trace.WriteLine($"Track #{j += 1}: {playlist.Items[i].Track.Artists[0].Name} / {playlist.Items[i].Track.Name}");
    }
    offset += limit;
    playlist = await playlists.GetTracks("4h4urfIy5cyCdFOc1Ff4iN", limit: limit, offset: offset);
}

User Authorization

// Get a list of a User's devices
// This requires User authentication and authorization. 
// A `UserAccountsService` is provided to help with this.

// HttpClient and UserAccountsService can be reused. 
// Tokens can be cached by your code
var http = new HttpClient();
var accounts = new UserAccountsService(http);

// See https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow
//  for an explanation of the Authorization code flow

// Generate a random state value to use in the Auth request
string state = Guid.NewGuid().ToString("N");
// Accounts service will derive the Auth URL for you
string url = accounts.AuthorizeUrl(state, new[] { "user-read-playback-state" });

/*
    Redirect the user to `url` and when they have auth'ed Spotify will redirect to your reply URL
    The response will include two query parameters: `state` and `code`.
    For a full working example see `SpotifyApi.NetCore.Samples`.
*/

// Check that the request has not been tampered with by checking the `state` value matches
if (state != query["state"]) throw new ArgumentException();

// Use the User accounts service to swap `code` for a Refresh token
BearerAccessRefreshToken token = await accounts.RequestAccessRefreshToken(query["code"]);

// Use the Bearer (Access) Token to call the Player API
var player = new PlayerApi(http, accounts);
Device[] devices = await player.GetDevices(accessToken: token.AccessToken);

foreach(Device device in devices)
{
    Trace.WriteLine($"Device {device.Name} Status = {device.Type} Active = {device.IsActive}");
}

See tests and SpotifyApi.NetCore.Samples for more usage examples.

Spotify Web API Coverage

Spotify API Endpoints Implemented %
Albums 3 3 100% ✅
Artists 5 5 100% ✅
Browse 7 7 100% ✅
Episodes 2 2 100% ✅
Follow 7 7 100% ✅
Library 8 8 100% ✅
Personalization 1 1 100% ✅
Player 14 14 100% ✅
Playlists 12 6 50%
Search 1 1 100% ✅
Shows 3 3 100% ✅
Tracks 5 5 100% ✅
Users Profile 2 2 100% ✅
Total 70 64 91%

Feature requests welcomed! (create an issue)

Maintainer

This project is actively maintained by @DanielLarsenNZ. The easiest way to get in touch is to create an issue. But you can also email [email protected].

Contributors

Huge thanks to @aevansme, @brandongregoryscott and @akshays2112 for their contributions!

Contributions welcomed. Read CONTRIB.md