# TVAI (Topaz Video AI) 集成文档

本文档介绍如何在 MixVideo 桌面应用中使用 TVAI (Topaz Video AI) 功能进行视频和图片的AI增强处理。

## 概述

TVAI 集成提供了以下主要功能：

1. **视频处理**
   - 视频超分辨率放大
   - 帧插值（慢动作效果）
   - 自动视频增强

2. **图片处理**
   - 图片超分辨率放大
   - 自动图片增强
   - 批量图片处理

3. **任务管理**
   - 异步任务处理
   - 实时进度监控
   - 任务取消和清理

## 架构设计

### 后端 (Rust/Tauri)

```
apps/desktop/src-tauri/src/presentation/commands/tvai_commands.rs
├── TvaiState - 状态管理
├── 系统检测命令
├── 配置管理命令
├── 视频处理命令
├── 图片处理命令
└── 任务管理命令
```

### 前端 (TypeScript/React)

```
apps/desktop/src/
├── types/tvai.ts - 类型定义
├── services/tvaiService.ts - 服务层
├── hooks/useTvai.ts - React Hooks
└── components/TvaiExample.tsx - 示例组件
```

## 使用方法

### 1. 系统检测和初始化

```typescript
import { useTvaiSystemInfo } from '../hooks/useTvai';

function MyComponent() {
  const { systemInfo, initializeTvai } = useTvaiSystemInfo();
  
  // 检查系统状态
  console.log('Topaz 路径:', systemInfo.topazPath);
  console.log('GPU 支持:', systemInfo.hasGpuSupport);
  console.log('FFmpeg 路径:', systemInfo.ffmpegPath);
  
  // 初始化 TVAI
  const handleInit = async () => {
    await initializeTvai({
      topazPath: '/path/to/topaz',
      useGpu: true,
      tempDir: '/tmp/tvai'
    });
  };
}
```

### 2. 快速处理

```typescript
import { tvaiService } from '../services/tvaiService';

// 快速视频放大
const taskId = await tvaiService.quickUpscaleVideo(
  '/path/to/input.mp4',
  '/path/to/output.mp4',
  2.0 // 放大倍数
);

// 快速图片放大
const taskId = await tvaiService.quickUpscaleImage(
  '/path/to/input.jpg',
  '/path/to/output.jpg',
  2.0 // 放大倍数
);
```

### 3. 高级处理

```typescript
// 高级视频放大
const taskId = await tvaiService.upscaleVideoAdvanced(
  '/path/to/input.mp4',
  '/path/to/output.mp4',
  2.0,                    // 放大倍数
  'iris-3',              // AI 模型
  0.0,                   // 压缩
  0.1,                   // 混合
  'high_quality'         // 质量预设
);

// 高级图片放大
const taskId = await tvaiService.upscaleImageAdvanced(
  '/path/to/input.jpg',
  '/path/to/output.png',
  2.0,                   // 放大倍数
  'iris-3',             // AI 模型
  0.0,                  // 压缩
  0.1,                  // 混合
  'png'                 // 输出格式
);
```

### 4. 任务管理

```typescript
import { useTvai } from '../hooks/useTvai';

function TaskManager() {
  const { 
    tasks, 
    cancelTask, 
    cleanupCompletedTasks,
    getRunningTasksCount 
  } = useTvai();
  
  return (
    <div>
      <p>运行中任务: {getRunningTasksCount()}</p>
      {tasks.map(task => (
        <div key={task.id}>
          <span>{task.task_type} - {task.status}</span>
          {task.status === 'Processing' && (
            <button onClick={() => cancelTask(task.id)}>
              取消
            </button>
          )}
        </div>
      ))}
      <button onClick={cleanupCompletedTasks}>
        清理已完成任务
      </button>
    </div>
  );
}
```

### 5. 事件监听

```typescript
import { addTvaiEventListener, removeTvaiEventListener } from '../services/tvaiService';

// 监听任务事件
const handleTaskCreated = (taskId: string) => {
  console.log('新任务创建:', taskId);
};

const handleTaskUpdated = (taskId: string) => {
  console.log('任务更新:', taskId);
};

// 添加监听器
addTvaiEventListener('tvai_task_created', handleTaskCreated);
addTvaiEventListener('tvai_task_updated', handleTaskUpdated);

// 移除监听器
removeTvaiEventListener('tvai_task_created', handleTaskCreated);
removeTvaiEventListener('tvai_task_updated', handleTaskUpdated);
```

