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

This library is currently in development. The following features are planned:

- [x] Basic project structure
- [x] FFmpeg management
- [x] Core processor framework
- [ ] Video upscaling implementation
- [ ] Frame interpolation implementation
- [ ] Image upscaling implementation
- [ ] Batch processing
- [ ] Progress callbacks
- [ ] Comprehensive testing

## License

MIT License - see LICENSE file for details.

## Contributing

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