audio-ducking
Original：🇺🇸 English
Translated
Duck a music bed under a voice track using Sonilo — automatically lowers the music wherever the voice speaks and lifts it back in the gaps. Use when mixing a separately-generated or existing music track under narration, dialogue, or a video's own voice track, without manual volume automation.
25installs
Sourcesonilo-ai/skills
Added on
NPX Install
npx skill4agent add sonilo-ai/skills audio-duckingTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →Sonilo Audio Ducking
Automatically duck a music bed under a voice track: Sonilo lowers the music wherever the voice is speaking and lifts it back in the gaps, then returns the mixed result. The voice input may be a video — its audio track is used as the voice, and the ducked mix is muxed back into a new video.
Setup: See the setup-api-key skill.
⚠️ Cost: makes an API call that may incur charges. Only call when explicitly requested.
Transport: MCP or CLI
Pick one at the start of the session and stay on it. Do not mix the two inside
a single job, and do not announce the choice.
- Sonilo MCP tools visible in this session (and friends) — use them. This is the preferred path: it needs no shell, and it is the only one that survives a very long generation. If a call fails to authenticate — rather than failing on its inputs — this transport is not usable in this session: go to 2 instead of retrying it.
audio_ducking - No usable Sonilo MCP tools, but exits 0 — use the CLI commands below. Same API, same account, same credential file. Probe with
sonilo account, notsonilo account: whoami exits 0 even when signed out, so it cannot tell the two states apart.sonilo whoami - Neither — stop and run the setup-api-key skill. Do not call with curl to work around it; both transports handle uploads, polling and retries that a bare request does not.
api.sonilo.com
Quick Start
MCP tool call (recommended)
audio_ducking(
voice_path="~/Desktop/interview.mp4",
music_path="~/Desktop/background-track.wav"
)Python (pip install "sonilo>=0.13"
)
pip install "sonilo>=0.13"python
from sonilo import Sonilo
client = Sonilo() # reads SONILO_API_KEY
result = client.audio_ducking.generate(
voice="interview.mp4", # audio or video; also voice_url=
music="background-track.wav", # audio only; also music_url=
)
result.save("ducked.mp4" if result.output_type == "video" else "ducked.wav")JavaScript / TypeScript (npm install sonilo@>=0.14
)
npm install sonilo@>=0.14ts
import { SoniloClient, download } from "sonilo";
import { writeFile } from "node:fs/promises";
const client = new SoniloClient(); // reads SONILO_API_KEY
const result = await client.audioDucking.generate({
voice: "./interview.mp4", // audio or video; also voiceUrl
musicUrl: "https://example.com/background-track.wav", // audio only; also music
});
await writeFile(
result.output_type === "video" ? "ducked.mp4" : "ducked.wav",
await download(result.output_url!),
);CLI (npm install -g sonilo-cli
or pip install sonilo-cli
)
npm install -g sonilo-clipip install sonilo-clibash
sonilo audio-ducking --voice interview.mp4 --music-url https://example.com/background-track.wavAlways async under the hood — the CLI submits and polls for you. Exactly one of / and one of /. The default output name follows what comes back (, or when the voice input was a video); overrides it. A local file must have an audio extension — the CLI rejects a video there up front, for the same reason the MCP tool does.
--voice--voice-url--music--music-urloutput.wavoutput.mp4--output--musiccURL (raw REST API, no MCP host)
bash
curl -X POST "https://api.sonilo.com/v1/audio-ducking" \
-H "Authorization: Bearer $SONILO_API_KEY" \
-F "voice_file=@interview.mp4" \
-F "music_file=@background-track.wav"
# -> {"task_id": "..."} poll GET /v1/tasks/{task_id}A local file uses the / multipart fields; a remote source uses / form fields instead (mix and match freely between the two inputs).
voice_filemusic_filevoice_urlmusic_urlTool
| Tool | Description |
|---|---|
| Mix |
Parameters
| Parameter | Type | Notes |
|---|---|---|
| string | Absolute path, or relative to |
| string | HTTPS URL to the voice audio/video. Exactly one of |
| string | Absolute path, or relative to the base path. Audio only — a video here is not treated specially and will be mishandled. |
| string | HTTPS URL to the music audio. Exactly one of |
| string | Defaults to |
Each input is capped at 360 seconds (6 minutes) and by the account's upload-size limit (typically 300 MB).
Workflow Tips
- This tool takes two already-existing tracks — it does not generate music or SFX itself. If you need to generate the music bed first, use the text-to-music or video-to-music skill (/
text_to_music), then feed the result in here asvideo_to_music.music_path - The voice input can be a video. If the user hands you a talking-head clip or an interview and a separate music file, pass the video straight through as — Sonilo extracts its audio track, ducks the music under it, and re-muxes the ducked mix back into a new video automatically.
voice_path - Prefer video-to-sound or when the music itself is also being generated for that same video — those tools duck internally as part of generation, so you don't need a separate ducking call. Reach for
video_to_music(ducking=true)specifically when the music track is fixed/external and you just need the mix.audio_ducking
Recovering a Timed-Out Call
This tool submits an async task on the backend. If the call times out, the error carries a — the job keeps running (already charged). Call later ( on the hosted server); see task-recovery.
task_idget_sfx_task(task_id)get_generation_task(task_id)Output Files
A single file: a if the voice input was audio, or a (ducked mix re-muxed in) if the voice input was a video. Named after the voice input (e.g. → ), falling back to .
.wav.mp4interview.mp4interview-ducked.mp4ducked-<first 8 chars of the task id>Error Handling
Common errors: invalid key, insufficient balance / trial exhausted, file too large, invalid parameters, rate limit. See the account skill.
401402413422429