mixvideo-v2/cargos/tvai/docs/USER_GUIDE.md

TVAI Library User Guide

Getting Started

Installation

Add TVAI to your Cargo.toml:

[dependencies]
tvai = "0.1.0"

Prerequisites

1. Topaz Video AI - Download and install from Topaz Labs
2. GPU Drivers - Latest NVIDIA or AMD drivers for GPU acceleration
3. Rust 1.70+ - For building the library

Quick Start

use tvai::*;

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

Common Use Cases

1. Video Enhancement

Upscaling Old Videos

use tvai::*;

let params = VideoUpscaleParams::for_old_video();
let mut processor = create_processor().await?;

let result = processor.upscale_video(
    Path::new("old_video.mp4"),
    Path::new("restored_video.mp4"),
    params,
    Some(&progress_callback),
).await?;

println!("Enhanced in {:?}", result.processing_time);

Creating Slow Motion

let params = InterpolationParams::for_slow_motion(30, 4.0); // 30fps -> 120fps
let result = processor.interpolate_video(
    Path::new("normal_speed.mp4"),
    Path::new("slow_motion.mp4"),
    params,
    Some(&progress_callback),
).await?;

Complete Enhancement

let enhance_params = VideoEnhanceParams {
    upscale: Some(VideoUpscaleParams::for_old_video()),
    interpolation: Some(InterpolationParams::for_slow_motion(24, 2.0)),
};

let result = processor.enhance_video(
    Path::new("input.mp4"),
    Path::new("enhanced.mp4"),
    enhance_params,
    Some(&progress_callback),
).await?;

2. Image Enhancement

Batch Photo Enhancement

let image_paths = vec![
    PathBuf::from("photo1.jpg"),
    PathBuf::from("photo2.jpg"),
    PathBuf::from("photo3.jpg"),
];

let params = ImageUpscaleParams::for_photo();
let results = processor.batch_upscale_images(
    &image_paths,
    Path::new("output_dir"),
    params,
    Some(&progress_callback),
).await?;

println!("Processed {} images", results.len());

Directory Processing

let results = processor.upscale_directory(
    Path::new("input_photos"),
    Path::new("output_photos"),
    ImageUpscaleParams::for_photo(),
    true, // recursive
    Some(&progress_callback),
).await?;

3. Format Conversion

Image Sequence to Video

let image_paths = collect_image_sequence("frames/")?;
processor.images_to_video(
    &image_paths,
    Path::new("output.mp4"),
    30.0, // fps
    QualityPreset::HighQuality,
    Some(&progress_callback),
).await?;

Video to Image Sequence

let image_paths = processor.video_to_images(
    Path::new("input.mp4"),
    Path::new("frames/"),
    "png",
    95, // quality
    Some(&progress_callback),
).await?;

println!("Extracted {} frames", image_paths.len());

Configuration

Global Settings

Set up global configuration for consistent behavior:

use tvai::config::global_settings;

let settings = global_settings();

// Configure defaults
settings.set_default_use_gpu(true)?;
settings.set_max_concurrent_jobs(2)?;

// Save settings
settings.save_to_file()?;

// Create processor from global settings
let config = settings.create_config()?;
let processor = TvaiProcessor::new(config)?;

Custom Configuration

let config = TvaiConfig::builder()
    .topaz_path("/custom/path/to/topaz")
    .use_gpu(true)
    .temp_dir("/fast/ssd/temp")
    .force_topaz_ffmpeg(true)
    .build()?;

let processor = TvaiProcessor::new(config)?;

Model Selection Guide

Upscaling Models

Model	Best For	Scale	Description
Iris v3	General purpose	1-4x	Best overall quality
Nyx v3	Portraits	1-4x	Face-optimized
Theia Fidelity v4	Old content	2x	Restoration focused
Gaia HQ v5	Games/CG	1-4x	Sharp details
Proteus v4	Problem footage	1-4x	Artifact repair

Interpolation Models

Model	Best For	Description
Apollo v8	High quality	Best overall interpolation
Chronos v2	Animation	Cartoon/anime content
Apollo Fast v1	Speed	Faster processing
Chronos Fast v3	Fast animation	Quick animation processing

Performance Optimization

GPU Optimization

use tvai::utils::GpuManager;

