Document voiceover background music ducking template

docs/voiceover-music-ducking.md

@@ -0,0 +1,53 @@
+# Voiceover + background music ducking
+
+The `voiceover_music_ducking` template mixes a video containing narration with a separate background-music file. FFmpeg side-chain compression lowers the music while narration is active, then mixes the narration and ducked music into the output. The source video stream is copied without re-encoding.
+
+## Endpoint
+
+`POST https://basyx-mediarouter.hf.space/v1/templates/run`
+
+## Request example
+
+```json
+{
+  "template": "voiceover_music_ducking",
+  "inputs": [
+    {
+      "url": "https://example.com/narrated-video.mp4"
+    },
+    {
+      "url": "https://example.com/background-music.mp3"
+    }
+  ],
+  "parameters": {
+    "music_volume": 0.22,
+    "voice_volume": 1,
+    "threshold": 0.03,
+    "ratio": 8,
+    "attack": 20,
+    "release": 300,
+    "audio_bitrate": "192k"
+  }
+}
+```
+
+Use the standard MediaRouter input contract for multiple media inputs; if your client uses a nested `input` object, supply the equivalent two-item input collection supported by the shared resolver.
+
+## Parameters
+
+| Parameter | Default | Range | Purpose |
+|---|---:|---:|---|
+| `music_volume` | 0.22 | 0–2 | Linear gain applied to the music before ducking |
+| `voice_volume` | 1 | 0–4 | Linear gain applied to narration |
+| `threshold` | 0.03 | 0.001–1 | Side-chain threshold; lower values trigger ducking more readily |
+| `ratio` | 8 | 1–20 | Compression ratio for the music |
+| `attack` | 20 ms | 1–2000 ms | How quickly music is reduced after narration starts |
+| `release` | 300 ms | 10–5000 ms | How quickly music returns after narration pauses |
+| `audio_bitrate` | `192k` | Supported AAC bitrates | Output audio bitrate |
+
+The source video must contain an audio stream with the narration, and its duration must be available from probing. This template does not generate narration or music. Listen to the rendered output and adjust music gain and compression settings for the particular mix.
+
+## Template discovery
+
+- `GET /v1/templates/voiceover_music_ducking`
+- `GET /v1/templates?category=podcast`