音频处理与音视频融合接口设计文档

文档信息

目录

• 1. 背景与现状
• 2. 目标与非目标
• 3. 术语表与关键实体
• 4. 系统上下文
• 5. 容器与组件视图
• 6. 核心数据流与控制流
• 7. API与接口设计
• 8. 数据存储设计
• 9. 关键算法与业务规则
• 10. 质量属性与横切关注点
• 11. 部署与运维
• 12. 测试策略
• 13. 方案对比与取舍
• 14. 风险清单与缓解措施
• 15. 未决问题与需补充材料
• 16. 附录

1. 背景与现状

1.1 业务背景

TransDubPlatform（译配平台）是一个视频翻译配音平台，核心业务流程包括：

1. 视频上传与音频提取
2. 语音分离（人声/背景音分离）
3. 语音识别（ASR）生成台本
4. 台本翻译
5. AI配音（TTS）与音频合并
6. 音视频融合输出

本文档聚焦于 /api/audio/process/{dubDetailId} 接口，该接口负责：

• 将多段TTS生成的配音音频按时间轴合并为完整音轨
• 将合并后的人声配音与背景音、原视频进行融合
• 输出最终的配音视频文件

依据: transdubplatform-service/.../AudioController.java

1.2 技术背景

1.3 当前痛点与约束

2. 目标与非目标

2.1 目标（Goals）

2.2 非目标（Non-Goals）

3. 术语表与关键实体

3.1 术语表

3.2 关键实体

4. 系统上下文（C4: Context）

4.1 系统边界与外部依赖

这张图回答：音频处理模块与哪些外部系统交互？

4.2 信任边界

5. 容器与组件视图（C4: Container + Component）

5.1 服务/模块清单

5.2 组件映射表

这张图回答：音频处理涉及哪些核心组件及其依赖关系？

5.3 目录到组件映射

6. 核心数据流与控制流

6.1 链路1：音频处理主流程（/api/audio/process/ {dubDetailId}）

这张图回答：音频处理接口的完整调用链路是什么？

6.1.1 时序图

6.1.2 数据流图

这张图回答：数据在各存储系统间如何流转？

6.1.3 关键数据结构

DubAudioInfo（音频片段信息）

// 依据: DubAudioInfo.java
{
    "id": 12345,
    "orderNumber": 0,                    // 序号，用于排序
    "programDubDetailId": 100,           // 关联配音详情ID
    "startTime": "00:00:05,200",         // 开始时间 HH:mm:ss,SSS
    "endTime": "00:00:08,500",           // 结束时间
    "audioPath": "/opt/.../0.mp3",       // 本地音频路径
    "deleteFlag": 1                      // 删除标识
}

VideoAudioMergeRequest（融合请求）

// 依据: VideoAudioMergeRequest.java
{
    "videoPath": "/path/to/video.mp4",           // OSS视频路径
    "backgroundAudioPath": "/path/to/bg.mp3",    // OSS背景音路径（可选）
    "voiceAudioPath": "/path/to/voice.mp3",      // OSS人声路径
    "outputFileName": "output.mp4",              // 输出文件名（可选）
    "outputFilePath": "/output/path/"            // 输出目录
}

6.2 链路2：音频归并合并流程

这张图回答：大量音频片段如何高效合并？

6.2.1 时序图

6.2.2 归并树示意

输入: 25个音频片段
                    
Level 0:  [1-10] [11-20] [21-25]     <- 3批并行
              ↓      ↓      ↓
Level 1:    [A]    [B]    [C]        <- 3个中间文件
              ↓      ↓      ↓
Level 2:        [Final]              <- 最终输出

6.3 链路3：音视频融合流程（有/无背景音）

这张图回答：两种融合模式的处理差异是什么？

7. API与接口设计

7.1 对外API

7.1.1 POST /api/audio/process/ {dubDetailId}

路径参数

请求体

{
    "partNumber": 1    // 片段编号
}

响应

鉴权: 需要Token认证（依据: application.yml token配置）

