mixvideo-v2/cargos/tvai-v2/tvai.md

# Topaz Video AI FFmpeg 深度分析文档

## 概述

Topaz Video AI 提供了一个定制版本的 FFmpeg，集成了 Topaz Labs 的 AI 视频增强技术。该版本基于 FFmpeg 7.1.git，包含了专门的 AI 滤镜和优化功能。

### 版本信息
- **FFmpeg 版本**: 7.1.git
- **编译器**: Microsoft (R) C/C++ Optimizing Compiler Version 19.43.34809 for x64
- **库版本**:
  - libavutil: 60.3.100
  - libavcodec: 62.3.101
  - libavformat: 62.0.102
  - libavdevice: 62.0.100
  - libavfilter: 11.0.100
  - libswscale: 9.0.100
  - libswresample: 6.0.100

### 编译配置详情
- **工具链**: MSVC
- **特殊配置标志**:
  - `--enable-tvai` (启用 Topaz Video AI 支持)
  - `--enable-libvpx` (VP8/VP9 编码支持)
  - `--enable-libaom` (AV1 编码支持)
  - `--enable-shared` (共享库支持)
  - `--enable-x86asm` (x86 汇编优化)
  - `--enable-nvenc` (NVIDIA 硬件编码)
  - `--enable-nvdec` (NVIDIA 硬件解码)
  - `--enable-amf` (AMD 硬件加速)
  - `--enable-libvpl` (Intel Video Processing Library)
  - `--enable-zlib` (压缩支持)
  - `--enable-libzimg` (图像缩放库)
  - `--disable-vulkan` (禁用 Vulkan 支持)

### 关键特性
- 集成 Topaz Video AI 模型
- 支持 NVIDIA NVENC/NVDEC 硬件加速
- 支持 AMD AMF 硬件加速
- 支持 Intel Quick Sync Video (QSV)
- 支持 VP8/VP9 和 AV1 编码
- 优化的 x86 汇编代码
- 禁用 Vulkan 支持（专注于其他硬件加速方案）

## Topaz Video AI 专用滤镜

**重要说明**:
- 所有 Topaz Video AI 滤镜都支持 timeline 功能，可以通过 `enable` 选项在特定时间段启用或禁用滤镜
- 所有滤镜都是单输入单输出（1 video input → 1 video output）
- 滤镜标记说明：T = Timeline support（时间线支持）

### 1. tvai_up - AI 视频放大滤镜

**功能**: 使用 Topaz Video AI 放大模型对视频进行智能放大和增强

**Timeline 支持**: 支持通过 `enable` 选项进行时间线控制

#### 基本参数
- **model** (string): 模型短名称
  - 默认值: "ahq-12"
  - 说明: 指定使用的 AI 模型

- **scale** (int): 输出缩放倍数
  - 范围: 0-4
  - 默认值: 1
  - 说明: 设置放大倍数

- **w** (int): 基于输出宽度估算缩放
  - 范围: 0-100000
  - 默认值: 0
  - 说明: 根据目标宽度自动计算缩放比例

- **h** (int): 基于输出高度估算缩放
  - 范围: 0-100000
  - 默认值: 0
  - 说明: 根据目标高度自动计算缩放比例

#### 设备和性能参数
- **device** (string): 设备索引
  - 默认值: "-2" (自动)
  - 选项:
    - "-2": 自动选择
    - "-1": CPU
    - "0": GPU0
    - "0.1.3": 多GPU (用点分隔)

- **instances** (int): 额外模型实例数量
  - 范围: 0-3
  - 默认值: 0
  - 说明: 在设备上使用的额外模型实例数

- **vram** (double): 最大内存使用量
  - 范围: 0.1-1
  - 默认值: 1
  - 说明: GPU 内存使用比例

#### 模型和下载参数
- **download** (int): 启用模型下载
  - 范围: 0-1
  - 默认值: 1
  - 说明: 是否允许自动下载模型

- **estimate** (int): 自动参数估算帧数
  - 范围: 0-100
  - 默认值: 0
  - 说明: 用于自动参数估算的帧数，0 表示禁用

#### 图像质量调整参数
- **preblur** (double): 预模糊调整
  - 范围: -1 到 1
  - 默认值: 0
  - 说明: 调整抗锯齿和去模糊强度。负值适用于有锯齿伪影的视频，正值适用于镜头模糊较多的视频

