Skip to main content
Glama

Fit music to a video's length

fit_music
Destructive

Fits a music track to a video by cutting or looping bars to exact length, landing the drop on a chosen hit, ending on a beat, ducking under voice, and setting loudness without changing tempo or pitch.

Instructions

Use it when the user wants a music track made as long as a video, its drop on a moment, or music ducked under a voice. Fits a music track to a video cut: makes it exactly the given length by cutting or looping whole bars, lands its drop on the hit, ends it on a beat, ducks it under a voice and sets its loudness, without changing its tempo or pitch. Writes fitted.wav, mix.wav with a voice (the voice over the ducked music), cues.json (every beat, bar, seam and the hit, in seconds and in frames at fps), seams.png (the picture to show the user) and FIT.md (what was done and where to listen). Given the video, it also writes video.mp4, the video's picture as it was with the track under it and its own sound as video_sound says. A launch film to carry the track is planned with plan_launch_film and music false, so its sound is its effects, and give out_dir a folder inside the film's, like its music/, so the film's folder holds its track. Give cues.json to check_video to check the cuts land on the beat. To read a track's tempo, drop and ending without fitting it, use analyze_music instead. The music playbook (makersmcp_playbook) has the whole job. (musicfit 0.2.2, on this machine.)

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": {
      "track": "<track>",
      "length": "<length>"
    },
    "name": "fit_music"
  }
}

Input Schema

