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

Эта страница предназначена для инженеров, использующих ACRCloud и рассматривающих AudD в качестве бэкенда для распознавания. Обе службы являются облачными сервисами аудио-отпечатков: вы отправляете аудио, а в ответ получаете распознанный трек. Два основных изменения в вашем коде касаются способа аутентификации (ACRCloud подписывает каждый запрос с помощью HMAC на основе ключа доступа/секрета, а AudD принимает одно поле формы api_token) и того, какой эндпоинт обрабатывает определенную задачу (короткий клип, длинный файл или прямая трансляция). В этом руководстве сопоставляются концепции и показываются эквивалентные вызовы AudD.

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

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

Аутентификация

Самое крупное изменение в коде связано с аутентификацией. ACRCloud требует создания строки для подписания и вычисления HMAC-SHA1 с использованием секретного ключа доступа для каждого запроса:

AudD выполняет аутентификацию с помощью одного поля формы — api_token, а официальный SDK устанавливает его автоматически из конструктора или переменной окружения AUDD_API_TOKEN. Здесь нет строки для подписания, временной метки и HMAC:

Если вы вызываете HTTP-эндпоинт напрямую, а не через SDK, весь запрос представляет собой многочастный POST-запрос (multipart POST) с параметром api_token и аудиофайлом:

api_token является секретом типа Bearer — храните его на стороне сервера. Поскольку для каждого запроса нет подписи, любой обладатель токена может потратить вашу квоту. Храните его на своем бэкенде (или в менеджере секретов), но никогда в клиентском коде. Обновляйте его в личном кабинете dashboard.audd.io.

api_token является секретом типа Bearer — храните его на стороне сервера. Поскольку для каждого запроса нет подписи, любой обладатель токена может потратить вашу квоту. Храните его на своем бэкенде (или в менеджере секретов), но никогда в клиентском коде. Обновляйте его в личном кабинете dashboard.audd.io.

Распознавание короткого клипа

Эндпоинт identify в ACRCloud и стандартный эндпоинт в AudD принимают короткий сэмпл и возвращают наиболее подходящий результат. Стандартный эндпоинт AudD отвечает менее чем за 2 секунды, ограничивает размер загружаемого файла до 10 МБ и производит поиск по базе данных из 160 миллионов песен. Поддерживаемые аудиоформаты: MP3, WAV, FLAC, M4A, OGG, AAC, WMA, AIFF.

Успешный вызов, не давший совпадений, возвращает None (API отправляет result: null). Это отличается от ошибки — воспринимайте это как «попробуйте снова», а не как сбой.

Сканирование длинного файла

Там, где вы использовали сканирование файлов в ACRCloud для обработки длинной записи, используйте корпоративный эндпоинт AudD. Он разбивает файл на части на стороне сервера и возвращает каждое совпадение по порядку.

Всегда устанавливайте параметр limit для корпоративных вызовов во время разработки. Корпоративный эндпоинт тарифицируется за каждые 12 секунд обработанного аудио. Неограниченный вызов для многочасового файла обработает его целиком. limit=N останавливает обработку после N совпадений.

Всегда устанавливайте параметр limit для корпоративных вызовов во время разработки. Корпоративный эндпоинт тарифицируется за каждые 12 секунд обработанного аудио. Неограниченный вызов для многочасового файла обработает его целиком. limit=N останавливает обработку после N совпадений.

Мониторинг трансляции или прямая линия

Там, где вы использовали мониторинг трансляций в ACRCloud, используйте эндпоинты стримов в AudD. Вы регистрируете URL обратного вызова (callback) и добавляете поток; AudD распознает песни по мере их воспроизведения и отправляет каждое совпадение методом POST на ваш callback.

radio_id — это целое число на ваш выбор, а не имя. В отличие от строковых ключей потоков в ACRCloud, это номер, который вы присваиваете каждому потоку и который возвращается с каждым callback-запросом, чтобы вы могли различать потоки.

URL потока принимает прямые ссылки на потоки (HLS, Icecast, m3u/m3u8), а также сокращения twitch:<channel>, youtube:<video_id> и youtube-ch:<channel_id>. Если вы не можете разместить публичный URL для callback, опрашивайте GET /longpoll/ вместо этого (audd.streams.longpoll(...)).

