Обнаружение сэмплов и повторного использования ваших собственных треков

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

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

Рабочий процесс из двух частей. Во-первых, этап загрузки (единоразовый или постоянный): ваши треки попадают в частную базу данных отпечатков вашей учетной записи через POST api.audd.io/upload/. Во-вторых, путь распознавания, который отправляет входящий контент через API и проверяет каждое совпадение, чтобы ответить на один вопрос: пришло ли это совпадение из моего частного каталога или из общедоступной базы данных на 160 миллионов песен?

Отличительным сигналом является поле audio_id. Совпадение из пользовательского каталога содержит audio_id (идентификатор трека, который вы загрузили), а его исполнитель и название могут быть null, поскольку частная мастер-запись не является публичным релизом с публичными тегами. Совпадение из общедоступной базы данных имеет заполненные поля исполнителя/названия и не имеет audio_id. Именно эта проверка отделяет «кто-то повторно использовал мой трек» от «кто-то использовал коммерческую песню» — последнее является рецептом сканера авторских прав, а не этим.

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

• API-токен с dashboard.audd.io.
• Доступ к загрузке в пользовательский каталог. Эндпоинт загрузки требует специального доступа для вашей учетной записи — напишите на [email protected], чтобы его включили. Распознавание по вашему каталогу работает с вашим обычным токеном после того, как треки были загружены.
• Python 3.10+ с официальным SDK: pip install audd
• Треки, которые вы хотите обнаруживать, в виде аудиофайлов (MP3, WAV, FLAC, M4A, OGG, AAC, WMA или AIFF).

Пошаговое руководство

Шаг 1: Загрузка ваших треков в пользовательский каталог

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

Для загрузки требуется специальный доступ к вашей учетной записи (напишите на [email protected] для включения), но сам вызов прост: вы отправляете каждый трек с целочисленным audio_id, который вы назначаете — ваш собственный ID трека — и AudD создает отпечаток под этим ID. ID вы выбираете сами; именно он будет возвращаться при каждом последующем распознавании, которое совпадает с этим треком. Сам ответ на загрузку не содержит полезной нагрузки ({"status": "success", "result": null}), поэтому считывать из него нечего — вы уже владеете ID, так как сами его установили.

custom_catalog.add(audio_id, source) принимает назначенный вами ID и трек (путь, URL или байты):

Пользовательский каталог является частным для вашей учетной записи. Треки, которые вы загружаете, могут быть сопоставлены только с вашего собственного токена. Они не добавляются в общедоступную базу данных на 160 миллионов песен, и другие учетные записи не могут выполнять распознавание по ним.

Пользовательский каталог является частным для вашей учетной записи. Треки, которые вы загружаете, могут быть сопоставлены только с вашего собственного токена. Они не добавляются в общедоступную базу данных на 160 миллионов песен, и другие учетные записи не могут выполнять распознавание по ним.

Поддерживайте собственное соответствие между audio_id и тем, что этот трек значит для вас (название релиза, внутренний ID, правообладатель). API хранит отпечаток и audio_id; бизнес-смысл остается на вашей стороне.

Шаг 2: Распознавание входящего контента

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

Для коротких клипов используйте стандартный эндпоинт. Для полных треков, диджейских сетов, видео или чего-либо произвольной длины используйте корпоративный эндпоинт (он разбивает контент на серверной стороне и возвращает по одному совпадению на каждый распознанный сегмент). Всегда устанавливайте limit для корпоративных вызовов во время разработки.

Стандартный вызов возвращает одно совпадение или None, если совпадений нет. Корпоративный вызов возвращает список (пустой, если совпадений нет). Ни один из них не вызывает ошибку при «ничего не распознано» — пустой результат или None является четким вердиктом, отличным от ошибки.

Шаг 3: Классификация каждого совпадения — ваше или публичное

Это основа рецепта. Для каждого совпадения проверьте audio_id. Если он установлен, совпадение пришло из вашего частного каталога; найдите его в вашей локальной карте. Если он отсутствует, это совпадение из общедоступной базы данных (коммерческая музыка), которое этот рецепт игнорирует.

audio_id — единственный надежный дискриминатор. Не ориентируйтесь на то, что исполнитель/название равны null — публичное совпадение также может иметь скудные теги. Наличие audio_id означает «это из вашего каталога».

Шаг 4: Подключение к обработчику загрузки

Собираем все вместе: принимайте входящий контент, распознавайте его и сообщайте, какие из ваших треков (если таковые имеются) он использует повторно.

reuses_my_catalog: true с заполненным списком my_matches — это ваш вердикт «этот контент содержит один из моих треков» — сэмпл, утечка неизданного мастера или прямой перезалив, в зависимости от того, что вы поместили в каталог и откуда пришел контент.

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

Совпадение из пользовательского каталога и публичное совпадение различаются именно теми полями, на которые вы ориентируетесь. Вот они оба, бок о бок, в том виде, в котором они появляются в результате:

В корпоративных ответах каждое совпадение дополнительно содержит start_offset и end_offset — секунды входящего контента, где совпадение начинается и заканчивается. Используйте их, чтобы указать, где именно в загрузке был повторно использован ваш трек; используйте тайм-код, чтобы узнать, какая часть вашего трека была взята.

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

Этот рабочий процесс имеет две различные области сбоев — загрузка (ingestion) и распознавание.

• Ошибки аутентификации (AudDAuthenticationError) — неверный или отсутствующий токен. Сбой при запуске.
• Ошибки подписки/доступа (AudDSubscriptionError) — эндпоинт загрузки не включен для вашего токена. Загрузка в пользовательский каталог требует специального доступа; напишите на [email protected]. Это проявляется при загрузке, а не при распознавании.
• Ошибки неверного аудио (AudDInvalidAudioError) — файл (будь то трек, который вы загружаете, или контент, который вы сканируете) не является декодируемым аудио/видео. Рассматривайте это как ошибку пользователя/ввода, а не ошибку сервера.
• Ошибки соединения (AudDConnectionError) — временные. Повторите попытку с экспоненциальной задержкой. Не повторяйте автоматически вызов загрузки вслепую — повторная загрузка может создать отпечаток одного и того же трека дважды и выдать вам два audio_id. Сделайте загрузку идемпотентной на своей стороне (отслеживайте, какие файлы вы уже загрузили).

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

• Чтение дополнительных полей помимо типизированных свойств результата: каждый результат и блок per-provider передают неизвестные поля через карту model_extra в Pydantic. Если ответ пользовательского каталога содержит метаданные, которые вам нужны, но которые не являются типизированным свойством, прочитайте их из model_extra.
• Чтобы обнаруживать коммерческую музыку в пользовательских загрузках (обратное этому рецепту — кто-то использует песню, которой вы не владеете), см. «Создание сканера авторских прав для пользовательского контента».
• Чтобы превратить подтвержденное совпадение в запрос на удаление, см. «Создание доказательств для удаления по DMCA».
• Мониторинг прямых трансляций для повторного использования вашего каталога (например, Twitch или радиоэфир, где воспроизводятся ваши треки) использует ту же классификацию audio_id в обратных вызовах потоков — см. конечные точки streams.
• Создайте сканер авторских прав для пользовательского контента
• Создание доказательств для удаления контента по DMCA
• Документация Python SDK
• Справочник по API