Skip to main content
Glama
Sign In

Vidova

by ai.vidova
OverviewDiscussionsAdmin

Preview one frame

preview_frame
Read-onlyIdempotent

Capture one composed frame at a known timecode in seconds. Zero is valid. The answer starts with its previewId and the numbers that relate the picture to the film and to each clip's source pixels (fit, crop, source second and frame); pass a point you read off the picture with space preview and that previewId to project or a tracking tool instead of converting it. Its json block gives the image size, the frame's rectangle as a row [index, timeline, x, y, width, height] and each clip's mapping; detail brief is one line. grid, annotate, overlays and loupes draw measurements on the frame. To check fine detail (small text, a logo, thin lines, edges), pass region to draw only that part of the frame, at a higher resolution; longEdge sets the image size. Do not loop over this to imitate a contact sheet; use preview_range.

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": {
      "timecode": "<timecode>",
      "region": "<region>",
      "longEdge": "<longEdge>",
      "detail": "<detail>",
      "grid": "<grid>",
      "gridStep": "<gridStep>",
      "gridDensity": "<gridDensity>",
      "annotate": "<annotate>",
      "overlays": "<overlays>",
      "loupes": "<loupes>",
      "projectId": "<projectId>",
      "space": "<space>",
      "previewId": "<previewId>",
      "clipId": "<clipId>"
    },
    "name": "preview_frame"
  }
}

Input Schema

