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 installed
• Rust 1.70+
• FFmpeg (included with Topaz Video AI)
• Optional: CUDA-compatible GPU for acceleration

Installation

Add this to your Cargo.toml:

[dependencies]
tvai = "0.1.0"

Quick Start

Video Upscaling

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

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

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:

// 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

// 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:

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!

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

Documentation

• 📖 API Documentation - Complete API reference
• 📚 User Guide - Comprehensive usage guide
• 🔧 Examples - Working code examples
• 🧪 Tests - Integration tests
• 📊 Benchmarks - 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:

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:

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)