Руководство по CLI AudD для ИИ-агентов

audd — это инструмент командной строки от AudD. Он распознает музыку в файлах, по URL-адресам, в папках и на длинных записях, отслеживает радиотрансляции и управляет учетной записью AudD. Когда его вывод перенаправляется (pipe), как это бывает у агента, выполняющего команды оболочки, каждая команда выводит JSON, принимает явные лимиты затрат и завершает работу с документированным кодом. На этой странице описано все необходимое для управления инструментом: команды, структура вывода, лимиты, ошибки и локальный MCP-сервер. Полная справочная информация находится на сайте docs.audd.io/cli.

Когда использовать CLI, API или MCP-сервер

Используйте CLI, когда у вас есть оболочка (shell) и разовая задача или скрипт: распознать файл, проставить теги для папки, получить список треков в миксе, проверить трансляцию или запросить статистику использования аккаунта. Если создаваемый вами код распознает аудио как часть приложения, вместо этого вызывайте из этого кода HTTP API или официальный SDK. Размещенный на хостинге MCP-сервер по адресу mcp.audd.io подходит для агентов без оболочки, которым нужны инструменты аккаунта (статистика использования, токен API, тарифные планы, документация). audd mcp — это локальный MCP-сервер, который предоставляет агенту функции распознавания, корпоративного сканирования и трансляций через CLI на его собственном компьютере.

Установка audd

Скрипт установки помещает audd в директорию ~/.local/bin без использования sudo и сверяет загрузку с контрольными суммами SHA-256 для конкретного релиза. Каждый пакет содержит один и тот же бинарный файл для macOS, Linux и Windows на архитектурах x86-64 и ARM64. Для фрагментов с --at требуются ffmpeg, а для audd listen — ffmpeg или sox; никакие другие инструменты не нужны. В Docker-образе нет ffmpeg.

Запуск audd без установки

Выберите один способ запуска и используйте его для каждой команды в сеансе. В примерах ниже используется audd; замените его на npx @audd/cli или uvx audd-cli.

Команда audd version выводит один JSON-документ с версией, хэшем коммита, датой, версией Go, ОС и архитектурой.

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

Для распознавания нужен API-токен. Получите свой токен на странице dashboard.audd.io. Самая простая настройка для агента — это токен, который пользователь добавляет в переменные среды:

audd считывает токен в следующем порядке: из параметра --token, из переменной среды AUDD_API_TOKEN, из токена, сохраненного с помощью команды audd config set token, и из токена, полученного командой audd login. Чтобы сохранить токен так, чтобы он не отображался в истории командной строки или списке процессов, передайте его через пайп:

Никогда не выводите токен на печать. Команда audd token show маскирует его; опустите флаг --reveal.

Вход в систему без браузера

Если пользователь хочет, чтобы вы вошли в систему за него, запустите audd login. Без терминала инструмент использует метод кодов, выводит запись login_pending в качестве первой строки JSON в stdout и ожидает:

Покажите пользователю значения verification_uri_complete и user_code. Он открывает страницу на любом устройстве, проверяет совпадение кода и подтверждает вход. Не прерывайте выполнение команды: она завершится, когда вход будет одобрен, отклонен или истечет срок действия (код действует 15 минут). При одобрении выводится строка результата:

При использовании явного указания --format json или --format csv запись login_pending отправляется в stderr, поэтому в stdout сохраняется только один документ. На странице подтверждения пользователь может снять галочки с разрешений; audd auth status показывает, что было одобрено. Флаги --browser и --device выбирают метод аутентификации. Если указан флаг --browser, но нет терминала, запись содержит поле "method":"browser", URL для открытия и команду complete_with, которую нужно выполнить, если браузер находится на другом компьютере.

Проверка входа и используемого токена

Команда audd auth status (она же audd whoami) показывает профиль, статус входа, одобренные разрешения и источник токена:

Параметр token_source может принимать значения flag, env, config, login или none. Если токен вообще отсутствует, команда выводит документ с полем "token_source":"none" и завершает работу с кодом 3 и ошибкой no_token.

Какие команды требуют входа в систему

