Skip to main content
Glama
Sign In

Vidova

by ai.vidova
OverviewDiscussionsAdmin

Preview a time range

preview_range
Read-onlyIdempotent

Look at a contact sheet of a source-time window in the composed timeline. durationSeconds is positive. The answer starts with its previewId, each tile's time and each clip's source second and fit; a point on a tile is space preview with that previewId and the tile. Its json block gives each tile as a row [index, timeline, x, y, width, height] and each clip's mapping once; detail brief is one line. grid, annotate, overlays and loupes draw measurements on every tile. Pass audio mix or tracks to see the sound under each row of frames and a sound summary. Use for motion and for lining sounds up with the frames; read the pixels. To follow a detail through the window (text, a logo, a cover over private details, a hand), pass region: every tile then draws only that part of the frame, at a higher resolution.

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": {
      "startSeconds": "<startSeconds>",
      "durationSeconds": "<durationSeconds>",
      "audio": "<audio>",
      "region": "<region>",
      "detail": "<detail>",
      "grid": "<grid>",
      "gridStep": "<gridStep>",
      "gridDensity": "<gridDensity>",
      "annotate": "<annotate>",
      "overlays": "<overlays>",
      "loupes": "<loupes>",
      "space": "<space>",
      "previewId": "<previewId>",
      "clipId": "<clipId>",
      "projectId": "<projectId>"
    },
    "name": "preview_range"
  }
}

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.
audioYesThe audio strip drawn under each row of frames, on the same time axis: a log-frequency spectrogram (sub, bass, mids, highs) with a loudness line and ticks for clip starts and ends, hits, beats and downbeats, plus a text summary of each lane's loudness, each sound's hit time and masking. mix is what the viewer hears; tracks stacks music, voice, sound effects and video sound as separate lanes; none draws frames only. null (or leaving it out) means 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).
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.
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.
startSecondsYes
durationSecondsYes

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. 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: -[
-  "startSeconds",
-  "durationSeconds",
-  "audio",
-  "region",
-  "projectId"
-]New value: +[
+  "startSeconds",
+  "durationSeconds",
+  "audio",
+  "region",
+  "detail",
+  "grid",
+  "gridStep",
+  "gridDensity",
+  "annotate",
+  "overlays",
+  "loupes",
+  "space",
+  "previewId",
+  "clipId",
+  "projectId"
+]
  3. Changed2 schema fields changed
    • addedInput schema / properties / region
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "number"
+      },
+      "maxItems": 4,
+      "minItems": 4,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "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."
+}
    • changedInput schema / required
      Previous value: -[
-  "startSeconds",
-  "durationSeconds",
-  "audio",
-  "projectId"
-]New value: +[
+  "startSeconds",
+  "durationSeconds",
+  "audio",
+  "region",
+  "projectId"
+]
  4. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description goes further by disclosing the answer shape (previewId, tile times, clip source seconds, json row format), how audio changes the output, and that grid/annotate/overlays/loupes draw measurements on every tile.

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?

The purpose is front-loaded, but the prose is dense and hard to parse in places, e.g. 'a point on a tile is space preview with that previewId and the tile.' Multiple ideas are packed into long semicolon-separated sentences instead of being structured for scanning.

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

Completeness4/5

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

For a complex 15-parameter tool with no output schema, the description covers the output anatomy, option effects, and use cases well enough to call it correctly. Minor gaps remain, such as not explaining startSeconds and the misleading 'leaving it out' language for required fields.

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 coverage is 87%, so the schema already carries most parameter meaning. The description adds some useful semantics (durationSeconds is positive, audio mix/tracks shows sound under frames, region raises resolution), but it also says 'null (or leaving it out)' for parameters that the schema marks required, which is misleading.

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

Purpose4/5

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

States a specific verb and resource: 'Look at a contact sheet of a source-time window in the composed timeline.' It makes clear this is a range-preview tool, though it does not explicitly contrast itself with siblings like preview_frame or preview_timeline.

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?

Gives concrete use cases: 'Use for motion and for lining sounds up with the frames; read the pixels' and explains using region to follow a detail. It provides clear context without naming when to avoid it or which sibling to choose instead.

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