Когда AudD распознает песню, вы можете попросить его прикрепить к результату метаданные от четырех внешних провайдеров — Apple Music, Spotify, Deezer и MusicBrainz. Каждый блок отражает объект трека/альбома самого провайдера, поэтому вы получаете прямую ссылку на сервис, предварительный просмотр аудио, обложку и идентификаторы провайдера без выполнения второго запроса. Провайдеры предоставляют разные поля, поэтому каждый блок задокументирован на отдельной странице; эта страница охватывает общие аспекты — как их запрашивать, общие механизмы и когда вместо этого достаточно song_link.
Блоки
Метаданные Napster больше недоступны: платформа прекратила работу, и napster был удален из API (отправка этого параметра вызывает предупреждение #51).
На каждой странице, посвященной конкретному провайдеру, задокументированы типизированные поля этого блока, способы чтения тех полей, которые действительно используют разработчики, и места, где можно найти полную схему провайдера.
В HTTP API перечислите провайдеров, которых вы хотите получить, в поле формы return в виде строки, разделенной запятыми:
В SDK эта опция называется returnMetadata (или идиоматический эквивалент для языка — return_metadata в Python). return — это имя в исходном API; return_metadata/returnMetadata — это имя в SDK для того же параметра.
Каждый блок считывается как типизированное свойство результата — result.spotify, result.apple_music и так далее (result.spotify в Node), с доступом к атрибутам типизированных подполей. Поля, выходящие за рамки типизированной структуры, проходят через model_extra (Python) / extras (Node) в Pydantic. На страницах для каждого провайдера показаны шаблоны доступа для каждого блока.
Три вещи, которые нужно знать перед тем, как запрашивать всё:
- Каждый запрашиваемый провайдер увеличивает задержку. AudD ищет трек в каждом сервисе, который вы запрашиваете. Запрашивайте только тех провайдеров, данные которых вы действительно будете считывать.
- Блок будет иметь значение null или отсутствовать, если вы его не запрашивали (или если у провайдера нет совпадения для этой записи). Наличие apple_music не гарантируется, даже если вы его запросили — обрабатывайте случай отсутствия и относитесь к каждому подполю как к потенциально отсутствующему или null.
- Корпоративный эндпоинт (enterprise) по умолчанию не возвращает блоки провайдеров. Для корпоративных совпадений используйте song_link (ниже), чтобы перейти к сервисам. Если вам нужны метаданные провайдеров для корпоративных результатов, напишите на [email protected].
Параметр market задает код страны, используемый для поиска в Apple Music и Spotify (по умолчанию us); он меняет запись в каталоге и список available_markets, которые вы получаете. Он не влияет на другие блоки.
Более простая альтернатива: song_link
Вам не нужен блок провайдера только для того, чтобы отправить пользователя в стриминговый сервис. Каждое совпадение — стандартное или корпоративное, без запроса return — содержит song_link: универсальный URL lis.tn, например https://lis.tn/NbkVb, который ведет на страницу со ссылками на песню в разных сервисах.
Добавьте ?thumb к song_link, чтобы получить обложку напрямую (https://lis.tn/NbkVb?thumb), не запрашивая никакой блок провайдера.
Поэтому перед добавлением провайдеров в return спросите себя, не покрывает ли song_link ваши потребности. Запрашивайте блоки провайдеров, когда вам нужны прямая ссылка конкретного сервиса, идентификаторы, превью или обложка в вашем собственном интерфейсе; используйте song_link, когда достаточно кросс-платформенной ссылки и обложки. Ознакомьтесь с концепцией ссылок lis.tn для полного понимания поведения.
Вспомогательные функции SDK: streaming_url(provider)
SDK предоставляют вспомогательную функцию, которая разрешает URL для конкретного провайдера из совпадения: streaming_url(provider) в Python, streamingUrl(provider) в SDK с camelCase. Она возвращает прямой URL провайдера, если вы запрашивали этот блок, а в противном случае возвращает редирект lis.tn для этого провайдера — поэтому она работает независимо от того, установили ли вы return.
Допустимые идентификаторы провайдеров: spotify, apple_music, deezer, youtube. (youtube разрешается только через lis.tn — блока метаданных youtube не существует. MusicBrainz — это база данных метаданных, а не стриминговый сервис, поэтому у него также нет streaming_url.)
Примечания
- Запрос провайдера не гарантирует появление его блока: AudD возвращает его только в том случае, если у этого провайдера есть совпадение для распознанной записи. Всегда проверяйте на null перед чтением.
- Параметр market влияет только на поиск в Apple Music и Spotify.
- ISRC — это надежный ключ объединения, если вы храните метаданные от нескольких провайдеров: один и тот же ISRC появляется в блоках Apple Music, Spotify и MusicBrainz для одной и той же записи.
- Блок метаданных Apple Music
- Блок метаданных Spotify
- Блок метаданных Deezer
- Блок метаданных Napster (больше не доступен)
- Блок метаданных MusicBrainz
- Ссылка на песню lis.tn
- Справочник полей результата
- Глоссарий
- Документация SDK
