Миграция с ShazamKit на AudD

Эта страница предназначена для разработчиков, использующих ShazamKit от Apple, которым требуется распознавание, работающее одинаково на разных платформах и серверах, или которым необходимо выполнять поиск по управляемой базе данных AudD, а не только по созданному ими каталогу. ShazamKit — это фреймворк Apple, который выполняет сопоставление аудио на устройстве на платформах Apple с каталогом Shazam от Apple или пользовательским каталогом, собранным из ваших собственных эталонных записей. AudD — это кроссплатформенный HTTP API: вы отправляете аудио (или URL) по сети и получаете распознанный трек, сопоставленный с базой данных AudD, содержащей 160 миллионов песен, или с вашим собственным загруженным пользовательским каталогом. В этом руководстве сопоставляются концепции и показывается код для iOS (Swift) «до/после» с использованием официального Swift SDK от AudD.

Сопоставление концепций

Эквивалентный вызов

До — ShazamKit на iOS

В ShazamKit вы захватываете аудио, передаете буферы генератору сигнатур, запускаете сопоставление в сеансе и считываете результат из сопоставленного медиаэлемента:

После — AudD с использованием Swift SDK

В AudD вы записываете короткий фрагмент с помощью AVAudioRecorder (или захватываете буферы и записываете файл), а затем передаете байты или URL файла в метод recognize. Создание отпечатков (фингерпринтинг) происходит на стороне сервера. Установите SDK через Swift Package Manager по адресу https://github.com/AudDMusic/audd-swift.

Метод recognize возвращает RecognitionResult? — значение nil возвращается, когда фрагмент был обработан, но совпадений не найдено, что API отправляет как result: null. Стандартный эндпоинт отвечает менее чем за 2 секунды, принимает короткий фрагмент размером до 10 МБ и выполняет поиск по базе данных AudD, содержащей 160 миллионов песен. Фрагмента продолжительностью 5–15 секунд вполне достаточно.

Храните токен на своем сервере в релизных приложениях. Собранное приложение для iOS может напрямую вызывать api.audd.io, но в таком случае api_token будет находиться в бинарном файле приложения, откуда его можно извлечь. Для продакшена направляйте запросы на распознавание через собственный бэкенд и храните токен на стороне сервера: устройство загружает фрагмент вам, а вы вызываете AudD.

Храните токен на своем сервере в релизных приложениях. Собранное приложение для iOS может напрямую вызывать api.audd.io, но в таком случае api_token будет находиться в бинарном файле приложения, откуда его можно извлечь. Для продакшена направляйте запросы на распознавание через собственный бэкенд и храните токен на стороне сервера: устройство загружает фрагмент вам, а вы вызываете AudD.

Пользовательский каталог

Класс SHCustomCatalog в ShazamKit позволяет производить поиск по эталонным сигнатурам, которые вы генерируете на устройстве из собственных записей. Эквивалентом в AudD является пользовательский каталог, который вы загружаете в свой аккаунт; после этого вызовы recognize для данного аккаунт производят поиск по вашим трекам в дополнение к общедоступной базе данных (или вместо нее). Совпадение с пользовательским каталогом содержит поле audio_id (ваша ссылка на загруженный трек), а поля artist и title могут иметь значение null, если вы не указали их при загрузке. Поля, для которых в SDK не определены типизированные свойства, доступны через result.extras или полный ответ result.rawResponse.

Доступ к пользовательскому каталогу ограничен — отправьте письмо на [email protected], чтобы включить его для вашего аккаунта, а затем загружайте файлы через POST-запрос на api.audd.io/upload/.

В чем разница

