Add side-chain background music ducking operation

app/operations/mix_audio.py

@@ -138,3 +138,57 @@ async def add_audio(
             "duration_seconds": duration,
         },
     )
+
+
+async def duck_background_music(
+    ffmpeg: FFmpegService,
+    inputs: Sequence[InputMedia],
+    params: dict[str, Any],
+    output_dir: Path,
+) -> OperationResult:
+    """Mix background music under the video's narration using side-chain compression."""
+    require_inputs(inputs, 2)
+    video, music = inputs[0], inputs[1]
+    duration = _video_duration(inputs)
+    if not _has_audio(video):
+        raise InputError("Background-music ducking requires narration audio in the source video")
+    music_volume = bounded_number(params, "music_volume", 0.22, 0, 2)
+    voice_volume = bounded_number(params, "voice_volume", 1, 0, 4)
+    threshold = bounded_number(params, "threshold", 0.03, 0.001, 1)
+    ratio = bounded_number(params, "ratio", 8, 1, 20)
+    attack = bounded_number(params, "attack", 20, 1, 2000)
+    release = bounded_number(params, "release", 300, 10, 5000)
+    bitrate = _audio_bitrate(params)
+    duration_value = f"{duration:.6f}"
+    filters = (
+        f"[0:a]apad=whole_dur={duration_value},atrim=duration={duration_value},"
+        f"volume={voice_volume:.6g}[voice];"
+        f"[1:a]apad=whole_dur={duration_value},atrim=duration={duration_value},"
+        f"volume={music_volume:.6g}[music];"
+        f"[music][voice]sidechaincompress=threshold={threshold:.6g}:"
+        f"ratio={ratio:.6g}:attack={attack:.6g}:release={release:.6g}[ducked];"
+        f"[voice][ducked]amix=inputs=2:duration=first:normalize=0[mixed]"
+    )
+    output = output_path(output_dir, "ducked-audio", "mp4")
+    args: list[str | Path] = []
+    for media in inputs:
+        args.extend(["-i", media.temp_path])
+    args.extend([
+        "-filter_complex", filters, "-map", "0:v:0", "-map", "[mixed]",
+        "-c:v", "copy", "-c:a", "aac", "-b:a", bitrate,
+        "-movflags", "+faststart", output,
+    ])
+    return await execute(
+        ffmpeg, args, output, "video.duck_background_music",
+        {
+            "preserve_video": True,
+            "mix_mode": "sidechain_ducking",
+            "music_volume": music_volume,
+            "voice_volume": voice_volume,
+            "threshold": threshold,
+            "ratio": ratio,
+            "attack_ms": attack,
+            "release_ms": release,
+            "duration_seconds": duration,
+        },
+    )