mixvideo-v2/cargos/tvai/README.md

# TVAI - Topaz Video AI Integration Library

A Rust library for integrating with Topaz Video AI to perform video and image enhancement including super-resolution upscaling and frame interpolation.

## Features

- 🎬 **Video Super-Resolution**: Upscale videos using AI models
- 🎞️ **Frame Interpolation**: Create smooth slow motion effects
- 🖼️ **Image Upscaling**: Enhance image resolution and quality
- ⚡ **GPU Acceleration**: CUDA and hardware encoding support
- 🔧 **Multiple AI Models**: 16 upscaling and 4 interpolation models
- 📦 **Batch Processing**: Process multiple files efficiently
- 🎛️ **Flexible Configuration**: Fine-tune processing parameters

## Requirements

- [Topaz Video AI](https://www.topazlabs.com/topaz-video-ai) installed
- Rust 1.70+ 
- FFmpeg (included with Topaz Video AI)
- Optional: CUDA-compatible GPU for acceleration

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
tvai = "0.1.0"
```

## Quick Start

### Video Upscaling

```rust
use tvai::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Quick 2x upscaling
    quick_upscale_video(
        std::path::Path::new("input.mp4"),
        std::path::Path::new("output.mp4"),
        2.0,
    ).await?;
    
    Ok(())
}
```

### Image Upscaling

```rust
use tvai::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Quick 4x image upscaling
    quick_upscale_image(
        std::path::Path::new("photo.jpg"),
        std::path::Path::new("photo_4x.png"),
        4.0,
    ).await?;
    
    Ok(())
}
```

### Advanced Usage

```rust
use tvai::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Detect Topaz installation
    let topaz_path = detect_topaz_installation()
        .ok_or("Topaz Video AI not found")?;
    
    // Create configuration
    let config = TvaiConfig::builder()
        .topaz_path(topaz_path)
        .use_gpu(true)
        .build()?;
    
    // Create processor
    let processor = TvaiProcessor::new(config)?;
    
    // Custom upscaling parameters
    let params = VideoUpscaleParams {
        scale_factor: 2.0,
        model: UpscaleModel::Iris3,
        compression: 0.0,
        blend: 0.1,
        quality_preset: QualityPreset::HighQuality,
    };
    
    // Process video
    let result = processor.upscale_video(
        std::path::Path::new("input.mp4"),
        std::path::Path::new("output.mp4"),
        params,
    ).await?;
    
    println!("Processing completed in {:?}", result.processing_time);
    Ok(())
}
```

## AI Models

### Upscaling Models

- **Iris v3** - Best general purpose model
- **Nyx v3** - Optimized for portraits
- **Theia Fidelity v4** - Old content restoration
- **Gaia HQ v5** - Game/CG content
- **Proteus v4** - Problem footage repair
- And more...

### Interpolation Models

- **Apollo v8** - High quality interpolation
- **Chronos v2** - Animation content
- **Apollo Fast v1** - Fast processing
- **Chronos Fast v3** - Fast animation

## Presets

The library includes optimized presets for common use cases:

```rust
// Video presets
let old_video_params = VideoUpscaleParams::for_old_video();
let game_params = VideoUpscaleParams::for_game_content();
let animation_params = VideoUpscaleParams::for_animation();
let portrait_params = VideoUpscaleParams::for_portrait();

// Image presets
let photo_params = ImageUpscaleParams::for_photo();
let artwork_params = ImageUpscaleParams::for_artwork();
let screenshot_params = ImageUpscaleParams::for_screenshot();
```

## System Detection

```rust
// Detect Topaz installation
let topaz_path = detect_topaz_installation();

// Check GPU support
let gpu_info = detect_gpu_support();

// Check FFmpeg availability
let ffmpeg_info = detect_ffmpeg();
```

## Error Handling

The library uses the `anyhow` crate for error handling:

```rust
use tvai::*;

match quick_upscale_video(input, output, 2.0).await {
    Ok(result) => println!("Success: {:?}", result),
    Err(TvaiError::TopazNotFound(path)) => {
        eprintln!("Topaz not found at: {}", path);
    },
    Err(TvaiError::FfmpegError(msg)) => {
        eprintln!("FFmpeg error: {}", msg);
    },
    Err(e) => eprintln!("Other error: {}", e),
}
```

## Development Status

✅ **COMPLETE** - All core features implemented and tested!

- [x] Basic project structure
- [x] FFmpeg management
- [x] Core processor framework
- [x] Video upscaling implementation (16 AI models)
- [x] Frame interpolation implementation (4 AI models)
- [x] Image upscaling implementation
- [x] Batch processing (videos and images)
- [x] Progress callbacks and monitoring
- [x] Global configuration management
- [x] Preset management system
- [x] Performance optimization
- [x] Enhanced error handling
- [x] Comprehensive testing (unit + integration + benchmarks)
- [x] Complete documentation (API + User Guide)

## Documentation

- 📖 [API Documentation](docs/API.md) - Complete API reference
- 📚 [User Guide](docs/USER_GUIDE.md) - Comprehensive usage guide
- 🔧 [Examples](examples/) - Working code examples
- 🧪 [Tests](tests/) - Integration tests
- 📊 [Benchmarks](benches/) - Performance benchmarks

## Performance

The library is optimized for performance with:

- **GPU Acceleration** - CUDA and hardware encoding support
- **Concurrent Processing** - Configurable parallel operations
- **Memory Management** - Efficient temporary file handling
- **Smart Caching** - Intelligent resource utilization
- **Progress Monitoring** - Real-time performance tracking

Run benchmarks with:
```bash
cargo bench
```

## Testing

Comprehensive test suite including:

- **Unit Tests** - Core functionality testing
- **Integration Tests** - End-to-end workflow testing
- **Benchmark Tests** - Performance validation

Run tests with:
```bash
cargo test
cargo test --release  # For performance tests
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development Setup

1. Install Rust 1.70+
2. Install Topaz Video AI
3. Clone the repository
4. Run tests: `cargo test`
5. Run examples: `cargo run --example basic_usage`

## Changelog

### v0.1.0 (Current)

- ✅ Complete video processing (upscaling + interpolation)
- ✅ Complete image processing (upscaling + batch operations)
- ✅ 16 AI upscaling models + 4 interpolation models
- ✅ Global configuration and preset management
- ✅ Performance monitoring and optimization
- ✅ Enhanced error handling with user-friendly messages
- ✅ Comprehensive documentation and examples
- ✅ Full test coverage (unit + integration + benchmarks)