Back to Details

audio-ducking

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sonilo Audio Ducking

Sonilo 音频闪避

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.
自动将背景音乐闪避到语音轨道下方：Sonilo会在有语音的地方降低音乐音量，并在无语音的间隙恢复音量，然后返回混合后的结果。语音输入可以是视频——其音频轨道会被用作语音源，闪避后的混音会重新封装到新视频中。
设置： 请查看 setup-api-key 技能。
⚠️ 费用： 会发起API调用，可能产生费用。仅在明确请求时调用。

Transport: MCP or CLI

传输方式：MCP 或 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.
  1. Sonilo MCP tools visible in this session (
    audio_ducking
    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.
  2. No usable Sonilo MCP tools, but 
    sonilo account
    exits 0     — use the CLI commands below. Same API, same account, same credential file. Probe with 
    sonilo account
    , not 
    sonilo whoami
    : whoami exits 0 even when signed out, so it cannot tell the two states apart.
  3. Neither — stop and run the setup-api-key skill. Do not call 
    api.sonilo.com
    with curl to work around it; both transports handle uploads, polling and retries that a bare request does not.
在会话开始时选择其中一种并保持使用。不要在单个任务中混合使用两种方式，也无需告知选择结果。
  1. 本次会话中可见Sonilo MCP工具（
    audio_ducking
    及相关工具）——使用这些工具。这是首选路径：无需shell，且是唯一支持长时间生成的方式。如果调用因认证失败（而非输入错误），则本次会话无法使用该传输方式：请转而使用方式2，不要重试。
  2. 无可用Sonilo MCP工具，但
    sonilo account
    执行返回0    ——使用下方的CLI命令。使用相同的API、账号和凭据文件。请用
    sonilo account
    探测状态，而非
    sonilo whoami
    ：即使已登出，whoami仍会返回0，无法区分两种状态。
  3. 上述两种方式均不可用——停止操作并运行 setup-api-key 技能。不要使用curl调用
    api.sonilo.com
    来规避问题；两种传输方式都能处理上传、轮询和重试，而裸请求无法做到这些。

Quick Start

快速开始

MCP tool call (recommended)

MCP工具调用（推荐）

audio_ducking(
    voice_path="~/Desktop/interview.mp4",
    music_path="~/Desktop/background-track.wav"
)
audio_ducking(
    voice_path="~/Desktop/interview.mp4",
    music_path="~/Desktop/background-track.wav"
)

Python (
pip install "sonilo>=0.13"
)

Python（
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")
python
from sonilo import Sonilo

client = Sonilo()  # 读取SONILO_API_KEY

result = client.audio_ducking.generate(
    voice="interview.mp4",  # 音频或视频；也可使用voice_url=
    music="background-track.wav",  # 仅支持音频；也可使用music_url=
)
result.save("ducked.mp4" if result.output_type == "video" else "ducked.wav")

JavaScript / TypeScript (
npm install sonilo@>=0.14
)

JavaScript / TypeScript（
npm install sonilo@>=0.14
）

ts
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!),
);
ts
import { SoniloClient, download } from "sonilo";
import { writeFile } from "node:fs/promises";

const client = new SoniloClient(); // 读取SONILO_API_KEY

const result = await client.audioDucking.generate({
  voice: "./interview.mp4", // 音频或视频；也可使用voiceUrl
  musicUrl: "https://example.com/background-track.wav", // 仅支持音频；也可使用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
)

CLI（
npm install -g sonilo-cli
或 
pip install sonilo-cli
）

bash
sonilo audio-ducking --voice interview.mp4 --music-url https://example.com/background-track.wav
Always async under the hood — the CLI submits and polls for you. Exactly one of 
--voice
/
--voice-url
and one of 
--music
/
--music-url
. The default output name follows what comes back (
output.wav
, or 
output.mp4
when the voice input was a video); 
--output
overrides it. A local 
--music
file must have an audio extension — the CLI rejects a video there up front, for the same reason the MCP tool does.
bash
sonilo audio-ducking --voice interview.mp4 --music-url https://example.com/background-track.wav
底层始终为异步操作——CLI会替你提交任务并轮询结果。必须指定
--voice
/
--voice-url
中的一个，以及
--music
/
--music-url
中的一个。默认输出名称与返回结果一致（
output.wav
，若语音输入为视频则为
output.mp4
）；
--output
参数可覆盖默认名称。本地
--music
文件必须为音频格式——CLI会直接拒绝视频文件，原因与MCP工具相同。

cURL (raw REST API, no MCP host)

cURL（原生REST API，无MCP主机）

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"
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}

-> {"task_id": "..."} 轮询GET /v1/tasks/{task_id}


A local file uses the `voice_file`/`music_file` multipart fields; a remote source uses `voice_url`/`music_url` form fields instead (mix and match freely between the two inputs).

