Skip to main content
Glama

Duck music under voice audio

audio_ducking

Ducks background music under a voice track by lowering volume during speech and raising it in pauses, returning a mixed audio or video file.

Instructions

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.

⚠️ COST WARNING: This tool makes an API call to Sonilo which may incur charges. Only use when explicitly requested by the user.

Args: voice_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Audio (.wav/.mp3/.m4a/.aac/.ogg/.flac) or video (.mp4/.mov/.avi/.wmv/.webm/.mkv). voice_url (str, optional): HTTPS URL to the voice audio/video. music_path (str, optional): Absolute local path, or relative to SONILO_MCP_BASE_PATH. Audio only. music_url (str, optional): HTTPS URL to the music audio. output_directory (str, optional): Where to save the result. Defaults to SONILO_MCP_BASE_PATH.

Exactly one of voice_path/voice_url, and exactly one of music_path/music_url, must be provided. A local file and a URL may be mixed across the two inputs. Each input is capped at 360 seconds (6 minutes) and by the account's upload-size limit (typically 300 MB).

Returns: TextContent with the absolute path of the saved file: a .wav, or a .mp4 when the voice input was a video. If the call times out, the error message includes the task_id — recover the result later with get_sfx_task.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "audio_ducking"
  }
}

Input Schema

NameRequiredDescriptionDefault
music_urlNo
voice_urlNo
music_pathNo
voice_pathNo
output_directoryNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations, it discloses cost implications, API call behavior, input duration and size caps, video handling and muxing, and timeout recovery via task_id. These are important behavioral traits for a non-read-only, open-world tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and a cost warning, then organized into Args, constraints, and Returns. The length is justified by the tool's complexity, and there is no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex media-processing tool with five parameters, the description covers inputs, formats, constraints, limits, return values, and failure recovery. Even though an output schema exists, the extra return and timeout details are helpful and complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description explains every parameter: voice_path/voice_url, music_path/music_url, output_directory, their allowed formats, path resolution, and the exactly-one-of constraints. It fully compensates for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: ducking a music bed under a voice track, including how Sonilo lowers and lifts the music. It clearly distinguishes this from sibling tools like text_to_music or video_to_sfx by focusing on the ducking mix operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear usage condition: only use when explicitly requested by the user due to API cost. It does not name explicit alternatives or when-not scenarios, but the cost constraint and input rules provide strong guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.