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

---

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