README.md

---
title: Audio Sentiment Analysis
emoji: 🎤
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
license: mit
short_description: Analyze emotions from audio with timeline visualization
app_port: 7860
---

# Audio Sentiment Analysis - Setup Guide

## Quick Start

### 1. Install Dependencies
```bash
uv sync
# or
pip install -r requirements.txt
```

### 2. Configure Environment
```bash
# Copy example config
cp .env.example .env

# Edit .env and set your preferred model
# Default: superb/wav2vec2-base-superb-er
```

### 3. Preload Model (Recommended)
```bash
# Download model before starting the app
uv run python preload_model.py

# This downloads ~100MB-1.3GB depending on model
# Cached in ~/.cache/huggingface/
```

### 4. Start the Application

**Terminal 1 - Flask API:**
```bash
uv run python flask_app.py
```

**Terminal 2 - Streamlit Dashboard:**
```bash
uv run streamlit run streamlit_app.py
```

### 5. Access the App
- **Streamlit UI:** http://localhost:8501
- **Flask API:** http://localhost:5000

---

## Available Models

| Model | Emotions | Size | Speed | Accuracy |
|-------|----------|------|-------|----------|
| `superb/wav2vec2-base-superb-er` | 4 | ~100MB | ⚡⚡⚡ | ⭐⭐ |
| `superb/hubert-large-superb-er` | 4 | ~300MB | ⚡⚡ | ⭐⭐⭐ |
| `ehcalabres/wav2vec2-lg-xlsr` | 7 | ~1.2GB | ⚡ | ⭐⭐⭐⭐ |

**To change model:** Edit `MODEL_NAME` in `.env` file

---

## Configuration Files

- **`.env`** - Your local configuration (not in git)
- **`.env.example`** - Template with all options
- **`config.py`** - Loads environment variables
- **`models_config.py`** - Model-specific settings

---

## Deployment

### Hugging Face Spaces

1. Push to HF Spaces git repository
2. Set environment variables in Space settings
3. Docker will build automatically
4. Model downloads on first run (or add to Dockerfile)

### Adding Model to Docker Image

Edit `Dockerfile` to preload model:
```dockerfile
RUN python preload_model.py
```

This caches the model in the image so deployment is faster.

---

## Troubleshooting

### Model Download Issues
- Check internet connection
- Verify model name in `.env`
- Check disk space (~2GB free recommended)

### "Model not found" errors
- Run `python preload_model.py` first
- Check HuggingFace Hub is accessible

### Slow processing
- Use smaller model (wav2vec2-base)
- Reduce `CHUNK_DURATION` in `.env`
- Consider GPU if available

---

## File Structure

```
.
├── flask_app.py           # Flask API backend
├── streamlit_app.py       # Streamlit dashboard
├── audio_processor.py     # Audio processing logic
├── config.py              # Configuration loader
├── models_config.py       # Model definitions
├── preload_model.py       # Model download script
├── .env                   # Your settings (gitignored)
├── .env.example           # Settings template
├── requirements.txt       # Python dependencies
├── input/                 # Example audio files
└── uploads/               # Temporary uploads (gitignored)
```