8.2 KiB
8.2 KiB
TVAI 库 API 文档
概述
TVAI 库为 Topaz Video AI 提供了全面的 Rust 接口，通过 AI 驱动的超分辨率和帧插值实现视频和图像增强。
核心组件
TvaiProcessor
所有视频和图像操作的主处理器。
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
处理器的主配置。
let config = TvaiConfig::builder()
.topaz_path("/topaz/路径")
.use_gpu(true)
.temp_dir("/自定义/临时目录")
.force_topaz_ffmpeg(true)
.build()?;
全局设置
持久化的全局配置。
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- 快速动画
参数预设
视频预设
// 内置预设
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);
图像预设
// 内置预设
let photo = ImageUpscaleParams::for_photo();
let artwork = ImageUpscaleParams::for_artwork();
let screenshot = ImageUpscaleParams::for_screenshot();
let portrait = ImageUpscaleParams::for_portrait();
预设管理
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();
快速开始函数
视频处理
// 快速 2 倍放大
quick_upscale_video(
Path::new("输入.mp4"),
Path::new("输出.mp4"),
2.0
).await?;
// 自动增强
auto_enhance_video(
Path::new("输入.mp4"),
Path::new("增强后.mp4")
).await?;
图像处理
// 快速 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 检测
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?;
性能监控
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();
错误处理
错误类型
库提供了带有用户友好消息的全面错误处理：
match result {
Ok(output) => println!("成功: {:?}", output),
Err(error) => {
println!("错误类别: {}", error.category());
println!("可恢复: {}", error.is_recoverable());
println!("用户消息:\n{}", error.user_friendly_message());
}
}
错误类别
installation- 找不到 Topaz/FFmpegprocessing- 处理失败parameter- 无效参数gpu- GPU 相关错误format- 不支持的格式resources- 资源不足permission- 权限被拒绝io- 文件 I/O 错误
系统检测
自动检测
// 检测 Topaz 安装
let topaz_path = detect_topaz_installation();
// 检测 FFmpeg 可用性
let ffmpeg_info = detect_ffmpeg();
// 检测 GPU 支持
let gpu_info = detect_gpu_support();
文件信息
// 获取视频信息
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);
进度跟踪
// 创建进度回调
let progress_callback: ProgressCallback = Box::new(|progress| {
println!("进度: {:.1}%", progress * 100.0);
});
// 与处理函数一起使用
processor.upscale_video(
input,
output,
params,
Some(&progress_callback)
).await?;
临时文件管理
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()?;
最佳实践
- 使用预设 处理常见场景
- 启用 GPU 获得更好性能
- 监控进度 处理长时间操作
- 优雅处理错误 使用用户友好消息
- 使用全局设置 保持一致配置
- 验证参数 在处理前
- 清理 处理后的临时文件
- 检查系统要求 开始前
示例
查看 examples/ 目录获取完整的工作示例：
basic_usage.rs- 简单入门示例advanced_usage.rs- 高级功能演示video_processing.rs- 全面的视频处理image_processing.rs- 全面的图像处理convenience_and_optimization.rs- 便捷功能和优化
参数详解
VideoUpscaleParams
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
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
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 格式 (未压缩)