# 视频转码配置说明

## 概述

由壹点3D素材平台支持视频素材的自动转码功能，可以将上传的视频转换为适合在线预览的格式。

## 环境要求

### 1. FFmpeg

视频转码需要 FFmpeg 工具。在 Docker 环境中，FFmpeg 已经在 Dockerfile 中安装：

```dockerfile
RUN apk add --no-cache ffmpeg
```

### 2. 环境变量配置

在 `docker-compose.yml` 或 `.env` 文件中配置以下环境变量：

```bash
# 视频转码编码器（推荐使用 libx265，压缩率更高）
VIDEO_TRANSCODE_CODEC=libx265

# 转码预设（速度与质量的平衡）
# 可选值：ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow
# 推荐：medium（平衡速度和质量）
VIDEO_TRANSCODE_PRESET=medium

# 恒定质量因子（CRF，控制视频质量）
# 范围：0-51，数值越小质量越高，文件越大
# 推荐：22-28（22 为高质量，28 为较低质量）
VIDEO_TRANSCODE_CRF=22

# 音频比特率
# 推荐：128k-192k（128k 为标准质量，192k 为高质量）
VIDEO_AUDIO_BITRATE=160k
```

### 3. Redis 配置（可选）

如果需要使用 Redis 管理转码队列（推荐用于生产环境），需要配置：

```bash
# 启用 Redis
USE_REDIS=true

# Redis 连接地址
REDIS_URL=redis://localhost:6379
```

**注意**：
- 如果不配置 Redis，系统会使用内存队列（重启后队列会丢失）
- 生产环境强烈推荐使用 Redis，确保转码任务不会因为重启而丢失

## 转码流程

### 1. 上传视频

用户上传视频素材时，系统会：
1. 保存原始视频文件到 S3
2. 创建素材记录，设置 `videoProcessingStatus = 'pending'`
3. 将转码任务加入队列

### 2. 转码处理

转码队列会自动处理待转码的视频：
1. 从队列中取出任务
2. 下载原始视频
3. 使用 FFmpeg 转码：
   - 生成 540p 预览视频（`videoPreview540Url`）
   - 生成 10 秒预览片段（`videoPreviewClipUrl`）
   - 提取视频封面（`videoCoverUrl`）
4. 上传转码后的文件到 S3
5. 更新素材记录，设置 `videoProcessingStatus = 'completed'`

### 3. 转码失败处理

如果转码失败：
1. 系统会记录错误信息到 `transcodeLastError` 字段
2. 增加重试次数（`transcodeAttempts`）
3. 如果重试次数超过限制（默认 3 次），标记为 `failed`
4. 用户可以在前端手动重试转码

## API 接口

### 查询转码状态

```http
GET /api/materials/transcode?materialId=xxx
```

**响应示例**：
```json
{
  "status": "processing",
  "progress": 45,
  "message": "正在转码中..."
}
```

### 启动转码任务

```http
POST /api/materials/transcode
Content-Type: application/json

{
  "materialId": "xxx"
}
```

**响应示例**：
```json
{
  "message": "转码任务已启动",
  "status": "processing"
}
```

## 转码参数说明

### VIDEO_TRANSCODE_CODEC

**libx264**（H.264）：
- 优点：兼容性好，几乎所有设备都支持
- 缺点：文件较大
- 适用场景：需要最大兼容性的场景

**libx265**（H.265/HEVC）：
- 优点：压缩率高，文件小，画质好
- 缺点：编码速度较慢，部分老设备不支持
- 适用场景：追求高画质和小文件的场景（推荐）

### VIDEO_TRANSCODE_PRESET

速度从快到慢：
- `ultrafast`：最快，质量最差
- `superfast`：很快，质量较差
- `veryfast`：快，质量一般
- `faster`：较快，质量较好
- `fast`：快，质量好
- `medium`：平衡（推荐）
- `slow`：慢，质量很好
- `slower`：很慢，质量极好
- `veryslow`：最慢，质量最好

**推荐配置**：
- 开发环境：`fast` 或 `faster`（快速测试）
- 生产环境：`medium`（平衡速度和质量）
- 高质量需求：`slow`（追求极致画质）

### VIDEO_TRANSCODE_CRF

CRF（Constant Rate Factor）控制视频质量：
- `0`：无损（文件极大，不推荐）
- `18-22`：高质量（推荐用于重要视频）
- `23-28`：标准质量（推荐用于一般视频）
- `29-35`：较低质量（不推荐）
- `51`：最低质量（不推荐）

