Skip to main content
Glama
Sign In

ChatCut

by io.chatcut
OverviewDiscussionsAdmin

isolate_voice

Apply or clear AI voice isolation on a video or audio item with spoken human voice. This is not generic denoise — it is speech-only enhancement.

External MCP voice-isolation rule: action="apply" without filePath requires itemId, sourceAssetId, full projectId and timelineId UUIDs, and a connected authenticated browser executor with readable media via the editor tool bridge. The visible page need not show that target. If browser execution is unavailable, create a DeepFilterNet3 full-source WAV locally, import it through import_media plus the asset-import upload-media.mjs helper, then action="attach" with its assetId as denoisedAssetId plus itemId and sourceAssetId. Attach/clear do not require browser execution. Do not pass workspace filePath on this connector.

Required inputs: apply and attach require itemId and sourceAssetId from inspect_item; attach also requires denoisedAssetId. Clear needs only itemId. Web apply without filePath executes in an authenticated browser and requires the full timelineId UUID; external callers also pass the full projectId UUID. Never pass shortened scope IDs. Get the target timelineId from editor state, read_project, or manage_timelines action="list". Workspace filePath apply, attach, and clear do not require browser execution. Desktop uses its separate native tool contract.

IMPORTANT — only for clips that contain spoken human voice: The open editor selects its native speech-enhancement engine: ChatCut Desktop uses flux MossFormer2 with a persistent disk cache; Web uses DeepFilterNet3. Both suppress everything EXCEPT human speech. Applying voice isolation to a clip with no speech (music, ambient noise, sound effects, action footage) will distort or silence the audio. If the user's clip does not contain spoken voice, tell them ChatCut does not have a suitable tool for that request.

Desktop MossFormer2 runs at its native fixed strength; Desktop normalizes legacy strength values to 100. Web DeepFilterNet3 continues to support strength 0-100.

Use this tool for spoken-voice dereverb too: When the user asks to reduce room echo, reverb, reverberation, or "echoey" / "distant" speech (去混响 / 回声大 / 空旷感 / 人声不贴耳), treat it as a voice-isolation use case if the target clip contains spoken human voice. Do not use it as generic dereverb for music, ambience, SFX, or non-speech recordings.

How this tool works:

  • Preferred route when the editor is open: call action="apply" with itemId and sourceAssetId, no filePath. The open editor runs the same platform-native AI Voice Isolation pipeline as the manual UI, creates the derived audio asset, and points the item at it.

  • Workspace route: run the deep-filter binary (DeepFilterNet3) locally to produce a voice-isolated WAV, then call action="apply" with filePath and sourceAssetId. The local engine MUST be DeepFilterNet3, or the derivative is incompatible with the editor's cache.

  • External connector route: call import_media action="create_session", run the asset-import upload-media.mjs helper on the already-cleaned WAV, then action="attach" with the returned audio assetId. The source asset is never modified; clearing reverts to the original.

If DeepFilterNet3 is missing, install it; do not substitute generic ffmpeg denoise. Use a deep-filter release binary, or a temp Python 3.11 venv with deepfilternet==0.5.6, torch==2.3.1, torchaudio==2.3.1, soundfile==0.12.1; run deep-filter-py --model-base-dir DeepFilterNet3 --atten-lim <0-100> --output-dir <dir> <input.wav>.

Workspace workflow (driven by the voice-isolation skill when the frontend route is unavailable):

  1. Use preview_timeline to find the target item, then inspect_item for its assetId and audio state. If it shows no speech signals and likely has no spoken voice, do NOT proceed — tell the user.

  2. Get the full source asset audio locally, not just the visible timeline range; timeline items can have sourceStart offsets. For video, extract the full audio track with ffmpeg and transcode to mono 48 kHz WAV.

  3. Run DeepFilterNet3 on that full-source WAV: deep-filter -a <0-100> <input.wav> or deep-filter-py --model-base-dir DeepFilterNet3 --atten-lim <0-100> --output-dir <dir> <input.wav> (atten-lim-db: 0=no reduction, 100=full).

  4. apply (workspace filePath) or attach (already-uploaded denoisedAssetId).

itemId / sourceAssetId / denoisedAssetId accept 10-hex prefix ids or full UUIDs.

