README.md

metadata

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

uv sync
# or
pip install -r requirements.txt

2. Configure Environment

# Copy example config
cp .env.example .env

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

3. Preload Model (Recommended)

# 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:

uv run python flask_app.py

Terminal 2 - Streamlit Dashboard:

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:

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)