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

# TVAI Library API Documentation

## Overview

The TVAI library provides a comprehensive Rust interface for Topaz Video AI, enabling video and image enhancement through AI-powered super-resolution and frame interpolation.

## Core Components

### TvaiProcessor

The main processor for all video and image operations.

```rust
use tvai::*;

// Create configuration
let config = TvaiConfig::builder()
    .topaz_path("/path/to/topaz")
    .use_gpu(true)
    .build()?;

// Create processor
let mut processor = TvaiProcessor::new(config)?;
```

#### Video Processing Methods

- `upscale_video()` - AI-powered video super-resolution
- `interpolate_video()` - Frame interpolation for slow motion
- `enhance_video()` - Combined upscaling and interpolation
- `images_to_video()` - Convert image sequence to video
- `video_to_images()` - Extract frames from video

#### Image Processing Methods

- `upscale_image()` - AI-powered image super-resolution
- `batch_upscale_images()` - Process multiple images
- `upscale_directory()` - Process entire directories
- `convert_image_format()` - Format conversion
- `resize_image()` - Traditional geometric scaling

### Configuration Management

#### TvaiConfig

Main configuration for the processor.

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

#### Global Settings

Persistent global configuration.

```rust
use tvai::config::global_settings;

let settings = global_settings();
settings.set_default_use_gpu(true)?;
settings.set_max_concurrent_jobs(2)?;
```

### AI Models

#### Upscaling Models

- `Iris3` - Best general purpose model
- `Nyx3` - Optimized for portraits
- `Thf4` - Old content restoration
- `Ghq5` - Game/CG content
- `Prob4` - Problem footage repair
- And 11 more specialized models

#### Interpolation Models

- `Apo8` - High quality interpolation
- `Chr2` - Animation content
- `Apf1` - Fast processing
- `Chf3` - Fast animation

### Parameter Presets

#### Video Presets

```rust
// Built-in presets
let old_video = VideoUpscaleParams::for_old_video();
let game_content = VideoUpscaleParams::for_game_content();
let animation = VideoUpscaleParams::for_animation();
let portrait = VideoUpscaleParams::for_portrait();

// Interpolation presets
let slow_motion = InterpolationParams::for_slow_motion(30, 2.0);
let animation_interp = InterpolationParams::for_animation(24, 2.0);
```

#### Image Presets

```rust
// Built-in presets
let photo = ImageUpscaleParams::for_photo();
let artwork = ImageUpscaleParams::for_artwork();
let screenshot = ImageUpscaleParams::for_screenshot();
let portrait = ImageUpscaleParams::for_portrait();
```

### Preset Management

```rust
use tvai::config::global_presets;

let presets = global_presets();
let preset_manager = presets.lock().unwrap();

// Get preset
if let Some(preset) = preset_manager.get_video_preset("general_2x") {
    // Use preset parameters
}

// List all presets
let video_presets = preset_manager.list_video_presets();
let image_presets = preset_manager.list_image_presets();
```

## Quick Start Functions

### Video Processing

```rust
// Quick 2x upscaling
quick_upscale_video(
    Path::new("input.mp4"),
    Path::new("output.mp4"),
    2.0
).await?;

// Automatic enhancement
auto_enhance_video(
    Path::new("input.mp4"),
    Path::new("enhanced.mp4")
).await?;
```

### Image Processing

```rust
// Quick 2x upscaling
quick_upscale_image(
    Path::new("photo.jpg"),
    Path::new("photo_2x.png"),
    2.0
).await?;

// Automatic enhancement
auto_enhance_image(
    Path::new("photo.jpg"),
    Path::new("enhanced.png")
).await?;

// Batch directory processing
batch_upscale_directory(
    Path::new("input_dir"),
    Path::new("output_dir"),
    2.0,
    true // recursive
).await?;
```

## Performance and Optimization

### GPU Detection

```rust
use tvai::utils::GpuManager;

// Detailed GPU information
let gpu_info = GpuManager::detect_detailed_gpu_info();
println!("CUDA available: {}", gpu_info.cuda_available);
println!("Devices: {}", gpu_info.devices.len());

// Check suitability for AI
let suitable = GpuManager::is_gpu_suitable_for_ai();

// Benchmark performance
let benchmark = GpuManager::benchmark_gpu_performance().await?;
```

### Performance Monitoring

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

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

// Monitor operation
let _permit = monitor.acquire_slot().await?;
let operation_monitor = monitor.start_operation("upscale", 100.0);

// ... perform processing ...

let metrics = operation_monitor.finish(200.0);
monitor.record_metrics(metrics);

// Get performance summary
let summary = monitor.get_summary();
```

## Error Handling

### Error Types

The library provides comprehensive error handling with user-friendly messages:

```rust
match result {
    Ok(output) => println!("Success: {:?}", output),
    Err(error) => {
        println!("Error category: {}", error.category());
        println!("Recoverable: {}", error.is_recoverable());
        println!("User message:\n{}", error.user_friendly_message());
    }
}
```

### Error Categories

- `installation` - Topaz/FFmpeg not found
- `processing` - Processing failures
- `parameter` - Invalid parameters
- `gpu` - GPU-related errors
- `format` - Unsupported formats
- `resources` - Insufficient resources
- `permission` - Permission denied
- `io` - File I/O errors

## System Detection

### Automatic Detection

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

// Detect FFmpeg availability
let ffmpeg_info = detect_ffmpeg();

// Detect GPU support
let gpu_info = detect_gpu_support();
```

### File Information

```rust
// Get video information
let video_info = get_video_info(Path::new("video.mp4")).await?;
println!("Duration: {:?}", video_info.duration);
println!("Resolution: {}x{}", video_info.width, video_info.height);

// Get image information
let image_info = get_image_info(Path::new("image.jpg"))?;
println!("Size: {}x{}", image_info.width, image_info.height);
```

## Progress Tracking

```rust
// Create progress callback
let progress_callback: ProgressCallback = Box::new(|progress| {
    println!("Progress: {:.1}%", progress * 100.0);
});

// Use with processing functions
processor.upscale_video(
    input,
    output,
    params,
    Some(&progress_callback)
).await?;
```

## Temporary File Management

```rust
use tvai::utils::TempFileManager;

let mut temp_manager = TempFileManager::new(None)?;

// Create temporary files
let temp_path = temp_manager.create_temp_path("operation", "temp.mp4");
let unique_path = temp_manager.create_unique_temp_path("output.png");

// Cleanup
temp_manager.cleanup_operation("operation")?;
temp_manager.cleanup_all()?;
```

## Best Practices

1. **Use presets** for common scenarios
2. **Enable GPU** for better performance
3. **Monitor progress** for long operations
4. **Handle errors** gracefully with user-friendly messages
5. **Use global settings** for consistent configuration
6. **Validate parameters** before processing
7. **Clean up** temporary files after processing
8. **Check system requirements** before starting

## Examples

See the `examples/` directory for complete working examples:

- `basic_usage.rs` - Simple getting started example
- `advanced_usage.rs` - Advanced features demonstration
- `video_processing.rs` - Comprehensive video processing
- `image_processing.rs` - Comprehensive image processing
- `convenience_and_optimization.rs` - Convenience features and optimization