- **noise** (double): 噪声去除
  - 范围: -1 到 1
  - 默认值: 0
  - 说明: 去除 ISO 噪声。数值相对于输入视频的噪声量

- **details** (double): 细节恢复
  - 范围: -1 到 1
  - 默认值: 0
  - 说明: 恢复因相机内噪声抑制而丢失的精细纹理和细节

- **halo** (double): 光晕伪影处理
  - 范围: -1 到 1
  - 默认值: 0
  - 说明: 处理过度锐化造成的光晕或环形伪影

- **blur** (double): 额外锐化
  - 范围: -1 到 1
  - 默认值: 0
  - 说明: 对视频进行额外锐化，适用于过软的输入视频

- **compression** (double): 压缩伪影减少
  - 范围: -1 到 1
  - 默认值: 0
  - 说明: 减少编码压缩伪影，如块状或蚊式噪声

#### 特效参数
- **prenoise** (double): 输入前噪声添加
  - 范围: 0-0.1
  - 默认值: 0
  - 说明: 处理前向输入添加的噪声量

- **grain** (double): 输出颗粒添加
  - 范围: 0-0.1
  - 默认值: 0
  - 说明: 向输出添加的颗粒量

- **gsize** (double): 颗粒大小
  - 范围: 0-5
  - 默认值: 0
  - 说明: 添加颗粒的大小

#### 其他参数
- **kcolor** (int): 额外颜色校正
  - 范围: 0-1
  - 默认值: 1
  - 说明: 如果模型需要，运行额外的颜色校正

- **blend** (double): 输入混合
  - 范围: 0-1
  - 默认值: 0
  - 说明: 输入与输出混合的比例

- **parameters** (dictionary): 额外参数字典
  - 默认值: ""
  - 说明: 用于传递模型特定的额外参数

#### 特殊模型参数
**Hyperion (hyp-1) 参数**:
- **sdr_ip**: SDR 高光阈值 (0.45-0.85)
- **hdr_ip_adjust**: 曝光调整量 (0-1)
- **saturate**: 饱和度调整量 (0-1)

**Segment-Anything-2 (vsam) 参数**:
- **clicks**: 点击表达式，用于对象分割和跟踪
  - 格式示例: `c0c1_2f0o0px1230y210x1260y390mx1218y561`
  - `c`: 控制对象在哪个通道出现
  - `f`: 控制点击的帧位置
  - `o`: 控制每个对象的点击
  - `p/m`: 正/负点击
  - `x/y`: 坐标位置（支持像素和归一化坐标）

### 2. tvai_fi - AI 帧插值滤镜

**功能**: 使用 Topaz Video AI 帧插值模型增加视频帧率

**Timeline 支持**: 支持通过 `enable` 选项进行时间线控制

#### 基本参数
- **model** (string): 模型短名称
  - 默认值: "chr-2"

- **slowmo** (double): 慢动作因子
  - 范围: 0.1-16
  - 默认值: 1
  - 说明: 输入视频的慢动作倍数

- **fps** (video_rate): 输出帧率
  - 默认值: "0" (与输入相同)
  - 说明: 目标输出帧率

#### 设备参数
- **device** (string): 设备索引 (同 tvai_up)
- **instances** (int): 额外模型实例数 (同 tvai_up)
- **vram** (double): 最大内存使用量 (同 tvai_up)
- **download** (int): 启用模型下载 (同 tvai_up)

#### 特殊参数
- **rdt** (double): 重复帧替换阈值
  - 范围: -0.01 到 0.2
  - 默认值: 0.01
  - 说明: 0 或以下表示不移除重复帧，高值会检测更多重复帧

- **parameters** (dictionary): 额外选项
  - 默认值: ""
  - 说明: 用于传递模型特定的额外参数

### 3. tvai_pe - AI 参数估算滤镜

**功能**: 使用 Topaz Video AI 参数估算模型自动分析视频特征

**Timeline 支持**: 支持通过 `enable` 选项进行时间线控制

#### 参数
- **model** (string): 模型短名称
  - 默认值: "prap-3"

- **download** (int): 启用模型下载
  - 范围: 0-1
  - 默认值: 1

### 4. tvai_cpe - AI 相机姿态估算滤镜

**功能**: 使用 Topaz Video AI 相机姿态估算模型分析相机运动

**Timeline 支持**: 支持通过 `enable` 选项进行时间线控制

#### 参数
- **model** (string): 模型短名称
  - 默认值: "cpe-1"

