mixvideo-v2/docs/tvai-integration.md

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. 系统检测和初始化

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. 快速处理

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. 高级处理

// 高级视频放大
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. 任务管理

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. 事件监听

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 - 高质量插帧

预设配置

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;

错误处理

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 文件。