Один интерфейс для всего музыкального веба
Музыкальный веб раздроблен по множеству независимых сайтов. Bandcamp продаёт вам FLAC и лицензию Creative Commons; SoundCloud транслирует ремикс, которого больше нигде нет; SomaFM держит набор радиоканалов, поддерживаемых слушателями; а ряд сайтов, ведомых сообществом, поддерживает курируемые энциклопедии прогрессивного рока, джаза, классики и метала. У каждого сайта своя разметка, свои причуды, своё представление о том, что вообще такое «трек».
Мы сопровождаем семейство небольших, узкоспециализированных Python-клиентов с открытым исходным кодом, которые укрощают этот хаос. По сути каждый из них делает одно и то же: обращается к музыкальному источнику и возвращает вам типизированные модели метаданных медиа — проверенные объекты вместо хрупких словарей — так что остальной вашей коде никогда не приходится задумываться, с какого сайта пришли данные. Семь из девяти опубликованы на PyPI; остальные два устанавливаются прямо с GitHub. Все они говорят на одном языке.
Вот наш обзор.
Стриминг и радио
py_bandcamp скрейпит Bandcamp: ищет треки, альбомы, исполнителей и лейблы; просматривает по жанровому тегу; извлекает рекомендации и связанных исполнителей из отправной точки; и получает URL воспроизводимого MP3. Поиск возвращает типизированные объекты Release, несущие название, обложку, жанры, кредиты и — что критически важно для приверженцев FOSS — поле лицензии в стиле SPDX с проверкой is_open(), так что вы можете отличить релиз под Creative Commons от релиза со всеми правами защищены. Полноценное преобразование альбома по запросу заполняет упорядоченный трек-лист.
nuvem_de_som — это наш клиент для SoundCloud, и он швейцарский нож всей компании. Три независимых бэкенда — насыщенный метаданными API-бэкенд, HTML-скрейпер без зависимостей и бэкенд на yt-dlp — работают за одним оркестратором, который плавно переключается с одного на следующий. Он ищет треки и людей, разрешает прямые URL потоков (progressive или HLS), скачивает треки и целые плейлисты и даже поставляет терминальное приложение nds для поиска и воспроизведения из командной строки. Релизы возвращаются с кодеком, битрейтом, жанрами, страной, лицензией SPDX и полными трек-листами наборов.
radiosoma оборачивает публичный API каналов SomaFM. SomaFM — это дружелюбный, открытый конец спектра, и клиент моделирует его чисто: каждый канал — это одна единица работы, а каждая кодировка потока — 130 кбит/с AAC, 256 кбит/с MP3, 64 и 32 кбит/с HE-AAC — становится собственным Release этого канала, так что потребитель может выбрать наилучший вариант и дедуплицировать по идентичности. Лента недавних треков всплывает как аккуратное расписание того, что играло.
tunein — неофициальный клиент TuneIn для мировых линейных радио- и IPTV-станций. Быстрый путь возвращает только полезную нагрузку поиска; опциональный вызов обогащения заполняет жанр, язык, страну, позывной и слоган. Поскольку TuneIn возвращает несколько URL потоков на станцию — разные битрейты, зеркала и протоколы — каждый становится собственным Release, снова позволяя потребителю выбрать в момент воспроизведения. Небольшой CLI выдаёт вывод в виде таблицы или JSON.
pyheartradio работает с публичным API iHeartRadio — без ключа, без аккаунта. Ищет станции, подкасты, исполнителей, треки и плейлисты; получает эпизоды подкастов с прямыми URL аудиопотоков; и полагается на параллельные запросы деталей, так что поиск станций и исполнителей выполняется одновременно. Каждая модель предлагает вспомогательные методы to_external_ids() и to_signals() для прямой встройки в типизированный конвейер метаданных.
Музыкальные энциклопедии и архивы
Вторая половина семейства нацелена на великие сообщественные каталоги.
pyprogarchives (Prog Archives), pyjazzmusicarchives (Jazz Music Archives) — оба устанавливаются прямо из своих репозиториев на GitHub, а не с PyPI — и pyclassicalarchives (Classical Archives) имеют почти идентичную форму: просмотр указателя от A до Я, поиск по имени и получение полной страницы исполнителя или композитора с биографией, страной и дискографией с оценками участников. Prog и Jazz Archives скрейпят HTML; Classical Archives оборачивает публичный JSON API и раскрывает альбомы композитора и рекурсивно развёрнутое дерево произведений. Каждая модель несёт стабильный канонический id сайта через to_external_ids_dict(), что как раз и нужно, чтобы сопоставить один каталог с другим.
pymetal — наш клиент для Encyclopaedia Metallum, Metal Archives — и самый амбициозный из набора. Большинство скрейперов сводит трек к (id, title, band, album). pymetal отказывается терять то, что Metal Archives хранит по отдельности: трек может кредитовать несколько групп (сплиты, коллаборации), состав группы нарезан по времени, а трек может появляться на многих релизах (сборники, переиздания, синглы). Он моделирует каждое как полноправную сущность с ключом по archive id, так что повторные скрейпы идемпотентны. Поверхность эндпоинтов широка — расширенный поиск групп/альбомов/песен, полные страницы релизов с атрибуцией по группам на сплитах, составы, разбитые по статусу с диапазонами дат ролей, рецензии, рекомендации, внешние ссылки и тексты песен — всё как Pydantic v2 модели, совершающие круговой обход через JSON.
Помимо музыки, tutubo скрейпит YouTube и YouTube Music, а pymal охватывает MyAnimeList — распространяя те же типизированные паттерны метаданных на более широкие категории медиа. Все они выдают один и тот же словарь, так что один нисходящий потребитель обрабатывает всё единообразно.
Создано для совместимого, низкообъёмного доступа
Эти клиенты запрашивают только публичные страницы каталогов, с низким объёмом запросов, и проверяют robots.txt каждого сайта перед скрейпингом — о том, как работает этот этап разведки, см.
статью про robots.txt и карты сайта.
По всему семейству HTTP-слой подключаемый: по умолчанию клиенты используют транспорт, чьё TLS-рукопожатие совпадает с реальным браузером (curl_cffi, совпадающий с TLS/JA3 Chrome), так что корректно ведущий себя клиент не классифицируется системами обнаружения, настроенными на скриптовые злоупотребления, как вредоносная автоматизация. Энциклопедии за Cloudflare могут дополнительно маршрутизироваться через инстанс FlareSolverr для живых данных или читать из Wayback Machine Интернет-архива как запасной вариант. Слой парсинга намеренно независим от того, как приходит HTML, так что один и тот же код работает независимо от выбранного вами транспорта.
Кросс-источниковый музыкальный каталог
Настоящая отдача наступает, когда вы перестаёте думать о них как о девяти отдельных инструментах. Поскольку все они выдают один и тот же типизированный словарь метаданных и раскрывают канонические внешние id, вы можете развернуть одного исполнителя по Bandcamp, SoundCloud, радиокаталогам и энциклопедиям, а затем свернуть результаты в один связный каталог — дедуплицированный по идентичности, знающий о лицензиях и готовый питать движок рекомендаций, медиасервер или исследовательский датасет.
Каждый из этих клиентов — свободное ПО, самостоятельно размещаемое и работающее на вашем собственном оборудовании, без необходимости в каком-либо ключе API. Выберите интересующий вас источник: выполните pip install, если он на PyPI, либо pip install git+https://github.com/TigreGotico/<repo> для pyprogarchives и pyjazzmusicarchives, которые доступны только через GitHub, — и начинайте строить.
Все скрейперы работают на наших компонуемых, готовых к работе сессиях requests. Клиенты стриминга и радио выдают схему mediavocab напрямую, и каждый клиент раскрывает канонические внешние id, так что музыкальные метаданные интегрируются с media-archivist — нашим кросс-источниковым индексатором и дедуплицирующим сервером метаданных.