README.md

---
title: AI Animation & Voice Studio
emoji: 🎬
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
suggested_hardware: cpu-upgrade
suggested_storage: large
pinned: true
license: apache-2.0
short_description: "Create mathematical animations with AI-powered using Manim"
tags:
  - text-to-speech
  - animation
  - mathematics
  - manim
  - ai-voice
  - educational
  - visualization
models:
  - kokoro-onnx/kokoro-v0_19
datasets: []
startup_duration_timeout: 30m
fullWidth: true
header: default
disable_embedding: false
preload_from_hub: []
---

# AI Animation & Voice Studio 🎬

A powerful application that combines AI-powered text-to-speech with mathematical animation generation using Manim and Kokoro TTS. Create stunning educational content with synchronized voice narration and mathematical visualizations.

## 🚀 Features

- **Text-to-Speech**: High-quality voice synthesis using Kokoro ONNX models
- **Mathematical Animations**: Create stunning mathematical visualizations with Manim
- **LaTeX Support**: Full LaTeX rendering capabilities with TinyTeX
- **Interactive Interface**: User-friendly Gradio web interface
- **Audio Processing**: Advanced audio manipulation with FFmpeg and SoX

## 🛠️ Technology Stack

- **Frontend**: Gradio for interactive web interface
- **Backend**: Python with FastAPI/Flask
- **Animation**: Manim (Mathematical Animation Engine)
- **TTS**: Kokoro ONNX for text-to-speech synthesis
- **LaTeX**: TinyTeX for mathematical typesetting
- **Audio**: FFmpeg, SoX, PortAudio for audio processing
- **Deployment**: Docker container optimized for Hugging Face Spaces

## 📦 Models

This application uses the following pre-trained models:

- **Kokoro TTS**: `kokoro-v0_19.onnx` - High-quality neural text-to-speech model
- **Voice Models**: `voices.bin` - Voice embedding models for different speaker characteristics

Models are automatically downloaded during the Docker build process from the official releases.

## 🏃‍♂️ Quick Start

### Using Hugging Face Spaces

1. Visit the [Space](https://huggingface.co/spaces/your-username/ai-animation-voice-studio)
2. Wait for the container to load (initial startup may take 3-5 minutes due to model loading)
3. Upload your script or enter text directly
4. Choose animation settings and voice parameters
5. Generate your animated video with AI narration!

### Local Development

```bash
# Clone the repository
git clone https://huggingface.co/spaces/your-username/ai-animation-voice-studio
cd ai-animation-voice-studio

# Build the Docker image
docker build -t ai-animation-studio .

# Run the container
docker run -p 7860:7860 ai-animation-studio
```

Access the application at `http://localhost:7860`

### Environment Setup

Create a `.env` file with your configuration:

```env
# Application settings
DEBUG=false
MAX_WORKERS=4

# Model settings
MODEL_PATH=/app/models
CACHE_DIR=/tmp/cache

# Optional: API keys if needed
# OPENAI_API_KEY=your_key_here
```

## 🎯 Usage Examples

### Basic Text-to-Speech

```python
# Example usage in your code
from src.tts import generate_speech

audio = generate_speech(
    text="Hello, this is a test of the text-to-speech system",
    voice="default",
    speed=1.0
)
```

### Mathematical Animation

```python
# Example Manim scene
from manim import *

class Example(Scene):
    def construct(self):
        # Your animation code here
        pass
```

## 📁 Project Structure

```
├── src/                    # Source code
│   ├── tts/               # Text-to-speech modules
│   ├── manim_scenes/      # Manim animation scenes
│   └── utils/             # Utility functions
├── models/                # Pre-trained models (auto-downloaded)
├── output/                # Generated content output
├── requirements.txt       # Python dependencies
├── Dockerfile            # Container configuration
├── gradio_app.py         # Main application entry point
└── README.md             # This file
```

## ⚙️ Configuration

### Docker Environment Variables

- `GRADIO_SERVER_NAME`: Server host (default: 0.0.0.0)
- `GRADIO_SERVER_PORT`: Server port (default: 7860)
- `PYTHONPATH`: Python path configuration
- `HF_HOME`: Hugging Face cache directory

### Application Settings

Modify settings in your `.env` file or through environment variables:

- Model parameters
- Audio quality settings
- Animation render settings
- Cache configurations

## 🔧 Development

### Prerequisites

- Docker and Docker Compose
- Python 3.12+
- Git

### Setting Up Development Environment

```bash
# Install dependencies locally for development
pip install -r requirements.txt

# Run tests (if available)
python -m pytest tests/

# Format code
black .
isort .

# Lint code
flake8 .
```

### Building and Testing

```bash
# Build the Docker image
docker build -t your-app-name:dev .

# Test the container locally
docker run --rm -p 7860:7860 your-app-name:dev

# Check container health
docker run --rm your-app-name:dev python -c "import src; print('Import successful')"
```

## 📊 Performance & Hardware

### Recommended Specs for Hugging Face Spaces

- **Hardware**: `cpu-upgrade` (recommended for faster rendering)
- **Storage**: `small` (sufficient for models and temporary files)
- **Startup Time**: ~3-5 minutes (due to model loading and TinyTeX setup)
- **Memory Usage**: ~2-3GB during operation

### System Requirements

- **Memory**: Minimum 2GB RAM, Recommended 4GB+
- **CPU**: Multi-core processor recommended for faster animation rendering
- **Storage**: ~1.5GB for models and dependencies
- **Network**: Stable connection for initial model downloads

### Optimization Tips

- Models are cached after first download
- Gradio interface uses efficient streaming for large outputs
- Docker multi-stage builds minimize final image size
- TinyTeX installation is optimized for essential packages only

## 🐛 Troubleshooting

### Common Issues

**Build Failures**:
```bash
# Clear Docker cache if build fails
docker system prune -a
docker build --no-cache -t your-app-name .
```

**Model Download Issues**:
- Check internet connection
- Verify model URLs are accessible
- Models will be re-downloaded if corrupted

**Memory Issues**:
- Reduce batch sizes in configuration
- Monitor memory usage with `docker stats`

**Audio Issues**:
- Ensure audio drivers are properly installed
- Check PortAudio configuration

### Getting Help

1. Check the [Discussions](https://huggingface.co/spaces/your-username/ai-animation-voice-studio/discussions) tab
2. Review container logs in the Space settings
3. Enable debug mode in configuration
4. Report issues in the Community tab

### Common Configuration Issues

**Space Configuration**:
- Ensure `app_port: 7860` is set in README.md front matter
- Check that `sdk: docker` is properly configured
- Verify hardware suggestions match your needs

**Model Loading**:
- Models download automatically on first run
- Check Space logs for download progress
- Restart Space if models fail to load

## 🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

### Code Style

- Follow PEP 8 for Python code
- Use Black for code formatting
- Add docstrings for functions and classes
- Include type hints where appropriate

## 📄 License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Manim Community](https://www.manim.community/) for the animation engine
- [Kokoro TTS](https://github.com/thewh1teagle/kokoro-onnx) for text-to-speech models
- [Gradio](https://gradio.app/) for the web interface framework
- [Hugging Face](https://huggingface.co/) for hosting and infrastructure

## 📞 Contact

- **Author**: Your Name
- **Email**: [email protected]
- **GitHub**: [@your-username](https://github.com/your-username)
- **Hugging Face**: [@your-username](https://huggingface.co/your-username)

---

*Built with ❤️ for the open-source community*