# 🎵 Global Music Scanner — Как пользоваться

## Что это такое

**Global Music Scanner** — это инструмент для проверки, на каких музыкальных платформах доступен конкретный артист. Он показывает полную картину присутствия музыканта в цифровых магазинах стриминговых сервисов.

**Для кого:** музыканты, менеджеры, лейблы, аналитики, фанаты.

---

## 🚀 Быстрый старт (5 минут)

### Шаг 1: Найдите артиста

1. Откройте [Global Scanner](http://localhost:3000)
2. Введите имя артиста в поисковую строку (например: "Avril Lavigne")
3. Выберите нужного артиста из выпадающего списка

### Шаг 2: Выберите платформы

По умолчанию включены:
- ✅ **Apple Music** (всегда включён)
- ✅ **Deezer**
- ✅ **Tidal**
- ✅ **Qobuz**

Можно добавить:
-  **MusicBrainz** — энциклопедия музыки (добавляет метаданные)
- ⚪ **Songlink** — находит ссылки между платформами
- ⚪ **Глубокий поиск** — ищет альбомы, которые есть только в одном сервисе

### Шаг 3: Выберите регионы

Apple Music показывает разный контент в разных странах. Выберите регионы:

- **"Топ-8"** — основные рынки (США, Великобритания, Германия, Франция, Канада, Австралия, Россия, Перу)
- **"Все"** — все 24 доступных региона
- Или выберите вручную

### Шаг 4: Запустите сканирование

Нажмите кнопку **"Запустить аудит"** и ждите.

- Для маленького артиста: ~30 секунд
- Для среднего: 2-5 минут
- Для крупного (100+ альбомов): 5-15 минут

### Шаг 5: Изучите результаты

После завершения вы увидите:
- Список всех альбомов с обложками
- На каких платформах доступен каждый альбом
- Длительность альбома
- Охват по регионам (какой % регионов Apple Music содержит этот альбом)

---

##  Что означают числа

### В правой панели (сайдбар)

| Показатель | Что значит |
|-----------|-----------|
| **Альбомы** | Общее количество найденных альбомов |
| **Клипы** | Количество музыкальных видео |
| **Только Apple** | Альбомы, которые есть только в Apple Music |
| **Только Deezer** | Альбомы, которые есть только в Deezer |
| **Только Tidal** | Альбомы, которые есть только в Tidal |
| **Только Qobuz** | Альбомы, которые есть только в Qobuz |
| **Только MusicBrainz** | Альбомы, которые нашлись только в базе MusicBrainz |
| **Apple** | Сколько альбомов есть в Apple Music (всего) |
| **Deezer** | Сколько альбомов есть в Deezer (всего) |
| **Tidal** | Сколько альбомов есть в Tidal (всего) |
| **Qobuz** | Сколько альбомов есть в Qobuz (всего) |
| **MB** | Сколько альбомов нашлось в MusicBrainz |
| **Общая длительность** | Суммарная длительность всех альбомов |

### В карточке альбома

| Элемент | Что значит |
|--------|-----------|
| **Обложка** | Изображение альбома |
| **Год** | Год выпуска |
| **Название** | Название альбома |
| **Исполнитель** | Имя артиста |
| **Треки** | Количество треков |
| **Длительность** | Общая длительность альбома |
| **Apple %** | Насколько широко альбом доступен в регионах Apple (0-100%) |
| **Иконки платформ** | На каких сервисах доступен альбом (кликабельно → открывает страницу альбома) |

---

##  Практические примеры использования

### Сценарий 1: Музыкант хочет понять своё присутствие

**Задача:** Вы артист и хотите знать, на каких платформах доступна ваша музыка.

**Действия:**
1. Найдите себя в поиске
2. Включите все платформы (включите MusicBrainz и Songlink)
3. Выберите все регионы
4. Запустите сканирование
5. Посмотрите, какие альбомы есть "Только в Apple" — возможно, их нет на других платформах из-за лицензионных ограничений

**Результат:** Вы увидите полный список своих альбомов и поймёте, где есть пробелы.

---

### Сценарий 2: Менеджер ищет проблемы с дистрибуцией

**Задача:** Вы менеджер артиста и подозреваете, что некоторые альбомы недоступны в определённых регионах.

**Действия:**
1. Найдите артиста
2. Выберите все регионы
3. Запустите сканирование
4. Отсортируйте по "Apple %" (охвату)
5. Альбомы с низким % — кандидаты на исправление

**Результат:** Список альбомов, которые недоступны в большинстве регионов Apple Music.

---

### Сценарий 3: Аналитик сравнивает двух артистов

**Задача:** Сравнить цифровое присутствие двух артистов.

**Действия:**
1. Отсканируйте первого артиста, экспортируйте XLSX
2. Отсканируйте второго, экспортируйте XLSX
3. Сравните в Excel:
   - Количество альбомов на каждой платформе
   - Средний охват по регионам
   - Наличие эксклюзивного контента

**Результат:** Таблица сравнения с метриками.

---

### Сценарий 4: Фанат ищет редкие альбомы

**Задача:** Найти альбомы, которые есть только на одной платформе (редкие/эксклюзивные).

**Действия:**
1. Найдите артиста
2. Включите все платформы
3. Запустите сканирование
4. Посмотрите секции "Только Apple", "Только Deezer" и т.д.
5. Эти альбомы — эксклюзивы платформы

**Результат:** Список редких альбомов, доступных только в одном месте.

---

## ️ Дополнительные функции

### 🔄 Кэширование

**Как работает:** Результаты сканирования сохраняются в браузере.

**Зачем:** Не нужно сканировать заново, если вы уже проверяли этого артиста.

**Использование:**
1. Откройте ранее отсканированного артиста
2. Нажмите **"Загрузить"** в зелёной плашке сверху
3. Результаты появятся мгновенно

**Очистка кэша:** Нажмите **"Удалить"** в плашке кэша.

---

###  История сканирований

**Как работает:** Каждое сканирование сохраняется с датой и временем.

**Зачем:** Видеть, как менялась дискография со временем.

**Использование:**
1. Нажмите кнопку **"История"** (оранжевая, рядом с "Экспорт XLSX")
2. Увидите график изменений
3. Можно сравнить два сканирования — покажет добавленные/удалённые альбомы

---

###  Экспорт в Excel

**Как работает:** Скачивает файл `.xlsx` со всеми данными.

**Зачем:** Для анализа в Excel, отчётов, презентаций.

**Использование:**
1. Нажмите **"Экспорт XLSX"** (зелёная кнопка)
2. Файл скачается автоматически
3. Откройте в Excel/Google Sheets/Numbers

**Что внутри:**
- Лист "Альбомы" — все альбомы с платформами
- Лист "Videoclips" — все клипы
- Лист "Apple Music" — детали по Apple (ID, ссылка, регионы)
- Лист "Deezer" — детали по Deezer
- Лист "Tidal" — детали по Tidal (качество звука, Atmos)
- Лист "Qobuz" — детали по Qobuz (Hi-Res)
- Лист "MusicBrainz" — метаданные из MusicBrainz

---

### 🌐 Переключение языка

**Как работает:** RU/EN переключатель в правом верхнем углу.

**Зачем:** Интерфейс на русском или английском.

**Использование:** Нажмите RU или EN.

---

## 💡 Советы и хитрости

### Совет 1: Начинайте с малого

Не включайте сразу все платформы и все регионы. Начните с:
- Apple Music + Deezer
- Топ-8 регионов
- Без MusicBrainz и Songlink

Это даст быстрый результат (~1 минута). Потом добавляйте остальные.

---

### Совет 2: Используйте "Без дублей"

**Проблема:** Один альбом может быть в каталоге несколько раз (разные издания, ремастеры, deluxe-версии).

**Решение:** Включите тумблер **"Без дублей"** (справа внизу).

**Результат:** Альбомы с одинаковым названием и годом объединяются в одну карточку.

---

### Совет 3: Songlink находит скрытые ссылки

**Проблема:** Альбом есть в Apple, но вы не знаете, есть ли он в Deezer/Tidal.

**Решение:** Включите **Songlink**.

**Как работает:** Songlink берёт ссылку Apple и находит соответствующие ссылки в других сервисах.

**Результат:** Больше альбомов найдётся на всех платформах.

---

### Совет 4: MusicBrainz добавляет метаданные

**Проблема:** Не хватает информации об альбоме (UPC, количество треков, длительность).

**Решение:** Включите **MusicBrainz**.

**Как работает:** MusicBrainz — это открытая энциклопедия музыки. Он добавляет:
- UPC (штрих-код альбома)
- Точное количество треков
- Длительность
- Формат издания (CD, винил, digital)
- Ссылки на другие платформы

**Минус:** Сканирование замедлится (1 RPS лимит).

---

### Совет 5: Глубокий поиск для "одиночек"

**Проблема:** Альбом есть только в одном сервисе (например, только в Qobuz).

**Решение:** Включите **"Глубокий поиск"**.

**Как работает:** Для каждого "одинокого" альбома сервис ищет его в остальных платформах по названию, исполнителю, году.

**Минус:** Долго (может добавить 5-10 минут к сканированию).

---

## ❓ Частые вопросы

### Вопрос: Почему сканирование такое долгое?

**Ответ:** Мы делаем сотни запросов к API музыкальных сервисов. У каждого есть лимиты (например, MusicBrainz — 1 запрос в секунду). Для артиста с 100 альбомами это может занять 5-15 минут.

---

### Вопрос: Можно ли ускорить?

**Ответ:**
- Отключите MusicBrainz (экономит до 50% времени)
- Отключите Songlink (экономит 20-30%)
- Используйте меньше регионов
- Отключите "Глубокий поиск"

---

### Вопрос: Почему некоторые альбомы не находятся?

**Ответ:**
- **Лицензионные ограничения** — альбом может быть недоступен в определённых регионах
- **Разные названия** — сервисы могут называть альбом по-разному (например, "Album (Deluxe Edition)" vs "Album")
- **Отсутствие в каталоге** — альбом физически не загружен на платформу
- **Технические проблемы** — API сервиса временно недоступен

---

### Вопрос: Что значит "Только в Apple"?

**Ответ:** Альбом найден в Apple Music, но не найден в Deezer, Tidal, Qobuz. Это может быть:
- Эксклюзив Apple Music
- Альбом ещё не добавлен на другие платформы
- Разное название в разных сервисах (алгоритм не смог сопоставить)

---

### Вопрос: Можно ли сканировать несколько артистов сразу?

**Ответ:** Нет, сейчас только по одному. Но вы можете:
1. Отсканировать первого
2. Экспортировать XLSX
3. Очистить поиск
4. Отсканировать второго
5. Сравнить в Excel

---

### Вопрос: Данные сохраняются после закрытия браузера?

**Ответ:** Да! Кэш хранится в IndexedDB браузера. Даже после закрытия вкладки данные останутся. Но если очистите данные браузера — кэш удалится.

---

### Вопрос: Что делать, если сканирование зависло?

**Ответ:**
1. Подождите ещё 2-3 минуты (иногда API отвечают медленно)
2. Если не помогло — обновите страницу (Ctrl+R)
3. Проверьте интернет-соединение
4. Попробуйте отключить MusicBrainz и Songlink

---

### Вопрос: Как связаться с разработчиками?

**Ответ:** [Здесь должна быть ссылка на GitHub/email/Telegram]

---

## 📚 Глоссарий

| Термин | Значение |
|--------|---------|
| **Storefront** | Региональный магазин Apple Music (например, US, RU, DE) |
| **UPC** | Универсальный код продукта (штрих-код альбома) |
| **ISRC** | Международный стандартный код записи (для треков) |
| **Hi-Res** | Высокое разрешение аудио (обычно 24-bit/96kHz+) |
| **Atmos** | Dolby Atmos — пространственный звук |
| **Master** | MQA-кодирование в Tidal (мастер-качество) |
| **Songlink** | Сервис для нахождения ссылок между платформами |
| **MusicBrainz** | Открытая энциклопедия музыки |
| **JSONP** | Техника обхода CORS-ограничений браузера |
| **CORS** | Политика безопасности браузера (Cross-Origin Resource Sharing) |

---

## 🎉 Заключение

Global Music Scanner — это мощный инструмент для анализа цифрового присутствия музыкантов. Он помогает:

- ✅ Найти пробелы в дистрибуции
- ✅ Сравнить покрытие платформ
- ✅ Экспортировать данные для отчётов
- ✅ Отслеживать изменения со временем

**Начните с простого сканирования и постепенно добавляйте функции!**

---

*Документация обновлена: 15 июля 2026*  
*Версия: 4.3.0*