幂等性: 非幂等，重复调用会重新处理

7.1.2 POST /api/audio/merge

请求体

{
    "videoPath": "/path/to/video.mp4",
    "backgroundAudioPath": "/path/to/background.mp3",
    "voiceAudioPath": "/path/to/voice.mp3",
    "outputFileName": "output.mp4",
    "outputFilePath": "/output/path/"
}

响应体

{
    "success": true,
    "outputOssPath": "/output/path/output.mp4",
    "outputSignedUrl": "https://oss.../output.mp4?sign=...",
    "costTimeMs": 12500,
    "errorMessage": null
}

错误码

7.2 内部接口

7.2.1 AudioSilenceAdder.processDubbingAudio()

// 依据: AudioSilenceAdder.java
public String processDubbingAudio(Long dubDetailId, FFmpegProcessAudioParams params)

7.2.2 VideoAudioMergeService.mergeVideoAudio()

// 依据: VideoAudioMergeService.java
public VideoAudioMergeResponse mergeVideoAudio(VideoAudioMergeRequest request)

7.2.3 OSSService.exitObject()

// 依据: OSSService.java
public Boolean exitObject(String objectName)

8. 数据存储设计

8.1 数据库表

8.1.1 dub_audio_info（配音音频信息表）

依据: V1.2.2_20250616__DB_init.sql

CREATE TABLE `dub_audio_info` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '自增主键',
  `order_number` int(11) NOT NULL COMMENT '序号',
  `fk_program_dub_detail_id` bigint(20) NOT NULL COMMENT '配音详细id',
  `start_time` varchar(255) NOT NULL COMMENT '开始时间',
  `end_time` varchar(255) NOT NULL COMMENT '结束时间',
  `audio_path` varchar(1024) NOT NULL COMMENT '音频文件路径',
  `delete_flag` tinyint(4) NOT NULL DEFAULT '1' COMMENT '删除标识',
  `create_time` datetime DEFAULT NULL,
  `update_time` datetime DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='配音输出音频信息表';

8.1.2 program_dub_detail（配音详情表）

依据: V1.1.0_20250328__DB_init.sql

CREATE TABLE `program_dub_detail` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `fk_program_process_detail_id` bigint(20) NOT NULL COMMENT '详单id',
  `part_number` int(11) NOT NULL COMMENT '片段编号',
  `delete_flag` tinyint(4) NOT NULL DEFAULT 1,
  `start_time` timestamp NULL,
  `completed_time` timestamp NULL,
  `status` tinyint(4) NOT NULL COMMENT '状态',
  `audio_file_path` varchar(1024) COMMENT '音频文件路径',
  `video_file_path` varchar(1024) COMMENT '视频文件路径',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='配音详表';

8.2 文件存储（OSS）

8.3 临时文件

8.4 缓存（Redis）

9. 关键算法与业务规则

9.1 音频时间轴对齐算法

依据: AudioSilenceAdder.java

输入: List<DubAudioInfo> 包含 startTime, endTime, audioPath
输出: 按时间轴对齐的完整音频

算法:
1. 解析时间字符串为毫秒: "HH:mm:ss,SSS" -> milliseconds
2. 计算全局最小起始时间: globalMinStartTime = min(all startTime)
3. 对每个音频片段计算相对延迟: relativeDelay = startTime - globalMinStartTime
4. 使用FFmpeg adelay滤镜添加延迟: adelay={relativeDelay}:all=1
5. 使用amix滤镜混合所有音频流

9.2 归并树合并算法

依据: AudioSilenceAdder.mergeAudioClipsWithTree()

输入: N个音频片段
参数: MERGE_BATCH_SIZE = 10

算法:
1. 如果N=1，直接处理单个片段返回
2. 将N个片段分成 ceil(N/10) 个批次
3. 并行处理每个批次:
   - 计算批次内最小起始时间
   - 使用amix合并批次内所有音频
   - 输出中间文件，记录绝对起始时间
