423 lines
8.8 KiB
Markdown
423 lines
8.8 KiB
Markdown
# TVAI 库用户指南
|
||
|
||
## 快速开始
|
||
|
||
### 安装
|
||
|
||
在您的 `Cargo.toml` 中添加 TVAI：
|
||
|
||
```toml
|
||
[dependencies]
|
||
tvai = "0.1.0"
|
||
```
|
||
|
||
### 前置要求
|
||
|
||
1. **Topaz Video AI** - 从 [Topaz Labs](https://www.topazlabs.com/topaz-video-ai) 下载并安装
|
||
2. **GPU 驱动** - 最新的 NVIDIA 或 AMD 驱动程序以支持 GPU 加速
|
||
3. **Rust 1.70+** - 用于构建库
|
||
|
||
### 快速开始
|
||
|
||
```rust
|
||
use tvai::*;
|
||
|
||
#[tokio::main]
|
||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||
// 快速 2 倍视频放大
|
||
quick_upscale_video(
|
||
std::path::Path::new("输入.mp4"),
|
||
std::path::Path::new("输出.mp4"),
|
||
2.0,
|
||
).await?;
|
||
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
## 常见使用场景
|
||
|
||
### 1. 视频增强
|
||
|
||
#### 老视频修复
|
||
|
||
```rust
|
||
use tvai::*;
|
||
|
||
let params = VideoUpscaleParams::for_old_video();
|
||
let mut processor = create_processor().await?;
|
||
|
||
let result = processor.upscale_video(
|
||
Path::new("老视频.mp4"),
|
||
Path::new("修复后视频.mp4"),
|
||
params,
|
||
Some(&progress_callback),
|
||
).await?;
|
||
|
||
println!("增强完成，耗时 {:?}", result.processing_time);
|
||
```
|
||
|
||
#### 创建慢动作效果
|
||
|
||
```rust
|
||
let params = InterpolationParams::for_slow_motion(30, 4.0); // 30fps -> 120fps
|
||
let result = processor.interpolate_video(
|
||
Path::new("正常速度.mp4"),
|
||
Path::new("慢动作.mp4"),
|
||
params,
|
||
Some(&progress_callback),
|
||
).await?;
|
||
```
|
||
|
||
#### 完整增强
|
||
|
||
```rust
|
||
let enhance_params = VideoEnhanceParams {
|
||
upscale: Some(VideoUpscaleParams::for_old_video()),
|
||
interpolation: Some(InterpolationParams::for_slow_motion(24, 2.0)),
|
||
};
|
||
|
||
let result = processor.enhance_video(
|
||
Path::new("输入.mp4"),
|
||
Path::new("增强后.mp4"),
|
||
enhance_params,
|
||
Some(&progress_callback),
|
||
).await?;
|
||
```
|
||
|
||
### 2. 图片增强
|
||
|
||
#### 批量照片增强
|
||
|
||
```rust
|
||
let image_paths = vec![
|
||
PathBuf::from("照片1.jpg"),
|
||
PathBuf::from("照片2.jpg"),
|
||
PathBuf::from("照片3.jpg"),
|
||
];
|
||
|
||
let params = ImageUpscaleParams::for_photo();
|
||
let results = processor.batch_upscale_images(
|
||
&image_paths,
|
||
Path::new("输出目录"),
|
||
params,
|
||
Some(&progress_callback),
|
||
).await?;
|
||
|
||
println!("处理了 {} 张图片", results.len());
|
||
```
|
||
|
||
#### 目录批量处理
|
||
|
||
```rust
|
||
let results = processor.upscale_directory(
|
||
Path::new("输入照片"),
|
||
Path::new("输出照片"),
|
||
ImageUpscaleParams::for_photo(),
|
||
true, // 递归处理子目录
|
||
Some(&progress_callback),
|
||
).await?;
|
||
```
|
||
|
||
### 3. 格式转换
|
||
|
||
#### 图片序列转视频
|
||
|
||
```rust
|
||
let image_paths = collect_image_sequence("帧/")?;
|
||
processor.images_to_video(
|
||
&image_paths,
|
||
Path::new("输出.mp4"),
|
||
30.0, // 帧率
|
||
QualityPreset::HighQuality,
|
||
Some(&progress_callback),
|
||
).await?;
|
||
```
|
||
|
||
#### 视频转图片序列
|
||
|
||
```rust
|
||
let image_paths = processor.video_to_images(
|
||
Path::new("输入.mp4"),
|
||
Path::new("帧/"),
|
||
"png",
|
||
95, // 质量
|
||
Some(&progress_callback),
|
||
).await?;
|
||
|
||
println!("提取了 {} 帧", image_paths.len());
|
||
```
|
||
|
||
## 配置管理
|
||
|
||
### 全局设置
|
||
|
||
设置全局配置以保持一致的行为：
|
||
|
||
```rust
|
||
use tvai::config::global_settings;
|
||
|
||
let settings = global_settings();
|
||
|
||
// 配置默认值
|
||
settings.set_default_use_gpu(true)?;
|
||
settings.set_max_concurrent_jobs(2)?;
|
||
|
||
// 保存设置
|
||
settings.save_to_file()?;
|
||
|
||
// 从全局设置创建处理器
|
||
let config = settings.create_config()?;
|
||
let processor = TvaiProcessor::new(config)?;
|
||
```
|
||
|
||
### 自定义配置
|
||
|
||
```rust
|
||
let config = TvaiConfig::builder()
|
||
.topaz_path("/自定义/topaz/路径")
|
||
.use_gpu(true)
|
||
.temp_dir("/快速/ssd/临时目录")
|
||
.force_topaz_ffmpeg(true)
|
||
.build()?;
|
||
|
||
let processor = TvaiProcessor::new(config)?;
|
||
```
|
||
|
||
## 模型选择指南
|
||
|
||
### 超分辨率模型
|
||
|
||
| 模型 | 最适合 | 倍数 | 描述 |
|
||
|------|--------|------|------|
|
||
| Iris v3 | 通用 | 1-4x | 最佳整体质量 |
|
||
| Nyx v3 | 人像 | 1-4x | 面部优化 |
|
||
| Theia Fidelity v4 | 老内容 | 2x | 专注修复 |
|
||
| Gaia HQ v5 | 游戏/CG | 1-4x | 锐利细节 |
|
||
| Proteus v4 | 问题素材 | 1-4x | 伪影修复 |
|
||
|
||
### 插值模型
|
||
|
||
| 模型 | 最适合 | 描述 |
|
||
|------|--------|------|
|
||
| Apollo v8 | 高质量 | 最佳整体插值 |
|
||
| Chronos v2 | 动画 | 卡通/动漫内容 |
|
||
| Apollo Fast v1 | 速度 | 更快处理 |
|
||
| Chronos Fast v3 | 快速动画 | 快速动画处理 |
|
||
|
||
## 性能优化
|
||
|
||
### GPU 优化
|
||
|
||
```rust
|
||
use tvai::utils::GpuManager;
|
||
|
||
// 检查 GPU 适用性
|
||
if GpuManager::is_gpu_suitable_for_ai() {
|
||
println!("GPU 适合 AI 处理");
|
||
|
||
// 获取详细信息
|
||
let gpu_info = GpuManager::detect_detailed_gpu_info();
|
||
println!("推荐内存限制: {:?} MB",
|
||
gpu_info.recommended_settings.memory_limit_mb);
|
||
}
|
||
```
|
||
|
||
### 性能监控
|
||
|
||
```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 summary = monitor.get_summary();
|
||
for recommendation in summary.recommendations {
|
||
println!("💡 {}", recommendation);
|
||
}
|
||
```
|
||
|
||
### 内存管理
|
||
|
||
```rust
|
||
// 为有限内存使用较小的块大小
|
||
let settings = PerformanceSettings {
|
||
chunk_size_mb: 50, // 较小的块
|
||
max_concurrent_ops: 1, // 单个操作
|
||
processing_mode: ProcessingMode::MemoryEfficient,
|
||
..Default::default()
|
||
};
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
### 全面的错误处理
|
||
|
||
```rust
|
||
match processor.upscale_video(input, output, params, None).await {
|
||
Ok(result) => {
|
||
println!("✅ 成功: {:?}", result.processing_time);
|
||
}
|
||
Err(error) => {
|
||
eprintln!("❌ 错误: {}", error.category());
|
||
eprintln!("{}", error.user_friendly_message());
|
||
|
||
if error.is_recoverable() {
|
||
eprintln!("💡 此错误可能可以通过不同设置恢复");
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 常见错误解决方案
|
||
|
||
#### 找不到 Topaz
|
||
```
|
||
错误: 找不到 Topaz Video AI
|
||
解决方案: 安装 Topaz Video AI 或设置正确路径
|
||
```
|
||
|
||
#### GPU 错误
|
||
```
|
||
错误: CUDA 内存不足
|
||
解决方案: 降低质量设置或禁用 GPU
|
||
```
|
||
|
||
#### 权限被拒绝
|
||
```
|
||
错误: 无法写入输出目录
|
||
解决方案: 以管理员身份运行或检查权限
|
||
```
|
||
|
||
## 进度跟踪
|
||
|
||
### 简单进度条
|
||
|
||
```rust
|
||
use std::io::{self, Write};
|
||
|
||
let progress_callback: ProgressCallback = Box::new(|progress| {
|
||
let percentage = (progress * 100.0) as u32;
|
||
print!("\r进度: [");
|
||
for i in 0..50 {
|
||
if i < percentage / 2 {
|
||
print!("=");
|
||
} else {
|
||
print!(" ");
|
||
}
|
||
}
|
||
print!("] {}%", percentage);
|
||
io::stdout().flush().unwrap();
|
||
});
|
||
```
|
||
|
||
### 详细进度跟踪
|
||
|
||
```rust
|
||
let progress_callback: ProgressCallback = Box::new(|progress| {
|
||
let percentage = (progress * 100.0) as u32;
|
||
let eta = estimate_time_remaining(progress);
|
||
println!("进度: {}% - 预计剩余时间: {:?}", percentage, eta);
|
||
});
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 文件管理
|
||
|
||
```rust
|
||
// 始终验证输入文件
|
||
processor.validate_input_file(input_path)?;
|
||
processor.validate_output_path(output_path)?;
|
||
|
||
// 为中间处理使用临时文件
|
||
let temp_path = processor.create_unique_temp_path("中间.mp4");
|
||
// ... 处理到临时文件 ...
|
||
std::fs::rename(temp_path, final_output)?;
|
||
```
|
||
|
||
### 2. 资源管理
|
||
|
||
```rust
|
||
// 使用 RAII 进行自动清理
|
||
{
|
||
let mut processor = TvaiProcessor::new(config)?;
|
||
// 处理在这里进行
|
||
// 处理器在丢弃时自动清理
|
||
}
|
||
```
|
||
|
||
### 3. 批量处理
|
||
|
||
```rust
|
||
// 分批处理以避免内存问题
|
||
let chunk_size = 10;
|
||
for chunk in image_paths.chunks(chunk_size) {
|
||
let results = processor.batch_upscale_images(
|
||
chunk,
|
||
output_dir,
|
||
params.clone(),
|
||
Some(&progress_callback),
|
||
).await?;
|
||
|
||
// 处理结果或保存状态
|
||
}
|
||
```
|
||
|
||
### 4. 错误恢复
|
||
|
||
```rust
|
||
// 为可恢复错误实现重试逻辑
|
||
let mut attempts = 0;
|
||
let max_attempts = 3;
|
||
|
||
loop {
|
||
match processor.upscale_video(input, output, params.clone(), None).await {
|
||
Ok(result) => break Ok(result),
|
||
Err(error) if error.is_recoverable() && attempts < max_attempts => {
|
||
attempts += 1;
|
||
eprintln!("尝试 {} 失败，重试中...", attempts);
|
||
tokio::time::sleep(Duration::from_secs(1)).await;
|
||
}
|
||
Err(error) => break Err(error),
|
||
}
|
||
}
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **处理缓慢**
|
||
- 启用 GPU 加速
|
||
- 使用更快的模型 (Apollo Fast, Chronos Fast)
|
||
- 降低质量设置
|
||
|
||
2. **内存不足**
|
||
- 减少块大小
|
||
- 降低质量预设
|
||
- 处理较小的文件
|
||
|
||
3. **质量结果差**
|
||
- 为内容类型使用适当的模型
|
||
- 调整压缩和混合参数
|
||
- 使用更高质量预设
|
||
|
||
4. **文件格式问题**
|
||
- 首先转换为支持的格式
|
||
- 检查文件损坏
|
||
- 验证文件权限
|
||
|
||
### 获取帮助
|
||
|
||
1. 检查错误消息和建议
|
||
2. 查看 API 文档
|
||
3. 运行示例以验证设置
|
||
4. 检查系统要求和 GPU 驱动程序
|