Для команд распознавания (recognize, listen, catalog add), потоков (streams), api и token show нужен только токен. Команды account, usage, billing, token rotate и token refresh-local требуют выполнения audd login; без него они завершаются с кодом 3 и ошибкой login_required.

Профили

У каждого профиля есть свои данные для входа, токен и настройки. Передайте --profile work, установите переменную среды AUDD_PROFILE или сделайте профиль по умолчанию с помощью команды audd auth switch work.

Чтение вывода в формате JSON

Когда stdout не является терминалом, вывод по умолчанию представляет собой JSON без каких-либо флагов. Каждый документ и каждая строка содержат поле "schema_version": 1. Результаты выводятся в stdout; примечания, планы и ошибки выводятся в stderr.

Один файл или URL

Поле result содержит информацию о песне: исполнитель (artist), название (title), альбом (album), дата выпуска (release_date), лейбл (label), таймкод (timecode — позиция совпадения фрагмента в песне), song_link, а для тарифных планов, которые их включают — isrc и upc. Поле cached принимает значение true, если результат получен из локального кэша (этот URL уже распознавался ранее); для свежего запроса выводится false. Для файла без совпадений выводится "result": null и происходит выход с кодом 0:

Фрагмент, полученный с помощью --at, добавляет объект clip с полями start_seconds и length_seconds. Корпоративное сканирование имеет поле "enterprise": true и массив matches вместо result (см. раздел "Поиск любой песни в длинной записи"). Поля, которые AudD добавит в будущем, передаются в неизменном виде по мере их появления.

Пакеты выводят строки JSON

Для папки, шаблона путей (glob), нескольких файлов или списка, поданного на stdin, выводится один JSON-объект на строку. Каждая строка имеет тип:

• event: первыми выводятся события job_started (с полями job_id, total, to_run) или job_resumed (добавляет done); dry_run — это план, выводимый с помощью --format jsonl.
• result: по одному на каждый файл, с полями job_id, index, input, status (matched, no_match, failed или pending), cached, result, а также объектом error для неудачного файла.
• summary: последняя строка со счетчиками для всего задания.

Команды потоковой передачи (streams watch, streams export, now-playing при перенаправлении и streams history --format jsonl) выводят результат и строки событий аналогичным образом.

Пакет из трех файлов: один совпал, для одного нет совпадений, один завершился ошибкой:

Затем этот пакет вывел ошибку partial_failure в stderr и завершился с кодом 7. Счетчики в сводке (summary), включая requests_spent, охватывают все задание целиком, как их сообщает audd jobs list; requests_spent_this_run — это то, что было потрачено за текущий запуск. Статус в выполнение сводки может быть done, partial (все файлы обработаны, некоторые завершились ошибкой), stopped (остановлено лимитом или ошибкой аккаунта) или interrupted.

Фильтрация вывода с помощью --fields, --format и --quiet

Параметр --fields сохраняет только указанные поля, для вложенных полей используется точечная нотация:

Поле, которого в выводе быть не может, вызывает ошибку использования (код выхода 2) со списком доступных полей до того, как что-либо будет отправлено. Поле, отсутствующее в одном из результатов, выводится как null. В строках JSON параметр --fields обрезает только строки результатов, поэтому строки событий и сводки сохраняют свой идентификатор задания и счетчики. Он не применяется к элементам внутри списков: выбирайте совпадения или треки целиком и фильтруйте их с помощью jq.

Параметр --format table|json|jsonl|csv (или AUDD_FORMAT) выбирает формат. --quiet скрывает примечания и прогресс в stderr; в табличном выводе он также выводит только строку с песней (Tears For Fears — Everybody Wants To Rule The World). Вывод в формате JSON при использовании --quiet не меняется.

Столбцы CSV

CSV имеет одинаковые плоские столбцы как для одного файла, так и для пакета:

job_id пуст для одиночного ввода. Корпоративное сканирование выводит по одной строке на каждое совпадение с заполненными полями start_seconds и end_seconds.

Ошибки в stderr

Неудачная команда выводит один JSON-документ в stderr:

