Универсальная кроссплатформенная экосистема скробблинга, музыкальной аналитики, геймификации и синхронного прослушивания.
-000000?style=for-the-badge&logo=next.js&logoColor=white){kind=icon}
VEIN Music — это современная, независимая платформа нового поколения для любителей музыки, совмещающая точный сбор прослушиваний из любых источников, продвинутую интерактивную аналитику, социальные взаимодействия, элементы RPG-геймификации, нативный десктопный клиент с Discord RPC и открытую платформу для разработчиков.
- Браузерное расширение (Chrome Manifest V3):
- Прямой перехват метаданных и прогресса воспроизведения на вкладках: Яндекс Музыка, Spotify, VK Музыка, YouTube Music, Apple Music, SoundCloud.
- Оффлайн-буферизация: при потере интернет-соединения прослушивания сохраняются в локальное хранилище и автоматически отправляются на сервер через
chrome.alarmsи событиеnavigator.onLine.
- Нативный десктопный клиент (
desktop_client/):- Автономное приложение для Windows (через Windows SMTC API) и Linux (через MPRIS и сканирование заголовков окон).
- Поддержка нативных плееров: Spotify Desktop, AIMP, foobar2000, VLC, VK Desktop, Яндекс Музыка Desktop.
- Discord Rich Presence (RPC) в реальном времени с отображением обложки альбома, названия трека, артиста и синхронизированного таймера.
- Локальная отказоустойчивая очередь
~/.veinmusic/queue.jsonс авто-досылом при восстановлении сети.
- Облачный скробблинг (Cloud Scrobbling):
- Фоновый автоматический опрос статусов воспроизведения через официальные API Spotify и Яндекс Музыка без необходимости держать открытыми вкладки или плееры.
- Двусторонняя синхронизация (Two-Way External Sync):
- Автоматический параллельный экспорт каждого зафиксированного скроббла в Last.fm, ListenBrainz и Libre.fm.
- Импорт истории:
- Пакетный импорт архива прослушиваний из Last.fm с отслеживанием прогресса и возможностью перезапуска сбойных задач.
- Нормализация метаданных: интеллектуальная очистка названий треков и альбомов от мусорных суффиксов (
[Remastered],(feat. ...),[Official Audio],Live at...). - Защита от накруток:
- Фильтрация спам-скробблинга и мгновенных скипов (учет только прослушиваний более 85% длительности или от 4 минут).
- Ограничение темпа скробблинга (Rate Limiting) и защита от одновременных дублей из разных источников.
- Черный список (Blacklist Engine):
- Гибкая блокировка нежелательных треков, артистов или подкастов по ключевым словам, точным именам и регулярным выражениям (Regex).
- Интерактивные графики:
- Распределение активности по часам суток и дням недели, динамика за периоды (неделя, месяц, год, все время) на базе Recharts.
- Сводки по топ-артистам, альбомам, трекам и любимым жанрам.
- Умный рекомендательный движок (Smart Recommendations Engine):
- Гибридная система на основе анализа жанровых векторов пользователя, вкусовых предпочтений похожих слушателей («Taste Neighbors») и глобальных трендов сообщества.
- Персонализированные рекомендации треков и неизведанных артистов (
/api/recommendations/me).
- Музыкальные итоги (Recap / Wrapped):
- Генерация персональных итогов за неделю и месяц.
- Система уровней и рангов:
- Начисление XP за каждое подтвержденное прослушивание (+ бонус за любимые треки).
- Градация уровней и престижных рангов (от Туриста до Божества).
- Анимированные аватарные рамки:
- Эксклюзивные визуальные границы профиля (Neon Glow, Cyberpunk, Hologram, Retro Wave, Void и др.), открывающиеся по мере роста уровня.
- Достижения (Achievements):
- Награды за особые музыкальные паттерны («Ночной слушатель», «Марафонец», «Мультижанровый фанат» и др.).
- Витрина музыки (Music Showcase):
- Размещение избранных релизов в профиле с пользовательскими рецензиями и оценками.
- Живой фид и социальные функции:
- Глобальная и персональная лента активности друзей (
/feed) с фильтрацией по источникам (Яндекс, Spotify, Desktop, Расширение), лайками и безопасными комментариями. - Лидерборд лучших слушателей сообщества.
- Глобальная и персональная лента активности друзей (
- Слушать вместе (Listen Together):
- Комнаты совместного прослушивания реального времени на WebSockets: один пользователь становится DJ, а остальные синхронно слушают его поток с интерактивным чатом.
- Динамические SVG-виджеты для GitHub README / сайтов:
Now Playing: актуальный статус прослушивания с анимированным эквалайзером (/api/widgets/now-playing/{username}.svg).Top Artists: топ-5 исполнителей пользователя (/api/widgets/top-artists/{username}.svg).
- Social Share OpenGraph карточки (1200x630 SVG):
- Эстетичные карточки итогов недели/месяца (
/api/widgets/og/recap/{username}.svg) и разблокированных достижений (/api/widgets/og/achievement/{username}/{id}.svg).
- Эстетичные карточки итогов недели/месяца (
- PWA и Web Push:
- Поддержка установки веб-приложения на смартфоны и ПК через Service Worker (
sw.js) иmanifest.json. - Фоновые Web Push уведомления о лайках, комментариях и новых комнатах совместного прослушивания.
- Поддержка установки веб-приложения на смартфоны и ПК через Service Worker (
- Developer API & Webhooks:
- Персональные токены разработчика (
vm_...) с безопасным хранением PBKDF2-HMAC-SHA256. - Подписка на вебхуки (
scrobble.created,achievement.unlockedи др.) с криптографической подписьюX-VEIN-Signature(HMAC-SHA256). - Веб-портал управления ключами и вебхуками (
/developers).
- Персональные токены разработчика (
- Полнофункциональный интерфейс
/admin:- Мониторинг системных метрик, активных комнат совместного прослушивания и пользователей.
- Управление правилами блэклиста и антифрода.
- Отслеживание и перезапуск фоновых задач импорта Last.fm.
- Модерация музыкального каталога и слияние дубликатов треков.
┌────────────────────────────────────────────────────────┐
│ КЛИЕНТСКИЙ СЛОЙ │
│ Next.js 16 (PWA) │ Chrome MV3 │ Desktop App (Py/RPC) │
└───────────────────────────┬────────────────────────────┘
│ HTTPS / WebSockets
▼
┌────────────────────────────────────────────────────────┐
│ FASTAPI SERVER │
│ Auth / API / WebSockets / Antifraud / Recommendations │
└───────────────┬────────────────────────┬───────────────┘
│ │
PostgreSQL 16 │ │ Redis 7 / ARQ
┌──────────────────────▼───────┐ ┌───────▼────────────────────────┐
│ Time-Series Partitioning │ │ Async Workers & Schedulers │
│ Scrobbles, Users, Webhooks │ │ External Sync, Last.fm Import │
└──────────────────────────────┘ └────────────────────────────────┘
- Backend: Python 3.12+, FastAPI, SQLAlchemy 2.0, Alembic, PostgreSQL 16, Redis 7, ARQ Worker, Pytest, Pydantic v2.
- Frontend: Next.js 16 (App Router, Turbopack, React 19), Tailwind CSS 4, Framer Motion, Recharts, Lucide Icons.
- Desktop: Python 3,
winrt(Windows SMTC),dbus/MPRIS (Linux), Discord IPC RPC. - Extension: JavaScript (ES2022), Chrome Extensions API (Manifest V3).
- CI/CD & Безопасность: GitHub Actions, ESLint 9, Prettier, CodeQL, SonarQube Cloud, Playwright E2E.
VEINMusic/
├── app/ # Бэкенд-сервер (FastAPI)
│ ├── core/ # Ядро: безопасность (PBKDF2), Redis, WebSockets, партиционирование
│ ├── models.py # Модели базы данных SQLAlchemy
│ ├── schemas.py # Схемы валидации Pydantic
│ ├── routers/ # Роутеры (auth, scrobbling, profile, admin, developer, widgets, etc.)
│ ├── services/ # Бизнес-логика (antifraud, recommendations, external_sync, webhooks, og)
│ ├── worker.py # Асинхронный фоновый воркер ARQ
│ └── main.py # Точка входа приложения
├── desktop_client/ # Нативный клиент для Windows и Linux (SMTC/MPRIS/Discord RPC)
├── frontend/ # Веб-приложение Next.js 16 (React 19)
│ ├── app/ # Страницы и маршруты (about, admin, auth, developers, feed, together, user)
│ ├── components/ # UI-компоненты (PWARegistration, StatsCharts, GlobalAnnouncementBanner)
│ └── public/ # Статика, манифест PWA и Service Worker (sw.js)
├── music-extension/ # Расширение для Chromium-браузеров (Manifest V3)
├── alembic/ # Миграции структуры базы данных PostgreSQL
├── tests/ # Комплексный набор тестов (48 шт., pytest)
└── docker-compose.yml # Сервисы PostgreSQL и Redis
git clone https://github.com/Peaostrel/VEINMusic.git
cd VEINMusicdocker-compose up -d# Установка зависимостей
pip install -r requirements.txt
# Применение миграций БД
alembic upgrade head
# Запуск сервера разработки
uvicorn app.main:app --reload --port 8000cd frontend
npm install
npm run devФронтенд будет доступен по адресу: http://localhost:3000.
cd desktop_client
pip install -r requirements.txt
python -m desktop_client.main- Откройте любой Chromium-браузер (Chrome, Edge, Яндекс Браузер, Brave).
- Перейдите в
chrome://extensions/и включите «Режим разработчика» (Developer Mode). - Нажмите «Загрузить распакованное расширение» (Load unpacked) и укажите папку
music-extension. - Авторизуйтесь на сайте
http://localhost:3000— расширение автоматически синхронизирует сессию!
# Запуск полного набора юнит- и интеграционных тестов бэкенда (48 тестов)
pytest
# Проверка типизации и линтинга бэкенда
flake8 app tests desktop_client
mypy app/
# Проверка линтера и форматирования фронтенда
cd frontend
npm run lint
npm run format:check
npm run buildПроект распространяется под условиями собственной лицензии. Подробнее см. в файле LICENSE.