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

文档信息

目录

• 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 系统边界与外部依赖

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

flowchart TB
    subgraph Users["用户/调用方"]
        FE["前端应用"]
        API["上游API服务"]
    end
    
    subgraph TransDubPlatform["TransDubPlatform 译配平台"]
        AudioAPI["音频处理API<br/>/api/audio/process/"]
    end
    
    subgraph ExternalSystems["外部系统"]
        OSS["阿里云OSS<br/>对象存储"]
        MySQL["MySQL<br/>业务数据库"]
        Redis["Redis<br/>缓存/进度"]
        ElevenLabs["ElevenLabs<br/>TTS服务"]
    end
    
    subgraph Infrastructure["基础设施"]
        FFmpeg["FFmpeg<br/>音视频处理引擎"]
    end
    
    FE -->|"HTTP POST"| AudioAPI
    API -->|"HTTP POST"| AudioAPI
    AudioAPI -->|"下载/上传文件"| OSS
    AudioAPI -->|"读写配音数据"| MySQL
    AudioAPI -->|"进度缓存"| Redis
    AudioAPI -->|"调用TTS"| ElevenLabs
    AudioAPI -->|"音视频处理命令"| FFmpeg

4.2 信任边界

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

5.1 服务/模块清单

5.2 组件映射表

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

flowchart TB
    subgraph Controller["Controller层"]
        AC["AudioController<br/>/api/audio/*"]
    end
    
    subgraph Service["Service层"]
        PTS["ProgramTtsServiceImpl<br/>TTS配音服务"]
        ASA["AudioSilenceAdder<br/>音频合并服务"]
        VAMS["VideoAudioMergeService<br/>音视频融合服务"]
        AS["AudioService<br/>音频信息服务"]
    end
    
    subgraph Infrastructure["基础设施层"]
        OSS["OSSService<br/>对象存储服务"]
        FFI["FfmpegInitializer<br/>FFmpeg初始化"]
    end
    
    subgraph Repository["数据访问层"]
        DAIR["DubAudioInfoRepository"]
        PDDR["ProgramDubDetailRepository"]
    end
    
    AC --> PTS
    AC --> VAMS
    PTS --> ASA
    ASA --> VAMS
    ASA --> AS
    ASA --> OSS
    VAMS --> OSS
    VAMS --> FFI
    ASA --> FFI
    AS --> DAIR
    ASA --> PDDR

5.3 目录到组件映射

6. 核心数据流与控制流

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

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

6.1.1 时序图

sequenceDiagram
    participant Client as 客户端
    participant AC as AudioController
    participant PTS as ProgramTtsService
    participant ASA as AudioSilenceAdder
    participant AS as AudioService
    participant VAMS as VideoAudioMergeService
    participant OSS as OSSService
    participant FFmpeg as FFmpeg进程
    participant DB as MySQL
    
    Client->>AC: POST /api/audio/process/{dubDetailId}
    AC->>PTS: mergeDubbingAudio(dubDetailId, partNumber)
    
    Note over PTS: 更新状态为 MERGE_VOICE_PROGRESS
    PTS->>ASA: processDubbingAudio(dubDetailId, params)
    
    ASA->>DB: 查询 ProgramDubDetail
    ASA->>AS: getAudioInfoList(dubDetailId)
    AS->>DB: 查询 DubAudioInfo 列表
    AS-->>ASA: 返回音频信息列表
    
    Note over ASA: 转换为 DialogueLine 列表
    ASA->>ASA: convertToDialogueLines()
    
    Note over ASA: 归并树并行合并音频
    loop 每批次音频
        ASA->>FFmpeg: 执行 amix + adelay 合并
        FFmpeg-->>ASA: 返回中间文件
    end
    
    ASA->>OSS: putObject(合并后音频)
    OSS-->>ASA: 返回OSS路径
    
    Note over ASA: 准备音视频融合
    ASA->>VAMS: mergeVideoAudio(request)
    
    VAMS->>OSS: checkBackgroundAudioExists()
    
    alt 有背景音
        par 并行下载
            VAMS->>OSS: downloadToFile(视频)
            VAMS->>OSS: downloadToFile(背景音)
            VAMS->>OSS: downloadToFile(人声)
        end
        VAMS->>FFmpeg: amix混合背景音+人声
    else 无背景音
        par 并行下载
            VAMS->>OSS: downloadToFile(视频)
            VAMS->>OSS: downloadToFile(人声)
        end
        VAMS->>FFmpeg: 人声直接替换音轨
    end
    
    FFmpeg-->>VAMS: 输出MP4文件
    VAMS->>OSS: putObject(融合视频)
    VAMS-->>ASA: 返回融合结果
    
    ASA->>DB: 更新 videoFilePath
    ASA-->>PTS: 返回音频OSS路径
    
    Note over PTS: 更新状态为 MERGE_VOICE_COMPLETED
    PTS-->>AC: 完成
    AC-->>Client: 返回成功