4. 收集所有中间文件作为下一层输入
5. 重复步骤2-4直到只剩1个文件
6. 最终层应用volume=10增益

复杂度: O(N) 音频处理，O(log N) 层级

9.3 背景音存在性判断规则

依据: VideoAudioMergeService.checkBackgroundAudioExists()

规则:
1. 如果 backgroundAudioPath 为空或空白 -> 无背景音模式
2. 如果 ossService.exitObject(backgroundAudioPath) 返回false -> 无背景音模式
3. 如果检查过程发生异常 -> 无背景音模式（降级处理）
4. 其他情况 -> 有背景音模式

9.4 FFmpeg命令构建规则

有背景音模式:

ffmpeg -y -threads 0 \
  -i {video} -i {background} -i {voice} \
  -filter_complex "[1:a][2:a]amix=inputs=2:duration=longest:normalize=0[aout]" \
  -map 0:v -map [aout] \
  -c:v copy -c:a aac -b:a 96k -ar 22050 -ac 1 \
  -shortest -movflags +faststart \
  {output}

无背景音模式:

ffmpeg -y -threads 0 \
  -i {video} -i {voice} \
  -map 0:v -map 1:a \
  -c:v copy -c:a aac -b:a 96k -ar 22050 -ac 1 \
  -shortest -movflags +faststart \
  {output}

10. 质量属性与横切关注点

10.1 性能与容量

瓶颈点:

1. OSS文件下载（已通过并行下载优化）
2. FFmpeg音频编码（已通过低质量参数优化）
3. 大量音频片段合并（已通过归并树优化）

10.2 可靠性

10.3 可观测性

日志

关键日志格式:

[{jobId}] 开始视频音频融合任务, 模式: {mode}, 请求参数: {request}
[{jobId}] FFmpeg命令: {command}
[{jobId}] FFmpeg进度: time={time} speed={speed}
[{jobId}] 视频音频融合任务完成，模式: {mode}, 总耗时: {cost}ms

指标（未知/需确认）

当前代码中未发现Prometheus指标埋点，但配置文件中有Prometheus端点配置：

# 依据: application.yml
management:
  endpoints:
    web:
      exposure:
        include: health,prometheus

10.4 安全

11. 部署与运维

11.1 部署架构

这张图回答：服务如何部署和依赖哪些基础设施？

11.2 Dockerfile分析

依据: transdubplatform-service/config/Dockerfile

FROM common-repos.startimes.me/startimes-ops/8u212-jdk-slim:latest

# FFmpeg从JAR包中提取
RUN jar xf transdubplatform-service.jar BOOT-INF/classes/static/ffmpeg ...
RUN chmod +x /opt/startimes/service/ffmpeg/ffmpeg

ENTRYPOINT java ${JAVA_OPTS} -jar /opt/startimes/service/transdubplatform-service.jar

关键点:

• 基础镜像: Java 8 (8u212)
• FFmpeg: 内嵌于JAR包，部署时提取
• 路径: /opt/startimes/service/ffmpeg/ffmpeg

11.3 环境配置

11.4 环境划分

12. 测试策略

12.1 测试层级

12.2 关键测试用例（建议）

12.3 Mock策略

13. 方案对比与取舍

13.1 音频合并方案

选择理由: 归并树方案在处理大量音频片段时性能优势明显，虽然实现复杂但可维护。

13.2 音视频融合方案

选择理由: -c:v copy 避免视频重编码，处理速度提升10倍以上。

13.3 背景音处理方案

选择理由: 通过 ossService.exitObject() 检测背景音存在性，自动切换处理模式，向后兼容。

14. 风险清单与缓解措施

15. 未决问题与需补充材料

15.1 需确认的问题

15.2 需补充的文件

16. 附录

16.1 关键文件索引

16.2 参考

本文档所有内容均基于以下仓库文件：

• 代码文件：如上表所列
• 配置文件：application.yml, Dockerfile
• 数据库脚本：db/migration/*.sql

文档结束