# Topaz Video AI 滤镜组合使用指南

## 概述

Topaz Video AI 滤镜组合库提供了一套易用的高级 API，封装了复杂的 TVAI 滤镜参数，让您能够轻松地进行各种视频和图片处理任务。

## 快速开始

### 基本用法

```rust
use tvai::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建处理器
    let topaz_path = detect_topaz_installation().unwrap();
    let config = TvaiConfig::builder()
        .topaz_path(topaz_path)
        .use_gpu(true)
        .build()?;
    
    let processor = TvaiProcessor::new(config)?;
    let mut filter_processor = FilterProcessor::new(processor);

    // 视频超分辨率放大
    let combination = FilterCombination::Upscale {
        model: UpscaleModel::Iris3,
        scale: 2.0,
        quality: QualityLevel::High,
    };

    let result = filter_processor.apply_to_video(
        Path::new("input.mp4"),
        Path::new("output.mp4"),
        combination,
        ProcessOptions::default(),
        None,
    ).await?;

    println!("处理完成！时间: {:?}", result.processing_time);
    Ok(())
}
```

### 快速函数

对于简单的处理任务，可以使用快速函数：

```rust
use tvai::filters::quick;

// 快速视频放大
let result = quick::upscale_video(
    Path::new("input.mp4"),
    Path::new("output.mp4"),
    2.0,
).await?;

// 快速慢动作处理
let result = quick::slow_motion(
    Path::new("input.mp4"),
    Path::new("output.mp4"),
    2.0,
).await?;

// 快速视频稳定化
let result = quick::stabilize_video(
    Path::new("input.mp4"),
    Path::new("output.mp4"),
    1.0,
).await?;
```

## 滤镜组合类型

### 1. 超分辨率放大 (Upscale)

```rust
let combination = FilterCombination::Upscale {
    model: UpscaleModel::Iris3,  // AI 模型
    scale: 2.0,                  // 放大倍数
    quality: QualityLevel::High, // 质量等级
};
```

**可用模型**:
- `Iris3`: 通用最佳模型
- `Ahq12`: 高质量模型
- `Nyx3`: 人像优化模型
- `Ghq5`: 游戏/CG 内容模型
- `Prob4`: 问题视频修复模型

### 2. 慢动作处理 (SlowMotion)

```rust
let combination = FilterCombination::SlowMotion {
    factor: 2.0,                 // 慢动作倍数
    quality: QualityLevel::High,
};
```

### 3. 视频稳定化 (Stabilize)

```rust
let combination = FilterCombination::Stabilize {
    strength: 1.0,               // 稳定化强度 (0.0-2.0)
    quality: QualityLevel::High,
};
```

### 4. 完整增强 (FullEnhance)

```rust
let combination = FilterCombination::FullEnhance {
    upscale_factor: 2.0,         // 放大倍数
    stabilize: true,             // 是否启用稳定化
    quality: QualityLevel::High,
};
```

### 5. 老视频修复 (RestoreOldVideo)

```rust
let combination = FilterCombination::RestoreOldVideo {
    upscale_factor: 2.0,         // 放大倍数
    denoise_level: 0.3,          // 降噪等级 (0.0-1.0)
    quality: QualityLevel::High,
};
```

### 6. 游戏录像优化 (GameFootage)

```rust
let combination = FilterCombination::GameFootage {
    upscale_factor: 1.5,         // 放大倍数
    sharpen: true,               // 是否启用锐化
    quality: QualityLevel::High,
};
```

## 构建器模式

使用构建器模式可以更灵活地配置处理参数：

```rust
use tvai::{FilterCombinationBuilder, quick_builders};

// 详细配置
let (combination, options) = FilterCombinationBuilder::new()
    .upscale(UpscaleModel::Ahq12, 2.0)
    .quality(QualityLevel::Maximum)
    .output_format("mp4".to_string())
    .output_resolution(3840, 2160)
    .vram_limit(0.8)
    .keep_audio(true)
    .device(0)  // 指定 GPU 0
    .build()?;

// 快速构建器
let (combination, options) = quick_builders::upscale_hq(2.0)
    .output_format("mov".to_string())
    .build()?;
```

### 可用的快速构建器