- **filename** (string): CPE 输出文件名
  - 默认值: "cpe.json"

- **device** (string): 设备索引 (同 tvai_up)
- **download** (int): 启用模型下载 (同 tvai_up)

#### 特殊参数
- **parameters** (dictionary): 额外选项
  - 默认值: ""
  - 说明: 用于传递模型特定的参数

#### AutoShot (ash-1) 参数
- **threshold**: 最小原始镜头检测结果阈值
  - 范围: 0-1
  - 默认值: ""
  - 说明: 被计算为参数的最小原始镜头检测结果

### 5. tvai_stb - AI 视频稳定滤镜

**功能**: 使用 Topaz Video AI 稳定模型对视频进行智能稳定

**Timeline 支持**: 支持通过 `enable` 选项进行时间线控制

#### 基本参数
- **model** (string): 模型短名称
  - 默认值: "ref-2"

- **full** (int): 执行全帧稳定
  - 范围: 0-1
  - 默认值: 1
  - 说明: 禁用时执行自动裁剪（忽略全帧相关选项）

#### 设备参数
- **device**, **instances**, **vram**, **download**: 同 tvai_up

#### 文件和时间参数
- **filename** (string): CPE 输出文件名
  - 默认值: "cpe.json"

- **rst** (double): 相对于 CPE 的读取开始时间
  - 范围: 0 到 DBL_MAX
  - 默认值: 0

- **wst** (double): 相对于读取开始时间的写入开始时间
  - 范围: 0 到 DBL_MAX
  - 默认值: 0

#### 稳定参数
- **smoothness** (double): 平滑度
  - 范围: 0-16
  - 默认值: 6
  - 说明: 应用于相机轨迹的平滑量

- **dof** (int): 运动自由度控制
  - 范围: 0-1111
  - 默认值: 1111
  - 说明: 4位数字控制不同运动的稳定：旋转(第1位)、水平平移(第2位)、垂直平移(第3位)、缩放(第4位)

#### 高级参数
- **postFlight** (int): 启用后期处理
  - 范围: 0-1
  - 默认值: 1

- **ws** (int): 全帧合成窗口大小
  - 范围: 0-512
  - 默认值: 64

- **csx** (double): 画布相对于输入宽度的缩放
  - 范围: 1-8
  - 默认值: 2

- **csy** (double): 画布相对于输入高度的缩放
  - 范围: 1-8
  - 默认值: 2

- **cache** (int): 内存缓存大小
  - 范围: 0-256
  - 默认值: 128

- **roll** (int): 启用滚动快门校正
  - 范围: 0-1
  - 默认值: 0

- **reduce** (int): 减少运动抖动
  - 范围: 0-5
  - 默认值: 0

#### 额外参数
- **parameters** (dictionary): 额外选项
  - 默认值: ""
  - 说明: 用于传递模型特定的额外参数

## 使用示例

### 基本视频放大
```bash
ffmpeg -i input.mp4 -vf "tvai_up=model=ahq-12:scale=2" output.mp4
```

### 高质量放大与降噪
```bash
ffmpeg -i input.mp4 -vf "tvai_up=model=ahq-12:scale=2:noise=0.3:details=0.2" output.mp4
```

### 帧插值提升帧率
```bash
ffmpeg -i input.mp4 -vf "tvai_fi=model=chr-2:fps=60" output.mp4
```

### 视频稳定
```bash
ffmpeg -i input.mp4 -vf "tvai_stb=model=ref-2:smoothness=8" output.mp4
```

### 组合处理
```bash
ffmpeg -i input.mp4 -vf "tvai_up=scale=2,tvai_fi=fps=60,tvai_stb=smoothness=6" output.mp4
```

### 高级用法示例

#### 使用 GPU 加速和多实例
```bash
ffmpeg -i input.mp4 -vf "tvai_up=model=ahq-12:scale=2:device=0:instances=2:vram=0.8" output.mp4
```

#### 自动参数估算
```bash
ffmpeg -i input.mp4 -vf "tvai_up=scale=2:estimate=10" output.mp4
```

#### 处理压缩严重的视频
```bash
ffmpeg -i input.mp4 -vf "tvai_up=scale=2:compression=0.5:noise=0.3:details=0.4" output.mp4
```

#### 稳定抖动视频并放大
```bash
ffmpeg -i input.mp4 -vf "tvai_stb=smoothness=10:dof=1111,tvai_up=scale=2" output.mp4
```