code — это стабильная строка, перечисленная в разделе "Коды ошибок и действия с ними". api_code — собственный номер ошибки AudD, если ее вернул API, в противном случае 0. hint обычно содержит точную команду, которая решает проблему. "retryable": true означает, что ожидание и повторная попытка могут помочь; false означает, что не помогут.

Лимиты затрат и подтверждения

Всё, что может расходовать большое количество запросов, требует явного ограничения. Если ограничение отсутствует, команда завершается с кодом 6 перед отправкой чего-либо:

• Папка, шаблон glob, несколько файлов или список из stdin представляют собой пакет и требуют указания --max-files N.
• Тарификация --enterprise осуществляется за каждые 12 секунд аудио и требует указания --limit N (12-секундных фрагментов на файл).
• При отсутствии терминала выполнение, которое может потратить больше одного запроса, требует --yes. Одиночное стандартное распознавание никогда не запрашивает подтверждение.
• --max-requests N останавливает выполнение до того, как будет потрачено более N запросов. Команда audd config set max_requests N задает значение по умолчанию.

--dry-run работает без --max-files или --limit и ничего не отправляет. Запустите ее сначала, покажите пользователю план и добавьте --yes только после его согласия. Никогда не передавайте --limit none или --max-files none, если пользователь не запросил обработку всего объема.

Папка без --max-files:

Файлов больше, чем разрешено через --max-files:

Ограниченный запуск без --yes выводит план в stderr, а затем ошибку:

Запуск, остановленный с помощью --max-requests, можно возобновить:

Чтение плана пробного запуска (dry-run)

input задает файл или URL для одиночного ввода и равен null для пакета. job_id устанавливается, когда запуск возобновляет незавершенную задачу. cost_usd использует цену с оплатой по факту (pay-as-you-go) — $5 за 1 000 запросов. Кешированные файлы ничего не стоят и учитываются в cached_files. Для корпоративного сканирования (enterprise) URL, длина которого неизвестна, план без --limit не имеет верхнего предела:

С параметром --limit 20 тот же план содержит "requests":20, "approximate":true и "cost_usd":0.1. При использовании --format jsonl план представляет собой одну строку с полями "type":"event" и "event":"dry_run", поэтому он никогда не учитывается как результат файла.

Коды выхода

Пакет, в котором для некоторых файлов не нашлось совпадений, все равно завершается с кодом 0. Добавьте --fail-on-no-match, чтобы вместо этого завершаться с кодом 1; файлы с ошибками имеют приоритет (код выхода 7).

Коды ошибок и что с ними делать

Внутри пакета поле error.code для файла использует те же названия. Файл, запрос которого отправлялся в момент остановки audd, фиксируется как interrupted_in_flight: AudD могла учесть его, поэтому он отправляется повторно только вместе с --retry-failed.

Основные задачи

Как распознать песню по файлу или URL

Стандартная конечная точка анализирует до первых 12 секунд аудио и принимает файлы размером до 10 МБ. Поддерживаются как аудио-, так и видеофайлы. Результаты кешируются по содержимому файлов (URL — в течение 24 часов), поэтому повторное распознавание того же аудио происходит бесплатно; --no-cache отправляет его в любом случае, а audd cache clear очищает кеш. audd listen выполняет запись с микрофона (по умолчанию 10 секунд, до 60 с параметром --seconds) и определяет, что играет.

Получение метаданных Apple Music, Spotify, Deezer или MusicBrainz

Параметр --return принимает значения apple_music, spotify, deezer и musicbrainz. Каждое из них добавляет под результатами блок с идентификаторами и ссылками соответствующего сервиса. Не работает с --enterprise.

Распознавание песни с определенного момента в файле

--at отправляет 12-секундный клип (или длительность, указанную в --duration), начиная с указанного времени. Принимает формат 90, 1:30 или 1m30s и требует наличия ffmpeg. В вывод добавляется объект clip; для --at 0:30 он выглядит так: "clip":{"start_seconds":30,"length_seconds":12}.

Безопасное сканирование папки

• Предварительный просмотр плана. Ничего не отправляется: audd recognize ./recordings --max-files 200 --dry-run

Предварительный просмотр плана. Ничего не отправляется:

• Покажите пользователю plan.files, plan.requests и plan.cost_usd и спросите, стоит ли продолжать.

