AudD отправляет полезную нагрузку HTTP POST на настроенный вами URL обратного вызова, когда песня распознается в одном из ваших потоков, а также когда с потоком что-то происходит. Таким образом, вы будете получать обратные вызовы с результатами и с уведомлениями. Longpoll доставляет те же самые тела ответов; см. ниже.

Примечание: Эти примеры представляют собой записанные ответы API.

Тело обратного вызова с результатом

По умолчанию обратные вызовы отправляются после окончания песни и содержат общее время проигрывания в потоке в поле play_length. Если вы добавите поток с параметром callbacks="before", обратные вызовы отправляются сразу после начала воспроизведения песни, и поле play_length не имеет значения.

Поля верхнего уровня

объект result

элементы массива results

Результаты содержат распознанные песни. Каждый элемент в массиве описывает один трек. Один и тот же обратный вызов может содержать несколько песен-кандидатов. Проходите в цикле по каждому объекту в массиве, а не только по первому.

Тело обратного вызова с уведомлением

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

Поля верхнего уровня

объект notification

значения notification_code

Ровно одно из полей result или notification в каждом обратном вызове

Каждый обратный вызов будет содержать ровно одно из полей: result или notification, но никогда оба одновременно. Выполняйте ветвление по присутствующему ключу или по полю status:

Если статус не равен "success" или "-", рассматривайте обратный вызов как ошибку на стороне сервера, а не как событие потока.

Ответ Longpoll

Вы можете использовать длинный опрос (long polling) вместо запуска сервера обратных вызовов. Адрес длинного опроса — https://api.audd.io/longpoll/, и на него отправляются GET-запросы. Ответ отправляется только после того, как событие готово или истек тайм-аут.

Пожалуйста, установите в качестве URL обратного вызова реальный URL, способный принимать POST-запросы, даже если вы хотите использовать только длинный опрос. Longpoll может не возвращать события для аккаунта, у которого не задан URL обратного вызова, даже во время распознавания песен.

Параметры запроса:

Вот пример URL запроса longpoll:

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

Keepalive при отсутствии событий

Если до истечения тайм-аута ни одно событие не готово, longpoll завершит запрос, и вы получите ответ keepalive следующего вида:

Это нормально. Отправьте запрос снова.

Список getStreams

Используйте метод getStreams (POST https://api.audd.io/getStreams/), чтобы получить все потоки, зарегистрированные в аккаунте. Он возвращает массив объектов потоков. Если в аккаунте нет потоков, массив пуст:

Каждый элемент массива представляет собой объект потока со следующими полями:

Примечание по SDK

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

Для синтаксического анализа обратного вызова используйте метод парсинга обратного вызова в клиенте потоков, например parseCallback или handleCallback. Этот метод возвращает объект result или notification для сырого тела POST-запроса. Клиенты longpoll в SDK (например, в библиотеке Go) возвращают те же типизированные объекты результатов. Они также управляют курсором since_time за вас.

Примечания

Поле score в элементе результата означает степень достоверности совпадения от 0 до 100; чем выше число, тем точнее совпадение.
Для совпадений из пользовательского каталога результат содержит загруженный вами идентификатор трека. Поля artist и title для таких записей могут быть равны null.
Обратный вызов потока по умолчанию не включает коды ISRC, UPC или метаданные провайдеров (Apple Music, Spotify, MusicBrainz). Свяжитесь с [email protected], чтобы включить дополнительные метаданные для ваших обратных вызовов.
Если ваш сервер не отвечает на обратные вызовы статусом 200 OK, AudD поместит обратные вызовы в очередь. Когда ваш сервер снова вернется в сеть, AudD постепенно отправит всю накопленную очередь.
Обратные вызовы против longpoll: выбор метода доставки
Создание виджета «Сейчас играет»
Мониторинг радиоэфира
Глоссарий
Справочник API