#### 使用硬件编码器输出
```bash
# NVIDIA NVENC H.265
ffmpeg -i input.mp4 -vf "tvai_up=scale=2" -c:v hevc_nvenc -preset slow -crf 18 output.mp4

# AMD AMF H.264
ffmpeg -i input.mp4 -vf "tvai_up=scale=2" -c:v h264_amf -quality quality -rc cqp -qp 20 output.mp4

# Intel QSV H.264
ffmpeg -i input.mp4 -vf "tvai_up=scale=2" -c:v h264_qsv -preset veryslow -global_quality 20 output.mp4
```

#### Timeline 功能使用示例
```bash
# 仅在前30秒应用放大滤镜
ffmpeg -i input.mp4 -vf "tvai_up=scale=2:enable='lt(t,30)'" output.mp4

# 在10-60秒之间应用帧插值
ffmpeg -i input.mp4 -vf "tvai_fi=fps=60:enable='between(t,10,60)'" output.mp4

# 在特定时间段应用稳定
ffmpeg -i input.mp4 -vf "tvai_stb=smoothness=8:enable='gte(t,5)*lte(t,120)'" output.mp4

# 组合使用：前半段放大，后半段稳定
ffmpeg -i input.mp4 -vf "tvai_up=scale=2:enable='lt(t,duration/2)',tvai_stb=smoothness=6:enable='gte(t,duration/2)'" output.mp4
```

## 常用模型说明

### tvai_up 放大模型
- **ahq-12**: 默认高质量模型，适用于大多数场景
- **hyp-1**: Hyperion 模型，专门用于 HDR 内容处理
- **vsam**: Segment-Anything-2 模型，支持对象分割

### tvai_fi 帧插值模型
- **chr-2**: 默认帧插值模型，适用于大多数视频类型
- 其他模型需要根据具体内容选择

### tvai_stb 稳定模型
- **ref-2**: 默认稳定模型，提供平衡的稳定效果

### tvai_pe 参数估算模型
- **prap-3**: 默认参数估算模型

### tvai_cpe 相机姿态估算模型
- **cpe-1**: 默认相机姿态估算模型
- **ash-1**: AutoShot 模型，用于镜头检测

## 注意事项

1. **模型下载**: 首次使用时会自动下载相应的 AI 模型，需要网络连接
2. **硬件要求**:
   - AI 处理需要较强的 GPU 支持，建议使用 NVIDIA RTX 系列显卡
   - 最低 8GB GPU 内存，推荐 16GB 或更多
   - CPU: Intel i7 或 AMD Ryzen 7 及以上
3. **内存管理**:
   - 通过 `vram` 参数控制 GPU 内存使用，避免内存溢出
   - 使用 `instances` 参数可以并行处理，但会增加内存消耗
4. **处理时间**:
   - AI 处理比传统滤镜耗时更长，需要耐心等待
   - 处理时间与视频分辨率、长度和模型复杂度成正比
5. **参数调优**:
   - 建议根据具体视频内容调整参数，避免过度处理
   - 先用小片段测试参数效果，再处理完整视频
6. **文件格式兼容性**:
   - 输入支持大多数常见视频格式
   - 建议使用无损或高质量格式作为输入
7. **批处理建议**:
   - 对于大量文件，建议编写脚本进行批处理
   - 可以使用 `-y` 参数自动覆盖输出文件

## 硬件加速支持

### 支持的硬件加速方法
- **CUDA**: NVIDIA GPU 通用计算加速
- **DXVA2**: DirectX Video Acceleration 2.0
- **QSV**: Intel Quick Sync Video
- **D3D11VA**: Direct3D 11 Video Acceleration
- **D3D12VA**: Direct3D 12 Video Acceleration
- **AMF**: AMD Advanced Media Framework

### NVIDIA NVENC/NVDEC
- **支持编码格式**: H.264、H.265、AV1
- **特点**: 显著提升编码速度，减少 CPU 负载
- **适用显卡**: GeForce GTX 10 系列及以上，RTX 系列

### AMD AMF
- **支持编码格式**: H.264、H.265、AV1
- **特点**: 硬件加速编码，适用于 AMD 显卡用户
- **适用显卡**: Radeon RX 400 系列及以上

### Intel Quick Sync Video (QSV)
- **支持编码格式**: H.264、H.265、MJPEG、MPEG-2、VP9
- **特点**: 集成在 Intel CPU 中的硬件编码器
- **适用处理器**: Intel Core 2 代及以上（带集成显卡）