Покажите пользователю plan.files, plan.requests и plan.cost_usd и спросите, стоит ли продолжать.

• Запустите с --yes, записывая результат в формате JSON lines или CSV в файл: audd recognize ./recordings --max-files 200 --yes > results.jsonl audd recognize ./recordings --max-files 200 --yes --format csv > results.csv

Запустите с --yes, записывая результат в формате JSON lines или CSV в файл:

Шаблон glob или список из stdin работают аналогичным образом. Список из stdin требует --yes всякий раз, когда он может потратить запросы, так как список занимает stdin, и audd не может запросить подтверждение:

--concurrency N задает количество параллельных запросов (по умолчанию 4). Добавьте --max-requests N, чтобы ограничить выполнение.

Возобновление прерванного пакета

Каждый пакет представляет собой задачу (job), сохраняемую после каждого файла, поэтому остановленный запуск не теряет уже завершенные файлы. Не запускайте его заново с нуля:

audd jobs list выводит {"schema_version":1,"items":[...]}, по одному элементу на задачу с полями id, inputs, total, done, no_match, failed, pending, remaining, requests_spent и status. audd jobs resume отправляет только оставшиеся файлы. Файлы, которые завершились ошибкой после начала загрузки или отправлялись в момент остановки audd, могли быть учтены, поэтому они отправляются повторно только с --retry-failed.

Повторный запуск той же пакетной команды, пока ее задача не завершена, приводит к выходу с кодом 6:

Передайте --resume для продолжения этой задачи или --new для повторного распознавания каждого файла. Возобновленный запуск выводит результаты только для оставшихся файлов; audd jobs show <id> выводит их все. audd jobs clean удаляет старые задачи (по умолчанию --older-than 30d, --all для всех незапущенных задач).

Поиск любой песни в длинной записи

Корпоративная конечная точка (enterprise) сканирует файл целиком и возвращает каждое совпадение с указанием его позиции. Тарификация идет за каждый 12-секундный фрагмент, поэтому требуется параметр --limit:

Каждый элемент в matches содержит поля песни, а также score, start_offset и end_offset (в миллисекундах внутри фрагмента), а также start_seconds и end_seconds (от начала файла). --tracklist добавляет массив tracks, который объединяет последовательные совпадения одной и той же песни. Фильтрация по полям --fields tracks:

Параметры --skip, --every, --skip-first-seconds, --use-timecode и --accurate-offsets передаются в корпоративную конечную точку. Для локального файла план использует его длину (точною при установленном ffprobe, иначе оцениваемую по размеру файла). Длина URL неизвестна, поэтому --limit является единственным ограничением. См. раздел контроля затрат enterprise для выбора лимита.

Мониторинг радиотрансляций

Мониторинг потоков должен быть включен в аккаунте. Добавьте поток под выбранным ID, а затем читайте его результаты:

streams add выводит {"schema_version":1,"added":true,"radio_id":1,...}. С параметром --start AudD отправляет каждый результат в момент начала песни, а не по ее окончании. streams remove <id> требует --yes при отсутствии терминала.

audd now-playing --once выводит последнюю песню в каждом потоке:

state принимает значение just_played, а позже last_recognized для результатов, отправляемых по окончании песни (по умолчанию, с полями played_seconds и ended_at), либо playing для потоков, добавленных с --start (с полем elapsed_seconds). length_seconds появляется только тогда, когда результаты потока содержат метаданные Apple Music, Spotify или Deezer, что включается командой audd streams callback set <url> --return apple_music. Поток, результаты которого не удается прочитать, перечисляется с объектом error; команда завершается с кодом 5 только тогда, когда ни один поток не может быть прочитан.

audd streams watch выводит строку результата для каждого воспроизведения и строки событий для состояния потока:

