Записанный DJ-сет или непрерывный микс представляет собой один длинный файл с десятками треков, сведенных по ритму и переходящих друг в друга. Этот рецепт отправляет такой файл на корпоративную точку доступа AudD и выдает треклист с временными метками — такой, какой вы бы опубликовали на форуме или на сайте вроде 1001Tracklists, где каждый трек указан в момент его вступления.
Что вы создадите
Скрипт, который распознает микс, считывает совпадения и форматирует каждый отдельный трек в виде «ЧЧ:ММ:СС Исполнитель — Название». Вы также разберетесь с тем, что делает миксы сложнее альбомов: треки накладываются друг на друга. Во время перехода у уходящего и входящего треков снимаются отпечатки, поэтому сервер может сопоставить две разные песни в один и тот же момент. В этом рецепте показано, как представить такие наложения (бленды), а не отбрасывать одну из сторон.
Каждая строка треклиста привязана к моменту вступления трека, и SDK предоставляет этот момент напрямую: recognize_enterprise возвращает плоский список list[EnterpriseMatch], и каждое совпадение содержит start_seconds / end_seconds — свою позицию в вашем миксе в абсолютных секундах файла. Запрос по умолчанию запрашивает точные смещения, поэтому эти позиции точны; не нужно производить вычисления со смещением чанков.
Для разового треклиста код не нужен. Интерфейс командной строки AudD выводит его сам: audd recognize set.mp3 --enterprise --limit none --tracklist. Создайте версию, приведенную ниже, если треклисты являются частью вашего собственного продукта.
Для разового треклиста код не нужен. Интерфейс командной строки AudD выводит его сам: audd recognize set.mp3 --enterprise --limit none --tracklist. Создайте версию, приведенную ниже, если треклисты являются частью вашего собственного продукта.
Предварительные требования
- API-токен с сайта dashboard.audd.io. Получите собственный токен там; для него должна быть включена корпоративная точка доступа (enterprise endpoint). В корпоративных ответах возвращаются поля label, isrc и upc (для ISRC/UPC требуется тарифный план Startup или выше) — это полезно, если вы хотите обогатить треклист, но не обязательно для базового варианта.
- Python 3.10+ с установленным SDK: pip install audd
- Файл микса или URL. https://audd.tech/example.mp3 — это общедоступный файл, на котором можно протестировать весь процесс от начала до конца.
Пошаговое руководство
Шаг 1: Распознайте микс
Передайте микс в recognize_enterprise в виде URL, байтов файла или пути. Какой бы длины ни был сет, вы получите плоский список list[EnterpriseMatch]: по одной записи на каждый распознанный фрагмент в хронологическом порядке, каждая с точными значениями start_seconds / end_seconds (точные смещения запрашиваются по умолчанию).
Когда вы запустите это, вы увидите по одной строке на каждое совпадение в хронологическом порядке. Трек, который играет три минуты, отображается как серия последовательных совпадений с указанием одной и той же песни; переходы отображаются либо как соседние совпадения, переключающиеся с одной песни на другую, либо — во время кроссфейда — как два совпадения с одинаковым значением start_seconds, поскольку сервер сопоставил оба трека в один и тот же момент микса.
Всегда устанавливайте limit во время разработки. Корпоративная точка доступа тарифицирует каждые 12 секунд обработанного аудио. 60-минутный микс состоит из сотен фрагментов; безлимитный вызов тарифицирует их все. Запускайте с параметром limit=25, пока ваше форматирование и обработка переходов не будут настроены правильно, а затем увеличьте лимит для полного микса.
Всегда устанавливайте limit во время разработки. Корпоративная точка доступа тарифицирует каждые 12 секунд обработанного аудио. 60-минутный микс состоит из сотен фрагментов; безлимитный вызов тарифицирует их все. Запускайте с параметром limit=25, пока ваше форматирование и обработка переходов не будут настроены правильно, а затем увеличьте лимит для полного микса.
Шаг 2: Выберите правильное поле времени
Вся суть продукта здесь заключается во временных метках, поэтому четко разграничивайте поля. Каждый EnterpriseMatch содержит три вида позиций:
- start_seconds / end_seconds — время звучания этого трека в вашем миксе в секундах (например, 288.0). Это значение используется для позиционирования трека. Оно имеет значение None только тогда, когда фрагмент поступил без пригодной для использования позиции.
- start_offset / end_offset — исходные смещения, из которых получены секунды: миллисекунды в рамках внутреннего 12-секундного фрагмента сканирования AudD, а не секунды файла. Они редко вам понадобятся.
- timecode — позиция внутри сопоставленного трека, а не вашего микса. Она указывает, какая часть песни играла; никогда не используйте ее для размещения трека.
Размещайте треки по значению start_seconds, а не timecode. start_seconds — это позиция в вашем файле; таймкод песни — это позиция внутри собственной записи этой песни. Их путаница приведет к тому, что каждый трек окажется в неверное время.
Размещайте треки по значению start_seconds, а не timecode. start_seconds — это позиция в вашем файле; таймкод песни — это позиция внутри собственной записи этой песни. Их путаница приведет к тому, что каждый трек окажется в неверное время.
Шаг 3: Отформатируйте позицию в формат ЧЧ:ММ:СС
Для треклиста требуется время в часах, а не сырые секунды. Отформатируйте его:
Это всегда дает формат ЧЧ:ММ:СС с ведущими нулями, который аккуратно сортируется и выравнивается в треклисте даже для сетов, длящихся больше часа.
Шаг 4: Сверните непрерывный трек, но сохраните переходы
Для одного трека вы получаете множество последовательных совпадений, ссылающихся на него. Сверните их в одну запись треклиста, привязанную к первому совпадению, в котором появляется трек. Но когда трек меняется от одного совпадения к другому — это настоящий переход, а не шум, и каждый новый трек получает собственную строку.
Правило: новая пара (artist, title) создает новую запись; та же самая пара (artist, title), что и у расширяемой в данный момент записи, — нет.
Любое поле совпадения может вернуться пустым или равным None (SDK обрабатывает ответы снисходительно), для чего и нужна проверка start_seconds: фрагмент без позиции пропускается, а не приводит к аварийному завершению сканирования.
Это выводит треклист в следующем виде:
Привязка каждого трека к его первому совпадению — это то, что нужно для треклиста: указанное время соответствует моменту вступления трека, даже если он продолжает звучать на протяжении нескольких последующих совпадений.
Шаг 5: Представьте совмещенные переходы (бленды)
В реальном миксе два трека делят эфирное время во время кроссфейда. Сервер может сопоставить оба трека в один и тот же ~12-секундный момент микса, и SDK возвращает их как два отдельных совпадения в плоском списке с одинаковым значением start_seconds, поскольку они исходят из одной и той же точки файла. Это общее время начала является сигналом для бленда: доминирующий трек и тот, который вливается или затухает, привязаны к одному и тому же мгновению. Логика Шага 4 сохраняет только первый трек в каждой новой позиции, поэтому отображается более чистая склейка. Если вы хотите использовать маркер наложения в стиле 1001Tracklists, ищите совпадения с одинаковым значением start_seconds.
Вы можете отобразить их в виде строки с w/ (совместно с), как это делают сайты треклистов при указании блендов:
Разумный порог уверенности (здесь score >= 50) исключает слабые, случайные совпадения из переходов. Повысьте его, если ваш микс выдает ложные строки «w/»; понизьте, если известный бленд не отображается. Проверка (b.score or 0) обрабатывает совпадение, у которого оценка вернулась как None.
Представление блендов здесь и представление треклиста из Шага 4 считывают одни и те же совпадения за один вызов распознавания — вы не платите дважды. Оба они получаются из плоского списка: треклист обходит его по порядку, а бленд — это просто случай, когда два совпадения приходятся на одно и то же значение start_seconds.
Шаг 6: Выборочное сканирование длинного сета, когда вам не нужен каждый трек
Для быстрого создания «приблизительного треклиста» многочасового сета используйте выборочное сканирование вместо распознавания каждого фрагмента. Передайте параметры выборки в тот же вызов:
every=1, skip=3 означает один фрагмент в минуту, примерно четверть аудио. Большинство треков в сете длятся дольше минуты, поэтому вы все равно их уловите, но короткие правки и быстрые даблы могут проскочить мимо. Используйте полный проход (без пропуска, с более высоким лимитом), если хотите, чтобы каждый трек был размещен точно.
Что вы получаете в ответ
recognize_enterprise возвращает плоский список list[EnterpriseMatch], по одному на каждый распознанный фрагмент в хронологическом порядке. Поля, которые вы здесь используете:
Общее значение start_seconds — это то, что делает возможной обработку миксов: два трека, играющие в один и тот же момент микса, возвращаются как два совпадения, привязанные к одной и той же позиции в файле, и вам не нужно сопоставлять их самостоятельно.
Обработка ошибок
SDK вызывает типизированные исключения; перехватывайте те, на которые вы можете отреагировать.
- Ошибки аутентификации (AudDAuthenticationError) — неверный или отсутствующий токен. Завершайте работу при запуске.
- Ошибки квоты / подписки (AudDSubscriptionError) — достигнут лимит запросов или корпоративная конечная точка не включена для вашего токена. Корпоративная конечная точка и ISRC/UPC зависят от тарифного плана; сообщайте об этом владельцу аккаунта, а не пытайтесь повторить запрос.
- Ошибки недопустимого аудио — URL-адрес микса или файл не удалось декодировать. Рассматривайте это как критический сбой для данного источника, а не как пустой треклист.
- Ошибки соединения (AudDConnectionError) — временные; повторите попытку с экспоненциальной задержкой.
Тихие вступления, эмбиент-брейкдауны или трек, которого нет в базе данных из 160 миллионов песен, просто не дадут совпадений для этого отрезка — это пропуск в треклисте, а не ошибка.
Дальнейшие шаги
- Сохраняйте треклист с ключом по ID микса; повторный запуск пересчитывает каждый фрагмент.
- Хотите создать список музыкальных титров для подкаста, где нужен один титр на песню с указанием временного диапазона? См. Создание музыкальных титров для эпизода подкаста.
- Для многочасовых сетов см. Оптимизация корпоративных затрат при выборе баланса между покрытием every/skip и измеренными фрагментами.
- Создание музыкальных титров для эпизода подкаста
- Оптимизация корпоративных затрат
- Standard, enterprise или streams: как выбрать
- Документация Python SDK
- Справочник API