// Check GPU suitability
if GpuManager::is_gpu_suitable_for_ai() {
    println!("GPU is suitable for AI processing");
    
    // Get detailed info
    let gpu_info = GpuManager::detect_detailed_gpu_info();
    println!("Recommended memory limit: {:?} MB", 
             gpu_info.recommended_settings.memory_limit_mb);
}

Performance Monitoring

use tvai::utils::{PerformanceMonitor, optimize_for_system};

// Create optimized settings
let settings = optimize_for_system();
let mut monitor = PerformanceMonitor::new(settings);

// Process with monitoring
let _permit = monitor.acquire_slot().await?;
// ... perform processing ...

// Get recommendations
let summary = monitor.get_summary();
for recommendation in summary.recommendations {
    println!("💡 {}", recommendation);
}

Memory Management

// Use smaller chunk sizes for limited memory
let settings = PerformanceSettings {
    chunk_size_mb: 50, // Smaller chunks
    max_concurrent_ops: 1, // Single operation
    processing_mode: ProcessingMode::MemoryEfficient,
    ..Default::default()
};

Error Handling

Comprehensive Error Handling

match processor.upscale_video(input, output, params, None).await {
    Ok(result) => {
        println!("✅ Success: {:?}", result.processing_time);
    }
    Err(error) => {
        eprintln!("❌ Error: {}", error.category());
        eprintln!("{}", error.user_friendly_message());
        
        if error.is_recoverable() {
            eprintln!("💡 This error might be recoverable with different settings");
        }
    }
}

Common Error Solutions

Topaz Not Found

Error: Topaz Video AI not found
Solution: Install Topaz Video AI or set correct path

GPU Errors

Error: CUDA out of memory
Solution: Reduce quality settings or disable GPU

Permission Denied

Error: Cannot write to output directory
Solution: Run as administrator or check permissions

Progress Tracking

Simple Progress Bar

use std::io::{self, Write};

let progress_callback: ProgressCallback = Box::new(|progress| {
    let percentage = (progress * 100.0) as u32;
    print!("\rProgress: [");
    for i in 0..50 {
        if i < percentage / 2 {
            print!("=");
        } else {
            print!(" ");
        }
    }
    print!("] {}%", percentage);
    io::stdout().flush().unwrap();
});

Detailed Progress Tracking

let progress_callback: ProgressCallback = Box::new(|progress| {
    let percentage = (progress * 100.0) as u32;
    let eta = estimate_time_remaining(progress);
    println!("Progress: {}% - ETA: {:?}", percentage, eta);
});

Best Practices

1. File Management

// Always validate input files
processor.validate_input_file(input_path)?;
processor.validate_output_path(output_path)?;

// Use temporary files for intermediate processing
let temp_path = processor.create_unique_temp_path("intermediate.mp4");
// ... process to temp file ...
std::fs::rename(temp_path, final_output)?;

2. Resource Management

// Use RAII for automatic cleanup
{
    let mut processor = TvaiProcessor::new(config)?;
    // Processing happens here
    // Processor automatically cleans up when dropped
}

3. Batch Processing

// Process in batches to avoid memory issues
let chunk_size = 10;
for chunk in image_paths.chunks(chunk_size) {
    let results = processor.batch_upscale_images(
        chunk,
        output_dir,
        params.clone(),
        Some(&progress_callback),
    ).await?;
    
    // Process results or save state
}

4. Error Recovery

// Implement retry logic for recoverable errors
let mut attempts = 0;
let max_attempts = 3;

loop {
    match processor.upscale_video(input, output, params.clone(), None).await {
        Ok(result) => break Ok(result),
        Err(error) if error.is_recoverable() && attempts < max_attempts => {
            attempts += 1;
            eprintln!("Attempt {} failed, retrying...", attempts);
            tokio::time::sleep(Duration::from_secs(1)).await;
        }
        Err(error) => break Err(error),
    }
}

Troubleshooting

Common Issues

1. Slow Processing

   • Enable GPU acceleration
   • Use faster models (Apollo Fast, Chronos Fast)
   • Reduce quality settings

2. Out of Memory

   • Reduce chunk size
   • Lower quality preset
   • Process smaller files

3. Poor Quality Results

   • Use appropriate model for content type
   • Adjust compression and blend parameters
   • Use higher quality presets

4. File Format Issues

   • Convert to supported formats first
   • Check file corruption
   • Verify file permissions

Getting Help

1. Check error messages and suggestions
2. Review the API documentation
3. Run the examples to verify setup
4. Check system requirements and GPU drivers