version: "1.0.0" name: add-audio-track description: "将指定的音频文件混入输入视频的默认播放音轨，并保留视频原有音轨作为非默认备用轨。当用户需要“给视频添加一条音轨”、“把 audio.mp3 merge 到视频里”、“add_audio_track”或“在不替换原音频的情况下加入新音频并默认可听见”时，必须立即调用此技能。"

添加音轨工具 (add-audio-track)

本技能用于将已有的音频文件混入视频的默认播放音轨，生成一个打开后即可同时听到原视频默认音频和新增音频的新视频。

⚠️ 注意：本技能不会替换或删除原视频的原始音轨；它会创建一条“原默认音轨 + 新音频”的混音默认播放音轨，并将原视频音轨保留为非默认备用轨。

核心功能与工作流程

当用户要求把独立音频加入视频、给视频增加一条音轨，且不希望替换掉原始音频，同时希望普通播放器默认就能听到新增音频时，使用本技能。

调用脚本添加并混入音轨

使用本技能自带的 scripts/add_audio_track.py 脚本来处理视频。

参数说明

执行逻辑与输出

执行脚本后，它会自动调用 FFmpeg 把输入音频混入默认播放音轨：

• 视频流不重新编码，直接 copy。
• 第一条/default 音轨会变成“原视频默认音轨 + 输入音频”的混音，普通播放器打开即可听到新增音频。
• 混音前会自动分析原视频默认音轨和输入音频的平均音量，并智能调整输入音频增益，使新增音频和原默认音轨的响度接近；自动增益限制在 ±12dB 内，避免极端放大或压低。
• 混音后会加 limiter，减少音频叠加导致的爆音/削波风险。
• 原视频中的音频流会被保留为非默认备用轨，不会被替换或删除。
• 输入音频也会作为最后一条非默认独立音轨保留，方便检查或切换。
• 音频统一编码为 aac，以保证 mp4 兼容性。

目标文件将保存在基于 session 生成的特定输出目录下：

• 输出视频: 保存为 [基于session生成的输出目录]/[原视频文件名无后缀]_add_audio_track.mp4

调用示例

python add-audio-track/scripts/add_audio_track.py "/path/to/your/video.mp4" "/path/to/your/audio.mp3"