🎵 Soundcharts Forecast App

A forecasting application to predict artist metrics evolution (Instagram, Spotify) with confidence intervals, using the Soundcharts API and NBEATS.

🚀 Installation

Prerequisites

• Python 3.11+
• uv - An extremely fast Python package and project manager

Setup

# Clone the repo
git clone https://github.com/IUseAMouse/Soundcharts-Forecast.git
cd Soundcharts-Forecast

# Install dependencies
uv sync
source .venv/bin/activate

🎯 Running the App

# Option 1: Via uv
uv run python run.py

# Option 2: Double-click on run.py (if Python is associated)

The application will automatically open in your browser.

🔐 API Configuration

On first launch, the application will prompt you for your Soundcharts credentials:

• App ID: NAME-API-SOMENUMBER
• API Key: Your API key

These credentials will be saved locally in a .env file (not versioned).

📊 Features

1. Artist Search: Search for any artist by name
2. Data Collection: Automatic retrieval of Instagram and Spotify metrics
3. Local Cache: Data is saved to avoid repeated API calls
4. Forecasting: 6-month predictions using Granite TTM R2 with bootstrap confidence intervals
5. Confidence Intervals: Visualization of quantiles (50%, 90%)

📁 Project Structure

soundcharts-forecast/
├── run.py              # Entry point
├── src/
│   ├── app.py          # Streamlit application
│   ├── api/            # Soundcharts API client
│   ├── data/           # Cache and storage
│   ├── forecast/       # NBEATS module
│   └── ui/             # UI components
└── data/               # Local cache (gitignored)

⚠️ Important Notes

• Never push the .env file or the data/ folder
• The application runs on CPU only; GPU is a bonus
• The first run takes a bit longer, this is expected