Skip to main content
Glama

start_recording

Record simulation frames as PNGs to disk from a camera or active viewport, optionally logging prim transforms and properties, so you can review motion and state later.

Instructions

Start recording simulation frames to disk.

Records camera_path, or the active viewport's camera when empty, at width x height (up to 4096 a side), through the render capture_viewport and inspect_prim keep when it is that size, else one of its own: the viewport, its camera and its size stay as they are. The render runs while the recording does and up to 30 s after, kept for the next capture or recording unless a capture's render is still kept at the stop, and slows the app's updates, the more the larger the frames.

Takes a frame every 1/fps seconds of the recording's own clock, at most one an app update. The clock runs with the simulation while it plays, so a simulation faster than real time gives more than fps frames a wall second, and with the wall clock while it is stopped or paused. Play it to record motion. Frames taken while it is stopped or paused show Kit's grid, as the viewport does; Isaac Sim 6.2 hides the grid while it plays. Frames stop if the stage changes or the camera is deleted; stop_recording says so. Frames are saved as PNGs in mcp_output/recordings/, by Kit itself. One recording runs at a time: another start is refused until stop_recording. Use stop_recording when done, then get_recording_frame to review any frame. Frames go on while the simulation is stopped, and a stop puts the scene back: pause it, or call stop_recording, before stopping it to end on the run's last state.

Optionally tracks prim state (transforms, properties) alongside video frames, in state.txt.

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

Input Schema

NameRequiredDescriptionDefault
fpsNoFrames a second: 5 takes one every 0.2 s, of simulation while it plays and by the clock while not
widthNoFrame width in pixels, up to 4096
heightNoFrame height in pixels, up to 4096
camera_pathNoThe camera to record, e.g. /World/RecCam; the active viewport's camera when empty
track_primsNoPrims whose state to record, descendants included, e.g. ["/World/G1"]
property_filterNoOnly properties whose names contain one of these, e.g. ["joint", "pos", "vel"]

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.4.1
    • changedInput schema / properties / fps / description
      Previous value: -"Frames a second: 5 captures one every 0.2 s"New value: +"Frames a second: 5 takes one every 0.2 s, of simulation while it plays and by the clock while not"
  2. Changed3 schema fields changedv0.2.3
    • changedInput schema / properties / camera_path / description
      Previous value: -"Ignored for now: frames come from the active viewport's camera (#25)"New value: +"The camera to record, e.g. /World/RecCam; the active viewport's camera when empty"
    • changedInput schema / properties / height / description
      Previous value: -"Ignored for now: frames come at the active viewport's size (#25)"New value: +"Frame height in pixels, up to 4096"
    • changedInput schema / properties / width / description
      Previous value: -"Ignored for now: frames come at the active viewport's size (#25)"New value: +"Frame width in pixels, up to 4096"
  3. First observedv0.2.2

TDQS

A4.5/5.0
Behavior4/5

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

Annotations only declare readOnly=false/destructive=false/openWorld=false; the description adds substantial context the agent could not infer: PNGs written to mcp_output/recordings/, the render continues up to 30 s past the recording and is reused, app updates slow with frame size, frames abort if the stage changes or the camera is deleted, and viewport/camera/size are left untouched. The one real gap is that it does not say what happens to already-written frames when recording is stopped early.

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 correctly with the one-line purpose, and every paragraph carries real information, but sentences are convoluted ('through the render capture_viewport and inspect_prim keep when it is that size, else one of its own') and the 30-second render-retention aside interrupts the main flow. It is dense rather than wasteful, yet readability suffers.

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 stateful, side-effecting recording tool this covers the full operational picture: output location/format, timing model, one-at-a-time constraint, abort conditions, interaction with sim stop, and how to review frames. An output schema exists, so return-value detail is correctly omitted.

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 baseline is 3; the description adds meaning by tying track_prims and property_filter to a concrete artifact ('tracks prim state ... alongside video frames, in state.txt'), which the schema does not state. The clock semantics for fps (simulation vs wall clock) are also restated in prose form that clarifies the schema's shorthand.

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?

Opens with a precise verb+resource ('Start recording simulation frames to disk') and immediately scopes what is captured, at what size, and where it lands. It implicitly separates itself from capture_viewport (single frame) and names stop_recording/get_recording_frame as the follow-on lifecycle tools, so an agent can distinguish it from siblings 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?

Explicitly states when to use it ('Play it to record motion'), the refusal condition ('One recording runs at a time: another start is refused until stop_recording'), and the follow-up sequence ('Use stop_recording when done, then get_recording_frame to review any frame'). It also gives a concrete when-not/do-this-instead rule: pause the sim or call stop_recording before stopping, rather than just stopping.

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