智剧通

<title>智剧通 - 视频压缩模块</title>

> 本文档抓取自官方文档中心（2026-10-10 快照），具体功能以实际产品为准。

# 视频压缩模块

## 概述

视频压缩模块用于在上传前自动压缩大体积视频文件，确保符合平台要求。系统提供前端（浏览器端）和后端（服务端）两套压缩方案。

## 前端压缩

前端压缩基于 Canvas + MediaRecorder API，在浏览器端完成视频压缩，无需上传到服务器。

### 压缩参数

| 参数 | 值 | 说明 |
|-|-|-|
| 目标短边 | 480px | 短边缩放到 480px，长边等比缩放 |
| 帧率 | 24fps | 输出帧率 |
| 视频码率 | 1.5 Mbps | 视频编码码率 |
| 压缩阈值 | 10MB | 文件超过此大小才触发压缩 |
| 最大时长 | 15秒 | 超过此时长的视频会被截断 |

### 触发条件

满足以下任一条件即触发压缩：

- 文件大小超过 10MB
- 视频短边超过 480px
- 视频时长超过设定的最大时长

### 压缩流程

1. 读取视频元数据（宽高、时长）
2. 判断是否需要压缩
3. 将视频逐帧绘制到 Canvas 上（缩放到目标分辨率）
4. 使用 MediaRecorder 录制 Canvas 流 + 原始音频
5. 输出压缩后的视频文件

### 编码优先级

系统会按以下顺序尝试编码格式：

1. VP9（WebM）
2. VP8（WebM）
3. MP4（回退方案）

## 后端压缩

后端压缩基于 ffmpeg，用于服务端视频处理。

### 压缩参数

| 参数 | 默认值 | 说明 |
|-|-|-|
| 目标短边 | 480px | 短边缩放到目标值 |
| CRF | 28 | 视频质量（越低质量越高） |
| 编码预设 | fast | 编码速度/质量平衡 |
| 音频码率 | 128k | AAC 音频编码码率 |
| 超时时间 | 300秒 | 压缩任务超时时间 |

### 技术细节

- 视频编码：H.264（libx264）
- 音频编码：AAC
- 输出格式：MP4（含 faststart 标志，支持流式播放）
- 分辨率对齐：宽高强制对齐到偶数（-2 参数）

## 使用场景

### 营销智能体视频上传

在营销智能体中上传视频素材时，系统会自动调用前端压缩：

1. 用户选择视频文件
2. 系统检测文件是否需要压缩
3. 如需压缩，显示压缩进度条
4. 压缩完成后自动上传

### 剧本创作平台视频上传

在剧本创作平台上传视频时，后端会验证视频分辨率：

- 如果视频短边超过 480px，上传会被拒绝
- 系统返回错误提示，要求用户先压缩视频

## 配置常量

相关配置位于 `config/constant.py`：

```python
class MediaConstants:
    VIDEO_COMPRESS_TARGET_HEIGHT = 480   # 前端压缩目标分辨率
    VIDEO_COMPRESS_THRESHOLD_MB = 10     # 触发前端压缩的文件大小阈值
```

## 注意事项

- 前端压缩在浏览器端完成，不消耗服务器资源
- 压缩过程中会显示实时进度
- 超长视频会被自动截断到最大时长
- 压缩后的视频会保留原始音频
- 后端压缩功能已实现但当前仅用于验证，未实际调用压缩