nakama/ALBUM_UPLOAD_GUIDE.md

# 📀 Руководство по загрузке альбомов

## 🎵 Загрузка ZIP альбома

### Подготовка ZIP архива

1. **Соберите треки в одну папку:**
```
My Album/
├── 01 - First Track.mp3
├── 02 - Second Track.mp3
├── 03 - Third Track.mp3
└── ...
```

2. **Создайте ZIP архив:**
- Правый клик на папке → Отправить → Сжатая ZIP-папка
- Или используйте любой архиватор (7-Zip, WinRAR)

3. **Требования:**
- Максимальный размер: **100MB**
- Поддерживаемые форматы: MP3, WAV, OGG, M4A, FLAC
- Файлы могут быть в подпапках - будут найдены автоматически

### 📋 Метаданные (ID3 теги)

Система автоматически извлекает из аудио файлов:
- ✅ **Название трека** (TITLE)
- ✅ **Исполнитель** (ARTIST)
- ✅ **Альбом** (ALBUM)
- ✅ **Год** (YEAR)
- ✅ **Жанр** (GENRE)
- ✅ **Номер трека** (TRACK NUMBER)
- ✅ **Обложка** (PICTURE/APIC)
- ✅ **Длительность** (автоматически)

### 🎨 Обложка альбома

Обложка извлекается из ID3 тегов первого трека:
- Если в треках есть встроенная обложка - она будет использована
- Поддерживаемые форматы: JPEG, PNG
- Размер: рекомендуется 500x500 - 1000x1000 пикселей

### 📝 Как загрузить

1. **Откройте Music раздел:**
   Media → Music

2. **Нажмите кнопку Upload** (иконка справа в табах)

3. **Выберите ZIP файл:**
   - Выберите подготовленный ZIP архив

4. **Заполните базовые данные:**
   - **Исполнитель*** - обязательно (можно оставить из метаданных)
   - **Название альбома*** - обязательно (можно оставить из метаданных)
   - **Год** - необязательно
   - **Жанр** - необязательно

5. **Нажмите "Загрузить альбом":**
   - Система распакует архив
   - Извлечет метаданные из каждого трека
   - Создаст исполнителя (если не существует)
   - Создаст альбом
   - Создаст все треки с правильными данными

### ⚡ Что происходит автоматически

1. **Распаковка ZIP:**
   - Поиск всех аудио файлов в архиве
   - Извлечение в папку `backend/uploads/music/`

2. **Извлечение метаданных:**
   - Чтение ID3 тегов из каждого файла
   - Извлечение обложки из первого трека
   - Сохранение обложки как отдельный файл

3. **Создание записей:**
   - Исполнитель (если не существует)
   - Альбом с обложкой
   - Треки с индивидуальными метаданными

4. **Обновление статистики:**
   - Счетчик треков исполнителя
   - Счетчик альбомов исполнителя
   - Общая длительность альбома

### 📊 Пример обработки

**Входные данные:**
```
Album.zip (содержит):
├── 01 - Track One.mp3 (ID3: title="Track One", artist="Artist", album="My Album", year=2024)
├── 02 - Track Two.mp3 (ID3: title="Track Two", artist="Artist", album="My Album", year=2024)
└── cover.jpg (встроена в треки)
```

**Результат:**
- Создан исполнитель: "Artist"
- Создан альбом: "My Album" (2024) с обложкой
- Созданы треки:
  1. "Track One" (№1)
  2. "Track Two" (№2)
- Все треки имеют обложку альбома

### 🔧 Редактирование метаданных

Если метаданные в файлах неполные или неверные:

1. **При загрузке можно изменить:**
   - Исполнителя (применится ко всем трекам)
   - Название альбома
   - Год
   - Жанр

2. **Что берется из файлов:**
   - Название каждого трека
   - Номер трека
   - Индивидуальная обложка (если есть)
   - Длительность

### 🎯 Рекомендации

**Для лучшего качества метаданных:**

1. Используйте программу для редактирования ID3 тегов:
   - **Mp3tag** (Windows) - бесплатно
   - **MusicBrainz Picard** - кросс-платформенный
   - **Kid3** - кросс-платформенный

2. Добавьте обложку во все треки:
   - Формат: JPEG или PNG
   - Размер: 500x500 или больше
   - Встроена в файл (не отдельным файлом)

3. Заполните базовые теги:
   ```
   TITLE: Track Name
   ARTIST: Artist Name
   ALBUM: Album Name
   YEAR: 2024
   GENRE: Electronic
   TRACK: 1/10
   ```

4. Используйте последовательную нумерацию:
   ```
   01 - Track Name.mp3
   02 - Track Name.mp3
   ...
   ```

### ⚠️ Ограничения

- Максимальный размер ZIP: **100MB**
- Максимальное количество треков: **неограниченно**
- Поддерживаемые форматы: MP3, WAV, OGG, M4A, FLAC
- Вложенные папки: **поддерживаются** (треки будут найдены на любом уровне)

### 🐛 Проблемы

**"В архиве нет аудио файлов"**
- Убедитесь что файлы имеют расширения: .mp3, .wav, .ogg, .m4a, .flac
- Проверьте что файлы не повреждены

**"ZIP файл слишком большой"**
- Уменьшите битрейт треков
- Разбейте альбом на несколько ZIP (по дискам)
- Используйте формат с меньшим размером (MP3 320kbps вместо FLAC)

**"Обложка не загрузилась"**
- Убедитесь что обложка встроена в ID3 теги
- Размер обложки не должен превышать 5MB
- Формат: JPEG или PNG

**"Неверные метаданные"**
- Отредактируйте ID3 теги перед загрузкой с помощью Mp3tag
- Или заполните поля вручную при загрузке

### 📚 Примеры структуры ZIP

**Вариант 1 - Простой:**
```
Album.zip
├── Track 01.mp3
├── Track 02.mp3
└── Track 03.mp3
```

**Вариант 2 - С подпапками:**
```
Album.zip
└── Album Name/
    ├── 01 - Track One.mp3
    ├── 02 - Track Two.mp3
    └── cover.jpg (не используется, нужна встроенная)
```

**Вариант 3 - Несколько дисков:**
```
Album Disc 1.zip
├── CD1/
│   ├── 01 - Track.mp3
│   └── 02 - Track.mp3

Album Disc 2.zip
├── CD2/
│   ├── 01 - Track.mp3
│   └── 02 - Track.mp3
```

---

**Удачной загрузки! 🚀**