streams history выводит хронологический порядок (новые сначала) {"schema_version":1,"since":...,"plays":[...],"gaps:[...]}. gaps — это периоды, когда поток не записывался, поэтому итоговые значения могут не учитывать воспроизведения за это время. streams report выводит строки с полями key, plays, airtime_seconds и stations, с флагом "complete": false, если из-за пропусков (gaps) итоговые данные неполные. --by принимает значение song, artist, label или station.

Первая команда потоков запускает фоновый регистратор, который получает каждый результат по длинному опросу (longpoll) и сохраняет его в локальную базу данных, благодаря чему история и отчеты остаются полными. audd streams recorder status|start|stop управляет им, audd streams record запускает его на переднем плане, а audd config set streams.background_recorder false отключает его.

Для живых результатов в аккаунте должен быть задан URL обратного вызова (callback URL). Если он не задан, команда streams watch останавливается с ошибкой callback_url_required (код выхода 6), если только вы не передадите параметр --yes, который устанавливает заполнитель https://audd.tech/empty/. Чтобы использовать собственный приемник, выполните audd streams callback set <url>. Параметр --forward-to URL для streams watch и streams record также отправляет каждый результат методом POST на указанный URL в формате обратного вызова AudD для тестирования обработчика локально. Подробнее читайте в заметках агента по потокам.

Проверка использования и управление аккаунтом

Для этого требуется выполнить audd login:

audd usage выводит лимит, used_this_cycle (использовано за цикл), remaining (остаток), cycle_start, cycle_end и ежедневный массив дат и запросов. Параметр --check --min-remaining N завершает работу с кодом 8, если осталось менее N запросов.

Команды выставления счетов никогда ничего не списывают. Они выводят ссылку на Stripe, которую пользователь может открыть и подтвердить платеж:

Предоставьте payment_url пользователю; не открывайте его за него. audd token rotate мгновенно отключает текущий токен везде одновременно, поэтому запускайте ее только по запросу пользователя; без терминала требуется параметр --yes. audd token refresh-local повторно запрашивает текущий токен из аккаунта. audd token show требует только токен и выводит его в маскированном виде.

Добавление песни в пользовательский каталог

Эта команда добавляет отпечаток песни в пользовательский каталог аккаунта под audio_id 42, заменяя любую песню, уже находящуюся под этим ID. Она ничего не распознает. Доступ к пользовательскому каталогу включается для каждого аккаунта; без него команда завершается с кодом 4 и ошибкой not_enabled. Каждая выгрузка оплачивается и никогда не повторяется автоматически, даже после сбоя сервера или сети, так как первая выгрузка могла быть учтена. Спросите пользователя, прежде чем запускать ее снова. См. заметки агента по пользовательскому каталогу.

Использование audd в качестве локального MCP-сервера

audd mcp запускает MCP-сервер через стандартный ввод (stdin) и вывод (stdout). Каждый инструмент запускает соответствующую команду audd с токеном, профилем, кэшем результатов и хранилищем потоков данной машины.

Добавление в Claude Code, Cursor и другие клиенты

Для клиентов, настроенных с помощью JSON, таких как Cursor и Claude Desktop, запустите команду audd с аргументом mcp:

Опустите переменную окружения env, когда audd вошел в систему или имеет сохраненный токен. Добавьте --profile NAME к аргументам, чтобы использовать другой профиль.

Инструменты и параметры

Каждый инструмент принимает один файл. Путь к папке отклоняется с подсказкой запустить audd recognize <dir> --max-files N вместо этого. Неработающий инструмент возвращает результат с ошибкой, текст которой заканчивается кодом ошибки и кодом выхода:

Как лимиты применяются к вызовам MCP-инструментов

Параметр --max-requests N, переданный в audd mcp, является верхним пределом для всей сессии. Вызов recognize или catalog_add считается за один запрос, а корпоративное сканирование — как его лимит. Когда остается меньше, чем лимит сканирования, отправляемый лимит снижается до оставшегося значения; вызов, превышающий лимит, отклоняется. Пробные запуски (dry runs), кэшированные результаты и вызовы, завершающиеся с кодами выхода 2, 3, 4 или 6, не учитываются. Реальный вызов recognize_enterprise всегда требует лимита от 1 и выше, поэтому сначала вызывайте его с установленным в true параметром dry_run, чтобы увидеть оценку.

Другие команды для агентов

• audd agent-setup записывает инструкции, которые учат агента кодирования использовать audd: навык Claude Code (.claude/skills/audd/SKILL.md), правило Cursor (.cursor/rules/audd.mdc) или раздел audd в AGENTS.md. Без флага он записывает инструкции для каждого агента, найденного в проекте, или в AGENTS.md, если ничего не найдено. Флаги --claude, --cursor, --codex и --agents-md выбирают цели, а --print выводит текст вместо записи файлов. Повторный запуск обновляет файлы на месте.
• audd docs <topic> выводит документацию AudD в формате markdown: api, enterprise, streams, upload, mcp, sdks или cli. Тема cli работает офлайн. Без указания темы выводится их список.
• audd commands --json выводит каждую команду, флаг, структуру вывода и код выхода в формате JSON. Ярлыки, такие как audd logout, указывают команду, которую они запускают, в поле alias_of.
• audd api <method> key=value... вызывает любой метод API и выводит ответ с добавленным полем "schema_version": 1. Токен добавляется автоматически, а передача api_token= является ошибкой. Каждый вызов отправляется один раз и никогда не повторяется, а методы распознавания тарифицируются в обычном режиме. Код выхода соответствует статусу ответа.

Устранение неполадок

Почему audd возвращает "result": null?

Аудио не совпало ни с одной песней. Это не ошибка, и код выхода равен 0. Стандартная конечная точка анализирует только первые 12 секунд, поэтому попробуйте другой момент с помощью --at 1:00 или просканируйте весь файл с помощью --enterprise --limit N. Передайте --fail-on-no-match, если скрипт должен завершаться с кодом 1.

Почему --at завершается с ошибкой missing_tool?

Для работы --at clips и audd listen требуется ffmpeg (audd listen также может использовать sox), а образ Docker его не содержит. Возникает ошибка missing_tool (код выхода 2). Установите ffmpeg с помощью пакетного менеджера или выполните распознавание файла без --at.

Что означают quota_exceeded и rate_limited?

quota_exceeded (код выхода 4) означает, что в текущем платежном цикле у аккаунта не осталось запросов; audd usage показывает цифры, а audd billing plans переводит планы. rate_limited означает, что AudD получает слишком много запросов от токена. Пакет ожидает и повторяет попытку самостоятельно после HTTP 429 и останавливается при ошибке API 611; возобновите его позже с помощью audd jobs resume.

Почему audd streams watch завершается с ошибкой callback_url_required?

Результаты прямых трансляций поступают в audd только тогда, когда у аккаунта есть URL обратного вызова. Запустите audd streams callback set с вашим собственным URL или передайте --yes, чтобы установить заполнитель https://audd.tech/empty/, который принимает и отбрасывает обратные вызовы.

Почему --token test перестал работать?

Публичный тестовый токен позволяет выполнять 10 стандартных распознаваний в день, общих для всех, кто его использует, и не распространяется на корпоративные сканирования или потоки. Когда дневной лимит исчерпан, audd завершает работу с кодом 3, токеном token_rejected и ошибкой API 901. Получите собственный токен на dashboard.audd.io.

Как использовать audd за прокси?

audd учитывает переменные окружения HTTPS_PROXY и NO_PROXY. Сетевая ошибка (код выхода 5) говорит о том, что при использовании прокси стоит проверить HTTPS_PROXY.

Как посмотреть, что именно audd отправляет в AudD?

Добавьте --debug к любой команде. Она записывает каждый HTTP-запрос в stderr с удаленными токенами.

Почему при повторном запуске пакета возвращается код выхода 6 с сообщением resume_available?

Предыдущий запуск тех же файлов с теми же настройками не завершился. Передайте --resume для продолжения, --new для повторного распознавания каждого файла или выполните audd jobs resume с ID задания из подсказки.

Почему в плане пробного запуска (dry-run) значение requests равно null?

Корпоративное сканирование URL без --limit не имеет ограничения, так как длина URL неизвестна. В плане отображается "unbounded": true. Добавьте --limit N, чтобы ограничить каждый файл N фрагментами по 12 секунд.

• Идентификация музыки из командной строки
• Стандартный, корпоративный или потоковый режим: как выбрать
• Заметки агента: корпоративная конечная точка
• Заметки агента: потоки и длинный опрос
• Справочник CLI на docs.audd.io