README.md

---
language: en
license: mit
tags:
- music
- audio-features
- popularity-prediction
- random-forest
- regression
- spotify
library_name: sklearn
pipeline_tag: tabular-regression
---

# 🎵 Acoustic Hit Predictor v1.0

Модель машинного обучения для прогнозирования популярности музыкальных треков на основе акустических характеристик из Spotify API.

## 📊 Описание модели

**Random Forest Regressor** обученная на 114,000 треков для предсказания популярности (0-100).

### Параметры модели:
- `n_estimators`: 50
- `max_depth`: 30
- `min_samples_split`: 5
- `min_samples_leaf`: 2
- `max_features`: 'sqrt'

## 📈 Метрики качества

| Метрика | Train | Test | Оценка |
|---------|-------|------|--------|
| MAE | 6.40 | 11.44 | ✅ Хорошо |
| R² | - | 0.52 | ⚠️ Средне |
| Стабильность CV | 0.98% | - | ✅ Отлично |

**Погрешность:** ±11 пунктов популярности в среднем

## 🎯 Основные характеристики

- ⚡ **Быстрый инференс:** ~1ms на трек
- 📊 **Признаков:** 30 (оригинальные + производные)
- ⏱️ **Время обучения:** 67.3 минуты
- 💾 **Размер:** 231 MB

## 🔍 Feature Importance

### Топ-5 факторов популярности:
1. **Danceability** — главный драйвер (среднее: 0.68)
2. **Energy** — умеренное влияние (среднее: 0.58)
3. **Valence** — позитивность (среднее: 0.47)
4. **Loudness** — технический фактор
5. **Tempo** — оптимально 110-130 BPM

## 💪 Сильные стороны

- ✅ Стабильная работа на средних значениях популярности (40-65)
- ✅ Хорошая генерализация (MAE 10.74 vs 11.44)
- ✅ Правильное понимание роли танцевальности
- ✅ Быстрая batch-обработка

## ⚠️ Слабые стороны

- Консервативность (редко предсказывает > 65)
- Проблемы с мега-хитами (popularity > 80)
- Систематическая недооценка в 70% случаев
- Не учитывает временной и культурный контекст

## 📥 Использование

```python
import pickle
import pandas as pd

# Загрузка модели
with open('final_random_forest_model.pkl', 'rb') as f:
    model = pickle.load(f)

# Подготовка данных (пример)
features = pd.DataFrame({
    'danceability': [0.7],
    'energy': [0.8],
    'loudness': [-5.0],
    'speechiness': [0.05],
    'acousticness': [0.1],
    'instrumentalness': [0.0],
    'liveness': [0.1],
    'valence': [0.6],
    'tempo': [120.0],
    'duration_ms': [200000],
    'key': [5],
    'mode': [1],
    'time_signature': [4]
    # + производные признаки (см. feature engineering)
})

# Предсказание
popularity = model.predict(features)
print(f"Предсказанная популярность: {popularity[0]:.1f}/100")
```

## 🎯 Интерпретация результатов

```
Предсказанная популярность:
  0-30  → ❌ Слабый потенциал
  30-50 → ⚠️ Средний потенциал
  50-70 → ✅ Хороший потенциал
  70+   → 🎯 Высокий потенциал (модель редко так предсказывает)
```

## ✅ Подходит для:
- **Независимых артистов** — первичная оценка потенциала трека
- **Продюсеров** — сравнение разных версий композиции
- **A&R менеджеров** — скрининг демо-материалов
- **Исследователей** — анализ факторов популярности

## 🚫 Ограничения:
- Не предсказывает мега-хиты (80+)
- Не учитывает маркетинг и промо
- Не заменяет экспертное мнение
- Работает только на аудио-характеристиках

## 📚 Дополнительные ресурсы

- **GitHub репозиторий:** [Acoustic-Hit-Predictor](https://github.com/mmobik/Acoustic-Hit-Predictor-From-Audio-Features-to-Chart-Success)
- **Детальный анализ:** См. `reports/model_analysis.md` в репозитории
- **Техническая спецификация:** См. `TECHNICAL_SPECIFICATION.md`

## 📄 Лицензия

MIT License

## 👨‍💻 Автор

**mmobik**
- GitHub: [@mmobik](https://github.com/mmobik)

## 📅 Версия

- **Дата обучения:** Декабрь 2024
- **Версия:** 1.0
- **Статус:** MVP (Minimum Viable Product)

## 🔄 Планируемые улучшения

1. Добавление большего количества треков с popularity > 80
2. Калибровка предсказаний для крайних значений
3. Временные признаки (год релиза, сезонность)
4. Метаданные (жанр, лейбл, популярность артиста)