# 媒体格式支持

<cite>
**本文引用的文件**
- [server/src/services/ffmpeg.processor.ts](file://server/src/services/ffmpeg.processor.ts)
- [server/src/modules/tts/audio-merger.ts](file://server/src/modules/tts/audio-merger.ts)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts](file://server/src/modules/video-generator/video-generator.ffmpeg.ts)
- [server/src/modules/video-generator/video-generator.types.ts](file://server/src/modules/video-generator/video-generator.types.ts)
- [server/src/modules/video-generator/video-generator.service.ts](file://server/src/modules/video-generator/video-generator.service.ts)
- [server/src/modules/video-generator/video-generator.controller.ts](file://server/src/modules/video-generator/video-generator.controller.ts)
- [server/src/services/storage.service.ts](file://server/src/services/storage.service.ts)
- [server/src/config/index.ts](file://server/src/config/index.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向“媒体格式支持”主题，系统梳理音频与视频在本项目中的支持矩阵、编解码标准、压缩算法、FFmpeg 集成方案、编解码器配置、格式转换流程、质量评估与比特率策略、采样率与帧率适配、元数据处理与字幕封面管理、兼容性测试与性能基准、以及格式选择指南与最佳实践。文档以代码为依据，辅以可视化图示帮助理解。

## 项目结构
围绕媒体格式支持的关键模块与文件如下：
- 音频处理：FFmpegProcessor（格式转换、合并、裁剪、音量调整、时长探测）、AudioMerger（本地/远程统一合并）
- 视频生成：video-generator.ffmpeg（FFmpeg 命令封装，Ken Burns、缩放填充、字幕、混音、输出配置）、video-generator.types（类型定义与预设）、video-generator.service（业务流程与进度控制）、video-generator.controller（REST API）
- 存储与配置：storage.service（OSS/本地统一存储）、config（模型与环境配置）

```mermaid
graph TB
subgraph "音频处理"
A1["FFmpegProcessor<br/>格式转换/合并/裁剪/音量/时长"]
A2["AudioMerger<br/>本地/远程合并"]
end
subgraph "视频生成"
V1["video-generator.ffmpeg<br/>滤镜/输出配置"]
V2["video-generator.types<br/>类型与预设"]
V3["video-generator.service<br/>业务流程/进度"]
V4["video-generator.controller<br/>REST API"]
end
subgraph "基础设施"
S1["storage.service<br/>OSS/本地存储"]
C1["config/index.ts<br/>环境与模型配置"]
end
A1 --> S1
A2 --> A1
V3 --> V1
V3 --> V2
V4 --> V3
V1 --> S1
C1 --> V3
```

**图表来源**
- [server/src/services/ffmpeg.processor.ts:24-379](file://server/src/services/ffmpeg.processor.ts#L24-L379)
- [server/src/modules/tts/audio-merger.ts:9-86](file://server/src/modules/tts/audio-merger.ts#L9-L86)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:23-300](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L23-L300)
- [server/src/modules/video-generator/video-generator.types.ts:75-93](file://server/src/modules/video-generator/video-generator.types.ts#L75-L93)
- [server/src/modules/video-generator/video-generator.service.ts:33-312](file://server/src/modules/video-generator/video-generator.service.ts#L33-L312)
- [server/src/modules/video-generator/video-generator.controller.ts:24-244](file://server/src/modules/video-generator/video-generator.controller.ts#L24-L244)
- [server/src/services/storage.service.ts:13-278](file://server/src/services/storage.service.ts#L13-L278)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)

**章节来源**
- [server/src/services/ffmpeg.processor.ts:24-379](file://server/src/services/ffmpeg.processor.ts#L24-L379)
- [server/src/modules/tts/audio-merger.ts:9-86](file://server/src/modules/tts/audio-merger.ts#L9-L86)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:23-300](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L23-L300)
- [server/src/modules/video-generator/video-generator.types.ts:75-93](file://server/src/modules/video-generator/video-generator.types.ts#L75-L93)
- [server/src/modules/video-generator/video-generator.service.ts:33-312](file://server/src/modules/video-generator/video-generator.service.ts#L33-L312)
- [server/src/modules/video-generator/video-generator.controller.ts:24-244](file://server/src/modules/video-generator/video-generator.controller.ts#L24-L244)
- [server/src/services/storage.service.ts:13-278](file://server/src/services/storage.service.ts#L13-L278)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)

## 核心组件
- FFmpegProcessor：统一处理远程/本地媒体文件，提供格式转换、合并、裁剪、音量调整、时长探测等能力，并通过 storage.service 上传至 OSS 或本地。
- AudioMerger：在本地与远程场景间选择不同合并策略；当存在远程 URL 时委托 FFmpegProcessor 执行。
- video-generator.ffmpeg：封装 FFmpeg 命令，实现 Ken Burns 效果、缩放填充、字幕绘制、音频混音、输出参数（编码器、码率、像素格式、最短时长等）。
- video-generator.types：定义视频配置、预设（竖屏/横屏/方形）、枚举类型（字幕位置、转场、素材类型等）。
- video-generator.service：项目生命周期管理、生成流程控制、进度与状态维护、章节关联与 WebSocket 推送。
- video-generator.controller：REST API 路由，提供项目 CRUD、生成、状态查询、素材管理等接口。
- storage.service：统一存储抽象，支持 OSS 与本地存储无缝切换，提供上传、下载、签名 URL、目录清理等。
- config：集中管理端口、JWT、DashScope TTS、模型列表与自动切换策略等。

**章节来源**
- [server/src/services/ffmpeg.processor.ts:24-379](file://server/src/services/ffmpeg.processor.ts#L24-L379)
- [server/src/modules/tts/audio-merger.ts:9-86](file://server/src/modules/tts/audio-merger.ts#L9-L86)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:23-300](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L23-L300)
- [server/src/modules/video-generator/video-generator.types.ts:75-93](file://server/src/modules/video-generator/video-generator.types.ts#L75-L93)
- [server/src/modules/video-generator/video-generator.service.ts:33-312](file://server/src/modules/video-generator/video-generator.service.ts#L33-L312)
- [server/src/modules/video-generator/video-generator.controller.ts:24-244](file://server/src/modules/video-generator/video-generator.controller.ts#L24-L244)
- [server/src/services/storage.service.ts:13-278](file://server/src/services/storage.service.ts#L13-L278)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)

## 架构总览
媒体处理链路自上而下分为三层：
- 控制层：controller 接收请求，调用 service。
- 业务层：service 组织流程、状态管理、进度上报、章节关联。
- 处理层：ffmpeg.processor 与 video-generator.ffmpeg 执行具体媒体操作；storage.service 负责持久化与访问。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Ctrl as "video-generator.controller"
participant Svc as "video-generator.service"
participant Ffm as "FFmpegProcessor/video-generator.ffmpeg"
participant Store as "storage.service"
Client->>Ctrl : "POST /api/video/projects/ : id/generate"
Ctrl->>Svc : "generateVideoForProject(id)"
Svc->>Svc : "校验状态/准备配置/解析素材"
Svc->>Ffm : "生成视频(含滤镜/输出)"
Ffm->>Store : "上传输出文件"
Store-->>Ffm : "返回访问URL"
Ffm-->>Svc : "返回时长/大小"
Svc->>Svc : "更新项目状态/进度/章节关联"
Svc-->>Ctrl : "返回结果"
Ctrl-->>Client : "生成完成/进度"
```

**图表来源**
- [server/src/modules/video-generator/video-generator.controller.ts:111-129](file://server/src/modules/video-generator/video-generator.controller.ts#L111-L129)
- [server/src/modules/video-generator/video-generator.service.ts:157-312](file://server/src/modules/video-generator/video-generator.service.ts#L157-L312)
- [server/src/services/ffmpeg.processor.ts:217-261](file://server/src/services/ffmpeg.processor.ts#L217-L261)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:23-118](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L23-L118)
- [server/src/services/storage.service.ts:43-63](file://server/src/services/storage.service.ts#L43-L63)

## 详细组件分析

### 音频格式支持矩阵与编解码器配置
- 支持格式与编解码器
  - mp3：音频编码器 libmp3lame，适合通用播放与兼容性。
  - wav：线性 PCM（pcm_s16le），无损，适合高质量中间态或专业处理。
  - aac：音频编码器 aac，H.264/AAC 视频容器常用，适合移动端与网页播放。
- 压缩算法与比特率
  - mp3：采用恒定或可变比特率（由调用方传入，如 192k），兼顾体积与音质。
  - wav：无压缩，文件较大，适合保留原始质量。
  - aac：可配置比特率（如 192k），在保证音质的同时降低体积。
- 采样率与通道
  - 采样率与通道由输入源决定，FFmpeg 在转换过程中通常保持或按目标容器要求进行适配。
- 质量评估与比特率选择策略
  - 通用播放：mp3 128k–192k；中等质量：192k–256k；高保真：aac 256k+ 或 wav。
  - 移动端与网页：aac 128k–192k；直播/低带宽：aac 96k–128k。
- 典型流程（格式转换）
  - 下载远程/本地文件 → 生成转换命令 → 执行 → 上传 → 返回 URL。

```mermaid
flowchart TD
Start(["开始"]) --> Detect["检测输入URL/本地路径"]
Detect --> Download["下载到临时目录"]
Download --> BuildCmd["构建FFmpeg命令<br/>选择编码器/比特率"]
BuildCmd --> Exec["执行转换"]
Exec --> Upload["上传至存储服务"]
Upload --> Done(["完成"])
```

**图表来源**
- [server/src/services/ffmpeg.processor.ts:30-61](file://server/src/services/ffmpeg.processor.ts#L30-L61)
- [server/src/services/ffmpeg.processor.ts:217-261](file://server/src/services/ffmpeg.processor.ts#L217-L261)
- [server/src/services/storage.service.ts:43-49](file://server/src/services/storage.service.ts#L43-L49)

**章节来源**
- [server/src/services/ffmpeg.processor.ts:217-261](file://server/src/services/ffmpeg.processor.ts#L217-L261)
- [server/src/modules/tts/audio-merger.ts:28-32](file://server/src/modules/tts/audio-merger.ts#L28-L32)

### 音频合并与时长探测
- 合并策略
  - 单文件：直接返回原 URL 或复制到目标路径。
  - 多文件：若存在远程 URL，委托 FFmpegProcessor 合并；否则走本地合并逻辑。
  - 输出格式差异：mp3 需转码（libmp3lame），其他格式可直接复制（-c copy）。
- 时长探测
  - 通过 ffprobe 获取 format.duration，支持远程 URL（经下载后探测）。

```mermaid
sequenceDiagram
participant Caller as "调用方"
participant AM as "AudioMerger"
participant FP as "FFmpegProcessor"
participant FS as "本地FS"
Caller->>AM : "merge(inputFiles, outputPath)"
alt 包含远程URL
AM->>FP : "mergeAudio(urls, ext)"
FP->>FP : "downloadFile() + 构建列表"
FP->>FP : "执行ffmpeg合并"
FP-->>AM : "返回存储URL"
else 全部本地
AM->>FS : "写入列表/执行ffmpeg"
FS-->>AM : "返回输出路径"
end
AM-->>Caller : "返回结果"
```

**图表来源**
- [server/src/modules/tts/audio-merger.ts:11-36](file://server/src/modules/tts/audio-merger.ts#L11-L36)
- [server/src/services/ffmpeg.processor.ts:69-122](file://server/src/services/ffmpeg.processor.ts#L69-L122)
- [server/src/modules/tts/audio-merger.ts:69-85](file://server/src/modules/tts/audio-merger.ts#L69-L85)

**章节来源**
- [server/src/modules/tts/audio-merger.ts:11-85](file://server/src/modules/tts/audio-merger.ts#L11-L85)
- [server/src/services/ffmpeg.processor.ts:69-122](file://server/src/services/ffmpeg.processor.ts#L69-L122)

### 视频格式支持范围与帧率/分辨率适配
- 编解码器与容器
  - 视频：libx264（H.264），像素格式 yuv420p（广泛兼容），输出容器 mp4。
  - 音频：aac（192k），与视频复用。
- 帧率与分辨率
  - 通过 scale 与 pad 滤镜实现目标分辨率与纵横比适配；支持 Ken Burns 效果（zoompan）。
  - 预设配置包含竖屏（9:16）、横屏（16:9）、方形（1:1），便于快速适配主流平台。
- 字幕与音量
  - drawtext 滤镜支持字幕文本、字号、颜色、边框与位置；音频滤镜支持音量调整与混音。
- 输出参数
  - preset/fast、crf 18、pix_fmt yuv420p、shortest（以较短媒体为准）等参数平衡速度与质量。

```mermaid
classDiagram
class VideoConfig {
+images : ImageConfig[]
+audio : AudioConfig
+bgm? : BgmConfig
+subtitle? : SubtitleConfig
+video : VideoParams
+kenburns : KenBurnsConfig
}
class VideoParams {
+width : number
+height : number
+fps : number
+bitrate : string
+format : string
}
class KenBurnsConfig {
+enabled : boolean
+minZoom : number
+maxZoom : number
}
class AudioConfig {
+url : string
+volume : number
}
class BgmConfig {
+url : string
+volume : number
+loop : boolean
}
class SubtitleConfig {
+text : string
+fontSize? : number
+fontColor? : string
+position : SubtitlePosition
}
VideoConfig --> VideoParams
VideoConfig --> KenBurnsConfig
VideoConfig --> AudioConfig
VideoConfig --> BgmConfig
VideoConfig --> SubtitleConfig
```

**图表来源**
- [server/src/modules/video-generator/video-generator.types.ts:75-93](file://server/src/modules/video-generator/video-generator.types.ts#L75-L93)
- [server/src/modules/video-generator/video-generator.types.ts:214-275](file://server/src/modules/video-generator/video-generator.types.ts#L214-L275)

**章节来源**
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:23-118](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L23-L118)
- [server/src/modules/video-generator/video-generator.types.ts:214-275](file://server/src/modules/video-generator/video-generator.types.ts#L214-L275)

### 视频生成流程（含背景音乐与字幕）
- 基础合成：图片（可循环）+ 音频 → 输出 mp4（H.264+AAC）。
- 背景音乐：amix 混合主音频与 BGM，支持独立音量控制与最长时长对齐。
- 字幕：drawtext 滤镜，支持 top/center/bottom 三位置与字号/颜色。
- 进度与元数据：监听 FFmpeg 进度事件，生成完成后 ffprobe 获取时长与文件大小。

```mermaid
sequenceDiagram
participant Svc as "video-generator.service"
participant Gen as "video-generator.ffmpeg"
participant FF as "FFmpeg命令"
participant Probe as "ffprobe"
Svc->>Gen : "generateVideo(image,audio,output,config)"
Gen->>FF : "构建滤镜(scale/pad/zoompan/drawtext)"
Gen->>FF : "设置输出参数(libx264,aac,yuv420p)"
FF-->>Gen : "生成完成"
Gen->>Probe : "获取时长/大小"
Probe-->>Gen : "返回元数据"
Gen-->>Svc : "返回时长/大小"
```

**图表来源**
- [server/src/modules/video-generator/video-generator.service.ts:246-255](file://server/src/modules/video-generator/video-generator.service.ts#L246-L255)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:23-118](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L23-L118)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:252-262](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L252-L262)

**章节来源**
- [server/src/modules/video-generator/video-generator.service.ts:246-255](file://server/src/modules/video-generator/video-generator.service.ts#L246-L255)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:23-118](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L23-L118)

### 元数据处理、标签与封面管理
- 元数据与字幕
  - 通过 ffprobe 获取视频时长、分辨率等；字幕通过 drawtext 滤镜叠加。
- 标签与分类
  - 素材表包含 tags、category、duration、size、width、height 等字段，支持查询与序列化。
- 封面图片
  - 通过 storage.service.uploadCover 统一上传封面，支持 OSS/本地。

**章节来源**
- [server/src/modules/video-generator/video-generator.service.ts:349-380](file://server/src/modules/video-generator/video-generator.service.ts#L349-L380)
- [server/src/modules/video-generator/video-generator.types.ts:118-133](file://server/src/modules/video-generator/video-generator.types.ts#L118-L133)
- [server/src/services/storage.service.ts:71-77](file://server/src/services/storage.service.ts#L71-L77)

### FFmpeg 集成方案与编解码器配置要点
- 统一命令封装：fluent-ffmpeg 封装命令与滤镜，避免直接拼接字符串带来的脆弱性。
- 输出参数策略
  - 视频：libx264 + preset/fast + crf 18，兼顾速度与质量；yuv420p 提升兼容性。
  - 音频：aac + 192k，满足移动端与网页播放需求。
  - shortest：确保音视频同步，避免拖尾。
- 进度与错误处理：监听 end/error 事件，异常时回滚状态并推送失败事件。

**章节来源**
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:87-98](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L87-L98)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:252-262](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L252-L262)
- [server/src/modules/video-generator/video-generator.service.ts:291-311](file://server/src/modules/video-generator/video-generator.service.ts#L291-L311)

## 依赖关系分析
- 组件耦合
  - controller 依赖 service；service 依赖 ffmpeg 与 storage；ffmpeg 依赖 ffprobe 获取元数据。
- 外部依赖
  - FFmpeg/ffprobe（系统工具）、fluent-ffmpeg（Node.js 封装）、OSS SDK（可选）。
- 循环依赖
  - 未见循环导入；模块职责清晰，通过 service 层协调。

```mermaid
graph LR
Ctrl["video-generator.controller"] --> Svc["video-generator.service"]
Svc --> Ffm["video-generator.ffmpeg"]
Svc --> Proc["FFmpegProcessor"]
Ffm --> Store["storage.service"]
Proc --> Store
Svc --> Types["video-generator.types"]
```

**图表来源**
- [server/src/modules/video-generator/video-generator.controller.ts:1-244](file://server/src/modules/video-generator/video-generator.controller.ts#L1-L244)
- [server/src/modules/video-generator/video-generator.service.ts:1-556](file://server/src/modules/video-generator/video-generator.service.ts#L1-L556)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:1-300](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L1-L300)
- [server/src/services/ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)
- [server/src/services/storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)
- [server/src/modules/video-generator/video-generator.types.ts:1-308](file://server/src/modules/video-generator/video-generator.types.ts#L1-L308)

**章节来源**
- [server/src/modules/video-generator/video-generator.controller.ts:1-244](file://server/src/modules/video-generator/video-generator.controller.ts#L1-L244)
- [server/src/modules/video-generator/video-generator.service.ts:1-556](file://server/src/modules/video-generator/video-generator.service.ts#L1-L556)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:1-300](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L1-L300)
- [server/src/services/ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)
- [server/src/services/storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)
- [server/src/modules/video-generator/video-generator.types.ts:1-308](file://server/src/modules/video-generator/video-generator.types.ts#L1-L308)

## 性能考量
- 并发与超时
  - 合并/转换/合并音视频均设置合理超时（数分钟级），避免长时间占用进程。
- 编码参数权衡
  - preset/fast 与 crf 18 在速度与质量间取得平衡；如需更高画质可调低 crf，或使用 slower preset。
- 存储与网络
  - 远程 URL 自动下载至本地临时目录，减少网络抖动影响；完成后清理临时文件。
- 进度与可观测性
  - FFmpeg 进度事件可用于前端反馈；错误事件用于快速失败与回滚。

[本节为通用指导，无需特定文件引用]

## 故障排查指南
- 常见错误定位
  - ffprobe 命令失败：检查输入文件路径/URL 是否可达、权限是否正确。
  - ffmpeg 命令执行失败：检查编码器是否安装、参数合法性、磁盘空间。
  - 存储上传失败：确认 STORAGE_TYPE 与 OSS 配置，或检查本地 uploads 目录权限。
- 日志与回滚
  - 生成失败时更新项目状态为 failed，并推送 WebSocket 事件；必要时清理临时文件。
- 时长与元数据
  - 若时长为 0，检查 ffprobe 命令与输入文件有效性；确认下载流程已完成。

**章节来源**
- [server/src/services/ffmpeg.processor.ts:190-208](file://server/src/services/ffmpeg.processor.ts#L190-L208)
- [server/src/modules/video-generator/video-generator.service.ts:291-311](file://server/src/modules/video-generator/video-generator.service.ts#L291-L311)
- [server/src/services/storage.service.ts:252-272](file://server/src/services/storage.service.ts#L252-L272)

## 结论
本项目通过 FFmpegProcessor 与 video-generator.* 模块实现了完整的媒体格式支持与处理链路：音频方面覆盖格式转换、合并、裁剪、音量调整与时长探测；视频方面覆盖滤镜、分辨率/帧率适配、字幕、背景音乐混音与输出。结合统一存储抽象与类型定义，形成可扩展、可维护且具备良好兼容性的媒体处理体系。

[本节为总结，无需特定文件引用]

## 附录

### 音频质量评估与比特率选择策略
- 通用播放：mp3 128k–192k；中等质量：192k–256k；高保真：aac 256k+ 或 wav。
- 移动端与网页：aac 128k–192k；直播/低带宽：aac 96k–128k。
- 评估维度（建议）
  - 听感主观评价、频谱分析、PESQ/LDMOS 等客观指标（可结合外部评测工具）。
- 选择建议
  - 优先考虑目标平台兼容性与带宽约束；对关键内容采用更高码率或无损格式。

[本节为通用指导，无需特定文件引用]

### 视频帧率/分辨率适配技术
- 通过 scale 与 pad 滤镜实现目标分辨率与纵横比适配；zoompan 实现 Ken Burns 效果。
- 预设配置（竖屏/横屏/方形）便于快速适配主流平台。

**章节来源**
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:58-65](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L58-L65)
- [server/src/modules/video-generator/video-generator.types.ts:214-275](file://server/src/modules/video-generator/video-generator.types.ts#L214-L275)

### 元数据处理与标签信息提取
- ffprobe 获取视频时长、分辨率等；素材表支持 tags、category、duration、size、width、height 等字段。
- 字幕通过 drawtext 滤镜叠加，支持多位置与样式配置。

**章节来源**
- [server/src/modules/video-generator/video-generator.ffmpeg.ts:285-299](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L285-L299)
- [server/src/modules/video-generator/video-generator.types.ts:118-133](file://server/src/modules/video-generator/video-generator.types.ts#L118-L133)

### 格式兼容性测试与性能基准
- 建议测试集
  - 音频：多种采样率/位深/声道组合；常见容器（mp3/wav/aac/mp4）互转。
  - 视频：不同分辨率/帧率/码率；字幕/背景音乐/Ken Burns 场景。
- 基准指标
  - 转换耗时、内存占用、CPU 占用、输出文件大小、PSNR/SSIM（可选）。
- 质量损失评估
  - 通过频谱、时域波形对比与主观听感/视觉评价相结合。

[本节为通用指导，无需特定文件引用]

### 格式选择指南与最佳实践
- 音频
  - 通用分发：mp3；高质量/专业：wav/aac；移动端：aac。
  - 比特率：根据目标平台与带宽选择，兼顾体积与音质。
- 视频
  - 容器：mp4（H.264+AAC）；像素格式：yuv420p。
  - 参数：preset/fast + crf 18；shortest 保证同步。
- 最佳实践
  - 使用预设配置快速适配；统一存储抽象便于迁移；严格错误处理与日志记录；合理设置超时与并发。

[本节为通用指导，无需特定文件引用]