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

# TVAI Library User Guide

## Getting Started

### Installation

Add TVAI to your `Cargo.toml`:

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

### Prerequisites

1. **Topaz Video AI** - Download and install from [Topaz Labs](https://www.topazlabs.com/topaz-video-ai)
2. **GPU Drivers** - Latest NVIDIA or AMD drivers for GPU acceleration
3. **Rust 1.70+** - For building the library

### Quick Start

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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:

```rust
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

```rust
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

```rust
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

```rust
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

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

```rust
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

```rust
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

```rust
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

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

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

### 3. Batch Processing

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

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