Trilhas sonoras

GET /3/movie/{movie_id}/soundtracks e GET /3/tv/{tv_id}/soundtracks retornam o álbum da trilha sonora de um título em uma lista results. Cada álbum tem fonte, nome, artista, data de lançamento, link e uma lista tracks com disco, número, título, artista e duração. Use append_to_response=soundtracks para juntá-lo aos detalhes.

Atualizado em Ver em Markdown

Obter a trilha sonora de um filme

GET /3/movie/{movie_id}/soundtracks retorna o álbum da trilha sonora de um filme. A resposta traz o id do filme e um array results. Cada entrada é um álbum com seus detalhes e uma lista tracks.

O exemplo carrega The Dark Knight (id 155) e imprime o álbum e uma linha por faixa.

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

Parâmetros

  • movie_idcaminhoobrigatório
    Id numérico do filme, por exemplo 155.
  • api_keyconsultaum dos dois
    Sua chave. Use este parâmetro ou o header Authorization: Bearer.

Campos da resposta

CampoTipoObservações
idinteiroId do filme. Não aparece quando você usa append_to_response.
resultsarrayÁlbuns. Vazio quando nenhum álbum é conhecido. Hoje tem no máximo um.
results[].sourcestringDe onde vem o álbum: musicbrainz ou deezer.
results[].albumstringTítulo do álbum.
results[].artiststring ou nullArtista do álbum, por exemplo Hans Zimmer & James Newton Howard.
results[].releasedstring ou nullData de lançamento no formato YYYY-MM-DD.
results[].urlstring ou nullLink para a página do álbum na fonte.
results[].track_countinteiroNúmero de faixas do álbum.
results[].tracksarrayFaixas na ordem do álbum.
results[].tracks[].discinteiroNúmero do disco, a partir de 1.
results[].tracks[].numberinteiroNúmero da faixa no disco.
results[].tracks[].titlestringTítulo da faixa.
results[].tracks[].artiststringArtista da faixa.
results[].tracks[].duration_msinteiroDuração em milissegundos.

Leia pelo nome as chaves que você usa e ignore as outras.

Exemplo de resposta

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

A lista de faixas foi cortada para 3 de 14. Um título sem álbum conhecido, como Fight Club (id 550), responde com uma lista vazia:

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

Obter a trilha sonora de uma série

GET /3/tv/{tv_id}/soundtracks retorna o mesmo formato para uma série. Passe o id da série, por exemplo 1396. Breaking Bad não tem álbum conhecido, então o array results vem vazio.

Método e caminhoRetornaParâmetros
GET /movie/{movie_id}/soundtracksid e resultsmovie_id
GET /tv/{tv_id}/soundtracksid e resultstv_id
append_to_response=soundtracksOs mesmos results sob soundtracksAcrescentado aos detalhes de filme ou de série

Para receber o álbum ao carregar a página de um filme, acrescente-o aos detalhes:

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

O bloco acrescentado fica sob a chave soundtracks do registro. Ele contém results e não tem id próprio. Conta como uma requisição.

Montar uma lista de músicas do filme

Ordene por disc e number, mostre o título e o artista, e esconda o bloco quando results estiver vazio. As funções abaixo retornam linhas de texto simples que você pode colocar em um elemento de 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)})`);
}

Algumas ideias de interface que não precisam de dados extras:

IdeiaComo
Lista numeradaUse number como o número da lista e agrupe por disc quando houver vários discos.
Link do álbumLigue o nome do álbum a url quando ele não for null.
Duração totalSome duration_ms de todas as faixas.
Par com o moodMostre a lista ao lado dos medidores de mood (clima emocional) do mesmo título.

Erros

Toda falha retorna success como false com um status_code numérico, como o TMDB faz.

HTTPstatus_codeQuando
4017A chave está ausente ou incorreta.
40236O período do plano terminou.
42925Você passou do seu limite de requisições por minuto. Espere os segundos indicados em Retry-After.

O endpoint de trilhas sonoras não responde 404 para um id desconhecido. Ele responde 200 com um array results vazio. Quando acrescentado aos detalhes, um id desconhecido vira um 404 da chamada de detalhes. Veja erros para todos os códigos e limites de requisições para os headers.

Notas práticas

  • Como os outros dados de detalhes, as trilhas sonoras têm cache de borda de 6 horas. Um cache de cliente mais curto não traz ganho.
  • Use append_to_response=soundtracks em uma página de detalhes que você já carrega. Isso poupa uma das suas 20, 40 ou 120 requisições por minuto.
  • Não exija que um álbum exista. Esconda o bloco de música quando results estiver vazio.
  • Alguns álbuns vêm do MusicBrainz e outros do Deezer. O filme 27205 (Inception) tem um álbum do Deezer. O formato é o mesmo, então confira source só se você o mostrar.
  • Nomes de faixas e de artistas são strings simples e podem conter qualquer caractere. Guarde-os em UTF-8 e escape-os ao colocá-los em HTML.
  • Para o trailer do mesmo título, veja vídeos e trailers.