nakama/MUSIC_SETUP.md

Настройка музыкального модуля Nakama

Установка зависимостей

Для работы музыкального модуля требуется установить дополнительные пакеты:

npm install adm-zip music-metadata

• adm-zip - для распаковки ZIP-архивов при загрузке альбомов
• music-metadata - для извлечения метаданных (название, исполнитель, обложка) из аудио файлов

Структура файлов

Backend

Модели:

• backend/models/Artist.js - Исполнители
• backend/models/Album.js - Альбомы
• backend/models/Track.js - Треки
• backend/models/FavoriteTrack.js - Избранные треки пользователей

Routes:

• backend/routes/music.js - API для музыки (загрузка, поиск, избранное)
• backend/routes/bot.js - Обновлен для отправки треков в Telegram
• backend/routes/posts.js - Обновлен для поддержки музыкальных вложений

Бот:

• backend/bot.js - Добавлена функция sendAudioToUser() для отправки треков

Frontend

Страницы:

• frontend/src/pages/Media.jsx - Главная страница Media с категориями
• frontend/src/pages/MediaFurry.jsx - Поиск Furry контента
• frontend/src/pages/MediaAnime.jsx - Поиск Anime контента
• frontend/src/pages/MediaMusic.jsx - Музыкальный сервис

Компоненты:

• frontend/src/components/MiniPlayer.jsx - Мини-плеер (внизу экрана)
• frontend/src/components/FullPlayer.jsx - Полный плеер
• frontend/src/components/MusicAttachment.jsx - Отображение музыки в постах

Контекст:

• frontend/src/contexts/MusicPlayerContext.jsx - Управление состоянием плеера

API:

• frontend/src/utils/musicApi.js - API функции для работы с музыкой

Функционал

1. Media Hub

• Главная страница с тремя категориями: Furry, Anime, Music
• Квадратные кнопки-карточки с цветовой кодировкой
• Анимации и состояния как в остальном приложении

2. Furry / Anime

• Отдельные страницы для каждой категории
• Поиск по тегам (e621 / gelbooru)
• Автокомплит тегов
• Просмотр изображений
• Добавление в посты
• Отправка в Telegram
• Режим выбора нескольких изображений

3. Music Service

Загрузка:

• Загрузка отдельных треков (MP3, WAV, OGG, M4A, FLAC)
• Загрузка альбомов из ZIP архива
• Автоматическое извлечение метаданных из аудио файлов:
  • Название трека
  • Исполнитель
  • Альбом
  • Год
  • Жанр
  • Номер трека
  • Обложка (из ID3 тегов)
• Возможность редактирования метаданных при загрузке
• Автоматическое создание исполнителей и альбомов

Поиск:

• Поиск по трекам, исполнителям, альбомам
• Фильтрация результатов

Плеер:

• Мини-плеер (закреплен внизу)
• Полный плеер (открывается по клику)
• Управление воспроизведением (play/pause/next/prev)
• Прогресс-бар с перемоткой
• Регулировка громкости
• Очередь воспроизведения

Избранное:

• Добавление треков в избранное
• Просмотр избранных треков

Telegram интеграция:

• Отправка треков в личные сообщения
• Треки отправляются как аудио файлы с метаданными

4. Музыка в постах

• Прикрепление треков к постам
• Воспроизведение через общий плеер
• Отображение в ленте

API Endpoints

Music

GET /api/music/search?q=query&type=all - Поиск музыки

GET /api/music/tracks?limit=50&page=1 - Список треков

GET /api/music/tracks/:trackId - Получить трек

GET /api/music/albums/:albumId - Получить альбом с треками

POST /api/music/upload-track - Загрузить трек

• FormData: track (file), title, artistName, albumTitle, trackNumber, year, genre

POST /api/music/upload-album - Загрузить альбом (ZIP)

• FormData: album (zip), artistName, albumTitle, year, genre

POST /api/music/favorites/:trackId - Добавить в избранное

DELETE /api/music/favorites/:trackId - Удалить из избранного

GET /api/music/favorites - Получить избранные треки

POST /api/music/tracks/:trackId/play - Отметить прослушивание

Bot

POST /api/bot/send-track - Отправить трек в Telegram

{
  "userId": 123456789,
  "trackId": "track_id"
}

Навигация

Вкладка "Search" переименована в "Media" с иконкой Layers.

Цветовая схема

• Furry: var(--tag-furry) - оранжевый (#FF8A33)
• Anime: var(--tag-anime) - синий (#4A90E2)
• Music: #9b59b6 - фиолетовый

Примечания

1. Музыкальные файлы хранятся в backend/uploads/music/
2. Поддерживаемые форматы: MP3, WAV, OGG, M4A
3. Максимальный размер файла: 50MB
4. ZIP архивы автоматически распаковываются и создают альбом
5. Плеер работает глобально - музыка продолжает играть при навигации
6. Треки в постах воспроизводятся через общий плеер