- `quick_builders::upscale(scale)` - 标准放大
- `quick_builders::upscale_hq(scale)` - 高质量放大
- `quick_builders::slow_motion(factor)` - 慢动作
- `quick_builders::stabilize()` - 视频稳定化
- `quick_builders::full_enhance()` - 完整增强
- `quick_builders::restore_old_video()` - 老视频修复
- `quick_builders::game_footage()` - 游戏录像优化
- `quick_builders::social_media()` - 社交媒体优化
- `quick_builders::portrait()` - 人像优化
- `quick_builders::animation()` - 动画优化

## 预设系统

### 内置预设

```rust
use tvai::PresetType;

// 使用内置预设
let preset = PresetType::Gaming;
let combination = preset.get_filter_combination();
let options = preset.get_process_options();

println!("预设描述: {}", preset.description());
```

**可用预设**:
- `SocialMedia` - 社交媒体优化
- `FilmRestoration` - 电影修复
- `Gaming` - 游戏录像
- `Surveillance` - 监控视频
- `Animation` - 动画内容
- `Portrait` - 人像视频
- `Landscape` - 风景视频
- `QuickPreview` - 快速预览

### 自定义预设

```rust
use tvai::CustomPreset;

// 创建自定义预设
let preset = CustomPreset::builder("我的预设".to_string())
    .with_combination(FilterCombination::Upscale {
        model: UpscaleModel::Iris3,
        scale: 2.0,
        quality: QualityLevel::High,
    })
    .with_options(ProcessOptions {
        output_format: Some("mp4".to_string()),
        keep_audio: true,
        ..Default::default()
    })
    .with_description("自定义高质量放大预设".to_string())
    .build()?;

// 保存预设
preset.save_to_file(Path::new("my_preset.json"))?;

// 加载预设
let loaded_preset = CustomPreset::load_from_file(Path::new("my_preset.json"))?;
```

## 处理选项

```rust
let options = ProcessOptions {
    output_format: Some("mp4".to_string()),    // 输出格式
    keep_audio: true,                          // 保留音频
    output_resolution: Some((1920, 1080)),     // 输出分辨率
    device: -2,                                // 设备 (-2=自动, -1=CPU, 0+=GPU)
    vram_limit: 1.0,                          // VRAM 使用限制 (0.1-1.0)
    enable_progress: true,                     // 启用进度回调
};
```

## 质量等级

- `QualityLevel::Fast` - 快速处理
- `QualityLevel::Balanced` - 平衡质量和速度
- `QualityLevel::High` - 高质量
- `QualityLevel::Maximum` - 最高质量

## 进度回调

```rust
let progress_callback = Box::new(|progress: f32| {
    let percentage = (progress * 100.0) as u32;
    println!("处理进度: {}%", percentage);
});

let result = filter_processor.apply_to_video(
    input_path,
    output_path,
    combination,
    options,
    Some(&progress_callback),
).await?;
```

## 智能推荐

系统可以根据视频特征自动推荐最适合的滤镜组合：

```rust
let recommended = filter_processor.get_recommended_combination(
    Path::new("input.mp4")
).await?;

println!("推荐的组合: {:?}", recommended);
```

## 错误处理

```rust
match result {
    Ok(process_result) => {
        println!("处理成功！");
        println!("输出文件: {}", process_result.output_path.display());
        println!("处理时间: {:?}", process_result.processing_time);
    }
    Err(TvaiError::TopazNotFound(path)) => {
        eprintln!("未找到 Topaz Video AI: {}", path);
    }
    Err(TvaiError::FileNotFound(path)) => {
        eprintln!("文件不存在: {}", path);
    }
    Err(TvaiError::FfmpegError(msg)) => {
        eprintln!("FFmpeg 错误: {}", msg);
    }
    Err(e) => {
        eprintln!("其他错误: {}", e);
    }
}
```

## 最佳实践

1. **选择合适的模型**: 根据内容类型选择最适合的 AI 模型
2. **合理设置质量等级**: 平衡处理时间和输出质量
3. **监控 VRAM 使用**: 避免显存不足导致的处理失败
4. **使用进度回调**: 为长时间处理提供用户反馈
5. **批量处理**: 对多个文件使用相同配置时，重用处理器实例
6. **错误处理**: 妥善处理各种可能的错误情况

## 性能优化

- 使用 GPU 加速可显著提升处理速度
- 调整 `vram_limit` 以优化内存使用
- 对于快速预览，使用 `QualityLevel::Fast`
- 批量处理时重用 `FilterProcessor` 实例
