Créez un lecteur de musique Web avec l'API Spotify
Lorsque vous apprenez de nouveaux concepts, il est toujours utile d'avoir des exemples et des projets pratiques sur lesquels travailler. L'API Spotify est une excellente introduction aux API Web en général. Avec lui, vous pouvez facilement construire des services publics simples qui effectuent diverses tâches liées à la musique.
Sommaire
À propos de l'API
Toutes les API sont limitées par les fonctions et les données que leur propriétaire choisit de mettre à disposition. Mais tout vaut mieux que rien, et l'API Spotify est peut-être étonnamment ouvert et facile à utiliser.
L'API a deux composantes principales:
-
Une API Web qui fournit des métadonnées sur les artistes, les pistes et les listes de lecture.
-
Un SDK de lecture Web qui vous permet d'intégrer un lecteur Spotify dans une page Web.
En général, ceux-ci sont assez restreints; Par exemple, Spotify déclare que vous ne devez pas utiliser le SDK de lecture pour développer des applications de streaming commercial. Mais il y a encore des projets intéressants que vous pouvez créer pour votre propre usage, et l'API Spotify est un bon exemple d'API Web en général, parfait pour apprendre et pratiquer.
Configuration des choses
La chose la plus évidente dont vous aurez besoin pour créer ces exemples d'applications est un compte Spotify. En utilisant, vous pouvez vous connecter au tableau de bord Spotify pour les développeurs et commencer par créer une application.
Vous aurez également besoin d'un serveur Web local, que vous avez peut-être déjà configuré. Sinon, c'est assez facile de le faire. Choisissez un emplacement approprié pour votre développement Spotify, par exemple, LocalHost / Spotify ou LocalHost: 8080.
Pendant ce temps, de retour sur le site Web de Spotify, remplissez le formulaire «Créer l'application». Assurez-vous de sélectionner à la fois les options «API Web» et «Web Playback SDK» et choisissez un URI redirigé. Par exemple, j'héberge la démo «Top» dans un fichier nommé Top.html, qui est servi sur http: // localhost: 8080 / top.html, c'est donc l'un de mes URI redirects. Si vous utilisez une architecture similaire pour vos démos, n'oubliez pas d'ajouter chaque nouveau fichier en tant qu'URI de redirection.
Une fois que vous avez créé votre application, prenez note de l'ID client et du secret client, qui sont tous deux affichés sur la page «Informations de base» de votre application.
Pour les applications de production, vous devrez prendre des mesures pour garder votre client secret caché. Pour cette démonstration locale, je n'incorpore que la valeur dans mon fichier JavaScript, mais vous ne devriez divulguer votre secret de votre client à personne.
À ce stade, vous souhaiterez peut-être télécharger les exemples de fichiers, les déplacer dans votre racine de document locale et commencer à expérimenter. Je ne peux couvrir qu'une fraction du code dans cet article, ce qui vous permettrai de suivre le processus.
Autoriser avec l'API
La première étape de la création de votre application consiste à autoriser l'utilisation d'OAuth. Il s'agit d'une norme populaire pour l'autorisation des applications Web, il est donc utile de les en savoir plus.
OAuth fonctionne en envoyant un jeton d'accès sur HTTP, et le processus est suffisamment établi pour que les bibliothèques d'assistance soient disponibles. Pourtant, pour nos fins de base, il est facile de tout gérer nous-mêmes.
J'ai isolé ce code dans le fichier Access.js. La première étape consiste à rediriger vers l'URL d'autorisation de Spotify, qui est https://accounts.spotify.com/authorize. Vous devez fournir quelques paramètres pour demander l'autorisation de l'utilisateur d'utiliser votre application:
-
Response_Type: Pour les types d'application d'échantillons que nous créons, utilisez simplement code.
-
client_id: il s'agit de l'ID client que vous avez noté lors de la configuration de l'application.
-
Portée: une chaîne de lunettes séparées dans l'espace pour accorder l'autorisation. Pour les deux démos, je couvrirai ici, « Streaming User-top Read » est assez bon, mais assurez-vous de consulter l'ensemble complet de lunettes si vous essayez d'autres points de terminaison.
-
redirect_uri: un URI de redirection valide que vous avez ajouté à votre application.
Vous devez également utiliser le État Paramètre pour des raisons de sécurité, mais il est bon de l'omettre pendant ces démos.
Dans Access.js, la fonction Autorité ressemble à ceci:
function authorize() {
let base = "https://accounts.spotify.com/authorize",
params = {
response_type: "code",
client_id: CLIENT_ID,
scope: "streaming ...",
redirect_uri: REDIRECT_URI,
}; window.location.assign(base + "?" + new URLSearchParams(params));
}
Cela redirige le navigateur vers une URL Spotify avec les paramètres pertinents. Lorsque vous affichez cette URL, vous verrez quelque chose comme ce qui suit:
Un utilisateur ne devra accorder des autorisations qu'une seule fois, sauf si vous modifiez la portée. Avec l'autorisation accordée, ils seront envoyés au redirect_uri, ainsi qu'un paramètre de code. Ils finiront donc à quelque chose comme http: // localhost: 8080 / top.html? Code = … Votre script devrait vérifier ce paramètre et passer à l'étape suivante si elle est présente:
let p = new URLSearchParams(window.location.search);if (p.has("code")) {
get_access_token(p.get("code"));
}
Cette deuxième étape consiste à envoyer le code que vous venez d'obtenir à Spotify en retour pour un jeton d'accès. Vous utiliserez ensuite le jeton d'accès dans toutes les autres demandes de l'API.
Le code de cet article est simplifié pour maintenir la longueur. Consultez le code complet dans le repo GitHub pour plus de détails. En particulier, vous devrez également actualiser le jeton à son expiration.
async function get_access_token(code) {
let url = "https://accounts.spotify.com/api/token",
data = {
grant_type: "authorization_code",
code: code,
redirect_uri: REDIRECT_URI,
},
headers = {
"content-type": "application/x-www-form-urlencoded",
Authorization: "Basic " + btoa(CLIENT_ID + ":" + CLIENT_SECRET),
}; let opts = {
method: "post",
headers: headers,
body: get_post_data(data),
};
const response = await fetch(url, opts),
token = await response.json();
if (token.access_token) {
localStorage.setItem("access-token", token.access_token);
} else {
console.error("Some kind of error getting access token", token);
}
}
Vous pouvez utiliser l'API de stockage local pour conserver un enregistrement du jeton d'accès et le récupérer à l'avenir:
let token = localStorage.getItem("access-token");
Vous devez maintenant envoyer le jeton d'accès dans un en-tête d'autorisation pour toutes les demandes d'API Spotify:
async function spotify_api_get(url) {
let headers = {
Authorization: "Bearer " + at.access_token,
}; let opts = { headers: headers, method: "GET" };
const response = await fetch(url, opts);
return await response.json();
}
Cette fonction occupe l'ensemble du fichier Spotify.js et gère les demandes d'obtention uniquement. Vous pouvez étendre ce fichier et écrire des fonctions similaires pour des méthodes telles que Put et Publier lorsque le point de terminaison que vous devez utiliser les nécessite.
Oauth est un sujet assez complexe, qui dépasse le cadre de cet article. Vous pouvez utiliser une version simple pour l'expérimentation; N'oubliez pas que vous devrez réinitialiser manuellement le jeton s'il expire (voir localStorage.RemoveItem).
Avec tout ce qui est configuré et le client autorisé, vous êtes enfin prêt à commencer à utiliser l'API. Retrouver les métadonnées est un peu plus simple, donc je vais commencer par l'échantillon «top» (top.html), qui vous montre vos meilleurs artistes, ainsi que un peu d'informations à leur sujet.
Commencez par consulter la documentation de l'API Spotify, qui explique comment utiliser le point de terminaison / moi / top / artistes. Vous pouvez garder cela simple en évitant les paramètres supplémentaires et en vous concentrant sur l'objet de réponse, qui contient des détails de vos meilleurs artistes dans son articles propriété.
Dans top.js, la fonction run () contient le code pour récupérer et afficher ces données. C'est très simple: d'abord, il appelle le point de terminaison de l'API et stocke l'objet renvoyé:
let top_artists = await spotify_api_get(
"https://api.spotify.com/v1/me/top/artists",
at.access_token,
);
Ensuite, il itère sur le articles Dans la réponse:
top_artists.items.forEach(function (artist) {
});
Et, à l'intérieur de cette boucle, il ajoute une ligne de table contenant des données pour chaque élément:
tr = tbody.appendChild(document.createElement("tr"));
td = tr.appendChild(document.createElement("td"));
td.appendChild(document.createTextNode(artist.name));
Le résultat est une table simple avec vos meilleurs artistes et leurs genres associés; Le mien ressemble à ceci:
Utilisation du joueur Spotify
Les métadonnées sont intéressantes, mais un joueur Spotify fonctionnel est peut-être plus utile. Bien qu'il y ait des limites, l'API vous donne essentiellement un contrôle total sur la lecture, donc – avec un peu de travail – vous pouvez créer votre propre client.
Le plus grand point de frottement est l'insistance de l'API à exécuter Spotify en même temps que votre propre client. Cela ne devrait pas être trop un problème pour votre développement, mais cela peut limiter les applications potentielles que vous pouvez développer. Vous devrez connecter explicitement l'application Spotify à votre client API, en tant qu'appareil:
De plus, vous devrez le faire chaque fois que vous actualisez votre application Web, ce qui peut être ennuyeux. J'ai ajouté un message d'erreur à la démo, ce qui vous rappelle de le faire; Cela facilite très légèrement la douleur!
Le fichier Player.html présente un client simple avec des illustrations d'album, des commandes de lecture et un indicateur de progression qui vous permet de chercher. La plupart des fonctionnalités pertinentes vivent dans Player.js.
La première chose à faire est d'insérer le script SDK de Spotify:
<script src="https://sdk.scdn.co/spotify-player.js">script>
Dans la démo, je l'injecte dynamiquement. Cela garantit que le script peut d'abord vérifier un jeton d'accès, en obtenir un si nécessaire. Sans jeton d'accès valide, le script SDK peut générer des erreurs.
Ensuite, le script crée une nouvelle instance de lecteur et tente de s'y connecter:
window.onSpotifyWebPlaybackSDKReady = () => {
player = new Spotify.Player({
name: "bobbykjack spotify client",
getOAuthToken: (cb) => {
cb(at.access_token);
},
volume: 0.5,
}); setup_player_state_event();
player.connect().then((success) => {
if (success) {
check_device_connected();
} else {
console.error("Oops, failed to connect to spotify");
}
});
};
Notez que le joueur doit être nourri d'un jeton d'accès valide, ainsi qu'un nom qui apparaîtra dans l'application Spotify en tant qu'appareil à qui se connecter. Le scrutin de contrôle_device_connected et check_player_state pour une connexion de périphérique; Sans un, le script affichera l'erreur « s'il vous plaît connecter » que j'ai mentionné plus tôt.
Lorsqu'un objet de lecteur est configuré et connecté, vous pouvez appeler des méthodes supplémentaires dessus pour charger les pistes et contrôler la lecture. Ces méthodes sont détaillées dans les documents de référence SDK de lecture Web. L'exemple de lecteur en utilise plusieurs: pause, recherche, reprendre, basculer et getcurrentState.
Certaines fonctionnalités nécessitent simplement la connexion d'un bouton sur la page à une méthode SDK correspondante. Par exemple, voici le code du bouton de lecture:
play.addEventListener("click", function (ev) {
player.resume().then(() => {
play.setAttribute("disabled", "1");
pause.removeAttribute("disabled");
});
});
Lorsque vous cliquez sur, le bouton appelle la méthode Player.Resume, puis se désactive et permet le bouton Pause.
Certaines fonctionnalités sont un peu plus compliquées. Lorsqu'une piste change, l'événement Player_State_Changed appelle une méthode du même nom, qui met à jour l'affichage, en modifiant les illustrations de l'album, par exemple:
let src = get_image(arg.track_window.current_track.album.images, 300),
set_attr("#currently_playing div.track-meta img", "src", src);
Pour montrer les progrès actuels de la piste, le code interroge la méthode Player.getCurrentState. Cela renvoie un objet contenant divers détails sur la lecture, y compris la position de piste actuelle:
function check_player_state(state) {
update_time(".position", state.position);
}
Enfin, la position de piste peut être modifiée en faisant glisser l'entrée de progression:
document
.querySelector("#track-progress")
.addEventListener("input", handle_seek_input);function handle_seek_input(ev) {
if (seek_timer) {
window.clearTimeout(seek_timer);
}
seek_timer = window.setTimeout(function () {
seek_to_ms(ev.target.value);
}, 200);
}
function seek_to_ms(position) {
player.pause().then(function () {
player.seek(position).then(function () {
player.resume();
update_time(".position", position);
});
});
}
Notez qu'une minuterie est utilisée pour injecter une méthode artificielle – mais petite – avant d'appeler la méthode Player.seek. Sans ce retard, faire glisser la barre de progression pendant une brève période pourrait entraîner des centaines d'appels à l'API; Il vaut mieux éviter.
Comme de nombreuses API, Spotify utilise des limites de taux pour vous assurer de ne pas submerger le service avec trop de demandes. C'est assez indulgent, cependant, et vous ne devriez rencontrer aucun problème avec ces échantillons; Vérifiez votre console pour 429 erreurs si quelque chose ne fonctionne pas comme prévu.
L'application finale présente un joueur de base qui se synchronise avec Spotify:
J'espère que vous pourrez apprendre de ces démos simples et commencer à écrire votre propre code pour travailler avec l'API Spotify. Cela peut sembler limité, mais il y a beaucoup de réglages que vous pourriez apporter à un client simple pour améliorer votre expérience Spotify.
J'ai toujours senti que les listes de lecture devraient pouvoir contenir des albums complets, donc c'est une fonctionnalité sur laquelle je vais certainement travailler bientôt. Vous pouvez également étudier d'autres API, comme YouTube, pour combiner des données avec un joueur ou des métadonnées Spotify, et créer une application qui présente le meilleur des deux.