NameRequiredDescriptionDefault
gridYesDraw a labelled grid and edge rulers to read coordinates off the picture: in source pixels (of the front video or image clip), film pixels (centre origin) or film_norm. null or none draws none.
spaceYesThe space of region's corners. null or film_norm: fractions of the frame. film: scene pixels from the frame's centre. film_tl: scene pixels from its top left. preview: pixels of a preview image you were shown, with previewId. source: pixels of the asset a clip plays, with clipId.
clipIdYesWith space source, source_norm or clip: the film clip whose picture the corners are on. Else null.
detailYesHow much the answer says: brief is one line per result with its ids; normal (null) adds the transform; full adds every matrix of the chain.
loupesYesA magnified inset around a point with a crosshair, for checking a corner to the pixel. The point may be in any space (type point).
regionYesThe part of the frame to draw, as [x0, y0, x1, y1]: its top left and bottom right corners as fractions of the frame from the frame's top left (0 to 1, at least 0.02 apart). Example: [0.5, 0, 1, 0.5] is the top right quarter. The scene draws only this region, at the image's full size and a higher resolution, so small text, logos, thin lines and edges show real detail instead of an enlarged frame. The image has the region's shape. With space, the corners are in that space instead (preview pixels with previewId, film pixels, a clip's source pixels with clipId) and the region is the box around them on the frame. null (or leaving it out) draws the whole frame.
annotateYesYour own points, boxes, quads, lines or polygons drawn on the frame in any space, to check them before you commit: e.g. the four corners you think a sign has, in source pixels. null draws none.
gridStepYesGrid spacing in the grid's own units. null picks a step that keeps the labels legible (see gridDensity).
longEdgeYesPixels on the long side of the image, 240 to 1536. The scene draws at this size. null (or leaving it out) gives 1024 for the whole frame and 1024 for a region.
overlaysYesWhat to outline on every frame: tracks (each object track on screen, a plane's corners numbered 0 to 3), pins (each <pin>'s corners), follows (each <follow>'s anchor), regions (each region's box), safeAreas (TikTok, Reels and Shorts safe areas), clipBounds (each clip's picture after fit, with its id), crop (what a cover fit cuts off), occluders (the box of what passes in front of each tracked surface, from track_occluders). null outlines nothing.
timecodeYes
previewIdYesWith space preview or preview_norm: the previewId the preview_frame, preview_range or preview_timeline answer printed. Else null.
projectIdYesThe project this call runs on without changing the open project. null (or leaving it out) uses the open project. wait_for_jobs takes the projectId of the calls that started the jobs.
gridDensityYesHow close the grid lines are when gridStep is null: sparse, normal (null) or dense.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / overlays / description
      Previous value: -"What to outline on every frame: tracks (each object track on screen, a plane's corners numbered 0 to 3), pins (each <pin>'s corners), follows (each <follow>'s anchor), regions (each region's box), safeAreas (TikTok, Reels and Shorts safe areas), clipBounds (each clip's picture after fit, with its id), crop (what a cover fit cuts off), occluders (not available yet). null outlines nothing."New value: +"What to outline on every frame: tracks (each object track on screen, a plane's corners numbered 0 to 3), pins (each <pin>'s corners), follows (each <follow>'s anchor), regions (each region's box), safeAreas (TikTok, Reels and Shorts safe areas), clipBounds (each clip's picture after fit, with its id), crop (what a cover fit cuts off), occluders (the box of what passes in front of each tracked surface, from track_occluders). null outlines nothing."
  2. Changed1 schema field changed
    • changedInput schema / properties / longEdge / description
      Previous value: -"Pixels on the long side of the image, 240 to 1536. The scene draws at this size. null (or leaving it out) gives 480 for the whole frame and 1024 for a region."New value: +"Pixels on the long side of the image, 240 to 1536. The scene draws at this size. null (or leaving it out) gives 1024 for the whole frame and 1024 for a region."
  3. Changed12 schema fields changed
    • addedInput schema / properties / annotate
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "color": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "CSS colour, or null for cyan."
+          },
+          "geometry": {
+            "additionalProperties": false,
+            "properties": {
+              "assetId": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "For space source or source_norm: the asset whose pixels these are (or give clipId). Else null."
+              },
+              "clipId": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "The clip whose chain to use: for space clip, and for source when several clips show the asset. Else null."
+              },
+              "points": {
+                "description": "The points, each [x, y], in the order the type says.",
+                "items": {
+                  "items": {
+                    "type": "number"
+                  },
+                  "maxItems": 2,
+                  "minItems": 2,
+                  "type": "array"
+                },
+                "type": "array"
+              },
+              "previewId": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "For space preview, preview_norm or tile: the previewId a preview_frame, preview_range or preview_timeline answer printed. Else null."
+              },
+              "space": {
+                "description": "The space the points are in: source, source_norm, clip, film, film_tl, film_norm, preview, preview_norm, surface, tile. source: pixels of the asset; film: scene pixels from the frame's centre; film_norm: 0 to 1 of the frame; preview: pixels of a preview image (with previewId); surface: UV on a tracked surface (with trackId).",
+                "enum": [
+                  "source",
+                  "source_norm",
+                  "clip",
+                  "film",
+                  "film_tl",
+                  "film_norm",
+                  "preview",
+                  "preview_norm",
+                  "surface",
+                  "tile"
+                ],
+                "type": "string"
+              },
+              "tile": {
+                "anyOf": [
+                  {
+                    "maximum": 9007199254740991,
+                    "minimum": -9007199254740991,
+                    "type": "integer"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "For a contact sheet: the tile index (0 is the top left tile). null picks the tile the point lies in."
+              },
+              "time": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Timeline seconds this geometry is at; null uses the call's time, or a preview tile's own time."
+              },
+              "trackId": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "For space surface: the object track whose surface the UV is on. Else null."
+              },
+              "type": {
+                "description": "point (1 point), box (2: top left, bottom right), quad (4: top left, top right, bottom right, bottom left), line (2), polygon (3 or more), polyline (2 or more).",
+                "enum": [
+                  "point",
+                  "box",
+                  "quad",
+                  "polygon",
+                  "line",
+                  "polyline"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "type",
+              "space",
+              "points",
+              "previewId",
+              "assetId",
+              "clipId",
+              "trackId",
+              "tile",
+              "time"
+            ],
+            "type": "object"
+          },
+          "label": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Text drawn beside it, or null."
+          }
+        },
+        "required": [
+          "geometry",
+          "label",
+          "color"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Your own points, boxes, quads, lines or polygons drawn on the frame in any space, to check them before you commit: e.g. the four corners you think a sign has, in source pixels. null draws none."
+}
    • addedInput schema / properties / clipId
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "With space source, source_norm or clip: the film clip whose picture the corners are on. Else null."
+}
    • addedInput schema / properties / detail
      Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "brief",
