Аудиоформаты и качество для распознавания музыки

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

Краткая суть

• Стандартный эндпоинт (api.audd.io) принимает короткий аудиофрагмент (обычно достаточно нескольких секунд) и отвечает менее чем за 2 секунды. Размер файла должен составлять 10 МБ или менее.
• Поддерживаемые аудиоформаты: MP3, WAV, FLAC, M4A, OGG, AAC, WMA, AIFF.
• Для более длинных аудиозаписей (полных песен, подкастов, трансляций, диджейских сетов) или видео используйте корпоративный эндпоинт (enterprise.audd.io). Он принимает те же аудиоформаты, а также видео — MP4, AVI, MOV, MKV, WebM — и не имеет практических ограничений на размер файла.
• Алгоритм создания отпечатков устойчив к сжатию с потерями и фоновому шуму. Это не магия: очень короткий фрагмент или фрагмент, утопающий в шуме, может не совпасть.
• Отправляйте самые чистые несколько секунд, которые у вас есть. Вам не нужно повышать частоту дискретизации, конвертировать файл в формат без потерь или предварительно очищать его.

Почему это важно

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

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

Второе важное условие — выбор правильного эндпоинта. Стандартный эндпоинт рассчитан на короткий фрагмент и устанавливает ограничение в 10 МБ. Если вы попытаетесь отправить через него песню целиком или видеофайл, вы либо превысите лимит, либо отправите гораздо больше аудио, чем требуется для одного распознавания. Именно для этого предназначен корпоративный эндпоинт.

Поддерживаемые форматы

Аудио

И стандартный, и корпоративный эндпоинты поддерживают следующие аудиоформаты:

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

Видео (корпоративный эндпоинт)

Корпоративный эндпоинт дополнительно принимает видеофайлы и извлекает аудиодорожку на стороне сервера:

Именно поэтому корпоративный эндпоинт является подходящим инструментом для сканирования загруженных пользователем видео или коротких клипов: вы отправляете видео как есть и вам не нужно самостоятельно извлекать аудиодорожку (демультиплексировать). Видео отправляется на enterprise.audd.io, а не на стандартный эндпоинт.

Размер файла и ограничение в 10 МБ

Стандартный эндпоинт ограничивает каждый запрос до 10 МБ. Это лимит для фрагмента, а не для песни; он рассчитан на короткий отрезок, под который спроектирован стандартный эндпоинт, а не на полноценный трек.

Для короткого фрагмента это редкое ограничение. Если говорить о масштабах приблизительно, несколько секунд аудио в MP3 весят значительно меньше мегабайта; даже минута WAV-файла CD-качества весит всего несколько мегабайт. Вы упираетесь в лимит, когда пытаетесь отправить то, для чего стандартный эндпоинт не предназначен — песню целиком в виде несжатого WAV или видеофайл.

Когда у вас аудио больше, чем помещается в лимит, у вас есть два варианта:

• Обрежьте аудио до короткого фрагмента и отправьте его на стандартный эндпоинт. Несколько секунд из середины песни подойдут идеально.
• Используйте корпоративный эндпоинт, который не имеет практического ограничения по размеру файла, разбивает файл на блоки на стороне сервера и может возвращать совпадение по каждому распознанному сегменту. Выбирайте его, когда вам действительно нужно обработать весь файл целиком (подкаст, диджейский сет, длинную загрузку), а не идентифицировать одну песню по короткому отрывку.

Ограничение в 10 МБ — это лимит стандартного эндпоинта, а не корпоративного. Если длинный файл упирается в этот лимит, обычно это знак того, что вам нужен корпоративный эндпоинт, а не обрезка файла. Корпоративный эндпоинт тарифицирует каждые 12 секунд обработанного аудио, поэтому всегда устанавливайте параметр limit во время разработки.

Ограничение в 10 МБ — это лимит стандартного эндпоинта, а не корпоративного. Если длинный файл упирается в этот лимит, обычно это знак того, что вам нужен корпоративный эндпоинт, а не обрезка файла. Корпоративный эндпоинт тарифицирует каждые 12 секунд обработанного аудио, поэтому всегда устанавливайте параметр limit во время разработки.

Длина фрагмента

Для стандартного эндпоинта обычно достаточно нескольких секунд. Алгоритму сопоставления отпечатков нужно достаточное количество записи, чтобы за нее зацепиться, и короткий фрагмент чистого аудио обычно обеспечивает это.

Два практических момента:

• Очень короткие фрагменты могут не совпасть. Односекундный фрагмент может не содержать достаточно характерного сигнала, особенно если он приходится на тихое вступление, брейкдаун или часть, похожую на многие другие песни. Если в ответ на очень короткий фрагмент возвращается result: null, первое, что стоит попробовать — отправить чуть более длинный фрагмент.
• Больше — не всегда лучше на стандартном эндпоинте. Как только вы отправили достаточно аудио для идентификации песни, добавление новых данных не улучшит результат, а длинный фрагмент увеличивает риск превышения лимита в 10 МБ. Отправляйте характерные несколько секунд, а не весь трек целиком.

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

result: null означает «нет совпадения», а не «ошибка». На стандартном эндпоинте фрагмент, не давший совпадения, возвращает result: null со статусом успешного выполнения (success). Воспринимайте это как отдельный, ожидаемый результат (например, предложите пользователю записать более длинный или чистый фрагмент), а не как сбой.

result: null означает «нет совпадения», а не «ошибка». На стандартном эндпоинте фрагмент, не давший совпадения, возвращает result: null со статусом успешного выполнения (success). Воспринимайте это как отдельный, ожидаемый результат (например, предложите пользователю записать более длинный или чистый фрагмент), а не как сбой.

