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.

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.

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.

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

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

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

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

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

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

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

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:

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

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

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

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

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