# 🚀 Quick Start - Ensemble TTS Annotation

## ⚡ 5-Minute Setup

### 1. Install Dependencies

```bash
pip install -r requirements.txt
```

### 2. (Optional) Fine-tune emotion2vec on PT-BR data

For best results, fine-tune emotion2vec on VERBO + emoUERJ datasets:

```bash
# Download datasets (see instructions)
python scripts/data/download_ptbr_datasets.py

# Fine-tune (requires datasets downloaded)
python scripts/training/finetune_emotion2vec.py \
    --epochs 20 \
    --batch-size 8 \
    --device cuda \
    --augment
```

**Note**: You can skip this step and use the base model. The system will automatically use the fine-tuned model if available.

### 3. Test Ensemble (Quick Mode - 2 models)

```bash
python scripts/ensemble/annotate_ensemble.py \
    --input marcosremar2/orpheus-tts-portuguese-dataset \
    --mode quick \
    --max-samples 10 \
    --output test_results.parquet
```

**Expected time:** ~2-3 minutes (with GPU) or ~5-10 minutes (CPU)

---

## 📊 Modes Explained

### Quick Mode (2 models)
```bash
--mode quick
```
- **Models**: emotion2vec + SenseVoice
- **Precision**: ~92%
- **Speed**: 2x slower than single model
- **Use case**: Testing, rapid prototyping

### Balanced Mode (3 models) ⭐ RECOMMENDED - OPTION A
```bash
--mode balanced
```
- **Models**: emotion2vec (fine-tuned) + Whisper + SenseVoice
- **Precision**: ~95-97%
- **Speed**: 3x slower
- **Cost-benefit**: OPTIMAL (academic research validated)
- **Use case**: Production, best balance of accuracy and cost

### Full Mode (5 models)
```bash
--mode full
```
- **Models**: emotion2vec + SenseVoice + Whisper + HuBERT + Wav2Vec2
- **Precision**: ~97-98% (+1-3% over balanced)
- **Speed**: 5x slower
- **Cost-benefit**: Marginal gains, high cost
- **Use case**: Research, when maximum accuracy is critical

---

## 🎯 Common Commands

### Annotate Small Sample (Testing)
```bash
python scripts/ensemble/annotate_ensemble.py \
    --input marcosremar2/orpheus-tts-portuguese-dataset \
    --mode balanced \
    --max-samples 100 \
    --device cuda
```

### Annotate Full Dataset
```bash
python scripts/ensemble/annotate_ensemble.py \
    --input marcosremar2/orpheus-tts-portuguese-dataset \
    --mode balanced \
    --device cuda \
    --output data/annotated/full_ensemble.parquet
```

### Use Different Voting Strategy
```bash
python scripts/ensemble/annotate_ensemble.py \
    --input your-dataset \
    --mode balanced \
    --voting confidence  # majority, weighted, or confidence
```

---

## 🔧 Troubleshooting

### CUDA Out of Memory
```bash
# Use CPU instead
--device cpu

# Or reduce batch processing
--max-samples 50
```

### Missing Dependencies
```bash
pip install -r requirements.txt --upgrade
```

### Models Not Loading
```bash
# Check HuggingFace cache
ls ~/.cache/huggingface/hub/

# Clear cache if needed
rm -rf ~/.cache/huggingface/hub/
```

---

## 📈 Expected Results

After annotation, you'll get:

```python
{
  "emotion_label": "happy",
  "emotion_confidence": 0.94,  # High confidence!
  "emotion_agreement": 0.8,    # 80% models agree
  "emotion_votes": "{'happy': 2, 'neutral': 1}"
}
```

---

## ⏱️ Processing Time Estimates

**Dataset: 118,000 samples**

| Mode | GPU (RTX 3090) | CPU (16 cores) |
|------|----------------|----------------|
| Quick | ~2-3 hours | ~8-10 hours |
| Balanced | ~4-6 hours | ~12-16 hours |
| Full | ~8-12 hours | ~24-30 hours |

---

## 🎓 Next Steps

1. ✅ Test with small sample
2. ✅ Review results
3. ✅ Run on full dataset
4. 📊 Evaluate quality
5. 🚀 Use for TTS fine-tuning

See [README.md](README.md) for full documentation.