Саундтраци

GET /3/movie/{movie_id}/soundtracks и GET /3/tv/{tv_id}/soundtracks връщат албума със саундтрака на заглавие в списък results. Всеки албум има source, име, изпълнител, дата на излизане, връзка и списък tracks с disc, number, title, artist и продължителност. Добавете append_to_response=soundtracks, за да го слеете с детайлите.

Обновено Отвори като Markdown

Вземане на саундтрака на филм

GET /3/movie/{movie_id}/soundtracks връща албума със саундтрака на един филм. Отговорът носи id на филма и масив results. Всеки запис е албум със своите детайли и списък tracks.

Примерът зарежда The Dark Knight (id 155) и отпечатва албума и по един ред за песен.

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

Параметри

  • movie_idпътзадължителен
    Числов id на филма, например 155.
  • api_keyзаявкаедин от двата
    Вашият ключ. Ползвайте него или заглавката Authorization: Bearer.

Полета на отговора

ПолеТипБележки
idцяло числоId на филма. Липсва, когато ползвате append_to_response.
resultsмасивАлбуми. Празен, когато няма известен албум. Днес съдържа най-много един.
results[].sourceнизОткъде идва албумът: musicbrainz или deezer.
results[].albumнизЗаглавие на албума.
results[].artistниз или nullИзпълнител на албума, например Hans Zimmer & James Newton Howard.
results[].releasedниз или nullДата на излизане във вида YYYY-MM-DD.
results[].urlниз или nullВръзка към страницата на албума при източника.
results[].track_countцяло числоБрой песни в албума.
results[].tracksмасивПесни по ред в албума.
results[].tracks[].discцяло числоНомер на диска, започвайки от 1.
results[].tracks[].numberцяло числоНомер на песента на диска.
results[].tracks[].titleнизЗаглавие на песента.
results[].tracks[].artistнизИзпълнител на песента.
results[].tracks[].duration_msцяло числоДължина в милисекунди.

Четете ключовете, които ползвате, по име и пропускайте останалите.

Примерен отговор

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

Списъкът с песни е съкратен до 3 от 14. Заглавие без известен албум, като Fight Club (id 550), отговаря с празен списък:

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

Вземане на саундтрака на сериал

GET /3/tv/{tv_id}/soundtracks връща същата форма за сериал. Подайте id на сериала, например 1396. Breaking Bad няма известен албум, затова масивът му results е празен.

Метод и пътКакво връщаПараметри
GET /movie/{movie_id}/soundtracksid и resultsmovie_id
GET /tv/{tv_id}/soundtracksid и resultstv_id
append_to_response=soundtracksСъщият results под soundtracksДобавя се към детайлите на филм или сериал

За да вземете албума, докато зареждате страница на филм, добавете го към детайлите:

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

Добавеният блок стои под ключа soundtracks на записа. Съдържа results и няма собствено id. Брои се като една заявка.

Списък „музика от този филм“

Сортирайте по disc и number, показвайте заглавието и изпълнителя и скривайте блока, когато results е празен. Функциите по-долу връщат прости текстови редове, които можете да сложите в елемент от списък.

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

Няколко идеи за интерфейс, които не искат допълнителни данни:

ИдеяКак
Номериран списъкПолзвайте number като номер в списъка и групирайте по disc, когато дисковете са няколко.
Връзка към албумаСвържете името на албума с url, когато не е null.
Обща продължителностСъберете duration_ms на песните.
Съчетание с настроениеПоказвайте списъка до индикаторите за настроение на същото заглавие.

Грешки

Всяка грешка връща success със стойност false и числов status_code, както прави TMDB.

HTTPstatus_codeКога
4017Ключът липсва или е грешен.
40236Периодът на плана е изтекъл.
42925Надхвърлен е лимитът на заявки в минута. Изчакайте Retry-After секунди.

Ендпойнтът за саундтраци не отговаря с 404 за непознато id. Отговаря със 200 и празен масив results. Когато се добавя към детайлите, непознато id дава 404 от извикването за детайли. Вижте грешки за всеки код и лимити на заявките за заглавките.

Практически бележки

  • Както другите данни за детайли, саундтраците се кешират на edge за 6 часа. По-кратък клиентски кеш не носи полза.
  • Ползвайте append_to_response=soundtracks на страница с детайли, която вече зареждате. Така спестявате една от вашите 20, 40 или 120 заявки в минута.
  • Не изисквайте албумът да съществува. Скривайте блока с музика, когато results е празен.
  • Някои албуми идват от MusicBrainz, а други от Deezer. Филм 27205 (Inception) има албум от Deezer. Формата е една и съща, така че проверявайте source, само ако го показвате.
  • Имената на песни и изпълнители са прости низове и могат да съдържат всякакъв знак. Пазете ги в UTF-8 и ги екранирайте, когато ги слагате в HTML.
  • За трейлъра на същото заглавие вижте видеа и трейлъри.