Bandes originales

GET /3/movie/{movie_id}/soundtracks et GET /3/tv/{tv_id}/soundtracks renvoient l'album de la bande originale d'un titre dans une liste results. Chaque album a une source, un nom, un artiste, une date de sortie, un lien et une liste tracks avec disque, numéro, titre, artiste et durée. Ajoutez append_to_response=soundtracks pour la fusionner aux détails.

Mis à jour le Voir en Markdown

Obtenir la bande originale d'un film

GET /3/movie/{movie_id}/soundtracks renvoie l'album de la bande originale d'un film. La réponse contient l'id du film et un tableau results. Chaque entrée est un album avec ses détails et une liste tracks.

L'exemple charge The Dark Knight (id 155) et affiche l'album et une ligne par morceau.

bashjspyphpgo
curl -sf "https://api.amodb.dev/3/movie/155/soundtracks" \
  -H "Authorization: Bearer $AMODB_KEY"
const res = await fetch('https://api.amodb.dev/3/movie/155/soundtracks', {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { results } = await res.json();
if (results.length === 0) console.log('no soundtrack album known');
for (const album of results) {
  console.log(`${album.album} by ${album.artist} (${album.track_count} tracks)`);
  for (const t of album.tracks) {
    console.log(`${t.number}. ${t.title} by ${t.artist}`);
  }
}
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/155/soundtracks",
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
results = r.json()["results"]
if not results:
    print("no soundtrack album known")
for album in results:
    print(f"{album['album']} by {album['artist']} ({album['track_count']} tracks)")
    for t in album["tracks"]:
        print(f"{t['number']}. {t['title']} by {t['artist']}")
<?php
$ch = curl_init('https://api.amodb.dev/3/movie/155/soundtracks');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
$results = json_decode($body, true)['results'];
if (!$results) {
    echo 'no soundtrack album known', PHP_EOL;
}
foreach ($results as $album) {
    echo $album['album'], ' by ', $album['artist'] ?? 'unknown', ' (', $album['track_count'], ' tracks)', PHP_EOL;
    foreach ($album['tracks'] as $t) {
        echo $t['number'], '. ', $t['title'], ' by ', $t['artist'], PHP_EOL;
    }
}
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type Track struct {
	Disc       int    `json:"disc"`
	Number     int    `json:"number"`
	Title      string `json:"title"`
	Artist     string `json:"artist"`
	DurationMs int    `json:"duration_ms"`
}

type Album struct {
	Source     string  `json:"source"`
	Album      string  `json:"album"`
	Artist     string  `json:"artist"`
	Released   string  `json:"released"`
	URL        string  `json:"url"`
	TrackCount int     `json:"track_count"`
	Tracks     []Track `json:"tracks"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/155/soundtracks", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var body struct {
		Results []Album `json:"results"`
	}
	if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
		panic(err)
	}
	if len(body.Results) == 0 {
		fmt.Println("no soundtrack album known")
	}
	for _, a := range body.Results {
		fmt.Printf("%s by %s (%d tracks)\n", a.Album, a.Artist, a.TrackCount)
		for _, t := range a.Tracks {
			fmt.Printf("%d. %s by %s\n", t.Number, t.Title, t.Artist)
		}
	}
}

Paramètres

  • movie_idcheminobligatoire
    Identifiant numérique du film, par exemple 155.
  • api_keyrequêtel'un des deux
    Votre clé. Utilisez-la ou l'en-tête Authorization: Bearer.

Champs de la réponse

ChampTypeRemarques
identierIdentifiant du film. Absent quand vous utilisez append_to_response.
resultstableauAlbums. Vide quand aucun album n'est connu. Aujourd'hui il en contient au plus un.
results[].sourcechaîneD'où vient l'album : musicbrainz ou deezer.
results[].albumchaîneTitre de l'album.
results[].artistchaîne ou nullArtiste de l'album, par exemple Hans Zimmer & James Newton Howard.
results[].releasedchaîne ou nullDate de sortie sous la forme YYYY-MM-DD.
results[].urlchaîne ou nullLien vers la page de l'album chez la source.
results[].track_countentierNombre de morceaux de l'album.
results[].trackstableauMorceaux dans l'ordre de l'album.
results[].tracks[].discentierNuméro du disque, à partir de 1.
results[].tracks[].numberentierNuméro du morceau sur le disque.
results[].tracks[].titlechaîneTitre du morceau.
results[].tracks[].artistchaîneArtiste du morceau.
results[].tracks[].duration_msentierDurée en millisecondes.

Lisez par leur nom les clés que vous utilisez et ignorez les autres.

Exemple de réponse

JSON
{
  "id": 155,
  "results": [
    {
      "source": "musicbrainz",
      "album": "The Dark Knight",
      "artist": "Hans Zimmer & James Newton Howard",
      "released": "2008-07-15",
      "url": "https://musicbrainz.org/release/814b2f7b-c27c-451e-abac-a316d2e6cea9",
      "track_count": 14,
      "tracks": [
        { "disc": 1, "number": 1, "title": "Why So Serious?", "artist": "Hans Zimmer", "duration_ms": 554000 },
        { "disc": 1, "number": 2, "title": "I'm Not a Hero", "artist": "Hans Zimmer", "duration_ms": 395000 },
        { "disc": 1, "number": 3, "title": "Harvey Two-Face", "artist": "James Newton Howard", "duration_ms": 377000 }
      ]
    }
  ]
}

La liste de morceaux est réduite à 3 sur 14. Un titre sans album connu, comme Fight Club (id 550), répond par une liste vide :

JSON
{
  "id": 550,
  "results": []
}

Obtenir la bande originale d'une série

GET /3/tv/{tv_id}/soundtracks renvoie la même forme pour une série. Passez l'identifiant de la série, par exemple 1396. Breaking Bad n'a aucun album connu : son tableau results est donc vide.

Méthode et cheminRenvoieParamètres
GET /movie/{movie_id}/soundtracksid et resultsmovie_id
GET /tv/{tv_id}/soundtracksid et resultstv_id
append_to_response=soundtracksLe même results sous soundtracksAjouté aux détails d'un film ou d'une série

Pour obtenir l'album pendant le chargement d'une page de film, ajoutez-le aux détails :

curl
curl -sf "https://api.amodb.dev/3/movie/155?append_to_response=credits,soundtracks" \
  -H "Authorization: Bearer $AMODB_KEY"

Le bloc ajouté se trouve sous la clé soundtracks de la fiche. Il contient results et n'a pas d'id propre. Il compte pour une seule requête.

Construire une liste « musique du film »

Triez par disc et number, affichez le titre et l'artiste, et masquez le bloc quand results est vide. Les fonctions ci-dessous renvoient des lignes de texte simple que vous pouvez placer dans un élément de liste.

JavaScript
function clock(ms) {
  const s = Math.round(ms / 1000);
  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`;
}

function musicLines(results) {
  const album = results[0];
  if (!album) return [];
  return [...album.tracks]
    .sort((a, b) => a.disc - b.disc || a.number - b.number)
    .map((t) => `${t.title} by ${t.artist} (${clock(t.duration_ms)})`);
}

Quelques idées d'interface qui n'exigent aucune donnée supplémentaire :

IdéeComment
Liste numérotéeUtiliser number comme numéro de liste, et regrouper par disc quand il y a plusieurs disques.
Lien vers l'albumRelier le nom de l'album à url quand il n'est pas null.
Durée totaleAdditionner duration_ms sur les morceaux.
Association avec les ambiancesAfficher la liste à côté des jauges d'ambiance du même titre.

Erreurs

Chaque échec renvoie success à false avec un status_code numérique, comme le fait TMDB.

HTTPstatus_codeQuand
4017La clé est absente ou fausse.
40236La période de l'offre est terminée.
42925Au-dessus de vos requêtes par minute. Attendez les secondes de Retry-After.

Le point de terminaison des bandes originales ne répond pas 404 pour un identifiant inconnu. Il répond 200 avec un tableau results vide. Ajouté aux détails, un identifiant inconnu donne un 404 de l'appel de détails. Voir erreurs pour tous les codes et limites de débit pour les en-têtes.

Remarques pratiques

  • Comme les autres données de détails, les bandes originales sont mises en cache 6 heures en périphérie. Un cache client plus court n'apporte rien.
  • Utilisez append_to_response=soundtracks sur une page de détails que vous chargez déjà. Cela économise une requête de vos 20, 40 ou 120 requêtes par minute.
  • N'exigez pas qu'un album existe. Masquez le bloc musique quand results est vide.
  • Certains albums viennent de MusicBrainz et d'autres de Deezer. Le film 27205 (Inception) a un album Deezer. La forme est la même : ne vérifiez donc source que si vous l'affichez.
  • Les noms de morceaux et d'artistes sont de simples chaînes et peuvent contenir n'importe quel caractère. Stockez-les en UTF-8 et échappez-les quand vous les placez dans du HTML.
  • Pour la bande-annonce du même titre, voir vidéos et bandes-annonces.