audd — это инструмент командной строки от AudD. В этом руководстве он используется для распознавания песни, тегирования папки с аудио, составления списка треков в миксе и прослушивания радиотрансляции, а затем те же команды объединяются в скрипт оболочки.
Установка
Установочный скрипт помещает audd в ~/.local/bin и сверяет загруженный файл с контрольными суммами релиза. Флаг --at clips и команда audd listen также требуют ffmpeg.
Запуск без установки
Команды ниже предполагают использование audd. Если вы используете npx или uvx, подставьте npx @audd/cli или uvx audd-cli на его место.
Вход в систему
audd login открывает браузер для подтверждения входа и сохраняет ваш API-токен. На сервере эта команда выводит код, который можно подтвердить с другого устройства. Если у вас уже есть токен, задайте его:
Получите собственный токен на сайте dashboard.audd.io.
1. Распознавание одной песни
В терминале вы получите карточку с обложкой, исполнителем, названием, альбомом, лейблом и ссылкой для прослушивания. Добавьте --return apple_music,spotify для получения ID и метаданных из стриминговых сервисов.
Стандартный эндпоинт анализирует до первых 12 секунд аудио. Если нужная вам песня начинается позже в файле, отправьте отрывок с этого момента:
audd listen выполняет запись с микрофона и определяет, что играет рядом с вами.
2. Тегирование папки с аудиофайлами в CSV
Папка представляет собой пакет, а для пакета всегда требуется флаг --max-files, чтобы опечатка в пути не привела к отправке десяти тысяч файлов. Флаг --dry-run показывает, сколько файлов было найдено и сколько запросов потратит выполнение, без отправки каких-либо данных. Когда план выглядит корректно:
CLI попросит вас подтвердить действие, а затем запишет по одной строке на файл с такими колонками, как artist, title, album, release_date, label, isrc, upc и song_link. Колонка status принимает значения matched, no_match или failed. Файлы без совпадений остаются в CSV, чтобы вы могли проверить их вручную.
Пакет сохраняет свой прогресс после каждого файла. Если выполнение прерывается (Ctrl-C, обрыв соединения), возобновите его:
Результаты кешируются по содержимому файлов, поэтому повторный запуск для той же папки не тратит запросы на уже распознанные файлы.
3. Превращение микса в треклист
В диджейском сете или записанном радиошоу много песен, поэтому используйте корпоративный эндпоинт, который сканирует файл целиком. Корпоративный тариф тарифицируется за каждые 12 секунд просканированного аудио, поэтому ему требуется лимит на количество сканируемых фрагментов:
Тестовый запуск показывает стоимость обработки всего файла. --tracklist объединяет последовательные совпадения в одну запись для каждого трека с указанием времени его начала и окончания в миксе. Для нового типа записи попробуйте небольшой --limit и проверьте результаты перед сканированием файлов целиком.
4. Отслеживание радиотрансляции
audd streams add подписывает трансляцию на распознавание, и AudD определяет каждую проигранную в ней песню. audd now-playing показывает последнюю песню на каждой трансляции с ее обложкой и тем, что играло до этого.
Первая команда streams запускает фоновый регистратор, который сохраняет каждый результат локально, чтобы вы могли сформировать отчет по трансляции позже:
По умолчанию AudD отправляет результат трансляции по окончании песни с указанием времени ее звучания. Добавьте трансляцию с флагом --start, чтобы получать каждую песню в момент ее начала.
Использование в скрипте
При перенаправлении вывода каждая команда выводит JSON вместо таблицы, с полем "schema_version": 1 в каждом документе:
--fields ограничивает вывод указанными полями, а --format csv работает для любой команды, выводящей строки:
В отсутствие терминала некому ответить на запрос подтверждения, поэтому для пакета требуется флаг --yes.
Коды выхода:
- 0: успех, включая файлы без совпадений (передайте --fail-on-no-match, чтобы вместо этого вернуть код 1).
- 3: проблема с входом или токеном.
- 4: квота.
- 5: сеть.
- 6: команда остановлена из-за лимита безопасности.
- 7: некоторые файлы в пакете завершились с ошибкой.
Задание cron, предупреждающее до исчерпания запросов:
audd usage --check возвращает код выхода 8, если оставшихся запросов меньше, чем вы запросили.
Что делать дальше
- Документация CLI для каждой команды и флага
- Сравнение стандартного, корпоративного и потокового эндпоинтов для выбора правильного при переходе от CLI к коду
- Официальные SDK для того же API для Python, Node, Go и еще восьми языков