+        "normal",
+        "full"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "How much the answer says: brief is one line per result with its ids; normal (null) adds the transform; full adds every matrix of the chain."
+}
    • addedInput schema / properties / grid
      Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "none",
+        "source",
+        "film",
+        "film_norm"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Draw a labelled grid and edge rulers to read coordinates off the picture: in source pixels (of the front video or image clip), film pixels (centre origin) or film_norm. null or none draws none."
+}
    • addedInput schema / properties / gridDensity
      Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "sparse",
+        "normal",
+        "dense"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "How close the grid lines are when gridStep is null: sparse, normal (null) or dense."
+}
    • addedInput schema / properties / gridStep
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Grid spacing in the grid's own units. null picks a step that keeps the labels legible (see gridDensity)."
+}
    • addedInput schema / properties / loupes
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "point": {
+            "additionalProperties": false,
+            "properties": {
+              "assetId": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "For space source or source_norm: the asset whose pixels these are (or give clipId). Else null."
+              },
+              "clipId": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "The clip whose chain to use: for space clip, and for source when several clips show the asset. Else null."
+              },
+              "points": {
+                "description": "The points, each [x, y], in the order the type says.",
+                "items": {
+                  "items": {
+                    "type": "number"
+                  },
+                  "maxItems": 2,
+                  "minItems": 2,
+                  "type": "array"
+                },
+                "type": "array"
+              },
+              "previewId": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "For space preview, preview_norm or tile: the previewId a preview_frame, preview_range or preview_timeline answer printed. Else null."
+              },
+              "space": {
+                "description": "The space the points are in: source, source_norm, clip, film, film_tl, film_norm, preview, preview_norm, surface, tile. source: pixels of the asset; film: scene pixels from the frame's centre; film_norm: 0 to 1 of the frame; preview: pixels of a preview image (with previewId); surface: UV on a tracked surface (with trackId).",
+                "enum": [
+                  "source",
+                  "source_norm",
+                  "clip",
+                  "film",
+                  "film_tl",
+                  "film_norm",
+                  "preview",
+                  "preview_norm",
+                  "surface",
+                  "tile"
+                ],
+                "type": "string"
+              },
+              "tile": {
+                "anyOf": [
+                  {
+                    "maximum": 9007199254740991,
+                    "minimum": -9007199254740991,
+                    "type": "integer"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "For a contact sheet: the tile index (0 is the top left tile). null picks the tile the point lies in."
+              },
+              "time": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Timeline seconds this geometry is at; null uses the call's time, or a preview tile's own time."
+              },
+              "trackId": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "For space surface: the object track whose surface the UV is on. Else null."
+              },
+              "type": {
+                "description": "point (1 point), box (2: top left, bottom right), quad (4: top left, top right, bottom right, bottom left), line (2), polygon (3 or more), polyline (2 or more).",
+                "enum": [
+                  "point",
+                  "box",
+                  "quad",
+                  "polygon",
+                  "line",
+                  "polyline"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "type",
+              "space",
+              "points",
+              "previewId",
+              "assetId",
+              "clipId",
+              "trackId",
+              "tile",
+              "time"
+            ],
+            "type": "object"
+          },
+          "radius": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Image pixels around the point, null for 24."
+          },
+          "zoom": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Magnification, null for 4."
+          }
+        },
+        "required": [
+          "point",
+          "radius",
+          "zoom"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "A magnified inset around a point with a crosshair, for checking a corner to the pixel. The point may be in any space (type point)."
+}
    • addedInput schema / properties / overlays
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "enum": [
+          "tracks",
+          "pins",
+          "follows",
+          "regions",
+          "safeAreas",
+          "clipBounds",
+          "crop",
+          "occluders"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "What to outline on every frame: tracks (each object track on screen, a plane's corners numbered 0 to 3), pins (each <pin>'s corners), follows (each <follow>'s anchor), regions (each region's box), safeAreas (TikTok, Reels and Shorts safe areas), clipBounds (each clip's picture after fit, with its id), crop (what a cover fit cuts off), occluders (not available yet). null outlines nothing."
+}
    • addedInput schema / properties / previewId
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "With space preview or preview_norm: the previewId the preview_frame, preview_range or preview_timeline answer printed. Else null."
+}
    • changedInput schema / properties / region / description
      Previous value: -"The part of the frame to draw, as [x0, y0, x1, y1]: its top left and bottom right corners as fractions of the frame from the frame's top left (0 to 1, at least 0.02 apart). Example: [0.5, 0, 1, 0.5] is the top right quarter. The scene draws only this region, at the image's full size and a higher resolution, so small text, logos, thin lines and edges show real detail instead of an enlarged frame. The image has the region's shape. null (or leaving it out) draws the whole frame."New value: +"The part of the frame to draw, as [x0, y0, x1, y1]: its top left and bottom right corners as fractions of the frame from the frame's top left (0 to 1, at least 0.02 apart). Example: [0.5, 0, 1, 0.5] is the top right quarter. The scene draws only this region, at the image's full size and a higher resolution, so small text, logos, thin lines and edges show real detail instead of an enlarged frame. The image has the region's shape. With space, the corners are in that space instead (preview pixels with previewId, film pixels, a clip's source pixels with clipId) and the region is the box around them on the frame. null (or leaving it out) draws the whole frame."
    • addedInput schema / properties / space
      Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "source",
