293 lines
7.3 KiB
Markdown
293 lines
7.3 KiB
Markdown
# 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` 文件。
|