Создание музыкальных титров для эпизода подкаста

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

Что вы создадите

Скрипт, который отправляет эпизод подкаста на корпоративную конечную точку AudD, проходит по возвращенным совпадениям, объединяет последовательности одной и той же песни в один кредит с временным диапазоном и выводит чистый блок титров.

Корпоративная конечная точка — это правильный инструмент здесь (а не стандартная конечная точка): эпизод имеет произвольную длину, и вам нужны все песни в нем, а не одна. recognize_enterprise возвращает плоский список list[EnterpriseMatch] — по одной записи на каждый распознанный фрагмент, в хронологическом порядке — и каждое совпадение несет свою позицию в вашем эпизоде непосредственно как start_seconds / end_seconds. Двухминутная финальная песня охватывает несколько последовательных совпадений, поэтому вы получите несколько почти идентичных записей для нее; шаг дедупликации превращает их обратно в одну строку, которая гласит «использовано с 48:00 по 50:00».

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

Предварительные требования

• API-токен с dashboard.audd.io. Получите свой собственный токен там; корпоративная конечная точка должна быть включена для него. Лейбл возвращается в корпоративных ответах; 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; именно это повторение и устраняет Шаг 3.

Всегда устанавливайте limit во время разработки. Корпоративная конечная точка тарифицируется за каждые 12 секунд обработанного аудио. 90-минутный эпизод — это сотни фрагментов; неограниченный вызов учитывает их все. Разрабатывайте с limit=20, подтвердите логику титров и только потом увеличивайте лимит для полного прохода.

Всегда устанавливайте limit во время разработки. Корпоративная конечная точка тарифицируется за каждые 12 секунд обработанного аудио. 90-минутный эпизод — это сотни фрагментов; неограниченный вызов учитывает их все. Разрабатывайте с limit=20, подтвердите логику титров и только потом увеличивайте лимит для полного прохода.

Шаг 2: Понимание полей времени

Перед дедупликацией разберитесь с полями времени — их легко перепутать, и блок титров зависит от использования правильного.

• start_seconds / end_seconds — где эта песня играет в вашем эпизоде, в секундах (например, с 64.2 по 71.6). Это значения, которые вы помещаете в примечания к шоу; фрагмент, который пришел без пригодной позиции, имеет здесь None.
• start_offset / end_offset — необработанные миллисекунды внутри внутреннего 12-секундного фрагмента сканирования AudD, из которых выводятся секунды. Это не секунды эпизода, и они редко нужны.
• timecode — позиция внутри сопоставленной песни, где фрагмент совпал (например, 00:41 означает, что фрагмент совпал на 41-й секунде той песни). Полезно для понимания того, какая часть песни была использована, но это не позиция в вашем эпизоде.

Все нижеперечисленное зависит от start_seconds и end_seconds.

Шаг 3: Объединение последовательных совпадений в один кредит

Правило дедупликации: проходите по совпадениям в хронологическом порядке; всякий раз, когда текущее совпадение имеет того же исполнителя и название, что и кредит, который вы сейчас создаете, продлевайте время окончания этого кредита вместо начала нового. Новый исполнитель/название начинают новый кредит.

Результат — одна запись на каждую отдельную песню в порядке ее первого появления с указанием занятого ею диапазона. SDK анализирует ответы гибко — любое поле может отсутствовать или быть None — отсюда проверка start_seconds и резервный вариант end_seconds, которые не дают фрагменту без позиции вызвать сбой.

Песня, которая повторяется, получает два кредита, и это сделано намеренно. Если одна и та же тема звучит в начале и снова в конце, два несмежных прогона создают два кредита. Обычно это именно то, что нужно в примечаниях к шоу — «использовано в 00:00 и снова в 48:00». Если вы предпочитаете объединить все появления песни в одну строку, сгруппируйте готовые кредиты по (исполнителю, названию) после этого.

