README.md

---
title: Kokoro TTS API - Professional & Fast
emoji: 🎤
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
---

# Kokoro TTS Service - Professional & Lightning Fast ⚡

**10x faster than XTTS** | Emotional voices for storytelling | CPU-optimized

## 🚀 Why Kokoro?

- ⚡ **Lightning Fast**: Generates audio in real-time on CPU
- 🎭 **Emotional Expression**: Perfect for audiobooks & storytelling
- 💾 **Lightweight**: Only 82M parameters (vs XTTS 400M+)
- 🔒 **Secure**: Supabase authentication with user management
- 📊 **High Quota**: 50 generations/day (vs 3 with XTTS)

## 🔐 Admin Credentials
```
Username: madhab
Password: Madhab@Studify2024!
```

## 📦 Setup

### 1. Supabase Database
Run `supabase_schema.sql` in your Supabase SQL Editor

### 2. Install & Run
```bash
pip install -r requirements.txt
python app.py
```

## 🎤 Available Voices

| Voice | Description | Best For |
|-------|-------------|----------|
| `af_heart` | American Female (warm) | General narration |
| `af_bella` | American Female (professional) | Educational content |
| `am_adam` | American Male (confident) | Business/Tech |
| `am_michael` | American Male (friendly) | Casual/Conversational |
| `bf_emma` | British Female (elegant) | Formal content |
| `bf_isabella` | British Female (storytelling) | **Audiobooks/Stories** ⭐ |

## 📡 API Usage

### Generate Speech (Fast!)
```bash
curl -X POST http://localhost:7860/api/generate \
  -F "username=madhab" \
  -F "password=Madhab@Studify2024!" \
  -F "text=The concept of artificial intelligence has evolved significantly over the past few decades." \
  -F "voice=bf_isabella" \
  -F "speed=1.0" \
  --output output.wav
```

### Check Quota
```bash
curl -X POST http://localhost:7860/api/quota \
  -F "username=madhab" \
  -F "password=Madhab@Studify2024!"
```

### Create New User (Admin)
```bash
curl -X POST http://localhost:7860/api/admin/create-user \
  -F "admin_username=madhab" \
  -F "admin_password=Madhab@Studify2024!" \
  -F "new_username=student" \
  -F "new_password=SecurePass123!" \
  -F "role=user" \
  -F "daily_limit=50"
```

## ⚡ Performance Comparison

| Model | Speed | Quality | CPU Usage | Max Chars |
|-------|-------|---------|-----------|-----------|
| **Kokoro** | **10x** | High | Low | 5000 |
| XTTS v2 | 1x | Very High | High | 3000 |
| Bark | 0.5x | High | Very High | 1000 |

## 🎯 Perfect For

- ✅ Long-form educational content
- ✅ Audiobook narration
- ✅ Real-time reader mode in apps
- ✅ Storytelling with emotion
- ✅ Multi-voice projects

## 🔧 Integration Example (Flutter)

Update your `AIService.dart`:
```dart
final response = await http.post(
  Uri.parse('https://your-space.hf.space/api/generate'),
  headers: {'Content-Type': 'multipart/form-data'},
  body: {
    'username': 'your_username',
    'password': 'your_password',
    'text': text,
    'voice': 'bf_isabella',  // Storytelling voice
    'speed': '1.0'
  }
);
```

## 📊 Quota System

| Role | Daily Limit | Speed Limit |
|------|-------------|-------------|
| User | 50 generations | Normal |
| Premium | Custom | Priority |
| Admin | Unlimited | Highest |

## 🌐 Deploy to Hugging Face

1. Push to GitHub
2. Create new Space on Hugging Face
3. Set secrets: `SUPABASE_URL`, `SUPABASE_KEY`
4. Deploy!

---

**Built for [Studify](https://github.com/your-repo)** - Making education accessible through AI