MusicArk

Windows-приложение для управления локальной музыкальной коллекцией и сопоставления её с библиотекой Яндекс Музыки. Помогает находить отсутствующие треки, проверять версии записей, восстанавливать метаданные и выполнять контролируемую синхронизацию.

Русский · English

🌐 Страница проекта · English website

Быстрый старт · Документация · Релизы · Обратная связь

---

О проекте

MusicArk предназначен для пользователей, которые хотят хранить локальную копию музыкальной коллекции и сверять её с библиотекой Яндекс Музыки. Приложение разделяет идентичность трека, метаданные, вариант записи и покрытие коллекции: высокая похожесть названий сама по себе не считается подтверждённым совпадением.

Основной сценарий:

Яндекс Музыка = желаемая коллекция
        ↓
Локальная библиотека = фактические файлы
        ↓
Identity Matching + Variant + Coverage
        ↓
Missing / Wanted
        ↓
Download / Metadata / подтверждённые Sync или Upload действия

Статус проекта

• стадия: Stable;
• текущий публичный релиз: v1.0.0;
• платформа релиза: Windows x64;
• SQLite schema: 1.9.0;
• Authenticode: UNSIGNED.

v1.0.0 опубликован как первый стабильный публичный релиз. Установщик и executable не подписаны Authenticode, поэтому Windows SmartScreen может показать предупреждение при первом запуске.

Скриншоты

Актуальный интерфейс MusicArk v1.0.0:

Возможности

• вход в Яндекс Музыку через пользовательский токен;
• cache-first просмотр любимых треков, плейлистов и понравившихся альбомов;
• индексирование нескольких локальных папок без изменения файлов во время обычного Scan;
• Identity Matching между треками Яндекс Музыки и локальными файлами;
• Variant-анализ и пользовательские метки ORIGINAL / CENSORED;
• Coverage / Missing для поиска отсутствующих и требующих проверки треков;
• очередь загрузок с Wanted, retry, cancel, remove и массовыми действиями;
• встроенное воспроизведение локальных и подготовленных Yandex-треков;
• Metadata Editor для безопасной записи MP3/ID3, artwork и подтверждённого связывания с Yandex identity;
• ручная загрузка собственных или разрешённых MP3 в Яндекс Музыку и recovery workflows;
• Controlled Sync с предварительным планом и подтверждением перед применением;
• System / Direct / Custom proxy modes;
• интерфейс RU/EN и темы System / Light / Dark;
• portable package, per-user installer и проверяемый механизм обновления.

Для библиотек в несколько тысяч треков используются cache-first загрузка, bounded batches, сохранённые очереди и последовательные workers для тяжёлых операций.

Быстрый старт

1. Откройте последний GitHub Release.
2. Скачайте MusicArk-Setup-1.0.0-x64.exe для обычной установки или MusicArk-1.0.0-win-x64.zip для portable-запуска.
3. Запустите MusicArk.
4. При необходимости войдите в Яндекс Музыку с пользовательским токеном.
5. Добавьте папки локальной библиотеки и запустите Scan.
6. Используйте Matching, Coverage и Downloads для проверки состояния коллекции.

Отдельно устанавливать Python или клонировать репозиторий для готовой Windows-сборки не требуется.

Требования

• 64-битная Windows;
• доступ к интернету для функций Яндекс Музыки, обновлений и внешних источников;
• пользовательский токен Яндекс Музыки для функций, требующих авторизации.

Для локального просмотра и работы с уже сохранёнными данными доступность внешних сервисов не должна быть обязательной.

Установка

Installer

MusicArk-Setup-1.0.0-x64.exe устанавливает приложение для текущего пользователя в:

%LOCALAPPDATA%\Programs\Music Ark

Portable

MusicArk-1.0.0-win-x64.zip можно распаковать в любой доступный пользователю каталог и запустить Music Ark.exe.

Пользовательские данные хранятся отдельно:

%LOCALAPPDATA%\MusicArk

Обычный uninstall не должен удалять базу данных, кеши и настройки пользователя.

Использование

Обычные Scan, Matching, Variant, Coverage и просмотр Sync-плана не изменяют пользовательские аудиофайлы.

Существующий MP3 изменяется только после явного действия в Metadata Editor. Запись выполняется через временную копию, проверку MPEG/metadata и атомарную замену. Неизвестные и custom ID3 frames сохраняются, если пользователь явно их не редактирует.

