269 lines
6.7 KiB
Markdown
269 lines
6.7 KiB
Markdown
# TVAI - Topaz Video AI Integration Library
|
|
|
|
A Rust library for integrating with Topaz Video AI to perform video and image enhancement including super-resolution upscaling and frame interpolation.
|
|
|
|
## Features
|
|
|
|
- 🎬 **Video Super-Resolution**: Upscale videos using AI models
|
|
- 🎞️ **Frame Interpolation**: Create smooth slow motion effects
|
|
- 🖼️ **Image Upscaling**: Enhance image resolution and quality
|
|
- ⚡ **GPU Acceleration**: CUDA and hardware encoding support
|
|
- 🔧 **Multiple AI Models**: 16 upscaling and 4 interpolation models
|
|
- 📦 **Batch Processing**: Process multiple files efficiently
|
|
- 🎛️ **Flexible Configuration**: Fine-tune processing parameters
|
|
|
|
## Requirements
|
|
|
|
- [Topaz Video AI](https://www.topazlabs.com/topaz-video-ai) installed
|
|
- Rust 1.70+
|
|
- FFmpeg (included with Topaz Video AI)
|
|
- Optional: CUDA-compatible GPU for acceleration
|
|
|
|
## Installation
|
|
|
|
Add this to your `Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
tvai = "0.1.0"
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Video Upscaling
|
|
|
|
```rust
|
|
use tvai::*;
|
|
|
|
#[tokio::main]
|
|
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
// Quick 2x upscaling
|
|
quick_upscale_video(
|
|
std::path::Path::new("input.mp4"),
|
|
std::path::Path::new("output.mp4"),
|
|
2.0,
|
|
).await?;
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
### Image Upscaling
|
|
|
|
```rust
|
|
use tvai::*;
|
|
|
|
#[tokio::main]
|
|
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
// Quick 4x image upscaling
|
|
quick_upscale_image(
|
|
std::path::Path::new("photo.jpg"),
|
|
std::path::Path::new("photo_4x.png"),
|
|
4.0,
|
|
).await?;
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
### Advanced Usage
|
|
|
|
```rust
|
|
use tvai::*;
|
|
|
|
#[tokio::main]
|
|
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
// Detect Topaz installation
|
|
let topaz_path = detect_topaz_installation()
|
|
.ok_or("Topaz Video AI not found")?;
|
|
|
|
// Create configuration
|
|
let config = TvaiConfig::builder()
|
|
.topaz_path(topaz_path)
|
|
.use_gpu(true)
|
|
.build()?;
|
|
|
|
// Create processor
|
|
let processor = TvaiProcessor::new(config)?;
|
|
|
|
// Custom upscaling parameters
|
|
let params = VideoUpscaleParams {
|
|
scale_factor: 2.0,
|
|
model: UpscaleModel::Iris3,
|
|
compression: 0.0,
|
|
blend: 0.1,
|
|
quality_preset: QualityPreset::HighQuality,
|
|
};
|
|
|
|
// Process video
|
|
let result = processor.upscale_video(
|
|
std::path::Path::new("input.mp4"),
|
|
std::path::Path::new("output.mp4"),
|
|
params,
|
|
).await?;
|
|
|
|
println!("Processing completed in {:?}", result.processing_time);
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
## AI Models
|
|
|
|
### Upscaling Models
|
|
|
|
- **Iris v3** - Best general purpose model
|
|
- **Nyx v3** - Optimized for portraits
|
|
- **Theia Fidelity v4** - Old content restoration
|
|
- **Gaia HQ v5** - Game/CG content
|
|
- **Proteus v4** - Problem footage repair
|
|
- And more...
|
|
|
|
### Interpolation Models
|
|
|
|
- **Apollo v8** - High quality interpolation
|
|
- **Chronos v2** - Animation content
|
|
- **Apollo Fast v1** - Fast processing
|
|
- **Chronos Fast v3** - Fast animation
|
|
|
|
## Presets
|
|
|
|
The library includes optimized presets for common use cases:
|
|
|
|
```rust
|
|
// Video presets
|
|
let old_video_params = VideoUpscaleParams::for_old_video();
|
|
let game_params = VideoUpscaleParams::for_game_content();
|
|
let animation_params = VideoUpscaleParams::for_animation();
|
|
let portrait_params = VideoUpscaleParams::for_portrait();
|
|
|
|
// Image presets
|
|
let photo_params = ImageUpscaleParams::for_photo();
|
|
let artwork_params = ImageUpscaleParams::for_artwork();
|
|
let screenshot_params = ImageUpscaleParams::for_screenshot();
|
|
```
|
|
|
|
## System Detection
|
|
|
|
```rust
|
|
// Detect Topaz installation
|
|
let topaz_path = detect_topaz_installation();
|
|
|
|
// Check GPU support
|
|
let gpu_info = detect_gpu_support();
|
|
|
|
// Check FFmpeg availability
|
|
let ffmpeg_info = detect_ffmpeg();
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
The library uses the `anyhow` crate for error handling:
|
|
|
|
```rust
|
|
use tvai::*;
|
|
|
|
match quick_upscale_video(input, output, 2.0).await {
|
|
Ok(result) => println!("Success: {:?}", result),
|
|
Err(TvaiError::TopazNotFound(path)) => {
|
|
eprintln!("Topaz not found at: {}", path);
|
|
},
|
|
Err(TvaiError::FfmpegError(msg)) => {
|
|
eprintln!("FFmpeg error: {}", msg);
|
|
},
|
|
Err(e) => eprintln!("Other error: {}", e),
|
|
}
|
|
```
|
|
|
|
## Development Status
|
|
|
|
✅ **COMPLETE** - All core features implemented and tested!
|
|
|
|
- [x] Basic project structure
|
|
- [x] FFmpeg management
|
|
- [x] Core processor framework
|
|
- [x] Video upscaling implementation (16 AI models)
|
|
- [x] Frame interpolation implementation (4 AI models)
|
|
- [x] Image upscaling implementation
|
|
- [x] Batch processing (videos and images)
|
|
- [x] Progress callbacks and monitoring
|
|
- [x] Global configuration management
|
|
- [x] Preset management system
|
|
- [x] Performance optimization
|
|
- [x] Enhanced error handling
|
|
- [x] Comprehensive testing (unit + integration + benchmarks)
|
|
- [x] Complete documentation (API + User Guide)
|
|
|
|
## Documentation
|
|
|
|
### English
|
|
- 📖 [API Documentation](docs/API.md) - Complete API reference
|
|
- 📚 [User Guide](docs/USER_GUIDE.md) - Comprehensive usage guide
|
|
|
|
### 中文文档
|
|
- 📖 [API 文档](docs/API文档.md) - 完整 API 参考
|
|
- 📚 [用户指南](docs/用户指南.md) - 详细使用指南
|
|
- 📋 [中文 README](README_CN.md) - 中文版说明文档
|
|
|
|
### Resources
|
|
- 🔧 [Examples](examples/) - Working code examples
|
|
- 🧪 [Tests](tests/) - Integration tests
|
|
- 📊 [Benchmarks](benches/) - Performance benchmarks
|
|
|
|
## Performance
|
|
|
|
The library is optimized for performance with:
|
|
|
|
- **GPU Acceleration** - CUDA and hardware encoding support
|
|
- **Concurrent Processing** - Configurable parallel operations
|
|
- **Memory Management** - Efficient temporary file handling
|
|
- **Smart Caching** - Intelligent resource utilization
|
|
- **Progress Monitoring** - Real-time performance tracking
|
|
|
|
Run benchmarks with:
|
|
```bash
|
|
cargo bench
|
|
```
|
|
|
|
## Testing
|
|
|
|
Comprehensive test suite including:
|
|
|
|
- **Unit Tests** - Core functionality testing
|
|
- **Integration Tests** - End-to-end workflow testing
|
|
- **Benchmark Tests** - Performance validation
|
|
|
|
Run tests with:
|
|
```bash
|
|
cargo test
|
|
cargo test --release # For performance tests
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
|
|
### Development Setup
|
|
|
|
1. Install Rust 1.70+
|
|
2. Install Topaz Video AI
|
|
3. Clone the repository
|
|
4. Run tests: `cargo test`
|
|
5. Run examples: `cargo run --example basic_usage`
|
|
|
|
## Changelog
|
|
|
|
### v0.1.0 (Current)
|
|
|
|
- ✅ Complete video processing (upscaling + interpolation)
|
|
- ✅ Complete image processing (upscaling + batch operations)
|
|
- ✅ 16 AI upscaling models + 4 interpolation models
|
|
- ✅ Global configuration and preset management
|
|
- ✅ Performance monitoring and optimization
|
|
- ✅ Enhanced error handling with user-friendly messages
|
|
- ✅ Comprehensive documentation and examples
|
|
- ✅ Full test coverage (unit + integration + benchmarks)
|