Музыкальный анализ с помощью AI-рассуждения — веб-приложение для извлечения музыкальных признаков из аудиофайлов с помощью Essentia и генерации структурированных обзоров на русском языке.
- Загрузка аудио через веб-интерфейс (drag & drop)
- Поддержка форматов: MP3, WAV, FLAC, OGG, M4A
- Извлечение признаков Essentia: темп, тональность, громкость, спектр, ритм, танцевальность, энергия
- Генерация музыкального обзора на русском языке с поддержкой нескольких LLM провайдеров:
- OpenAI — GPT-4o-mini и другие модели (платно)
- Anthropic Claude — Claude 3.5 Sonnet (платно)
- Ollama — локальный запуск, бесплатно (приватность)
- NVIDIA Nemotron — мощная API (платно или free tier)
- Шаблонный fallback — без API ключей, всегда работает
- RAG (Retrieval Augmented Generation) — обзоры дополняются фрагментами из учебника «Теория современной композиции» для теоретически обоснованных оценок
- Возврат сырых параметров (JSON) и текста обзора
muse analyse/
├── app/
│ ├── __init__.py # Версия пакета
│ ├── config.py # Конфигурация из .env
│ ├── audio_analysis.py # Essentia: извлечение признаков
│ ├── llm_providers.py # Поддержка OpenAI, Claude, Ollama, Nemotron
│ ├── review_generator.py # Генерация обзоров с fallback
│ ├── rag/ # RAG: индексация PDF, семантический поиск
│ └── main.py # FastAPI-приложение
├── data/
│ ├── knowledge/ # PDF-учебники (версионируются)
│ └── rag_index/ # ChromaDB-индекс (gitignored, пересоздаётся)
├── scripts/
│ └── index_knowledge.py # CLI для построения RAG-индекса
├── static/
│ ├── index.html # Веб-интерфейс
│ ├── style.css
│ └── app.js
├── uploads/ # Временные файлы (gitignored)
├── examples_test_providers.py # Примеры использования API
├── run.py # Запуск сервера
├── requirements.txt
├── .env.example
├── LLM_PROVIDERS.md # Документация по провайдерам
├── .gitignore
└── README.md
Для локального запуска и VPS используйте один и тот же контейнерный сценарий. Docker Desktop нужен только на рабочей машине; на VPS нужен Docker Engine и Compose plugin.
Docker Compose поднимает production-контейнер одной командой и устанавливает системные зависимости, включая ffmpeg:
cp .env.example .env
docker compose up --buildОткрыть: http://localhost:8000
Кроме самого приложения это поднимает redis (очередь задач) и worker
(отдельный процесс, который выполняет анализ и Growth Copilot — без него
задачи будут ставиться в очередь, но никогда не завершатся).
Этот вариант запускает базовый linux/amd64-образ с готовой Linux wheel Essentia TensorFlow, но без тяжёлых RAG-зависимостей. Чтобы включить RAG, остановите базовый сервис и запустите профиль (с воркером — worker-rag, а не worker):
docker compose down
docker compose --profile rag up --build muse-analyse-rag worker-ragПосле добавления PDF в data/knowledge/ постройте RAG-индекс в отдельном профиле:
docker compose --profile rag run --rm muse-analyse-rag python scripts/index_knowledge.pyИндекс хранится в именованном Docker volume muse-analyse_rag_index и переживает пересоздание контейнера. Для остановки:
docker compose downДля удаления индекса вместе с volume используйте docker compose down -v.
Этот режим предназначен для разработки и может требовать отдельной установки Essentia и ffmpeg. Для production используйте Compose выше.
brew install ffmpegcd /path/to/muse-analyse
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtconda create -n muse-analyse python=3.10
conda activate muse-analyse
conda install -c conda-forge essentia
pip install -r requirements.txtpip install essentiaПроверка:
python -c "import essentia; print(essentia.__version__)"cp .env.example .env
# Отредактируйте .env — выберите провайдер и добавьте ключи (опционально)Анализ и Growth Copilot выполняются в отдельном процессе-воркере — без него
запросы будут ставиться в очередь и никогда не завершатся. Нужны Redis
(brew install redis && redis-server на macOS, либо docker run -p 6379:6379 redis:7-alpine)
и два процесса — сервер и воркер:
source .venv/bin/activate
# Терминал 1: сервер
uvicorn app.main:app --host 127.0.0.1 --port 8000 --log-level info
# Терминал 2: воркер
celery -A app.tasks worker --loglevel=infoОткрыть: http://localhost:8000
В каталоге data/knowledge/ уже лежит учебник «Теория современной композиции». Для первого запуска постройте векторный индекс:
pip install chromadb pymupdf sentence-transformers
python scripts/index_knowledge.pyПроверка статуса:
python scripts/index_knowledge.py --statusПри первом запуске скачается мультиязычная модель эмбеддингов (~470 МБ). Индекс сохраняется в data/rag_index/.
Чтобы добавить другие учебники — положите PDF в data/knowledge/ и выполните:
python scripts/index_knowledge.py --forceОтключить RAG: RAG_ENABLED=false в .env.
По умолчанию используется OpenAI, но вы можете выбрать любого из четырёх:
| Провайдер | Конфиг | Стоимость | Лучше для |
|---|---|---|---|
| OpenAI | LLM_PROVIDER=openai |
Платно | Быстрый старт, высокое качество |
| Claude | LLM_PROVIDER=claude |
Платно | Глубокий анализ, структурированность |
| Ollama | LLM_PROVIDER=ollama |
Бесплатно | Приватность, локальный запуск |
| Nemotron | LLM_PROVIDER=nemotron |
Платно / Free tier | GPU оптимизация |
Подробная настройка: см. LLM_PROVIDERS.md
Проверка состояния, доступности Essentia и LLM провайдеров.
{
"status": "ok",
"version": "1.0.0",
"essentia_available": true,
"llm_providers": {
"openai": true,
"claude": false,
"ollama": true,
"nemotron": false
}
}Список доступных LLM провайдеров.
{
"available": {
"openai": true,
"claude": false,
"ollama": true,
"nemotron": false
},
"description": { ... }
}Загружает аудиофайл и ставит анализ в очередь (Celery) — Essentia-анализ и генерация обзора могут занимать десятки секунд и выполняются в отдельном воркер-процессе, а не внутри самого запроса.
Запрос:
curl -X POST -F "file=@track.mp3" http://localhost:8000/api/analyzeОтвет (сразу):
{"task_id": "d8805c13-27b5-4be0-83f6-35996314c93a"}Статус и результат фоновой задачи — опрашивайте, пока status не станет
done или error.
curl http://localhost:8000/api/tasks/d8805c13-27b5-4be0-83f6-35996314c93a{"status": "pending"}Если вы хотите вызвать внутреннюю обёртку mcp_server.py (не требует запуска FastMCP транспорта):
# В одном терминале запустите API (см. выше):
source .venv/bin/activate
uvicorn app.main:app --host 127.0.0.1 --port 8000
# В другом терминале выполните анализ файла через инструмент:
python -c "from mcp_server import analyze_audio; print(analyze_audio('/absolute/path/to/track.mp3'))"Если хотите запустить interactive FastMCP transport (stdin/stdout) для интеграции с внешними менеджерами MCP, используйте:
# Запуск FastMCP (пример):
python mcp_server.pyОтвет (когда готово, status: "done"):
{
"status": "done",
"result": {
"success": true,
"filename": "track.mp3",
"features": { ... },
"review": {
"source": "openai",
"model": "gpt-4o-mini",
"language": "ru",
"score": 7.5,
"sections": {
"summary": "...",
"rhythm": "...",
"tonality": "...",
"production": "...",
"verdict": "..."
},
"full_text": "..."
}
}
}Growth Copilot (POST /api/growth/start, POST /api/growth/select) устроен
так же: запрос сразу возвращает task_id, результат — через тот же
GET /api/tasks/{task_id}.
| Категория | Признаки |
|---|---|
| Ритм | BPM, уверенность бита, количество ударов, onset rate, beat loudness |
| Тональность | Тоника, лад (мажор/минор), сила тональности, строй (Гц), аккорды |
| Динамика | LUFS (EBU R128), громкость по Стивенсу (не дБ), динамическая сложность, RMS, replay gain |
| Спектр | Спектральный центроид, яркость, rolloff, flux, zero-crossing rate, MFCC |
| Прочее | Танцевальность (Danceability), энергия (композитная оценка 0–1) |
Если в .env задан OPENAI_API_KEY, обзоры генерируются через ChatGPT (OPENAI_MODEL, по умолчанию gpt-4o-mini).
Без ключа приложение работает полностью — используется встроенный шаблонный генератор обзоров на русском языке.
- При локальном запуске Essentia на macOS может потребовать отдельную установку; контейнерный VPS-сценарий использует готовую Linux x86_64 wheel.
- Docker решает проблему системных зависимостей только внутри Linux-контейнера; для Docker Desktop нужен доступный объём памяти и диска.
- Образы целенаправленно собираются под
linux/amd64, что соответствует большинству VPS; на ARM Mac Docker Desktop использует эмуляцию и сборка может быть медленнее. - Образ крупный: Essentia, ffmpeg и модель эмбеддингов RAG увеличивают время сборки и первый запуск.
- Для VPS используется зафиксированная wheel
essentia-tensorflowпод Linux x86_64 и Python 3.11; другие архитектуры потребуют отдельной сборки или другой версии пакета. - При первом обращении к RAG модель эмбеддингов может скачиваться из сети; без сети RAG-индексация не завершится.
- Docker Compose не запускает Ollama автоматически: для Ollama нужен отдельный сервис/хост и корректный
OLLAMA_BASE_URL. - Загруженные аудиофайлы находятся во временной файловой системе контейнера и удаляются после анализа; это не хранилище исходников.
- Для публичного deployment нужно отдельно настроить reverse proxy, TLS, аутентификацию, лимиты запросов и управление секретами.
- Анализ длинных треков (>5 мин) может занимать значительное время.
- При локальном запуске MP3/M4A требуют установленного ffmpeg; в Docker-образ он включён.
- Загруженные файлы удаляются сразу после анализа (не сохраняются на диске).
- Оценка «энергии» — прокси-метрика на основе RMS, BPM, яркости и танцевальности (Essentia не имеет прямого алгоритма «energy» как Spotify).
- AI-обзор без API — шаблонный, не заменяет живого критика.
| Проблема | Решение |
|---|---|
Essentia не установлена |
Проверьте docker compose logs muse-analyse; для локального запуска см. раздел установки Essentia выше |
Не удалось загрузить аудио |
В Docker ffmpeg уже включён; при локальном запуске установите brew install ffmpeg |
Пустой файл / повреждён |
Проверьте целостность аудиофайла |
| OpenAI ошибка | Проверьте ключ; приложение автоматически переключится на шаблон |
MIT.
Essentia распространяется под лицензией AFFERO GPL v3.