Удаление failed/needs-review задачи загрузки удаляет запись очереди, а не готовый аудиофайл.

Сеть и прокси

MusicArk поддерживает три режима:

System  — системные сетевые настройки
Direct  — прямое соединение
Custom  — пользовательский proxy

Встроенное управление Cloudflare WARP удалено из release runtime. MusicArk не устанавливает и не удаляет WARP автоматически.

Сетевые ошибки внешних metadata/download источников должны локализоваться в соответствующей функции и не блокировать работу с локальной библиотекой и кешированными данными.

Безопасность

• Scan, Matching, Variant и Coverage не должны изменять локальные аудиофайлы;
• запись MP3 выполняется только после явного действия пользователя;
• upload и sync требуют явного выбора или подтверждения;
• updater проверяет размер и SHA-256 installer перед запуском;
• release package включает LICENSE, THIRD_PARTY_NOTICES.md и тексты лицензий сторонних компонентов.

Приватность

• токены, cookies, signed media URLs и proxy passwords не должны попадать в Git;
• Flutter UI не получает Yandex token или защищённые provider media URLs для playback/download;
• автоматические diagnostics для feedback ограничены версией MusicArk, ОС и архитектурой и не включают музыкальную библиотеку, локальные пути или credentials;
• изменяемые данные установленной версии хранятся в пользовательском каталоге, а не рядом с program files.

Обновление

Stable updater использует update-manifest.json из последнего GitHub Release.

check   → получить и проверить manifest
prepare → скачать installer и проверить размер + SHA-256
apply   → после подтверждения повторно проверить и запустить installer

Ошибка update endpoint не должна мешать обычному запуску MusicArk. Установка обновления выполняется только после явного подтверждения пользователя.

Разработка

Для локального запуска из исходников нужны Python, Flutter и Windows toolchain, соответствующий текущему проекту.

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .
python -m pip install -r requirements-yandex.txt

$env:MUSICARK_PYTHON = (Resolve-Path ".\.venv\Scripts\python.exe").Path
$env:MUSICARK_REPO_ROOT = (Get-Location).Path
Set-Location .\ui\musicark_ui
flutter run -d windows

Сборка

Финальная Windows-упаковка выполняется из source state, где VERSION уже соответствует версии релиза:

.\scripts\release.ps1 -Version v1.0.0

Для v1.0.0 pipeline формирует:

MusicArk-1.0.0-win-x64.zip
MusicArk-Setup-1.0.0-x64.exe
SHA256SUMS.txt
update-manifest.json

Тестирование

Основной локальный regression entry point:

.\scripts\ci.ps1

Репозиторий также содержит Trusted CI для доверенных owner PR/workflow-dispatch запусков на self-hosted Windows x64 runner. Внешние или недоверенные fork PR не должны выполняться на persistent self-hosted runner владельца.

Документация

• CHANGELOG.md — история изменений;
• Release notes v1.0.0 — подробности первого публичного релиза;
• THIRD_PARTY_NOTICES.md — сторонние компоненты, лицензии и source obligations.

Обратная связь

Ошибки и предложения принимаются через GitHub Issues.

При сообщении об ошибке не публикуйте токены, cookies, proxy passwords, signed URLs и другие credentials.

Ограничения

• Windows x64 — единственная release-платформа;
• полноценная безопасная запись metadata реализована для MP3/ID3; другие поддерживаемые форматы могут оставаться read-only в Metadata Editor;
• часть provider-функций зависит от внешних API и доступности сервисов;
• автоматическое определение ORIGINAL / CENSORED не считается абсолютной истиной и сомнительные случаи требуют проверки;
• MusicArk не является двунаправленным filesystem mirror и не должен автоматически удалять, переименовывать или перезаписывать существующие локальные треки;
• update/install действия не выполняются без явного пользовательского шага;
• v1.0.0 распространяется без Authenticode-подписи.

Лицензия

Собственный код MusicArk распространяется под MIT License.

Сторонние компоненты сохраняют собственные лицензии. Их notices и source obligations описаны в THIRD_PARTY_NOTICES.md и каталоге licenses/.

Интеграция с Яндекс Музыкой использует неофициальный API через стороннюю библиотеку yandex-music. MusicArk не является официальным продуктом Яндекса и не аффилирован с Яндексом.