**推荐配置**：
- 高质量：`20-22`
- 标准质量：`23-25`（推荐）
- 节省空间：`26-28`

### VIDEO_AUDIO_BITRATE

音频比特率控制音频质量：
- `96k`：低质量（不推荐）
- `128k`：标准质量
- `160k`：较高质量（推荐）
- `192k`：高质量
- `256k`：极高质量（文件较大）

## 生产环境配置示例

### 正式系统（docker-compose.yml）

```yaml
environment:
  # 视频转码配置
  - VIDEO_TRANSCODE_CODEC=libx265
  - VIDEO_TRANSCODE_PRESET=medium
  - VIDEO_TRANSCODE_CRF=22
  - VIDEO_AUDIO_BITRATE=160k
  # Redis 配置（可选）
  - USE_REDIS=true
  - REDIS_URL=redis://redis:6379
```

### 影子系统（docker-compose.shadow.yml）

影子系统已经配置了完整的视频转码环境，包括：
- 独立的 Redis 实例（端口 6380）
- 完整的转码环境变量
- 独立的 uploads 目录

## 监控和排查

### 查看转码统计

管理员可以访问以下 API 查看转码统计：

```http
GET /api/admin/video-transcode-stats
```

**响应示例**：
```json
{
  "pending": 5,
  "processing": 2,
  "completed": 150,
  "failed": 3,
  "recentFailures": [
    {
      "id": "xxx",
      "productModel": "产品名称",
      "transcodeLastError": "FFmpeg 转码失败：...",
      "transcodeAttempts": 3,
      "createdAt": "2025-12-20T10:00:00Z"
    }
  ]
}
```

### 常见问题

#### 1. 转码失败：FFmpeg not found

**原因**：Docker 镜像中没有安装 FFmpeg

**解决**：
1. 确认 Dockerfile 中已添加 `ffmpeg` 到 apk 安装列表
2. 重新构建镜像：`docker compose build`
3. 重启容器：`docker compose up -d`

#### 2. 转码速度很慢

**原因**：转码预设太慢（如 `slow` 或 `slower`）

**解决**：
1. 调整 `VIDEO_TRANSCODE_PRESET` 为 `medium` 或 `fast`
2. 重启容器使配置生效

#### 3. 转码后文件太大

**原因**：CRF 值太小（质量太高）

**解决**：
1. 调整 `VIDEO_TRANSCODE_CRF` 为 `25-28`
2. 或使用 `libx265` 编码器（压缩率更高）

#### 4. 转码队列卡住

**原因**：
- 转码任务失败但状态未更新
- Redis 连接失败
- 内存队列因重启丢失

**解决**：
1. 查看转码统计 API，确认是否有 `processing` 状态的任务
2. 如果有卡住的任务，可以手动重置状态：
   ```sql
   UPDATE materials 
   SET "videoProcessingStatus" = 'pending' 
   WHERE "videoProcessingStatus" = 'processing';
   ```
3. 重启容器，队列会自动恢复

## 性能优化建议

### 1. 使用 Redis

生产环境强烈推荐使用 Redis：
- 转码任务持久化，重启不丢失
- 支持分布式部署（多个转码节点）
- 更好的队列管理和监控

### 2. 调整转码参数

根据实际需求调整参数：
- 如果用户主要在移动端观看：使用 `libx265` + `CRF 25`
- 如果追求极致画质：使用 `libx265` + `CRF 20` + `slow`
- 如果需要快速转码：使用 `libx264` + `CRF 23` + `fast`

### 3. 分离转码服务

如果转码任务很多，可以考虑：
- 部署独立的转码服务器
- 使用消息队列（如 RabbitMQ）管理任务
- 使用 GPU 加速转码（需要支持 NVENC 的 FFmpeg）

## 总结

视频转码功能已经完整实现，包括：
- ✅ FFmpeg 已在 Dockerfile 中安装
- ✅ 环境变量已在 docker-compose.yml 中配置
- ✅ 转码 API 已实现（查询状态、启动任务）
- ✅ 转码队列已实现（支持 Redis 和内存队列）
- ✅ 错误处理和重试机制已实现
- ✅ 管理员监控 API 已实现

**下一步**：
1. 重新构建 Docker 镜像（包含 FFmpeg）
2. 部署到正式环境
3. 测试视频上传和转码功能
4. 监控转码队列状态