mixvideo-v2/cargos/tvai-v2/USAGE_GUIDE.md

# Topaz Video AI SDK 使用指南

## 快速开始

### 1. 基本设置

```rust
use tvai_v2::{TvaiSdk, TemplateBuilder};

// 创建 SDK 实例（自动加载内置配置）
let mut sdk = TvaiSdk::new();
```

### 2. 创建简单的增强模板

```rust
let template = TemplateBuilder::new("基本增强")
    .description("使用 Proteus 模型进行基本视频增强")
    .enable_enhancement("prob-4")  // 使用 Proteus 4 模型
    .enhancement_params(25, 30, 20)  // 降噪25%, 细节30%, 锐化20%
    .build()?;
```

### 3. 生成 FFmpeg 命令

```rust
let command = sdk.generate_ffmpeg_command(
    &template,
    "input.mp4",
    "output.mp4"
)?;

println!("FFmpeg 命令: {}", command);
```

## 高级功能

### 1. 使用内置编解码器

```rust
// 查看可用的音频编解码器
for codec in sdk.ffmpeg_generator.get_available_audio_codecs() {
    println!("音频编解码器: {} - {}", codec.name, codec.ffmpeg_opts);
}

// 查看可用的视频编码器
for encoder in sdk.ffmpeg_generator.get_available_video_encoders() {
    println!("视频编码器: {} - {}", encoder.id, encoder.encoder);
}
```

### 2. 自动编码器选择

```rust
// 根据目标平台自动选择编码器
let auto_command = sdk.ffmpeg_generator.generate_with_auto_encoder(
    &template,
    "input.mp4",
    "output.mp4",
    "windows",      // 目标操作系统
    Some("nvidia")  // GPU 类型
)?;
```

### 3. 模型推荐

```rust
// 根据分辨率获取推荐模型
let recommended = sdk.ffmpeg_generator.recommend_model_for_resolution(1080);
println!("1080p 推荐模型: {:?}", recommended);

// 使用推荐模型创建模板
let optimized_template = TemplateBuilder::new("优化模板")
    .enable_enhancement(&recommended[0])
    .build()?;
```

### 4. 平台特定的编码器筛选

```rust
// 获取 Windows 兼容的编码器
let windows_encoders = sdk.ffmpeg_generator.get_compatible_video_encoders("windows", None);

// 获取支持 NVIDIA GPU 的编码器
let nvidia_encoders = sdk.ffmpeg_generator.get_compatible_video_encoders("windows", Some("nvidia"));

// 获取支持 MP4 格式的编码器
let mp4_encoders = sdk.ffmpeg_generator.get_encoders_for_extension("mp4");
```

## 常用模板示例

### 1. 4K 上采样

```rust
let upscale_4k = TemplateBuilder::new("4K 上采样")
    .enable_enhancement("prob-4")
    .resolution(3840, 2160)
    .video_codec("hevc_nvenc", Some(18))
    .audio_settings("AAC", 256, 2)
    .build()?;
```

### 2. 60fps 插帧

```rust
let fps_60 = TemplateBuilder::new("60fps 插帧")
    .enable_frame_interpolation("chr-2", 1.0)
    .output_settings(0, 60.0)  // 原始尺寸，60fps
    .build()?;
```

### 3. 降噪处理

```rust
let denoise = TemplateBuilder::new("降噪处理")
    .enable_enhancement("nyx-3")  // 使用 Nyx 降噪模型
    .enhancement_params(60, 10, 5)  // 高降噪，低细节增强
    .build()?;
```

### 4. 稳定化处理

```rust
let stabilize = TemplateBuilder::new("视频稳定")
    .enable_stabilization(70, 0)  // 高平滑度，自动裁剪
    .build()?;
```

### 5. 动画优化

```rust
let animation = TemplateBuilder::new("动画优化")
    .enable_enhancement("art-2")  // 使用 Artemis 动画模型
    .ai_engine("artemis")
    .enhancement_params(15, 40, 25)
    .build()?;
```

### 6. HDR 处理

```rust
let hdr = TemplateBuilder::new("HDR 处理")
    .enable_enhancement("hyp-1")  // 使用 Hyperion HDR 模型
    .video_codec("hevc_nvenc", Some(16))
    .color_settings(
        "bt2020nc",
        "bt2020",
        "smpte2084"
    )
    .build()?;
```

## 批处理

```rust
let input_files = vec![
    "video1.mp4".to_string(),
    "video2.mp4".to_string(),
    "video3.mp4".to_string(),
];

let batch_commands = sdk.generate_batch_commands(
    &template,
    &input_files,
    "output_directory"
)?;

for command in batch_commands {
    println!("批处理命令: {}", command);
}
```

## 硬件加速

```rust
// 使用 GPU 加速
let gpu_command = sdk.generate_ffmpeg_command_with_gpu(
    &template,
    "input.mp4",
    "output.mp4",
    "0"  // GPU 设备 ID
)?;

// 自定义编解码器
let custom_command = sdk.generate_ffmpeg_command_with_codec(
    &template,
    "input.mp4",
    "output.mp4",
    "hevc_nvenc",
    Some(18)
)?;
```

## 模板验证

```rust
// 验证模板
sdk.validate_template_for_ffmpeg(&template)?;

// 验证并完善模板
let mut incomplete_template = TemplateBuilder::new("未完成")
    .enable_enhancement("prob-4")
    .build()?;

sdk.validate_and_complete_template(&mut incomplete_template)?;
```

## 错误处理

```rust
match sdk.generate_ffmpeg_command(&template, "input.mp4", "output.mp4") {
    Ok(command) => println!("成功生成命令: {}", command),
    Err(e) => eprintln!("生成命令失败: {}", e),
}
```

## 内置配置说明

SDK 内置了以下配置：

- **音频编解码器**: AAC、AC3、PCM、Vorbis
- **视频编码器**: H.264/H.265 的 NVENC、VideoToolbox、AMF、软件编码器
- **模型推荐规则**: 基于分辨率的智能模型推荐

所有配置都编译到代码中，无需外部文件依赖。

## 调试和诊断

```rust
// 生成编码器报告
let report = sdk.ffmpeg_generator.generate_encoder_report();
println!("{}", report);

// 获取模型映射
let mappings = sdk.get_model_mappings();
for (template_model, ffmpeg_model) in mappings {
    println!("{} -> {}", template_model, ffmpeg_model);
}
```