VK music covers (Mashup DB)

Загрузка обложек треков из постов сообществ ВКонтакте и встраивание их в теги локальных аудиофайлов.

Мэшап-паблики публикуют посты вида «аудио + фото», где фотография и есть обложка трека. Этот инструмент собирает такие пары (артист, название, обложка) со стены группы через VK API, а затем сопоставляет их с вашей локальной музыкальной библиотекой и вшивает обложки в теги — MP3, FLAC, M4A и OGG.

Работает на ПК (Windows/Linux/macOS) и на Android через Termux.

Возможности

• Парсинг всей стены сообщества (wall.get), включая неструктурированные посты — fallback-парсинг текста по шаблону Артист - Название
• Поддержка нескольких сообществ — каждый запуск создаёт отдельный JSON-файл, ничего не перезаписывая
• Сопоставление файлов с обложками: точное совпадение по artist + title, по title, затем fuzzy-matching через rapidfuzz

• Пропуск файлов с уже встроенной обложкой (или принудительная замена)
• Локальный кэш скачанных обложек — повторные запуски не зависят от сети
• CSV-лог по каждому файлу: статус, способ совпадения, источник обложки

Требования

• Python 3.8+
• [Только для шага 1] Токен VK API с правом доступа к wall (пользовательский или групповой)

Установка

pip install -r requirements.txt

Шаг 1. Парсинг группы

Note

В репозитории уже присутствуют пропарсенные основные группы от 29 июля 2026 года.

Скопируйте .env.example в .env и заполните:

VK_TOKEN=ваш_токен
GROUP_DOMAIN=mashup.hk

Как получить токен: создайте Standalone-приложение на vk.com/apps?act=manage и откройте в браузере ссылку авторизации со скоупом wall,offline, либо простым способом тут через авторизацию через существующее приложение. После входа токен появится в адресной строке — скопируйте его в .env.

python vk_parsing.py

Скрипт обойдёт всю стену указанной группы и сохранит пары «трек → обложка» в output/vk_covers_<group>.json. Каждый следующий запуск создаёт новый файл с номером (vk_covers_<group>_2.json, _3.json и т.д.).

Чтобы добавить ещё одно сообщество, поменяйте GROUP_DOMAIN в .env и запустите снова — например, поочерёдно mashup.hk, alt_shitpost, chilish. Все файлы автоматически подхватятся на следующем шаге.

Шаг 2. Встраивание обложек в метаданные

python apply_covers.py /path/to/music

Скрипт объединяет все найденные vk_covers*.json, обходит указанную папку (рекурсивно) и вшивает обложки в теги файлов.

Полезные параметры

# Строже подбор совпадений (порог fuzzy-соответствия 0-100, по умолчанию 85)
python apply_covers.py /path/to/music --min-score 90

# Заменить обложки, которые уже вшиты
python apply_covers.py /path/to/music --replace-existing

Про порог совпадения: 80-85 — обычный режим, 90+ — почти только точные совпадения. Если по логу видно, что валидные треки уходят в no_match — снижайте, если вшивается чужая обложка — повышайте.

Результат

После запуска в output/cover_apply_log.csv появится лог со статусами:

Статус	Значение
applied	Обложка встроена
skipped_existing	Обложка уже была (пропущено)
no_match	Не найдено совпадение в JSON
download_or_embed_error	Ошибка скачивания или записи

Скачанные обложки кэшируются в output/cover_cache/ — при повторном запуске скрипт не будет обращаться к сети за уже скачанными картинками.

Запуск на Android (Termux)

pkg update -y && pkg install python -y
pip install -r requirements.txt
termux-setup-storage
exit  # перезапустить Termux для доступа к хранилищу

Затем скопируйте проект в /storage/emulated/0/Music/vkpars/, заполните .env и запускайте скрипты как обычно:

python vk_parsing.py
python apply_covers.py /storage/emulated/0/Music