+        "source_norm",
+        "clip",
+        "film",
+        "film_tl",
+        "film_norm",
+        "preview",
+        "preview_norm"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The space of region's corners. null or film_norm: fractions of the frame. film: scene pixels from the frame's centre. film_tl: scene pixels from its top left. preview: pixels of a preview image you were shown, with previewId. source: pixels of the asset a clip plays, with clipId."
+}
    • changedInput schema / required
      Previous value: -[
-  "timecode",
-  "region",
-  "longEdge",
-  "projectId"
-]New value: +[
+  "timecode",
+  "region",
+  "longEdge",
+  "detail",
+  "grid",
+  "gridStep",
+  "gridDensity",
+  "annotate",
+  "overlays",
+  "loupes",
+  "projectId",
+  "space",
+  "previewId",
+  "clipId"
+]
  4. First observed

TDQS

A4.6/5.0
Behavior5/5

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

The description adds substantial behavior beyond the annotations: it explains that the answer starts with previewId and mapping numbers, describes the json block's image size and frame rectangle, and clarifies detail brief vs fuller responses. These are meaningful operational details for a read-only, non-destructive capture tool whose safety profile is already covered by annotations.

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?

The description is front-loaded with the core action and then adds targeted guidance, but it remains dense and somewhat clause-heavy. It is appropriately sized for a complex 14-parameter tool, though better structure could improve scanability.

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?

Given the tool's complexity, lack of an output schema, and rich annotations, the description is complete enough for correct invocation. It covers the main output shape, detail levels, region cropping, longEdge sizing, overlay behavior, and the important alternative to preview_range.

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

Parameters3/5

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

Schema description coverage is 93%, so the schema already explains nearly all parameter semantics in detail. The description adds only a small amount beyond that, notably that timecode zero is valid and reiterates region and longEdge behavior that the schema already documents.

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: "Capture one composed frame at a known timecode in seconds." It distinguishes this from the sibling preview_range by explicitly warning not to loop over preview_frame to imitate a contact sheet and directing the agent to preview_range instead.

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 explicitly says when to use region for fine detail and when not to use the tool for contact-sheet generation. It also names an alternative workflow for passing a point read from the picture to project or a tracking tool rather than converting coordinates manually.

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

All Vidova 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