# TVAI 库 API 文档

## 概述

TVAI 库为 Topaz Video AI 提供了全面的 Rust 接口，通过 AI 驱动的超分辨率和帧插值实现视频和图像增强。

## 核心组件

### TvaiProcessor

所有视频和图像操作的主处理器。

```rust
use tvai::*;

// 创建配置
let config = TvaiConfig::builder()
    .topaz_path("/topaz/路径")
    .use_gpu(true)
    .build()?;

// 创建处理器
let mut processor = TvaiProcessor::new(config)?;
```

#### 视频处理方法

- `upscale_video()` - AI 驱动的视频超分辨率
- `interpolate_video()` - 慢动作帧插值
- `enhance_video()` - 组合超分辨率和插值
- `images_to_video()` - 图像序列转视频
- `video_to_images()` - 从视频提取帧

#### 图像处理方法

- `upscale_image()` - AI 驱动的图像超分辨率
- `batch_upscale_images()` - 处理多张图像
- `upscale_directory()` - 处理整个目录
- `convert_image_format()` - 格式转换
- `resize_image()` - 传统几何缩放

### 配置管理

#### TvaiConfig

处理器的主配置。

```rust
let config = TvaiConfig::builder()
    .topaz_path("/topaz/路径")
    .use_gpu(true)
    .temp_dir("/自定义/临时目录")
    .force_topaz_ffmpeg(true)
    .build()?;
```

#### 全局设置

持久化的全局配置。

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

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

### AI 模型

#### 超分辨率模型

- `Iris3` - 最佳通用模型
- `Nyx3` - 人像优化
- `Thf4` - 老内容修复
- `Ghq5` - 游戏/CG 内容
- `Prob4` - 问题素材修复
- 以及 11 个其他专业模型

#### 插值模型

- `Apo8` - 高质量插值
- `Chr2` - 动画内容
- `Apf1` - 快速处理
- `Chf3` - 快速动画

### 参数预设

#### 视频预设

```rust
// 内置预设
let old_video = VideoUpscaleParams::for_old_video();
let game_content = VideoUpscaleParams::for_game_content();
let animation = VideoUpscaleParams::for_animation();
let portrait = VideoUpscaleParams::for_portrait();

// 插值预设
let slow_motion = InterpolationParams::for_slow_motion(30, 2.0);
let animation_interp = InterpolationParams::for_animation(24, 2.0);
```

#### 图像预设

```rust
// 内置预设
let photo = ImageUpscaleParams::for_photo();
let artwork = ImageUpscaleParams::for_artwork();
let screenshot = ImageUpscaleParams::for_screenshot();
let portrait = ImageUpscaleParams::for_portrait();
```

### 预设管理

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

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

// 获取预设
if let Some(preset) = preset_manager.get_video_preset("general_2x") {
    // 使用预设参数
}

// 列出所有预设
let video_presets = preset_manager.list_video_presets();
let image_presets = preset_manager.list_image_presets();
```

## 快速开始函数

### 视频处理

```rust
// 快速 2 倍放大
quick_upscale_video(
    Path::new("输入.mp4"),
    Path::new("输出.mp4"),
    2.0
).await?;

// 自动增强
auto_enhance_video(
    Path::new("输入.mp4"),
    Path::new("增强后.mp4")
).await?;
```

### 图像处理

```rust
// 快速 2 倍放大
quick_upscale_image(
    Path::new("照片.jpg"),
    Path::new("照片_2x.png"),
    2.0
).await?;

// 自动增强
auto_enhance_image(
    Path::new("照片.jpg"),
    Path::new("增强后.png")
).await?;

// 批量目录处理
batch_upscale_directory(
    Path::new("输入目录"),
    Path::new("输出目录"),
    2.0,
    true // 递归
).await?;
```

## 性能和优化

### GPU 检测

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

// 详细的 GPU 信息
let gpu_info = GpuManager::detect_detailed_gpu_info();
println!("CUDA 可用: {}", gpu_info.cuda_available);
println!("设备数量: {}", gpu_info.devices.len());

// 检查 AI 适用性
let suitable = GpuManager::is_gpu_suitable_for_ai();

// 基准测试性能
let benchmark = GpuManager::benchmark_gpu_performance().await?;
```

### 性能监控

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

// 创建优化设置
let settings = optimize_for_system();
let mut monitor = PerformanceMonitor::new(settings);

// 监控操作
let _permit = monitor.acquire_slot().await?;
let operation_monitor = monitor.start_operation("upscale", 100.0);