Actions:

  • apply: itemId, sourceAssetId (the item's current assetId), optional strength (0-100, default 100). With no filePath, asks the open editor to run AI Voice Isolation. With filePath, uploads the workspace wav and points the item at it; strength must match the deep-filter -a value.

  • attach: itemId, denoisedAssetId (an already-uploaded voice-isolated audio asset), sourceAssetId, optional strength. Points the item at that asset. The asset must actually contain the item's audio: a freshly uploaded cleaned file must span the whole source, and an apply-produced derivative keeps the source slice it was made for. Never reuse one item's apply output on other items — the item would go silent; call apply on each item instead. On connectors with no workspace, import the cleaned WAV through import_media plus the asset-import upload-media.mjs helper, then attach its returned assetId.

  • clear: itemId only. Reverts to the original audio.

Returns JSON describing what changed.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>",
      "itemId": "<itemId>"
    },
    "name": "isolate_voice"
  }
}

Input Schema

NameRequiredDescriptionDefault
actionYesapply requires sourceAssetId; without filePath it also requires full timelineId browser scope. attach requires sourceAssetId and denoisedAssetId. clear requires only itemId.
itemIdYesTarget audio/video item id (prefix or full UUID) from preview_timeline.
strengthNoapply/attach: voice isolation strength 0-100 (atten-lim-db), default 100.
projectIdNoFull project UUID. Required for external browser work; internal agents may omit. Execution/explicit-timeline calls never change later calls' target.
timelineIdNoFull timeline UUID, not a prefix. Required for browser work, even unplaced assets. Get it from read_project or manage_timelines action="list". Never switches visible timeline.
sourceAssetIdNoRequired for apply and attach; optional only for clear. Copy the target item's current assetId from inspect_item. Asset IDs may be unambiguous prefixes; projectId and timelineId must be full UUIDs.
idempotencyKeyNoStable key for this browser execution. Reuse only with identical scope and parameters after a lost acknowledgement; applies only to this call.
denoisedAssetIdNoRequired for attach, otherwise omit: assetId of the already-uploaded voice-isolated audio asset.
browserProfileIdNoOptional browser profile override. Omit to select automatically; do not ask the user to choose.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only declare non-read-only/non-destructive; the description supplies the real behavioural load: engine selection differs by platform (MossFormer2 desktop with persistent cache vs DeepFilterNet3 web), desktop normalizes legacy strength to 100, the source asset is never modified and clear reverts to the original, and reusing one item's apply output on other items silences them. It also discloses the authentication/browser-executor requirement and the visible-page-need-not-show-target caveat.

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

Conciseness3/5

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

Front-loaded and organised with headers and a numbered workflow, but roughly triple-length: the external connector route (import_media + upload-media.mjs + attach) is stated in the rule block, again in the route list, and a third time inside the attach action, and the browser-scope requirements are restated across three paragraphs. Substantial compression is possible without losing any information.

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 9-parameter, three-action, multi-route tool with no output schema, the description covers engine install fallbacks (deep-filter binary, Python 3.11 venv pins), source-range offset pitfalls in step 2, full-source extraction requirement, and every action's required/optional inputs. Nothing an agent needs in order to call this correctly appears to be missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning beyond the schema — where itemId/sourceAssetId come from (inspect_item), that prefixes 10-hex ids are acceptable for asset IDs but projectId/timelineId must be full UUIDs, that strength must match the deep-filter -a value, and that attach's denoisedAssetId must actually span the item's whole source. It does not add much on idempotencyKey or browserProfileId beyond what the schema says.

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?

States a specific verb+resource ('apply or clear AI voice isolation on a video or audio item with spoken human voice') and immediately differentiates from the nearest neighbour ('not generic denoise — it is speech-only enhancement'), naming smooth_audio's likely competitor domain. An agent can tell what this does and what it is not without opening the schema.

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

Usage Guidelines5/5

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

Explicit when-to-use (spoken voice; also dereverb/'echoey' speech with the Chinese synonyms), explicit when-NOT-to-use ('music, ambient noise, sound effects, action footage' → distortion or silence; tell the user no suitable tool exists), and named routing alternatives (import_media + upload-media.mjs + attach when browser execution is unavailable). Nothing left to inference.

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

All ChatCut toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources