mixvideo-v2/cargos/tvai/docs/用户指南.md

TVAI 库用户指南

快速开始

安装

在您的 Cargo.toml 中添加 TVAI：

[dependencies]
tvai = "0.1.0"

前置要求

1. Topaz Video AI - 从 Topaz Labs 下载并安装
2. GPU 驱动 - 最新的 NVIDIA 或 AMD 驱动程序以支持 GPU 加速
3. Rust 1.70+ - 用于构建库

快速开始

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. 视频增强

老视频修复

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);

创建慢动作效果

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?;

完整增强

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. 图片增强

批量照片增强

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());

目录批量处理

let results = processor.upscale_directory(
    Path::new("输入照片"),
    Path::new("输出照片"),
    ImageUpscaleParams::for_photo(),
    true, // 递归处理子目录
    Some(&progress_callback),
).await?;

3. 格式转换

图片序列转视频

let image_paths = collect_image_sequence("帧/")?;
processor.images_to_video(
    &image_paths,
    Path::new("输出.mp4"),
    30.0, // 帧率
    QualityPreset::HighQuality,
    Some(&progress_callback),
).await?;

视频转图片序列

let image_paths = processor.video_to_images(
    Path::new("输入.mp4"),
    Path::new("帧/"),
    "png",
    95, // 质量
    Some(&progress_callback),
).await?;

println!("提取了 {} 帧", image_paths.len());

配置管理

全局设置

设置全局配置以保持一致的行为：

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)?;

自定义配置

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 优化

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);
}

性能监控

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);
}

内存管理

// 为有限内存使用较小的块大小
let settings = PerformanceSettings {
    chunk_size_mb: 50, // 较小的块
    max_concurrent_ops: 1, // 单个操作
    processing_mode: ProcessingMode::MemoryEfficient,
    ..Default::default()
};

错误处理

全面的错误处理

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

权限被拒绝

错误: 无法写入输出目录
解决方案: 以管理员身份运行或检查权限

进度跟踪

简单进度条

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();
});

详细进度跟踪

let progress_callback: ProgressCallback = Box::new(|progress| {
    let percentage = (progress * 100.0) as u32;
    let eta = estimate_time_remaining(progress);
    println!("进度: {}% - 预计剩余时间: {:?}", percentage, eta);
});

最佳实践

1. 文件管理

// 始终验证输入文件
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. 资源管理

// 使用 RAII 进行自动清理
{
    let mut processor = TvaiProcessor::new(config)?;
    // 处理在这里进行
    // 处理器在丢弃时自动清理
}

3. 批量处理

// 分批处理以避免内存问题
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. 错误恢复

// 为可恢复错误实现重试逻辑
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 驱动程序