Что изменилось

• Модель аутентификации. ACRCloud подписывает каждый запрос с помощью ключа/секрета доступа и HMAC-подписи (плюс метка времени). AudD использует одно поле формы api_token без подписания запросов. Меньше кода с вашей стороны; это также означает, что токен необходимо защищать как любой секрет типа Bearer.
• Выбор эндпоинтов. ACRCloud разделяет продукты по сценариям использования (идентификация, сканирование файлов, мониторинг трансляций) и по региональным хостам. AudD использует один стандартный хост для клипов, один корпоративный хост для длинного аудио и эндпоинты стримов для мониторинга в реальном времени — без необходимости выбирать региональный хост.
• Сигнал об отсутствии совпадений. AudD возвращает status: "success" с result: null при отсутствии совпадений, что отличается от ответа об ошибке. Обрабатывайте этот случай отдельно, чтобы тихий фрагмент не воспринимался как сбой.
• Единица тарификации корпоративной версии. Корпоративный эндпоинт AudD тарифицируется за каждые 12 секунд обработанного аудио и требует установки параметра limit. Рассчитывайте бюджет исходя из длительности аудио, а не только количества запросов.
• Пользовательское аудио. ACRCloud позволяет выполнять поиск по вашим собственным бакетам; AudD позволяет загружать ваши собственные треки в кастомный каталог (POST api.audd.io/upload/, доступ ограничен — отправьте запрос на [email protected]). Совпадение из кастомного каталога возвращает audio_id, а поля artist и title могут быть null, если вы не указали их при загрузке.
• Поля метаданных. AudD возвращает artist, title, album, release_date, label, timecode, song_link, а также (в корпоративных вызовах или на аккаунтах тарифа Startup и выше) isrc и upc. Блоки провайдеров (apple_music, spotify, deezer, musicbrainz) возвращаются только тогда, когда вы запрашиваете их через параметр return.
• Прозрачность цен. Цены AudD являются общедоступными: 300 бесплатных запросов для новых аккаунтов без привязки карты, затем ежемесячные планы от $5 (включая 1,000 запросов, дополнительные запросы — $5.00 за 1,000), все тарифы доступны на audd.io/pricing.
• Поддержка SDK. AudD поставляет 11 официальных SDK, поэтому единый контракт аутентификации и распознавания доступен на разных языках программирования без необходимости вручную писать клиент.

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

• Получите токен AudD. Зарегистрируйтесь на dashboard.audd.io (300 бесплатных запросов, карта не нужна) и скопируйте api_token.
• Установите SDK для вашего языка программирования. Например, pip install audd, npm install @audd/sdk или go get github.com/AudDMusic/audd-go. Документация по SDK содержит информацию для всех 11 языков.
• Замените код подписания на токен. Удалите генератор HMAC/подписи и поля формы access_key/access_secret/timestamp. Инициализируйте клиент с помощью api_token (или установите переменную AUDD_API_TOKEN).
• Сопоставьте каждый вызов с эндпоинтом. Identify → стандартный recognize(...). Сканирование файлов → recognize_enterprise(..., limit=N). Мониторинг трансляций → streams (set_callback_url + add) или longpoll, если вы не можете развернуть callback.
• Пересопоставьте поля ответа. Настройте ваш код на схему результатов AudD (artist, title, album, release_date, label, timecode, isrc, upc, song_link и блоки провайдеров). Добавьте явную ветку для результата result == null при отсутствии совпадений.
• Перенесите пользовательское аудио, если таковое имеется. Если вы полагались на бакеты ACRCloud с вашими собственными треками, запросите доступ к кастомному каталогу (напишите на [email protected]) и загружайте файлы через POST api.audd.io/upload/.
• Проверьте работу с помощью фиксированного файла. Пропустите известный файл (https://audd.tech/example.mp3) через каждый мигрированный путь и убедитесь, что необходимые вам поля присутствуют, прежде чем переключать продакшн-трафик.
• Стандартный, корпоративный или стримы: как выбрать
• Публичная база данных против вашего кастомного каталога
• Документация по SDK
• Справочник API