本地文件使用`voice_file`/`music_file`多部分字段；远程资源则使用`voice_url`/`music_url`表单字段（两种输入可自由组合）。

Tool

工具

ToolDescription
audio_ducking(voice_path? | voice_url?, music_path? | music_url?, output_directory?)
Mix 
music
under 
voice
, ducking automatically wherever the voice speaks.
工具描述
audio_ducking(voice_path? | voice_url?, music_path? | music_url?, output_directory?)
将
music
混合到
voice
下方，自动在有语音的地方闪避音乐音量。

Parameters

参数

ParameterTypeNotes
voice_path
stringAbsolute path, or relative to 
SONILO_MCP_BASE_PATH
. Audio or video: 
.wav/.mp3/.m4a/.aac/.ogg/.flac
or 
.mp4/.mov/.avi/.wmv/.webm/.mkv
.
voice_url
stringHTTPS URL to the voice audio/video. Exactly one of 
voice_path
/
voice_url
.
music_path
stringAbsolute path, or relative to the base path. Audio only — a video here is not treated specially and will be mishandled.
music_url
stringHTTPS URL to the music audio. Exactly one of 
music_path
/
music_url
.
output_directory
stringDefaults to 
SONILO_MCP_BASE_PATH
.
Each input is capped at 360 seconds (6 minutes) and by the account's upload-size limit (typically 300 MB).
参数类型说明
voice_path
string绝对路径，或相对于
SONILO_MCP_BASE_PATH
的路径。支持音频或视频：
.wav/.mp3/.m4a/.aac/.ogg/.flac
或 
.mp4/.mov/.avi/.wmv/.webm/.mkv
。
voice_url
string语音音频/视频的HTTPS URL。必须指定
voice_path
/
voice_url
中的一个。
music_path
string绝对路径，或相对于基础路径的路径。仅支持音频——若传入视频文件，会被错误处理。
music_url
string背景音乐的HTTPS URL。必须指定
music_path
/
music_url
中的一个。
output_directory
string默认为
SONILO_MCP_BASE_PATH
。
每个输入文件的时长上限为360秒（6分钟），且受账号上传大小限制（通常为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
    /
    video_to_music
    ), then feed the result in here as 
    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 
    voice_path
    — Sonilo extracts its audio track, ducks the music under it, and re-muxes the ducked mix back into a new video automatically.
  • Prefer video-to-sound or 
    video_to_music(ducking=true)
     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 
    audio_ducking
    specifically when the music track is fixed/external and you just need the mix.
  • 本工具需要两个已有的轨道——不会生成音乐或音效。如果需要先生成背景音乐，请使用 text-to-music 或 video-to-music 技能（
    text_to_music
    /
    video_to_music
    ），然后将结果作为
    music_path
    传入本工具。
  • 语音输入可以是视频。如果用户提供了访谈视频或独白视频以及单独的音乐文件，直接将视频作为
    voice_path
    传入——Sonilo会提取其音频轨道，将音乐闪避到下方，然后自动将闪避后的混音重新封装到新视频中。
  • 当音乐是为同一视频生成时，优先使用 video-to-sound 或
    video_to_music(ducking=true)
    ——这些工具会在生成过程中自动处理闪避，无需单独调用闪避工具。仅当音乐轨道是固定/外部资源，仅需要混音时，才使用
    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 
task_id
— the job keeps running (already charged). Call 
get_sfx_task(task_id)
later (
get_generation_task(task_id)
on the hosted server); see task-recovery.
本工具会在后端提交异步任务。如果调用超时，错误信息中会包含
task_id
——任务仍会继续运行（已产生费用）。之后可调用
get_sfx_task(task_id)
（在托管服务器上为
get_generation_task(task_id)
）；请查看 task-recovery。

Output Files

输出文件

A single file: a 
.wav
if the voice input was audio, or a 
.mp4
(ducked mix re-muxed in) if the voice input was a video. Named after the voice input (e.g. 
interview.mp4
→ 
interview-ducked.mp4
), falling back to 
ducked-<first 8 chars of the task id>
.
单个文件：若语音输入为音频，则输出
.wav
文件；若语音输入为视频，则输出
.mp4
文件（闪避后的混音重新封装）。文件名基于语音输入命名（例如
interview.mp4
→ 
interview-ducked.mp4
），若无法获取则默认使用
ducked-<任务ID前8位>
。

Error Handling

错误处理

Common errors: 
401
invalid key, 
402
insufficient balance / trial exhausted, 
413
file too large, 
422
invalid parameters, 
429
rate limit. See the account skill.
常见错误：
401
密钥无效，
402
余额不足/试用到期，
413
文件过大，
422
参数无效，
429
请求超限。请查看 account 技能。