Colonne sonore

GET /3/movie/{movie_id}/soundtracks e GET /3/tv/{tv_id}/soundtracks restituiscono l'album della colonna sonora di un titolo in una lista results. Ogni album ha source, nome, artista, data di uscita, link e una lista tracks con disco, numero, titolo, artista e durata. Aggiungi append_to_response=soundtracks per unirla ai dettagli.

Aggiornato il Vedi in Markdown

Ottenere la colonna sonora di un film

GET /3/movie/{movie_id}/soundtracks restituisce l'album della colonna sonora di un film. La risposta contiene l'id del film e un array results. Ogni voce è un album con i suoi dettagli e una lista tracks.

L'esempio carica The Dark Knight (id 155) e stampa l'album e una riga per brano.

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)
		}
	}
}

Parametri

  • movie_idpercorsoobbligatorio
    ID numerico del film, per esempio 155.
  • api_keyqueryuno dei due
    La tua chiave. Usa questa o l'header Authorization: Bearer.

Campi della risposta

CampoTipoNote
idinteroID del film. Assente quando usi append_to_response.
resultsarrayAlbum. Vuoto quando non è noto alcun album. Oggi ne contiene al massimo uno.
results[].sourcestringaDa dove viene l'album: musicbrainz o deezer.
results[].albumstringaTitolo dell'album.
results[].artiststringa o nullArtista dell'album, per esempio Hans Zimmer & James Newton Howard.
results[].releasedstringa o nullData di uscita come YYYY-MM-DD.
results[].urlstringa o nullLink alla pagina dell'album presso la fonte.
results[].track_countinteroNumero di brani dell'album.
results[].tracksarrayBrani nell'ordine dell'album.
results[].tracks[].discinteroNumero del disco, a partire da 1.
results[].tracks[].numberinteroNumero del brano sul disco.
results[].tracks[].titlestringaTitolo del brano.
results[].tracks[].artiststringaArtista del brano.
results[].tracks[].duration_msinteroDurata in millisecondi.

Leggi per nome le chiavi che usi e salta le altre.

Risposta di esempio

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 }
      ]
    }
  ]
}

L'elenco dei brani è tagliato a 3 su 14. Un titolo senza un album noto, come Fight Club (id 550), risponde con una lista vuota:

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

Ottenere la colonna sonora di una serie

GET /3/tv/{tv_id}/soundtracks restituisce la stessa struttura per una serie. Passa l'ID della serie, per esempio 1396. Breaking Bad non ha un album noto, quindi il suo array results è vuoto.

Metodo e percorsoRestituisceParametri
GET /movie/{movie_id}/soundtracksid e resultsmovie_id
GET /tv/{tv_id}/soundtracksid e resultstv_id
append_to_response=soundtracksLo stesso results sotto soundtracksAggiunto ai dettagli di un film o di una serie

Per ottenere l'album mentre carichi la pagina di un film, aggiungilo ai dettagli:

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

Il blocco aggiunto sta sotto la chiave soundtracks della scheda. Contiene results e non ha un id proprio. Conta come una sola richiesta.

Costruire una lista «musica in questo film»

Ordina per disc e number, mostra il titolo e l'artista, e nascondi il blocco quando results è vuoto. Le funzioni qui sotto restituiscono righe di testo semplice che puoi mettere in un elemento di lista.

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)})`);
}

Alcune idee di interfaccia che non richiedono dati aggiuntivi:

IdeaCome
Elenco numeratoUsare number come numero dell'elenco, e raggruppare per disc quando ci sono più dischi.
Link all'albumCollegare il nome dell'album a url quando non è null.
Durata totaleSommare duration_ms su tutti i brani.
Abbinamento con i moodMostrare la lista accanto agli indicatori di mood dello stesso titolo.

Errori

Ogni errore restituisce success a false con uno status_code numerico, come fa TMDB.

HTTPstatus_codeQuando
4017La chiave manca o è sbagliata.
40236Il periodo del piano è terminato.
42925Oltre le tue richieste al minuto. Attendi i secondi di Retry-After.

L'endpoint delle colonne sonore non risponde 404 per un ID sconosciuto. Risponde 200 con un array results vuoto. Aggiunto ai dettagli, un ID sconosciuto dà un 404 dalla chiamata dei dettagli. Vedi errori per tutti i codici e limiti di richieste per gli header.

Note pratiche

  • Come gli altri dati dei dettagli, le colonne sonore restano in cache sull'edge per 6 ore. Una cache client più breve non porta nulla.
  • Usa append_to_response=soundtracks su una pagina di dettagli che già carichi. Risparmia una richiesta delle tue 20, 40 o 120 richieste al minuto.
  • Non pretendere che un album esista. Nascondi il blocco musicale quando results è vuoto.
  • Alcuni album vengono da MusicBrainz e altri da Deezer. Il film 27205 (Inception) ha un album Deezer. La struttura è la stessa, quindi controlla source solo se la mostri.
  • I nomi di brani e artisti sono semplici stringhe e possono contenere qualsiasi carattere. Salvali in UTF-8 e fai l'escape quando li metti nell'HTML.
  • Per il trailer dello stesso titolo, vedi video e trailer.