Песня, которая повторяется, получает два кредита, и это сделано намеренно. Если одна и та же тема звучит в начале и снова в конце, два несмежных прогона создают два кредита. Обычно это именно то, что нужно в примечаниях к шоу — «использовано в 00:00 и снова в 48:00». Если вы предпочитаете объединить все появления песни в одну строку, сгруппируйте готовые кредиты по (исполнителю, названию) после этого.

Шаг 4: Отрисовка блока титров

Отформатируйте каждый кредит как диапазон временных меток плюс исполнитель, название и лейбл.

Это выводит блок вроде:

Песни, которые звучали только на фоне нескольких секунд речи, сворачиваются в короткий промежуток; трек полного сегмента сворачивается в свое реальное время звучания. В любом случае вы получаете одну строку на песню.

Шаг 5: Пропуск холодного вступления, выборка длинных фоновых треков

Два параметра позволяют снизить стоимость и шум в реальных эпизодах. Передайте их как аргументы ключевых слов в recognize_enterprise:

• skip_first_seconds начинает распознавание с середины — удобно, если каждый эпизод открывается одной и той же динамически вставленной рекламой, которую вы не хотите указывать в титрах.
• every и skip выполняют выборку файла: every=1, skip=4 распознает один фрагмент, затем пропускает следующие четыре (одно совпадение в минуту). Для титров обычно требуется полное покрытие, чтобы не пропустить короткий джингл, но для грубого прохода «какая музыка здесь есть» выборка сокращает количество тарифицируемых фрагментов в несколько раз.

Примечание: skip_first_seconds нельзя комбинировать с use_timecode; используйте что-то одно.

Что вы получаете в ответ

Каждая запись в возвращенном списке — это один распознанный фрагмент в хронологическом порядке. Поля, которые важны для списка титров:

Для примера файла совпадение может вернуться с start_seconds = 0.0, end_seconds = 57.0, artist = "Tears For Fears", title = "Everybody Wants To Rule The World" и label = "UMC (Universal Music Catalogue)" — что отображается как одна строка кредита выше.

Обработка ошибок

SDK вызывает типизированные исключения; перехватывайте те, на которые можете отреагировать.

• Ошибки аутентификации (AudDAuthenticationError) — неверный или отсутствующий токен. Завершайте работу при запуске, а не на каждом эпизоде.
• Ошибки квоты / подписки (AudDSubscriptionError) — вы достигли лимита запросов или корпоративная конечная точка не включена для вашего токена. Корпоративная конечная точка и ISRC/UPC зависят от уровня плана; сообщайте об этом владельцу учетной записи, а не пытайтесь повторить запрос.
• Ошибки Invalid-audio — URL или файл не содержали декодируемого аудио. Рассматривайте это как случай некорректного ввода: сообщите, какой эпизод вызвал сбой, и продолжайте работу.
• Ошибки соединения (AudDConnectionError) — временные; повторите попытку с использованием экспоненциальной задержки.

Чистый фрагмент без музыки не является ошибкой — такие фрагменты просто не дают совпадений, поэтому они не добавляют титры.

Дальнейшие шаги

• Сохраняйте готовые титры, привязывая их к ID эпизода, чтобы никогда не сканировать их повторно (повторное сканирование снова расходует лимиты на каждый фрагмент).
• Если ваше шоу всегда начинается и заканчивается одной и той же музыкальной темой, выполните постобработку титров, чтобы объединить не соседствующие друг с другом блоки с одинаковыми (исполнитель, название) в одну строку.
• Нужно распознать архив эпизодов? Ознакомьтесь с разделом «Оптимизация затрат для Enterprise», чтобы узнать, как параметры every, skip и limit влияют на соотношение охвата и количества тарифицируемых фрагментов.
• Хотите превратить DJ-сет или непрерывный микс в треклист вместо блока титров? См. «Превращение DJ-сета или микса в треклист».
• Создание музыкального cue-листа из видео, трансляции или записи занятия
• Превращение DJ-сета или микса в треклист
• Оптимизация затрат для Enterprise
• Standard, enterprise или потоки: как сделать выбор
• Документация Python SDK
• Справочник API