6.1.2 数据流图

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

flowchart LR
    subgraph Input["输入数据"]
        TTS_FILES["TTS音频文件<br/>(OSS)"]
        VIDEO["原视频文件<br/>(OSS)"]
        BG_AUDIO["背景音文件<br/>(OSS)"]
    end
    
    subgraph Process["处理过程"]
        LOCAL_TEMP["本地临时目录<br/>/opt/startimes/service/temp/"]
        FFMPEG["FFmpeg处理"]
    end
    
    subgraph Output["输出数据"]
        MERGED_AUDIO["合并音频<br/>(OSS)"]
        FINAL_VIDEO["融合视频<br/>(OSS)"]
    end
    
    subgraph DB["数据库"]
        DUB_AUDIO_INFO["dub_audio_info<br/>(读取)"]
        PROGRAM_DUB_DETAIL["program_dub_detail<br/>(读写)"]
    end
    
    DUB_AUDIO_INFO -->|"音频路径列表"| TTS_FILES
    TTS_FILES -->|"下载"| LOCAL_TEMP
    VIDEO -->|"下载"| LOCAL_TEMP
    BG_AUDIO -->|"下载(可选)"| LOCAL_TEMP
    
    LOCAL_TEMP -->|"音频合并"| FFMPEG
    FFMPEG -->|"输出"| LOCAL_TEMP
    LOCAL_TEMP -->|"上传"| MERGED_AUDIO
    LOCAL_TEMP -->|"上传"| FINAL_VIDEO
    
    FINAL_VIDEO -->|"更新videoFilePath"| PROGRAM_DUB_DETAIL

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 时序图

sequenceDiagram
    participant ASA as AudioSilenceAdder
    participant Pool as ExecutorService线程池
    participant FFmpeg as FFmpeg进程
    
    Note over ASA: 输入: N个音频片段
    ASA->>ASA: 计算全局最小起始时间
    
    loop 归并层级 (直到剩余1个)
        ASA->>ASA: 分批 (每批10个)
        
        par 并行处理每批
            ASA->>Pool: 提交批次1合并任务
            Pool->>FFmpeg: amix + adelay
            FFmpeg-->>Pool: 中间文件1
            
            ASA->>Pool: 提交批次2合并任务
            Pool->>FFmpeg: amix + adelay
            FFmpeg-->>Pool: 中间文件2
        end
        
        Pool-->>ASA: 收集所有中间文件
        Note over ASA: 中间文件作为下一层输入
    end
    
    ASA->>FFmpeg: 最终层应用 volume=10
    FFmpeg-->>ASA: 最终合并文件

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：音视频融合流程（有/无背景音）

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

flowchart TB
    Start["开始融合"] --> CheckBG{"检查背景音<br/>ossService.exitObject()"}
    
    CheckBG -->|"存在"| HasBG["有背景音模式"]
    CheckBG -->|"不存在/为空"| NoBG["无背景音模式"]
    
    subgraph HasBG_Flow["有背景音流程"]
        HasBG --> Download3["并行下载3个文件<br/>视频+背景音+人声"]
        Download3 --> FFmpeg_Mix["FFmpeg amix混合<br/>[1:a][2:a]amix=inputs=2"]
        FFmpeg_Mix --> Map_Mix["映射: 0:v + [aout]"]
    end
    
    subgraph NoBG_Flow["无背景音流程"]
        NoBG --> Download2["并行下载2个文件<br/>视频+人声"]
        Download2 --> FFmpeg_Replace["FFmpeg直接映射<br/>-map 0:v -map 1:a"]
        FFmpeg_Replace --> Map_Replace["映射: 0:v + 1:a"]
    end
    
    Map_Mix --> Encode["音频编码<br/>AAC 96k 22050Hz"]
    Map_Replace --> Encode
    
    Encode --> VideoCopy["视频流复制<br/>-c:v copy"]
    VideoCopy --> Output["输出MP4<br/>+faststart"]
    Output --> Upload["上传OSS"]
    Upload --> End["完成"]

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 部署架构

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

flowchart TB
    subgraph K8s["Kubernetes集群"]
        subgraph Pod["transdubplatform-service Pod"]
            Container["Java容器<br/>8u212-jdk-slim"]
            FFmpeg["FFmpeg<br/>/opt/startimes/service/ffmpeg/"]
            TempDir["临时目录<br/>/opt/startimes/service/temp/"]
        end
    end
    
    subgraph External["外部服务"]
        OSS["阿里云OSS<br/>ai-dubbing-platform-*"]
        MySQL["MySQL<br/>业务数据库"]
        Redis["Redis<br/>缓存服务"]
    end
    
    Container --> FFmpeg
    Container --> TempDir
    Container --> OSS
    Container --> MySQL
    Container --> Redis

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

文档结束