## 设备支持

### 输入设备
- **DirectShow**: Windows 系统摄像头和采集卡
- **GDI API**: Windows 桌面录制
- **VfW**: Video for Windows 设备
- **Libavfilter**: 虚拟输入设备

## 网络协议支持

### 输入协议
- HTTP/HTTPS、FTP、RTMP/RTMPS、RTP/SRTP
- HLS (HTTP Live Streaming)
- TCP/UDP 流媒体
- IPFS/IPNS 分布式存储

### 输出协议
- HTTP/HTTPS、FTP、RTMP/RTMPS、RTP/SRTP
- Icecast 流媒体服务器
- TCP/UDP 推流

## 第三方库集成

### 视频编码库
- **libvpx**: Google VP8/VP9 编码器
- **libaom**: AV1 开源编码器
- **libzimg**: 高质量图像缩放库

### 系统库
- **zlib**: 数据压缩库
- **NASM**: 网络汇编器（用于 x86 优化）

## 性能优化特性

### 汇编优化
- 启用 x86 汇编优化代码
- 使用 NASM 汇编器进行性能优化
- 针对现代 x64 处理器优化

### 内存管理
- 共享库支持，减少内存占用
- 优化的内存分配策略
- 支持大文件处理

## 与标准 FFmpeg 的主要区别

### 独有功能
1. **Topaz Video AI 滤镜**: 5 个专用 AI 滤镜
2. **AI 模型集成**: 自动下载和管理 AI 模型
3. **专用库路径**: 集成 Topaz VideoAI 库
4. **优化配置**: 针对视频 AI 处理优化的编译配置

### 缺失功能
- **Vulkan 支持**: 被禁用以专注于其他硬件加速方案
- **某些开源编码器**: 可能缺少一些标准 FFmpeg 中的编码器

## 故障排除

### 常见问题

#### 1. 模型下载失败
```bash
# 错误信息: Failed to download model
# 解决方案: 检查网络连接，或手动下载模型文件
```

#### 2. GPU 内存不足
```bash
# 错误信息: CUDA out of memory
# 解决方案: 降低 vram 参数值
ffmpeg -i input.mp4 -vf "tvai_up=scale=2:vram=0.5" output.mp4
```

#### 3. 处理速度过慢
```bash
# 解决方案: 使用多实例并行处理
ffmpeg -i input.mp4 -vf "tvai_up=scale=2:instances=2" output.mp4
```

#### 4. 输出质量不理想
```bash
# 解决方案: 调整质量参数
ffmpeg -i input.mp4 -vf "tvai_up=scale=2:noise=0.2:details=0.3:compression=0.1" output.mp4
```

### 性能优化建议

#### 1. 硬件配置优化
- 使用 NVMe SSD 存储输入和输出文件
- 确保充足的系统内存（32GB 推荐）
- 使用高端 GPU（RTX 4080/4090 推荐）

#### 2. 参数优化
```bash
# 对于高分辨率视频，降低 VRAM 使用
ffmpeg -i 4k_input.mp4 -vf "tvai_up=scale=2:vram=0.6" output.mp4

# 对于长视频，使用缓存优化
ffmpeg -i long_video.mp4 -vf "tvai_stb=cache=256" output.mp4
```

#### 3. 批处理脚本示例
```bash
# Windows 批处理脚本
@echo off
for %%f in (*.mp4) do (
    "C:\Program Files\Topaz Labs LLC\Topaz Video AI\ffmpeg.exe" -i "%%f" -vf "tvai_up=scale=2" "enhanced_%%f"
)
```

## 总结

这个定制版 FFmpeg 为视频处理提供了强大的 AI 增强功能，特别适合需要高质量视频放大、帧插值和稳定的专业应用场景。它在保持 FFmpeg 核心功能的同时，添加了 Topaz Labs 的专业 AI 视频处理能力。

### 主要优势
1. **AI 驱动**: 使用深度学习模型进行智能视频处理
2. **硬件加速**: 充分利用现代 GPU 的计算能力
3. **专业品质**: Topaz Labs 在视频增强领域的专业技术
4. **易于集成**: 基于标准 FFmpeg，易于集成到现有工作流程

### 适用场景
- 老旧视频的高清化处理
- 低帧率视频的流畅化
- 抖动视频的稳定处理
- 专业视频后期制作
- 内容创作和媒体制作