## 支持的AI模型

### 视频/图片放大模型

- `aaa-9` - 通用模型
- `ahq-12` - 高质量模型
- `alq-13` - 低质量输入优化
- `alqs-2` - 低质量输入优化 v2
- `amq-13` - 中等质量优化
- `amqs-2` - 中等质量优化 v2
- `ghq-5` - 游戏内容优化
- `iris-2` - 通用模型 v2
- `iris-3` - 通用模型 v3 (推荐)
- `nyx-3` - 人像优化
- `prob-4` - 问题修复
- `thf-4` - 老视频优化
- `thd-3` - 细节增强
- `thm-2` - 运动模糊处理
- `rhea-1` - 新模型
- `rxl-1` - 超高分辨率

### 插帧模型

- `apo-8` - 通用插帧 (推荐)
- `apf-1` - 快速插帧
- `chr-2` - 动画插帧
- `chf-3` - 高质量插帧

## 预设配置

```typescript
import { TVAI_PRESETS } from '../types/tvai';

// 视频预设
const oldVideoPreset = TVAI_PRESETS.VIDEO_UPSCALE_MODELS.OLD_VIDEO;
const gameContentPreset = TVAI_PRESETS.VIDEO_UPSCALE_MODELS.GAME_CONTENT;
const animationPreset = TVAI_PRESETS.VIDEO_UPSCALE_MODELS.ANIMATION;
const portraitPreset = TVAI_PRESETS.VIDEO_UPSCALE_MODELS.PORTRAIT;

// 图片预设
const photoPreset = TVAI_PRESETS.IMAGE_UPSCALE_MODELS.PHOTO;
const artworkPreset = TVAI_PRESETS.IMAGE_UPSCALE_MODELS.ARTWORK;
const screenshotPreset = TVAI_PRESETS.IMAGE_UPSCALE_MODELS.SCREENSHOT;

// 质量预设
const fastPreset = TVAI_PRESETS.QUALITY_PRESETS.FAST;
const highQualityPreset = TVAI_PRESETS.QUALITY_PRESETS.HIGH_QUALITY;
```

## 错误处理

```typescript
try {
  const taskId = await tvaiService.quickUpscaleVideo(
    inputPath, 
    outputPath, 
    scaleFactor
  );
  console.log('任务创建成功:', taskId);
} catch (error) {
  if (error.message.includes('Topaz Video AI not found')) {
    // 处理 Topaz 未安装的情况
    console.error('请安装 Topaz Video AI');
  } else if (error.message.includes('GPU not supported')) {
    // 处理 GPU 不支持的情况
    console.error('GPU 不支持，将使用 CPU 处理');
  } else {
    // 其他错误
    console.error('处理失败:', error.message);
  }
}
```

## 性能优化建议

1. **GPU 加速**: 确保启用 GPU 支持以获得最佳性能
2. **批量处理**: 对于多个文件，考虑使用批量处理功能
3. **临时目录**: 设置 SSD 作为临时目录以提高 I/O 性能
4. **内存管理**: 定期清理已完成的任务以释放内存
5. **并发控制**: 避免同时运行过多任务以防止系统过载

## 故障排除

### 常见问题

1. **Topaz Video AI 未检测到**
   - 确保 Topaz Video AI 已正确安装
   - 检查安装路径是否正确
   - 手动指定 Topaz 安装路径

2. **GPU 不工作**
   - 检查 GPU 驱动是否最新
   - 确认 CUDA 支持
   - 尝试禁用 GPU 使用 CPU 处理

3. **处理失败**
   - 检查输入文件是否存在且可读
   - 确认输出路径有写入权限
   - 查看错误日志获取详细信息

4. **性能问题**
   - 检查系统资源使用情况
   - 减少并发任务数量
   - 使用较低的质量预设

## 开发注意事项

1. **异步处理**: 所有 TVAI 操作都是异步的，需要正确处理 Promise
2. **事件监听**: 使用事件监听器获取实时任务状态更新
3. **错误处理**: 实现完善的错误处理机制
4. **资源清理**: 及时清理临时文件和已完成的任务
5. **用户体验**: 提供进度指示和取消功能

## 示例代码

完整的使用示例请参考 `apps/desktop/src/components/TvaiExample.tsx` 文件。