# TVAI 库用户指南

## 快速开始

### 安装

在您的 `Cargo.toml` 中添加 TVAI：

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

### 前置要求

1. **Topaz Video AI** - 从 [Topaz Labs](https://www.topazlabs.com/topaz-video-ai) 下载并安装
2. **GPU 驱动** - 最新的 NVIDIA 或 AMD 驱动程序以支持 GPU 加速
3. **Rust 1.70+** - 用于构建库

### 快速开始

```rust
use tvai::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 快速 2 倍视频放大
    quick_upscale_video(
        std::path::Path::new("输入.mp4"),
        std::path::Path::new("输出.mp4"),
        2.0,
    ).await?;
    
    Ok(())
}
```

## 常见使用场景

### 1. 视频增强

#### 老视频修复

```rust
use tvai::*;

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

let result = processor.upscale_video(
    Path::new("老视频.mp4"),
    Path::new("修复后视频.mp4"),
    params,
    Some(&progress_callback),
).await?;

println!("增强完成，耗时 {:?}", result.processing_time);
```

#### 创建慢动作效果

```rust
let params = InterpolationParams::for_slow_motion(30, 4.0); // 30fps -> 120fps
let result = processor.interpolate_video(
    Path::new("正常速度.mp4"),
    Path::new("慢动作.mp4"),
    params,
    Some(&progress_callback),
).await?;
```

#### 完整增强

```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("输入.mp4"),
    Path::new("增强后.mp4"),
    enhance_params,
    Some(&progress_callback),
).await?;
```

### 2. 图片增强

#### 批量照片增强

```rust
let image_paths = vec![
    PathBuf::from("照片1.jpg"),
    PathBuf::from("照片2.jpg"),
    PathBuf::from("照片3.jpg"),
];

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

println!("处理了 {} 张图片", results.len());
```

#### 目录批量处理

```rust
let results = processor.upscale_directory(
    Path::new("输入照片"),
    Path::new("输出照片"),
    ImageUpscaleParams::for_photo(),
    true, // 递归处理子目录
    Some(&progress_callback),
).await?;
```

### 3. 格式转换

#### 图片序列转视频

```rust
let image_paths = collect_image_sequence("帧/")?;
processor.images_to_video(
    &image_paths,
    Path::new("输出.mp4"),
    30.0, // 帧率
    QualityPreset::HighQuality,
    Some(&progress_callback),
).await?;
```

#### 视频转图片序列

```rust
let image_paths = processor.video_to_images(
    Path::new("输入.mp4"),
    Path::new("帧/"),
    "png",
    95, // 质量
    Some(&progress_callback),
).await?;

println!("提取了 {} 帧", image_paths.len());
```

## 配置管理

### 全局设置

设置全局配置以保持一致的行为：

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

let settings = global_settings();

// 配置默认值
settings.set_default_use_gpu(true)?;
settings.set_max_concurrent_jobs(2)?;

// 保存设置
settings.save_to_file()?;

// 从全局设置创建处理器
let config = settings.create_config()?;
let processor = TvaiProcessor::new(config)?;
```

### 自定义配置

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

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

## 模型选择指南

### 超分辨率模型

| 模型 | 最适合 | 倍数 | 描述 |
|------|--------|------|------|
| Iris v3 | 通用 | 1-4x | 最佳整体质量 |
| Nyx v3 | 人像 | 1-4x | 面部优化 |
| Theia Fidelity v4 | 老内容 | 2x | 专注修复 |
| Gaia HQ v5 | 游戏/CG | 1-4x | 锐利细节 |
| Proteus v4 | 问题素材 | 1-4x | 伪影修复 |

### 插值模型

| 模型 | 最适合 | 描述 |
|------|--------|------|
| Apollo v8 | 高质量 | 最佳整体插值 |
| Chronos v2 | 动画 | 卡通/动漫内容 |
| Apollo Fast v1 | 速度 | 更快处理 |
| Chronos Fast v3 | 快速动画 | 快速动画处理 |

## 性能优化

### GPU 优化

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

// 检查 GPU 适用性
if GpuManager::is_gpu_suitable_for_ai() {
    println!("GPU 适合 AI 处理");
    
    // 获取详细信息
    let gpu_info = GpuManager::detect_detailed_gpu_info();
    println!("推荐内存限制: {:?} MB", 
             gpu_info.recommended_settings.memory_limit_mb);
}
```

### 性能监控

```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 summary = monitor.get_summary();
for recommendation in summary.recommendations {
    println!("💡 {}", recommendation);
}
```

### 内存管理

```rust
// 为有限内存使用较小的块大小
let settings = PerformanceSettings {
    chunk_size_mb: 50, // 较小的块
    max_concurrent_ops: 1, // 单个操作
    processing_mode: ProcessingMode::MemoryEfficient,
    ..Default::default()
};
```

## 错误处理

### 全面的错误处理

```rust
match processor.upscale_video(input, output, params, None).await {
    Ok(result) => {
        println!("✅ 成功: {:?}", result.processing_time);
    }
    Err(error) => {
        eprintln!("❌ 错误: {}", error.category());
        eprintln!("{}", error.user_friendly_message());
        
        if error.is_recoverable() {
            eprintln!("💡 此错误可能可以通过不同设置恢复");
        }
    }
}
```

### 常见错误解决方案

#### 找不到 Topaz
```
错误: 找不到 Topaz Video AI
解决方案: 安装 Topaz Video AI 或设置正确路径
```

#### GPU 错误
```
错误: CUDA 内存不足
解决方案: 降低质量设置或禁用 GPU
```

#### 权限被拒绝
```
错误: 无法写入输出目录
解决方案: 以管理员身份运行或检查权限
```

## 进度跟踪

### 简单进度条

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

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

### 详细进度跟踪

```rust
let progress_callback: ProgressCallback = Box::new(|progress| {
    let percentage = (progress * 100.0) as u32;
    let eta = estimate_time_remaining(progress);
    println!("进度: {}% - 预计剩余时间: {:?}", percentage, eta);
});
```

## 最佳实践

### 1. 文件管理

```rust
// 始终验证输入文件
processor.validate_input_file(input_path)?;
processor.validate_output_path(output_path)?;

// 为中间处理使用临时文件
let temp_path = processor.create_unique_temp_path("中间.mp4");
// ... 处理到临时文件 ...
std::fs::rename(temp_path, final_output)?;
```

### 2. 资源管理

```rust
// 使用 RAII 进行自动清理
{
    let mut processor = TvaiProcessor::new(config)?;
    // 处理在这里进行
    // 处理器在丢弃时自动清理
}
```

### 3. 批量处理

```rust
// 分批处理以避免内存问题
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?;
    
    // 处理结果或保存状态
}
```

### 4. 错误恢复

```rust
// 为可恢复错误实现重试逻辑
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!("尝试 {} 失败，重试中...", attempts);
            tokio::time::sleep(Duration::from_secs(1)).await;
        }
        Err(error) => break Err(error),
    }
}
```

## 故障排除

### 常见问题

1. **处理缓慢**
   - 启用 GPU 加速
   - 使用更快的模型 (Apollo Fast, Chronos Fast)
   - 降低质量设置

2. **内存不足**
   - 减少块大小
   - 降低质量预设
   - 处理较小的文件

3. **质量结果差**
   - 为内容类型使用适当的模型
   - 调整压缩和混合参数
   - 使用更高质量预设

4. **文件格式问题**
   - 首先转换为支持的格式
   - 检查文件损坏
   - 验证文件权限

### 获取帮助

1. 检查错误消息和建议
2. 查看 API 文档
3. 运行示例以验证设置
4. 检查系统要求和 GPU 驱动程序