• Где выполняется сопоставление. ShazamKit выполняет сопоставление на устройстве. AudD выполняет сопоставление на сервере посредством HTTP-вызова. Локальное сопоставление работает офлайн и сохраняет аудио на устройстве; серверный API требует сетевого кругового пути (round trip), но работает одинаково на любой платформе и централизует каталог.
• Доступность на платформах. ShazamKit — это фреймворк Apple для платформ Apple (iOS, macOS, watchOS, tvOS, visionOS) плюс вариант для Android. AudD — это не зависящий от языка программирования HTTP API с 11 официальными SDK (Python, Node, Go, Rust, PHP, Swift, Kotlin, .NET, Java, C, C++), поэтому один и тот же контракт распознавания может вызываться из вашего приложения iOS, приложения Android и сервера.
• По какой базе данных ведется поиск. ShazamKit выполняет поиск по каталогу Shazam от Apple или пользовательскому каталогу, созданному вами из эталонных сигнатур. AudD производит поиск по своей управляемой базе данных из 160 миллионов песен, загруженному вами пользовательскому каталогу или по обеим базам одновременно.
• Отсутствие этапа создания сигнатуры на стороне клиента. ShazamKit требует генерации сигнатуры из записанного аудио перед сопоставлением. В AudD вы отправляете аудио (URL, путь к файлу или байты), а создание отпечатков выполняется на стороне сервера.
• Длинные аудиозаписи и прямые трансляции. ShazamKit ориентирован на сопоставление записанного семпла. AudD дополнительно предлагает корпоративный эндпоинт, который разбивает длинные файлы на фрагменты (полные песни, подкасты, DJ-сеты, трансляции) и возвращает каждое совпадение, а также эндпоинты для потоковой передачи, которые распознают живые трансляции и отправляют совпадения методом POST на указанный callback.
• Поля метаданных. AudD возвращает артиста, название, альбом, дату релиза, лейбл, таймкод, ссылку на песню, а также (в корпоративных вызовах или на аккаунтах с тарифом Startup и выше) коды isrc и upc. Блоки провайдеров (apple_music, spotify, deezer, musicbrainz) возвращаются только тогда, когда это запрошено через параметр return.
• Ценообразование. Цены AudD находятся в открытом доступе: 300 бесплатных запросов для новых аккаунтов без привязки карты, затем ежемесячные тарифные планы от $5 (включено 1,000 запросов, дополнительные запросы по $5.00 за 1,000). Все тарифные планы доступны на audd.io/pricing.

Шаги миграции

• Определите, где выполняется вызов. Для релизного приложения запланируйте маршрутизацию распознавания через ваш бэкенд, чтобы api_token оставался на сервере. Для прототипа SDK может напрямую вызывать api.audd.io с тестовым токеном (10 запросов в день, только стандартный эндпоинт).
• Получите токен AudD. Зарегистрируйтесь на dashboard.audd.io и скопируйте api_token.
• Добавьте SDK. В Xcode выберите File → Add Package Dependencies… и вставьте https://github.com/AudDMusic/audd-swift. Добавьте продукт AudD в ваш таргет.
• Замените процесс записи и сопоставления. Замените цепочку SHSignatureGenerator / SHSession на запись короткого фрагмента (например, с помощью AVAudioRecorder) и вызов try await audd.recognize(.file(clip)).
• Перенастройте сопоставление результатов. Настройте код интерфейса на использование полей RecognitionResult (artist, title, album, songLink, thumbnailURL, ссылки на провайдеров через streamingUrl(_:)). Добавьте явную ветку для обработки случая отсутствия совпадений (nil).
• Перенесите свой пользовательский каталог, если он есть. Если вы выполняли поиск по SHCustomCatalog, запросите доступ к пользовательскому каталогу (написав на [email protected]) и загрузите свои эталонные треки с помощью POST-запроса на api.audd.io/upload/.
• Проверьте работу с помощью фиксированных входных данных. Запустите файл https://audd.tech/example.mp3 по мигрированному пути и убедитесь, что отображаемые поля присутствуют, прежде чем переводить на него реальный трафик.
• Создание приложения для распознавания музыки в стиле Shazam
• Публичная база данных против пользовательского каталога
• Документация по SDK
• Справочник по API