Используйте API потоков AudD на api.audd.io для распознавания песен, играющих на радиостанциях (или в любом другом потоковом аудио). Обратные вызовы — это запросы с результатами распознавания, которые серверы AudD отправят на ваш сервер. Прочитайте эти предостережения перед написанием интеграции потоков.

1. URL обратного вызова задается один раз для всего аккаунта

Установите URL для обратных вызовов с помощью метода API setCallbackUrl. Обратные вызовы от всех потоков будут отправляться на указанный URL в виде JSON-структуры в теле POST-запроса. Отдельного URL обратного вызова для каждого потока не существует.

Не вызывайте setCallbackUrl при каждом добавлении потока (addStream). Установите его один раз при настройке. Повторный вызов перезаписывает URL обратного вызова для всех существующих потоков, а не только для нового, и не вызывает никаких предупреждений. Вместо этого выполняйте маршрутизацию для каждого потока по полю radio_id в теле обратного вызова: оно однозначно идентифицирует конкретный поток.

Не вызывайте setCallbackUrl при каждом добавлении потока (addStream). Установите его один раз при настройке. Повторный вызов перезаписывает URL обратного вызова для всех существующих потоков, а не только для нового, и не вызывает никаких предупреждений. Вместо этого выполняйте маршрутизацию для каждого потока по полю radio_id в теле обратного вызова: оно однозначно идентифицирует конкретный поток.

2. addStream принимает прямые URL и три сокращения

Отправьте URL потока в параметре url метода addStream. Он поддерживает большинство форматов потоков, а также сокращения для Twitch и YouTube:

Прямые URL потоков: HLS, Icecast, .m3u / .m3u8, обычные MP3-потоки и т. д.
twitch:<канал>, например twitch:monstercat для twitch.tv/monstercat.
youtube:<ид_видео>, например youtube:5qap5aO4i9A (конкретнее живое видео).
youtube-ch:<ид_канала>, например youtube-ch:UC3zwjSYv4k5HKGXCHMpjVRg, текущая прямая трансляция канала.

Используйте сокращенную форму для Twitch и YouTube вместо вставки обычной ссылки на просмотр: именно сокращение распознается API.

3. Longpoll также требует наличия URL обратного вызова

С помощью GET-запроса https://api.audd.io/longpoll/ вы можете получать новые результаты без необходимости запускать публичный веб-сервер. Longpoll работает только после того, как вы установите URL обратного вызова с помощью метода setCallbackUrl. Если вы не установите URL обратного вызова, longpoll не вернет никаких результатов и не выдаст ошибку, объясняющую причину. Из-за этого агенты часто думают, что longpoll не работает.

Установите URL обратного вызова, даже если вы хотите использовать только longpoll. Укажите в качестве него https://audd.tech/empty/: это пустой приемник (no-op), который всегда отвечает кодом 200 OK. После этого longpoll будет доставлять результаты в ваш цикл.

Установите URL обратного вызова, даже если вы хотите использовать только longpoll. Укажите в качестве него https://audd.tech/empty/: это пустой приемник (no-op), который всегда отвечает кодом 200 OK. После этого longpoll будет доставлять результаты в ваш цикл.

Вы можете использовать longpoll вместо получения обратных вызовов или вместе с ними. Longpoll является частью потоков, а не отдельной функцией. Если какая-то песня отсутствует в вашем цикле longpoll, сначала проверьте URL обратного вызова.

4. Тело обратного вызова содержит либо результат, либо уведомление, но никогда то и другое одновременно

Вы будете получать обратные вызовы с результатами и с уведомлениями. Каждое тело обратного вызова содержит либо результат, либо уведомление, но не то и другое сразу.

Результаты содержат распознанные песни:

Уведомления содержат информацию о состоянии потоков и не содержат песен:

Если с аудиопотоком что-то происходит, AudD отправляет уведомление, чтобы вы могли исправить поток или изменить его URL. Есть 3 кода, которые вы должны обрабатывать:

Не предполагайте, что каждый обратный вызов содержит результат. Каждое уведомление с кодом 650 или 651 вызовет исключение в коде, который считывает body["result"] без предварительной проверки. Если поле notification существует, то обратный вызов является уведомлением и не содержит результата, поэтому сначала проверяйте его. Корректно обрабатывайте коды 650 (исправьте или переустановите URL потока) и 651 (источник не воспроизводит музыку), чтобы они фиксировались, а не приводили к сбою вашего кода.

Не предполагайте, что каждый обратный вызов содержит результат. Каждое уведомление с кодом 650 или 651 вызовет исключение в коде, который считывает body["result"] без предварительной проверки. Если поле notification существует, то обратный вызов является уведомлением и не содержит результата, поэтому сначала проверяйте его. Корректно обрабатывайте коды 650 (исправьте или переустановите URL потока) и 651 (источник не воспроизводит музыку), чтобы они фиксировались, а не приводили к сбою вашего кода.

5. callbacks="before" отправляет обратные вызовы при начале воспроизведения песен

По умолчанию обратные вызовы с результатами отправляются после окончания песни и содержат общую длительность потокового воспроизведения песни. Передайте параметр callbacks=before в метод addStream, если вы хотите получать обратные вызовы сразу же после начала воспроизведения песни (а не после ее окончания).

С параметром callbacks=before вы не получите общую длительность воспроизведения в обратных вызовах, так как песня еще не закончилась и суммировать нечего. При использовании before совпадение приходит раньше. Выбирайте before для отображения информации о текущей воспроизводимой песне (Now Playing). Для логирования длительности воспроизведения песен сохраняйте обратные вызовы по окончании песни. Это поведение по умолчанию, его не нужно задавать специально.

6. Тестовый токен не работает с потоками

Обратите внимание, что api_token=test работает только на стандартной конечной точке с лимитом в 10 запросов в день. Методы setCallbackUrl, addStream и longpoll не принимают тестовый токен, поэтому для потоков нет быстрого способа протестировать их в стиле «hello world». Чтобы использовать потоки, получите собственный токен в dashboard.audd.io и отправляйте его с самого первого вызова.