// ... 执行处理 ...

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

// 获取性能摘要
let summary = monitor.get_summary();
```

## 错误处理

### 错误类型

库提供了带有用户友好消息的全面错误处理：

```rust
match result {
    Ok(output) => println!("成功: {:?}", output),
    Err(error) => {
        println!("错误类别: {}", error.category());
        println!("可恢复: {}", error.is_recoverable());
        println!("用户消息:\n{}", error.user_friendly_message());
    }
}
```

### 错误类别

- `installation` - 找不到 Topaz/FFmpeg
- `processing` - 处理失败
- `parameter` - 无效参数
- `gpu` - GPU 相关错误
- `format` - 不支持的格式
- `resources` - 资源不足
- `permission` - 权限被拒绝
- `io` - 文件 I/O 错误

## 系统检测

### 自动检测

```rust
// 检测 Topaz 安装
let topaz_path = detect_topaz_installation();

// 检测 FFmpeg 可用性
let ffmpeg_info = detect_ffmpeg();

// 检测 GPU 支持
let gpu_info = detect_gpu_support();
```

### 文件信息

```rust
// 获取视频信息
let video_info = get_video_info(Path::new("视频.mp4")).await?;
println!("时长: {:?}", video_info.duration);
println!("分辨率: {}x{}", video_info.width, video_info.height);

// 获取图像信息
let image_info = get_image_info(Path::new("图像.jpg"))?;
println!("尺寸: {}x{}", image_info.width, image_info.height);
```

## 进度跟踪

```rust
// 创建进度回调
let progress_callback: ProgressCallback = Box::new(|progress| {
    println!("进度: {:.1}%", progress * 100.0);
});

// 与处理函数一起使用
processor.upscale_video(
    input,
    output,
    params,
    Some(&progress_callback)
).await?;
```

## 临时文件管理

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

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

// 创建临时文件
let temp_path = temp_manager.create_temp_path("操作", "临时.mp4");
let unique_path = temp_manager.create_unique_temp_path("输出.png");

// 清理
temp_manager.cleanup_operation("操作")?;
temp_manager.cleanup_all()?;
```

## 最佳实践

1. **使用预设** 处理常见场景
2. **启用 GPU** 获得更好性能
3. **监控进度** 处理长时间操作
4. **优雅处理错误** 使用用户友好消息
5. **使用全局设置** 保持一致配置
6. **验证参数** 在处理前
7. **清理** 处理后的临时文件
8. **检查系统要求** 开始前

## 示例

查看 `examples/` 目录获取完整的工作示例：

- `basic_usage.rs` - 简单入门示例
- `advanced_usage.rs` - 高级功能演示
- `video_processing.rs` - 全面的视频处理
- `image_processing.rs` - 全面的图像处理
- `convenience_and_optimization.rs` - 便捷功能和优化

## 参数详解

### VideoUpscaleParams

```rust
pub struct VideoUpscaleParams {
    pub scale_factor: f32,        // 缩放倍数 (1.0-4.0)
    pub model: UpscaleModel,      // AI 模型
    pub compression: f32,         // 压缩设置 (-1.0 到 1.0)
    pub blend: f32,              // 混合设置 (0.0 到 1.0)
    pub quality_preset: QualityPreset, // 质量预设
}
```

### ImageUpscaleParams

```rust
pub struct ImageUpscaleParams {
    pub scale_factor: f32,        // 缩放倍数 (1.0-4.0)
    pub model: UpscaleModel,      // AI 模型
    pub compression: f32,         // 压缩设置 (-1.0 到 1.0)
    pub blend: f32,              // 混合设置 (0.0 到 1.0)
    pub output_format: ImageFormat, // 输出格式
}
```

### InterpolationParams

```rust
pub struct InterpolationParams {
    pub input_fps: u32,           // 输入帧率
    pub multiplier: f32,          // 倍数 (1.0-8.0)
    pub model: InterpolationModel, // 插值模型
    pub target_fps: Option<u32>,  // 目标帧率 (可选)
}
```

## 质量预设

- `HighQuality` - 高质量 (慢速)
- `Balanced` - 平衡 (中等速度)
- `Fast` - 快速 (低质量)
- `Custom` - 自定义设置

## 图像格式

- `Png` - PNG 格式 (无损)
- `Jpg` - JPEG 格式 (有损)
- `Tiff` - TIFF 格式 (专业)
- `Bmp` - BMP 格式 (未压缩)