376 lines
8.2 KiB
Markdown
376 lines
8.2 KiB
Markdown
# TVAI 库 API 文档
|
|
|
|
## 概述
|
|
|
|
TVAI 库为 Topaz Video AI 提供了全面的 Rust 接口，通过 AI 驱动的超分辨率和帧插值实现视频和图像增强。
|
|
|
|
## 核心组件
|
|
|
|
### TvaiProcessor
|
|
|
|
所有视频和图像操作的主处理器。
|
|
|
|
```rust
|
|
use tvai::*;
|
|
|
|
// 创建配置
|
|
let config = TvaiConfig::builder()
|
|
.topaz_path("/topaz/路径")
|
|
.use_gpu(true)
|
|
.build()?;
|
|
|
|
// 创建处理器
|
|
let mut processor = TvaiProcessor::new(config)?;
|
|
```
|
|
|
|
#### 视频处理方法
|
|
|
|
- `upscale_video()` - AI 驱动的视频超分辨率
|
|
- `interpolate_video()` - 慢动作帧插值
|
|
- `enhance_video()` - 组合超分辨率和插值
|
|
- `images_to_video()` - 图像序列转视频
|
|
- `video_to_images()` - 从视频提取帧
|
|
|
|
#### 图像处理方法
|
|
|
|
- `upscale_image()` - AI 驱动的图像超分辨率
|
|
- `batch_upscale_images()` - 处理多张图像
|
|
- `upscale_directory()` - 处理整个目录
|
|
- `convert_image_format()` - 格式转换
|
|
- `resize_image()` - 传统几何缩放
|
|
|
|
### 配置管理
|
|
|
|
#### TvaiConfig
|
|
|
|
处理器的主配置。
|
|
|
|
```rust
|
|
let config = TvaiConfig::builder()
|
|
.topaz_path("/topaz/路径")
|
|
.use_gpu(true)
|
|
.temp_dir("/自定义/临时目录")
|
|
.force_topaz_ffmpeg(true)
|
|
.build()?;
|
|
```
|
|
|
|
#### 全局设置
|
|
|
|
持久化的全局配置。
|
|
|
|
```rust
|
|
use tvai::config::global_settings;
|
|
|
|
let settings = global_settings();
|
|
settings.set_default_use_gpu(true)?;
|
|
settings.set_max_concurrent_jobs(2)?;
|
|
```
|
|
|
|
### AI 模型
|
|
|
|
#### 超分辨率模型
|
|
|
|
- `Iris3` - 最佳通用模型
|
|
- `Nyx3` - 人像优化
|
|
- `Thf4` - 老内容修复
|
|
- `Ghq5` - 游戏/CG 内容
|
|
- `Prob4` - 问题素材修复
|
|
- 以及 11 个其他专业模型
|
|
|
|
#### 插值模型
|
|
|
|
- `Apo8` - 高质量插值
|
|
- `Chr2` - 动画内容
|
|
- `Apf1` - 快速处理
|
|
- `Chf3` - 快速动画
|
|
|
|
### 参数预设
|
|
|
|
#### 视频预设
|
|
|
|
```rust
|
|
// 内置预设
|
|
let old_video = VideoUpscaleParams::for_old_video();
|
|
let game_content = VideoUpscaleParams::for_game_content();
|
|
let animation = VideoUpscaleParams::for_animation();
|
|
let portrait = VideoUpscaleParams::for_portrait();
|
|
|
|
// 插值预设
|
|
let slow_motion = InterpolationParams::for_slow_motion(30, 2.0);
|
|
let animation_interp = InterpolationParams::for_animation(24, 2.0);
|
|
```
|
|
|
|
#### 图像预设
|
|
|
|
```rust
|
|
// 内置预设
|
|
let photo = ImageUpscaleParams::for_photo();
|
|
let artwork = ImageUpscaleParams::for_artwork();
|
|
let screenshot = ImageUpscaleParams::for_screenshot();
|
|
let portrait = ImageUpscaleParams::for_portrait();
|
|
```
|
|
|
|
### 预设管理
|
|
|
|
```rust
|
|
use tvai::config::global_presets;
|
|
|
|
let presets = global_presets();
|
|
let preset_manager = presets.lock().unwrap();
|
|
|
|
// 获取预设
|
|
if let Some(preset) = preset_manager.get_video_preset("general_2x") {
|
|
// 使用预设参数
|
|
}
|
|
|
|
// 列出所有预设
|
|
let video_presets = preset_manager.list_video_presets();
|
|
let image_presets = preset_manager.list_image_presets();
|
|
```
|
|
|
|
## 快速开始函数
|
|
|
|
### 视频处理
|
|
|
|
```rust
|
|
// 快速 2 倍放大
|
|
quick_upscale_video(
|
|
Path::new("输入.mp4"),
|
|
Path::new("输出.mp4"),
|
|
2.0
|
|
).await?;
|
|
|
|
// 自动增强
|
|
auto_enhance_video(
|
|
Path::new("输入.mp4"),
|
|
Path::new("增强后.mp4")
|
|
).await?;
|
|
```
|
|
|
|
### 图像处理
|
|
|
|
```rust
|
|
// 快速 2 倍放大
|
|
quick_upscale_image(
|
|
Path::new("照片.jpg"),
|
|
Path::new("照片_2x.png"),
|
|
2.0
|
|
).await?;
|
|
|
|
// 自动增强
|
|
auto_enhance_image(
|
|
Path::new("照片.jpg"),
|
|
Path::new("增强后.png")
|
|
).await?;
|
|
|
|
// 批量目录处理
|
|
batch_upscale_directory(
|
|
Path::new("输入目录"),
|
|
Path::new("输出目录"),
|
|
2.0,
|
|
true // 递归
|
|
).await?;
|
|
```
|
|
|
|
## 性能和优化
|
|
|
|
### GPU 检测
|
|
|
|
```rust
|
|
use tvai::utils::GpuManager;
|
|
|
|
// 详细的 GPU 信息
|
|
let gpu_info = GpuManager::detect_detailed_gpu_info();
|
|
println!("CUDA 可用: {}", gpu_info.cuda_available);
|
|
println!("设备数量: {}", gpu_info.devices.len());
|
|
|
|
// 检查 AI 适用性
|
|
let suitable = GpuManager::is_gpu_suitable_for_ai();
|
|
|
|
// 基准测试性能
|
|
let benchmark = GpuManager::benchmark_gpu_performance().await?;
|
|
```
|
|
|
|
### 性能监控
|
|
|
|
```rust
|
|
use tvai::utils::{PerformanceMonitor, optimize_for_system};
|
|
|
|
// 创建优化设置
|
|
let settings = optimize_for_system();
|
|
let mut monitor = PerformanceMonitor::new(settings);
|
|
|
|
// 监控操作
|
|
let _permit = monitor.acquire_slot().await?;
|
|
let operation_monitor = monitor.start_operation("upscale", 100.0);
|
|
|
|
// ... 执行处理 ...
|
|
|
|
let metrics = operation_monitor.finish(200.0);
|
|
monitor.record_metrics(metrics);
|
|
|
|
// 获取性能摘要
|
|
let summary = monitor.get_summary();
|
|
```
|
|
|
|
## 错误处理
|
|
|
|
### 错误类型
|
|
|
|
库提供了带有用户友好消息的全面错误处理：
|
|
|
|
```rust
|
|
match result {
|
|
Ok(output) => println!("成功: {:?}", output),
|
|
Err(error) => {
|
|
println!("错误类别: {}", error.category());
|
|
println!("可恢复: {}", error.is_recoverable());
|
|
println!("用户消息:\n{}", error.user_friendly_message());
|
|
}
|
|
}
|
|
```
|
|
|
|
### 错误类别
|
|
|
|
- `installation` - 找不到 Topaz/FFmpeg
|
|
- `processing` - 处理失败
|
|
- `parameter` - 无效参数
|
|
- `gpu` - GPU 相关错误
|
|
- `format` - 不支持的格式
|
|
- `resources` - 资源不足
|
|
- `permission` - 权限被拒绝
|
|
- `io` - 文件 I/O 错误
|
|
|
|
## 系统检测
|
|
|
|
### 自动检测
|
|
|
|
```rust
|
|
// 检测 Topaz 安装
|
|
let topaz_path = detect_topaz_installation();
|
|
|
|
// 检测 FFmpeg 可用性
|
|
let ffmpeg_info = detect_ffmpeg();
|
|
|
|
// 检测 GPU 支持
|
|
let gpu_info = detect_gpu_support();
|
|
```
|
|
|
|
### 文件信息
|
|
|
|
```rust
|
|
// 获取视频信息
|
|
let video_info = get_video_info(Path::new("视频.mp4")).await?;
|
|
println!("时长: {:?}", video_info.duration);
|
|
println!("分辨率: {}x{}", video_info.width, video_info.height);
|
|
|
|
// 获取图像信息
|
|
let image_info = get_image_info(Path::new("图像.jpg"))?;
|
|
println!("尺寸: {}x{}", image_info.width, image_info.height);
|
|
```
|
|
|
|
## 进度跟踪
|
|
|
|
```rust
|
|
// 创建进度回调
|
|
let progress_callback: ProgressCallback = Box::new(|progress| {
|
|
println!("进度: {:.1}%", progress * 100.0);
|
|
});
|
|
|
|
// 与处理函数一起使用
|
|
processor.upscale_video(
|
|
input,
|
|
output,
|
|
params,
|
|
Some(&progress_callback)
|
|
).await?;
|
|
```
|
|
|
|
## 临时文件管理
|
|
|
|
```rust
|
|
use tvai::utils::TempFileManager;
|
|
|
|
let mut temp_manager = TempFileManager::new(None)?;
|
|
|
|
// 创建临时文件
|
|
let temp_path = temp_manager.create_temp_path("操作", "临时.mp4");
|
|
let unique_path = temp_manager.create_unique_temp_path("输出.png");
|
|
|
|
// 清理
|
|
temp_manager.cleanup_operation("操作")?;
|
|
temp_manager.cleanup_all()?;
|
|
```
|
|
|
|
## 最佳实践
|
|
|
|
1. **使用预设** 处理常见场景
|
|
2. **启用 GPU** 获得更好性能
|
|
3. **监控进度** 处理长时间操作
|
|
4. **优雅处理错误** 使用用户友好消息
|
|
5. **使用全局设置** 保持一致配置
|
|
6. **验证参数** 在处理前
|
|
7. **清理** 处理后的临时文件
|
|
8. **检查系统要求** 开始前
|
|
|
|
## 示例
|
|
|
|
查看 `examples/` 目录获取完整的工作示例：
|
|
|
|
- `basic_usage.rs` - 简单入门示例
|
|
- `advanced_usage.rs` - 高级功能演示
|
|
- `video_processing.rs` - 全面的视频处理
|
|
- `image_processing.rs` - 全面的图像处理
|
|
- `convenience_and_optimization.rs` - 便捷功能和优化
|
|
|
|
## 参数详解
|
|
|
|
### VideoUpscaleParams
|
|
|
|
```rust
|
|
pub struct VideoUpscaleParams {
|
|
pub scale_factor: f32, // 缩放倍数 (1.0-4.0)
|
|
pub model: UpscaleModel, // AI 模型
|
|
pub compression: f32, // 压缩设置 (-1.0 到 1.0)
|
|
pub blend: f32, // 混合设置 (0.0 到 1.0)
|
|
pub quality_preset: QualityPreset, // 质量预设
|
|
}
|
|
```
|
|
|
|
### ImageUpscaleParams
|
|
|
|
```rust
|
|
pub struct ImageUpscaleParams {
|
|
pub scale_factor: f32, // 缩放倍数 (1.0-4.0)
|
|
pub model: UpscaleModel, // AI 模型
|
|
pub compression: f32, // 压缩设置 (-1.0 到 1.0)
|
|
pub blend: f32, // 混合设置 (0.0 到 1.0)
|
|
pub output_format: ImageFormat, // 输出格式
|
|
}
|
|
```
|
|
|
|
### InterpolationParams
|
|
|
|
```rust
|
|
pub struct InterpolationParams {
|
|
pub input_fps: u32, // 输入帧率
|
|
pub multiplier: f32, // 倍数 (1.0-8.0)
|
|
pub model: InterpolationModel, // 插值模型
|
|
pub target_fps: Option<u32>, // 目标帧率 (可选)
|
|
}
|
|
```
|
|
|
|
## 质量预设
|
|
|
|
- `HighQuality` - 高质量 (慢速)
|
|
- `Balanced` - 平衡 (中等速度)
|
|
- `Fast` - 快速 (低质量)
|
|
- `Custom` - 自定义设置
|
|
|
|
## 图像格式
|
|
|
|
- `Png` - PNG 格式 (无损)
|
|
- `Jpg` - JPEG 格式 (有损)
|
|
- `Tiff` - TIFF 格式 (专业)
|
|
- `Bmp` - BMP 格式 (未压缩)
|