NameRequiredDescriptionDefault
bpmNoThe tempo, when the one found is half or double the real one; FIT.md warns when it could be (default: found).
endNoHow it ends: auto takes the track's own ending, its last hit ringing out, when it has one and there is room for it, and a fade otherwise; natural asks for that ending, fade for a fade (default auto).
fpsNoThe video's frame rate, like 25 or 29.97: the frames in cues.json and FIT.md count at it, and length, hit and drop given in frames are read at it. 25 for a launch film, the fps in a demo's steps.json (default: the video's with video, else 30).
hitNoWhere the drop lands in the result, as text in seconds like "24" or frames like "600f", inside length and at least 0.5 s before its end. A launch film's logo close is the start of its logo clip in film.timeline.json, a demo's click its pressedAt in steps.json. Without it the track starts as it starts.
dropNoWhere the drop is in the track, as text in seconds like "41.3" or frames, when the one found is not the one wanted (default: found). analyze_music lists the other candidates.
duckNoHow far the music dips under the voice, in dB (default 10), and the most it dips under the video's own sound with video_sound keep.
fadeNoLength of the closing fade in seconds, rounded to whole beats and at least one, a bar by default, ending on the last beat before the end; for a track with no steady beat, as given, 2 by default. It is used only when the result ends with a fade.
lufsNoLoudness of the result in LUFS (default -14). A limiter keeps the true peaks at -1 dBTP or lower, so a peaky track can come out a little quieter; FIT.md says.
meterNoBeats to a bar, "3" or "4", when FIT.md warns the bars may have the other (default: found).
trackYesThe music file, or a video whose sound to use; anything ffmpeg reads. An instrumental a little longer than the video fits best.
videoNoThe video to lay the result under, length long to a frame: the run also writes video.mp4, its picture copied as it was with the track under it at lufs. Its frames count at its own frame rate unless fps is given.
voiceNoA voice track on the video's timeline, from its first frame. The music dips under it, and the run adds mix.wav, the voice over the ducked music at lufs; fitted.wav is then the ducked music alone.
lengthYesThe video's exact length, as text: seconds like "29.333" or "32s", frames at fps like "733f", or "1:05"; from 1 to 3600 seconds. A launch film's is seconds in its film.timeline.json, a demo's video.duration in its steps.json.
out_dirNoFolder to save into, absolute or relative to /app. Default: musicfit-<track-name>, where <track-name> is the name of track without its extension. A run replaces the files an earlier run of this kit left there, so give each version its own out_dir.
video_soundNoWhat becomes of the video's own sound, needed when it has more than a faint room tone: keep, for sound effects, each set a little over the music, which dips under one by duck at most where it must; voice, for speech, set to lufs with the music ducked under it; drop, for music of its own, left out. Ask the user when it is not known.
wait_secondsNoHow long to wait for the result, counted from the start of the call, before returning a job_id to wait on. Some clients end a call after 60 or 240 seconds; 45 is safe in all of them.

Output Schema

NameRequiredDescriptionDefault
kitYes
docsNoThe notes the text shows, and where each one is.
nextNoWhat to do next, as the Next line says.
toolYes
filesNo
folderNoWhere the kit saved its files.
job_idYes
passedNoFor checks: whether the check passed.
statusYes
continuedNoTrue when this call continued the job of an identical call whose answer did not reach the client, instead of starting another.
exit_codeNo
last_lineNoWhat the kit was doing last.
expires_atNoWhen the download links stop working.
next_actionNo
elapsed_secondsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed32 schema fields changedv0.2.0
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / bpm / description
      Previous value: -"The tempo, when the one found is half or double the real one."New value: +"The tempo, when the one found is half or double the real one; FIT.md warns when it could be (default: found)."
    • addedInput schema / properties / drop / anyOf
      Added value: +[
      +  {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
    • changedInput schema / properties / drop / description
      Previous value: -"Where the drop is in the track (default: found)."New value: +"Where the drop is in the track, as text in seconds like \"41.3\" or frames, when the one found is not the one wanted (default: found). analyze_music lists the other candidates."
    • removedInput schema / properties / drop / minLength
      Removed value: -1
    • removedInput schema / properties / drop / type
      Removed value: -"string"
    • changedInput schema / properties / duck / description
      Previous value: -"How far the music dips under the voice, in dB (default 10)."New value: +"How far the music dips under the voice, in dB (default 10), and the most it dips under the video's own sound with video_sound keep."
    • changedInput schema / properties / end / description
      Previous value: -"How it ends: auto, natural (the track's own ending) or fade (default auto)."New value: +"How it ends: auto takes the track's own ending, its last hit ringing out, when it has one and there is room for it, and a fade otherwise; natural asks for that ending, fade for a fade (default auto)."
    • changedInput schema / properties / fade / description
      Previous value: -"Length of the closing fade, in whole beats (default a bar)."New value: +"Length of the closing fade in seconds, rounded to whole beats and at least one, a bar by default, ending on the last beat before the end; for a track with no steady beat, as given, 2 by default. It is used only when the result ends with a fade."
    • changedInput schema / properties / fps / description
      Previous value: -"Frame rate for frame numbers, like 30, 25 or 29.97 (default 30)."New value: +"The video's frame rate, like 25 or 29.97: the frames in cues.json and FIT.md count at it, and length, hit and drop given in frames are read at it. 25 for a launch film, the fps in a demo's steps.json (default: the video's with video, else 30)."
    • addedInput schema / properties / hit / anyOf
      Added value: +[
      +  {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
    • changedInput schema / properties / hit / description
      Previous value: -"Where the drop lands in the result, in seconds or frames like 825f."New value: +"Where the drop lands in the result, as text in seconds like \"24\" or frames like \"600f\", inside length and at least 0.5 s before its end. A launch film's logo close is the start of its logo clip in film.timeline.json, a demo's click its pressedAt in steps.json. Without it the track starts as it starts."
    • removedInput schema / properties / hit / minLength
      Removed value: -1
    • removedInput schema / properties / hit / type
      Removed value: -"string"
    • addedInput schema / properties / length / anyOf
      Added value: +[
      +  {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
    • changedInput schema / properties / length / description
      Previous value: -"How long the result is: seconds like 32 or 32s, frames like 960f, or 1:05."New value: +"The video's exact length, as text: seconds like \"29.333\" or \"32s\", frames at fps like \"733f\", or \"1:05\"; from 1 to 3600 seconds. A launch film's is seconds in its film.timeline.json, a demo's video.duration in its steps.json."
    • removedInput schema / properties / length / minLength
      Removed value: -1
    • removedInput schema / properties / length / type
      Removed value: -"string"
    • changedInput schema / properties / lufs / description
      Previous value: -"Loudness target in LUFS (default -14)."New value: +"Loudness of the result in LUFS (default -14). A limiter keeps the true peaks at -1 dBTP or lower, so a peaky track can come out a little quieter; FIT.md says."
    • addedInput schema / properties / meter / anyOf
      Added value: +[
      +  {
      +    "enum": [
      +      "3",
      +      "4"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "enum": [
      +      3,
      +      4
      +    ],
      +    "type": "number"
      +  }
      +]
    • changedInput schema / properties / meter / description
      Previous value: -"Beats to a bar (default: found)."New value: +"Beats to a bar, \"3\" or \"4\", when FIT.md warns the bars may have the other (default: found)."
    • removedInput schema / properties / meter / enum
      Removed value: -[
      -  "3",
      -  "4"
      -]
    • removedInput schema / properties / meter / type
      Removed value: -"string"
    • changedInput schema / properties / out_dir / description
      Previous value: -"Folder to save into, absolute or relative to /app. Default: musicfit-{stem:track}."New value: +"Folder to save into, absolute or relative to /app. Default: musicfit-<track-name>, where <track-name> is the name of track without its extension. A run replaces the files an earlier run of this kit left there, so give each version its own out_dir."
    • changedInput schema / properties / track / description
      Previous value: -"The music file, or a video whose sound to use; anything ffmpeg reads."New value: +"The music file, or a video whose sound to use; anything ffmpeg reads. An instrumental a little longer than the video fits best."
    • addedInput schema / properties / video
      Added value: +{
      +  "description": "The video to lay the result under, length long to a frame: the run also writes video.mp4, its picture copied as it was with the track under it at lufs. Its frames count at its own frame rate unless fps is given.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / video_sound
      Added value: +{
      +  "description": "What becomes of the video's own sound, needed when it has more than a faint room tone: keep, for sound effects, each set a little over the music, which dips under one by duck at most where it must; voice, for speech, set to lufs with the music ducked under it; drop, for music of its own, left out. Ask the user when it is not known.",
      +  "enum": [
      +    "keep",
      +    "voice",
      +    "drop"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / voice / description
      Previous value: -"A voice track on the video's timeline; the music dips under it."New value: +"A voice track on the video's timeline, from its first frame. The music dips under it, and the run adds mix.wav, the voice over the ducked music at lufs; fitted.wav is then the ducked music alone."
    • changedInput schema / properties / wait_seconds / description
      Previous value: -"How long to wait for the result before returning a job_id to wait on. 45 is safe for clients that stop a tool call after 60 seconds."New value: +"How long to wait for the result, counted from the start of the call, before returning a job_id to wait on. Some clients end a call after 60 or 240 seconds; 45 is safe in all of them."
    • addedOutput schema / properties / continued
      Added value: +{
      +  "description": "True when this call continued the job of an identical call whose answer did not reach the client, instead of starting another.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / docs
      Added value: +{
      +  "description": "The notes the text shows, and where each one is.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "name": {
      +        "type": "string"
      +      },
      +      "path": {
      +        "type": "string"
      +      },
      +      "url": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "name"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / next
      Added value: +{
      +  "description": "What to do next, as the Next line says.",
      +  "type": "string"
      +}
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses the full write footprint (fitted.wav, mix.wav, cues.json, seams.png, FIT.md, video.mp4), that the run replaces files a prior run left in out_dir, and the wait_seconds/job_id fallback for client timeouts. It also states invariants — tempo and pitch are unchanged — which the annotations cannot convey.

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

Conciseness4/5

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

It is front-loaded with the triggering intent before the mechanics, and nearly every clause carries operational information. Some sentences are densely stacked ('lands its drop on the hit, ends it on a beat, ducks it under a voice...'), but little is redundant.

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 16-parameter, destructive, multi-output tool, the description covers the workflow, produced artifacts, cross-tool handoffs (cues.json to check_video, out_dir into the film's folder) and default behavior. With an output schema present, return values needn't be spelled out, and nothing essential is 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, but the description adds real meaning: why out_dir should be versioned, that wait_seconds guards against 60/240-second client cutoffs, and how duck relates to video_sound=keep. Most per-parameter detail still lives in the schema, which caps this below 5.

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 opens with a concrete verb and resource — 'Fits a music track to a video cut: makes it exactly the given length by cutting or looping whole bars' — and explicitly separates itself from analyze_music, which reads tempo/drop/ending 'without fitting it'. An agent can distinguish this from every sibling 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?

It names the triggering user intents ('wants a music track made as long as a video, its drop on a moment, or music ducked under a voice') and gives explicit alternatives: analyze_music for reading a track without fitting, check_video for verifying cuts, plan_launch_film for the launch-film flow. It even specifies the out_dir nesting for the launch-film case.

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