Частота дискретизации, каналы и сжатие

Это характеристики входных данных, о которых люди беспокоятся чаще всего. На практике ни одна из них не требует специальной обработки.

Частота дискретизации

Вам не нужно повышать частоту дискретизации (upsample). Записи с обычной частотой — с телефона, ноутбука и источников CD-качества — содержат достаточную часть частотного диапазона, на которую опирается отпечаток. Конвертация записи с низкой частотой в более высокую частоту дискретизации не добавит информации, которая не была записана изначально, поэтому это не спасет плохо записанный фрагмент. Отправляйте аудио с той частотой, с которой оно было записано.

Моно против стерео

Моно вполне подходит. Отпечаток не зависит от стереопанорамы, поэтому одноканальная запись с микрофона работает так же хорошо, как и стереофайл. Если ваш трафик захвата предоставляет моно (так делают большинство микрофонных входов), нет необходимости искусственно создавать второй канал.

Сжатие с потерями

Форматы с потерями — MP3, AAC, M4A, OGG, WMA — полностью поддерживаются и являются стандартным случаем. Отпечаток (fingerprint) строится таким образом, чтобы быть устойчивым к артефактам, вносимым кодеками с потерями. Вам не нужно конвертировать файл в формат без потерь перед отправкой; перекодирование файла с потерями в FLAC или WAV не восстановит детали, отброшенные при исходном кодировании, а лишь увеличит размер файла.

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

Фоновый шум

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

Пример работы

Две распространенные ситуации: запись с микрофона в реальном времени и файл, который уже есть на диске.

Подготовка записи с микрофона

Вы записываете несколько секунд с микрофона — телефона, микрофона ноутбука, USB-входа — и отправляете их на стандартную конечную точку (endpoint).

• Записывайте несколько секунд, а не одну. Стремитесь к короткому фрагменту с четким музыкальным содержанием, а не к максимально короткому отрывку. Если первая попытка возвращает result: null, запишите чуть более длинный фрагмент, прежде чем делать вывод, что песни нет в базе данных.
• Не боритесь с форматом. Моно — это нормально, родная частота дискретизации устройства — это нормально, и сжатый формат (M4A, AAC, MP3) — это тоже нормально. Сэкономьте время на конвертации.
• Выбирайте чистый момент. Записывайте, когда музыка звучит четко, а не во время паузы или внезапного всплеска шума толпы.
• Отправляйте. Несколько секунд типичного аудио с микрофона значительно меньше лимита в 10 МБ, поэтому стандартная конечная точка — это правильный выбор.

Подготовка загрузки файла

У вас есть аудиофайл на диске, и вы хотите его идентифицировать.

• Если это короткий фрагмент размером менее 10 МБ, отправьте его на стандартную конечную точку «как есть», в том формате, в котором он находится. result = audd.recognize("https://audd.tech/example.mp3") print(result.title if result else "No match")

Если это короткий фрагмент размером менее 10 МБ, отправьте его на стандартную конечную точку «как есть», в том формате, в котором он находится.

• Если это полноценная песня, подкаст, трансляция или видео — или если файл весит более 10 МБ — отправляйте его на корпоративную (enterprise) конечную точку. Она разбивает файл на части на стороне сервера и может возвращать совпадение для каждого распознанного сегмента. Установите limit во время разработки, чтобы длинный файл не обрабатывал больше аудио, чем вы планировали. matches = audd.recognize_enterprise( "full-episode.mp3", limit=10, # ограничение платных чанков при разработке — enterprise тарифицируется по 12-секундным отрезкам ) for m in matches: print(f"{m.timecode} {m.artist} — {m.title}")

Если это полноценная песня, подкаст, трансляция или видео — или если файл весит более 10 МБ — отправляйте его на корпоративную (enterprise) конечную точку. Она разбивает файл на части на стороне сервера и может возвращать совпадение для каждого распознанного сегмента. Установите limit во время разработки, чтобы длинный файл не обрабатывал больше аудио, чем вы планировали.

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

Распространенные ошибки

• Отправка целой песни на стандартную конечную точку. Полный трек в несжатом формате WAV часто превышает 10 МБ, и даже если он проходит по размеру, вы отправляете гораздо больше данных, чем нужно для распознавания. Обрежьте файл до нескольких секунд или используйте корпоративную конечную точку.
• Апсемплинг или конвертация в формат без потерь «для точности». Конвертация записи с телефона в более высокую частоту дискретизации или файла с потерями в FLAC увеличивает размер файла, не добавляя информации. Отправляйте аудио в том виде, в котором оно было записано.
• Отправка односекундного фрагмента и восприятие result: null как окончательного вердикта «отсутствует в базе данных». Очень короткий фрагмент может просто не содержать достаточно сигнала. Попробуйте более длинный фрагмент, прежде чем делать вывод, что песня неизвестна.
• Восприятие result: null как ошибки. На стандартной конечной точке отсутствие совпадения — это успешный ответ с result: null, что отличается от статуса ошибки. Обрабатывайте эти два случая раздельно.
• Использование стандартной конечной точки для видео. Видеоформаты принимаются только на корпоративной конечной точке, которая сама извлекает из них аудио.
• Агрессивная предварительная обработка. Сильное шумоподавление или перекодирование с низким битрейтом могут удалить детали, на которые опирается отпечаток. Если у вас есть более чистый исходник, отдайте предпочтение ему, а не сильно обработанной копии.
• Стандартная, корпоративная или потоки: как выбрать
• Создание функции «что играет» в стиле Shazam
• Документация SDK
• Справочник API