> ## Documentation Index > Fetch the complete documentation index at: https://docs.videodb.io/llms.txt > Use this file to discover all available pages before exploring further. # MCP Tools Reference > Every tool exposed by the hosted VideoDB MCP server, grouped by toolset, with its kind, inputs and prerequisites. The hosted VideoDB MCP server at `https://mcp.videodb.io/mcp` exposes 89 tools, grouped into toolsets by what they operate on. Every tool is annotated with a kind, which is how a client knows whether the call changes your account and whether to ask you first. | Kind | Meaning | | ----------- | ------------------------------------------------------------------- | | read | No change to your account. Lists, lookups, search and ask. | | create | Makes something new: assets, indexes, streams, jobs. | | update | Changes something that exists: renames, status toggles, visibility. | | destructive | Deletes. | ## IDs and conventions | Prefix | Object | | ------ | ---------------- | | `m-` | Video | | `a-` | Audio | | `img-` | Image | | `rts-` | Real-time stream | | `c-` | Collection | Every ID input takes one of those prefixed forms: `video_id` is an `m-` ID, `audio_id` an `a-` ID, `image_id` an `img-` ID, `rtstream_id` an `rts-` ID, `collection_id` a `c-` ID. `media_id` accepts a video or an audio ID. Every account has a collection named `default`, so leaving `collection_id` out sends the call there. Reading the Inputs column: a plain name is required, a trailing `?` means optional, and `?=value` is the default the server applies when you omit it. Tools with more than eight inputs show the first six, and a full table of every field follows the toolset table. * Inputs and outputs are snake\_case. * A write that runs long returns `{"status": "processing", ...}` with a `retry_with` field naming the read tool that shows the finished result. * Large lists are capped. A capped result carries `truncated: true` and `total`. ## collections Collections hold your media. Account usage and invoices live here too. | Tool | Kind | Inputs | What it does | | ------------------- | ----------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `list_collections` | read | none | List all collections in the account with IDs, names, descriptions and visibility. | | `get_collection` | read | `collection_id?=default` | Get one collection's ID, name, description and public/private visibility. | | `create_collection` | create | `name`, `description?=""`, `is_public?=false` | Create a new collection to organize videos. | | `update_collection` | update | `collection_id?=default`, `name?`, `description?`, `is_public?` | Rename a collection, change its description, or switch it between public and private. | | `delete_collection` | destructive | `collection_id` | Permanently delete a collection and everything in it. | | `get_account_usage` | read | none | Get the account's current usage and billing summary. | | `list_invoices` | read | none | List the account's invoices (first 200; `truncated` is set when more exist). | ## media List, fetch, upload, rename and delete videos, audio and images, plus thumbnails, signed download URLs and transcoding. | Tool | Kind | Inputs | What it does | | ------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `list_assets` | read | `collection_id?`, `asset_type?`, `name_pattern?`, `min_duration?`, `max_duration?`, `min_size?`, +5 more (see below) | List videos, audio and images together in one paginated result, filtered by type, name pattern, duration or file size, and sorted by name, duration or size. | | `list_videos` | read | `collection_id?=default` | List videos in a collection: IDs, names, durations, and playable stream/player URLs. | | `list_audios` | read | `collection_id?=default` | List audio files in a collection: IDs, names, durations and sizes. | | `list_images` | read | `collection_id?=default` | List images in a collection: IDs, names and URLs. | | `get_video` | read | `video_id`, `collection_id?=default` | Get metadata for one video: name, duration, thumbnail, stream URL, and a player URL for watching it in a browser. | | `get_audio` | read | `audio_id`, `collection_id?=default` | Get metadata for one audio file: name, duration and size. | | `get_image` | read | `image_id`, `collection_id?=default` | Get metadata for one image: name and URL. | | `upload_media` | create | `url`, `collection_id?=default`, `name?`, `description?`, `media_type?`, `callback_url?` | Upload a video, audio file or image from a public URL (direct file links and YouTube URLs both work). | | `search_youtube` | read | `query`, `result_threshold?=10`, `duration?=medium` | Search YouTube and return titles, URLs and metadata, useful for finding URLs to pass to `upload_media`. | | `search_videos_by_title` | read | `collection_id?=default`, `query` | Find videos in a collection whose title matches a natural-language query. | | `update_video` | update | `video_id`, `collection_id?=default`, `name` | Update a video's display name. | | `generate_thumbnail` | create | `video_id`, `collection_id?=default`, `time_seconds?` | Get the default thumbnail of a video, or generate one from a specific timestamp (in seconds). | | `list_thumbnails` | read | `video_id`, `collection_id?=default` | List every thumbnail image generated for a video, with image IDs and URLs. | | `get_media_download_url` | read | `media_id`, `collection_id?=default` | Get a signed, time-limited download URL for an audio file (`a-`) or image (`img-`). | | `transcode_media` | create | `source`, `callback_url`, `mode?=economy`, `resolution?`, `quality?`, `framerate?`, +3 more (see below) | Start a transcode job for a video at a public URL: change resolution, quality, framerate or aspect ratio, or mute audio. | | `get_transcode_status` | read | `job_id` | Get the status and output of a transcode job started by `transcode_media`. | | `delete_video` | destructive | `video_id`, `collection_id?=default` | Permanently delete a video from a collection. | | `delete_audio` | destructive | `audio_id`, `collection_id?=default` | Permanently delete an audio file from a collection. | | `delete_image` | destructive | `image_id`, `collection_id?=default` | Permanently delete an image from a collection. | | `remove_video_storage` | destructive | `video_id`, `collection_id?=default` | Delete the stored media bytes of a video while keeping its record, indexes and transcripts. | #### `list_assets` inputs | Field | Type | Required | What it is | | --------------- | ------------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | | `collection_id` | `string` | no | Scope to one collection. Omitted = every collection in the account. | | `asset_type` | `('video' \| 'audio' \| 'image')[]` | no | Asset types to include. Omitted = all three. | | `name_pattern` | `string` | no | Case-insensitive regular expression matched against the asset name, e.g. 'keynote\|demo'. | | `min_duration` | `number` | no | Minimum duration in seconds (videos and audio). | | `max_duration` | `number` | no | Maximum duration in seconds (videos and audio). | | `min_size` | `number` | no | Minimum file size in bytes. | | `max_size` | `number` | no | Maximum file size in bytes. | | `sort_by` | `'created_at' \| 'name' \| 'duration' \| 'size'` | no (default `created_at`) | Field to sort on. created\_at is newest-first per type only, since rows carry no timestamp. | | `sort_order` | `'desc' \| 'asc'` | no (default `desc`) | Sort direction. | | `page` | `number` | no (default `1`) | Page number (1-based). | | `page_size` | `number` | no (default `100`) | Items per page. | #### `transcode_media` inputs | Field | Type | Required | What it is | | -------------- | -------------------------- | ---------------------- | ------------------------------------------------------------------------- | | `source` | `string` | yes | Public, downloadable URL of the source video. | | `callback_url` | `string` | yes | Webhook URL VideoDB calls when the job finishes (required). | | `mode` | `'economy' \| 'lightning'` | no (default `economy`) | economy = cheaper/slower, lightning = faster. | | `resolution` | `number` | no | Output height in pixels, e.g. 720 or 1080 (max 4K). | | `quality` | `number` | no | Encoder CRF quality, lower = better (default 23). | | `framerate` | `number` | no | Output frames per second. | | `aspect_ratio` | `string` | no | Output aspect ratio, e.g. "16:9", "9:16", "1:1". | | `resize_mode` | `'crop' \| 'fit' \| 'pad'` | no | How to reach aspect\_ratio: crop edges, fit (letterbox) or pad with bars. | | `mute` | `boolean` | no | Strip the audio track. | **Notes** * `get_media_download_url` covers audio and images only. For a video, render it with `download_stream`. * Uploads take a public URL. Local file paths are not supported. * A write that runs long comes back as `status: "processing"` with a `retry_with`: `upload_media` names `list_videos`, `generate_thumbnail` names `list_thumbnails`, `transcode_media` names `get_transcode_status`. ## transcripts Speech to text, plus translation of what comes back. | Tool | Kind | Inputs | What it does | | ---------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `get_transcript` | read | `media_id?`, `video_id?`, `collection_id?=default`, `timestamped?=false`, `start?`, `end?`, `segmenter?`, `segment_length?` | Get the transcript of a video or audio file, as plain text or with timestamped segments (per word, sentence or time window). | | `generate_transcript` | create | `media_id?`, `video_id?`, `collection_id?=default`, `force?=false`, `language_code?` | Transcribe a video or audio file, optionally forcing a fresh transcription or hinting the spoken language. | | `translate_transcript` | create | `video_id`, `collection_id?=default`, `language`, `additional_notes?`, `callback_url?` | Translate a video's transcript into another language and return the translated segments. | **Prerequisites** * `translate_transcript` needs an existing transcript. Run `get_transcript` or `generate_transcript` first. It works on videos only. * `get_transcript` and `generate_transcript` accept either `media_id` or `video_id`. Give exactly one. * While a transcription is still running, both come back as `status: "processing"` with `retry_with: get_transcript`. ## indexing Two pipelines: the v1 spoken-word and scene indexes, and the v2 flow where `understand_video` extracts artifacts and `create_index` turns one analyzer's output into a searchable index. | Tool | Kind | Inputs | What it does | | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `index_spoken_words` | create | `video_id`, `collection_id?=default`, `language_code?`, `force?=false`, `segmentation_type?`, `callback_url?` | Transcribe and index everything spoken in a video so it becomes searchable with `search_video` / `search_collection` (v1 index). | | `index_scenes` | create | `video_id`, `collection_id?=default`, `prompt?`, `name?`, `batch_type?=shot`, `batch_value?`, +3 more (see below) | Visually index a video (v1 scene index): samples frames per shot or per time window and describes what is on screen, so visual moments become searchable. | | `list_scene_indexes` | read | `video_id`, `collection_id?=default` | List the visual (scene) indexes that exist for a video, with IDs, names and status. | | `get_scene_index` | read | `video_id`, `collection_id?=default`, `scene_index_id` | Return the per-scene records (start, end, description) of one visual scene index. | | `delete_scene_index` | destructive | `video_id`, `collection_id?=default`, `scene_index_id` | Permanently delete one visual scene index of a video. The video is kept. | | `understand_video` | create | `video_id`, `collection_id?=default`, `analyzers`, `segmentation?`, `callback_url?` | Run one or more analyzers over a video to extract artifacts: transcript, scene descriptions, on-screen text, objects, brands, activities, locations. | | `get_understanding` | read | `video_id`, `collection_id?=default`, `understanding_id` | Get the status of one understanding run and of each analyzer in it (pending, running, done, failed). | | `list_understandings` | read | `video_id`, `collection_id?=default` | List every understanding run of a video with its status and analyzers. | | `delete_understanding` | destructive | `video_id`, `collection_id?=default`, `understanding_id` | Permanently delete an understanding run and its stored analyzer artifacts. Indexes built from it keep their own data. | | `get_analyzer_output` | read | `video_id`, `collection_id?=default`, `understanding_id`, `analyzer_name?`, `analyzer_id?` | Return the raw artifact one analyzer produced, such as transcript segments or per-scene descriptions with start/end. | | `create_index` | create | `video_id`, `collection_id?=default`, `understanding_id`, `analyzer_name?`, `analyzer_id?`, `name?`, +3 more (see below) | Build a retrieval-ready index from one analyzer's output of an understanding run. | | `get_index` | read | `video_id`, `collection_id?=default`, `index_id?`, `name?` | Get one v2 index manifest by ID or name: status (building/ready/failed), record count, capabilities and field schema. | | `list_indexes` | read | `video_id`, `collection_id?=default`, `use_for?` | List the v2 indexes of a video (ID, name, status, capabilities, record count). | | `delete_index` | destructive | `video_id`, `collection_id?=default`, `index_id` | Permanently delete a v2 index. The video and understanding artifacts are kept. | | `get_index_records` | read | `video_id`, `collection_id?=default`, `index_id`, `limit?=20`, `cursor?` | Page through the records stored in a v2 index (scene\_id, start, end, data). | #### `index_scenes` inputs | Field | Type | Required | What it is | | --------------- | ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------ | | `video_id` | `string` | yes | VideoDB video ID (starts with m-). | | `collection_id` | `string` | no (default `default`) | VideoDB collection ID. Defaults to "default" (every account has one). | | `prompt` | `string` | no | Instruction for how to describe scenes. | | `name` | `string` | no | Name for this scene index. | | `batch_type` | `'shot' \| 'time'` | no (default `shot`) | Split by detected shots or fixed time windows. | | `batch_value` | `number` | no | Shot threshold (default 20) or window seconds (default 10). | | `frame_count` | `number` | no (default `1`) | Frames sampled per scene. | | `model_name` | `string` | no | Vision model tier or name used to describe scenes, e.g. 'basic', 'pro', 'ultra'. Omit for the default. | | `callback_url` | `string` | no | Optional webhook URL VideoDB calls when the job finishes (makes the call return immediately). | #### `create_index` inputs | Field | Type | Required | What it is | | ------------------ | ------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | | `video_id` | `string` | yes | VideoDB video ID (starts with m-). | | `collection_id` | `string` | no (default `default`) | VideoDB collection ID. Defaults to "default" (every account has one). | | `understanding_id` | `string` | yes | Understanding run ID (from understand\_video / list\_understandings). | | `analyzer_name` | `string` | no | Analyzer name inside the run, e.g. 'transcript', 'scene', 'objects'. Give this or analyzer\_id. | | `analyzer_id` | `string` | no | Analyzer ID (an\_...). Give this or analyzer\_name. | | `name` | `string` | no | Index name; used by semantic\_search index\_names and get\_index. | | `use_for` | `('semantic' \| 'query' \| 'aggregate')[]` | no | Retrieval capabilities: semantic (embeddings), query (filter/sort), aggregate (group/count). | | `fields` | `object` | no | Per-field capabilities, e.g. `{description:['semantic'], label:['filter','aggregate']}`. Omit for VideoDB defaults. | | `callback_url` | `string` | no | Optional webhook URL VideoDB calls when the job finishes (makes the call return immediately). | **Prerequisites** * `create_index` needs an `understand_video` run whose analyzer has finished. Check with `get_understanding`. * `create_index` and `get_analyzer_output` accept either `analyzer_name` or `analyzer_id`. Give exactly one. * An index declares what it can serve through `use_for`. The values are `semantic`, `query` and `aggregate`, and they map to the search tools below. * `understand_video` takes `analyzers` as a list of objects, `[{type: "spoken_words"}, {type: "vlm", prompt: "Describe the scene"}]`, and `segmentation` as `{type: "time", seconds: 5}` or `{type: "shot", threshold: 30}`. * A write that runs long comes back as `status: "processing"` with a `retry_with`: `index_spoken_words` names `search_video`, `index_scenes` names `list_scene_indexes`, `understand_video` names `get_understanding`, `create_index` names `get_index`. ## search Moment search and question answering, over one video or a whole collection. | Tool | Kind | Inputs | What it does | | ------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | `search_video` | read | `video_id`, `collection_id?=default`, `query`, `search_type?`, `index_type?`, `result_threshold?`, +5 more (see below) | Search within one video and get matching moments with start/end timestamps, text and relevance scores. | | `search_collection` | read | `collection_id?=default`, `query`, `index_type?`, `result_threshold?`, `top_k?`, `mode?`, `include_clip?`, `session_id?` | Search every indexed video in a collection and get matching moments grouped by video, with timestamps and scores. | | `ask_video` | read | `video_id`, `collection_id?=default`, `question`, `top_k?`, `mode?`, `include_sources?` | Answer a natural-language question from one video's indexed content. | | `ask_collection` | read | `collection_id?=default`, `question`, `top_k?`, `mode?`, `include_sources?` | Answer a natural-language question from every indexed video in a collection. | | `semantic_search` | read | `collection_id?=default`, `video_id?`, `query`, `index_names?`, `index_ids?`, `top_k?`, +3 more (see below) | Vector search over one or more indexes in a video or across a collection. | | `query_index` | read | `collection_id?=default`, `video_id?`, `index_name?`, `index_id?`, `filter?`, `sort?`, `limit?`, `return_fields?` | Structured filter and sort over one index in a video or across a collection. | | `aggregate_index` | read | `collection_id?=default`, `video_id?`, `index_name?`, `index_id?`, `group_by?`, `metric?`, +3 more (see below) | Counts, groups and facets over one index in a video or across a collection. | #### `search_video` inputs | Field | Type | Required | What it is | | ------------------ | --------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- | | `video_id` | `string` | yes | VideoDB video ID (starts with m-). | | `collection_id` | `string` | no (default `default`) | VideoDB collection ID. Defaults to "default" (every account has one). | | `query` | `string` | yes | What to look for, e.g. 'moments where pricing is discussed'. | | `search_type` | `'semantic' \| 'keyword'` | no | Legacy: semantic (default) or keyword matching. Keyword works on videos only. | | `index_type` | `'spoken_word' \| 'scene'` | no | Legacy: index to search, spoken\_word (default) or scene. | | `result_threshold` | `number` | no | Legacy: max results (default 5). | | `scene_index_id` | `string` | no | Legacy: search one scene index (from list\_scene\_indexes). | | `top_k` | `number` | no | v2: maximum moments to return. | | `mode` | `'default' \| 'deepsearch'` | no | v2: default = single-step planned retrieval; deepsearch = multi-step investigation with follow-up sessions. | | `include_clip` | `boolean` | no | v2: also return a playable clip for each moment. | | `session_id` | `string` | no | v2: continue a deepsearch session (session\_id from a previous response). Only valid with mode=deepsearch. | #### `semantic_search` inputs | Field | Type | Required | What it is | | ----------------- | ------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `collection_id` | `string` | no (default `default`) | VideoDB collection ID. Defaults to "default" (every account has one). | | `video_id` | `string` | no | VideoDB video ID (starts with m-). Omit to run against the whole collection. | | `query` | `string` | yes | Natural-language query. | | `index_names` | `string[]` | no | Restrict to these index names. | | `index_ids` | `string[]` | no | Restrict to these index IDs. | | `top_k` | `number` | no | Max moments to return (default 10). | | `score_threshold` | `number` | no | Minimum similarity score. | | `filter` | `object[] \| object` | no | Structured filter over index fields, e.g. `[{"field": "label", "op": "==", "value": "phone"}]` or `{"activity": "walking"}`. | | `return_fields` | `string \| string[] \| object` | no | Index fields to hydrate into each moment's metadata; "all" for everything. | #### `aggregate_index` inputs | Field | Type | Required | What it is | | --------------- | -------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `collection_id` | `string` | no (default `default`) | VideoDB collection ID. Defaults to "default" (every account has one). | | `video_id` | `string` | no | VideoDB video ID (starts with m-). Omit to run against the whole collection. | | `index_name` | `string` | no | Index name (from list\_indexes). | | `index_id` | `string` | no | Index ID (from list\_indexes). | | `group_by` | `string` | no | Aggregatable field to group by; dotted paths allowed, e.g. frames.detections.label. | | `metric` | `string` | no | count (default), or sum(field), avg(field), min(field), max(field). | | `filter` | `object[] \| object` | no | Structured filter over index fields, e.g. `[{"field": "label", "op": "==", "value": "phone"}]` or `{"activity": "walking"}`. | | `sort` | `string \| array` | no | Sort order, e.g. \[\["start", "asc"]]. | | `limit` | `number` | no | Max groups (default 100). | **Prerequisites** * `search_video` and `search_collection` read the v1 indexes: spoken-word search needs `index_spoken_words`, and `index_type='scene'` needs `index_scenes`. * `ask_video` and `ask_collection` need v2 indexes built by `create_index`. * `semantic_search`, `query_index` and `aggregate_index` need an index built by `create_index` whose `use_for` includes `semantic`, `query` and `aggregate` respectively. Each takes `index_name` or `index_id`, and each runs over one video with `video_id` or the whole collection without it. * `filter` takes `[{"field": "label", "op": "==", "value": "phone"}]` or the shorthand `{"activity": "walking"}`. `sort` takes `[["start", "asc"]]`. `return_fields` takes a field name, a list of them, or `"all"`. ## streams Cut, stitch, subtitle and reframe videos into playable streams, then render them to MP4. | Tool | Kind | Inputs | What it does | | ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `generate_clip` | create | `video_id`, `collection_id?=default`, `timeline` | Cut a clip, or a supercut of several segments, from a single video without re-encoding. | | `compile_clips` | create | `clips` | Stitch moments from one or more videos into a single new stream. | | `add_subtitles` | create | `video_id`, `collection_id?=default`, `font_name?`, `font_size?`, `primary_colour?`, `secondary_colour?`, +17 more (see below) | Burn subtitles into a video from its transcript. | | `create_highlight_clip` | create | `video_id`, `collection_id?=default`, `prompt`, `content_type?=spoken`, `model_name?=basic` | Pick the moments of a video that match a natural-language prompt and compile them into one stream. | | `reframe_video` | create | `video_id`, `collection_id?=default`, `start?`, `end?`, `target?=vertical`, `mode?=smart`, `callback_url?` | Re-crop a video, or a segment of it, to a new aspect ratio (vertical, square, landscape or custom dimensions) and save it as a new video in the same collection. | | `download_stream` | create | `stream_url`, `name` | Render any VideoDB stream URL into a downloadable MP4 file. | #### `add_subtitles` inputs | Field | Type | Required | What it is | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `video_id` | `string` | yes | VideoDB video ID (starts with m-). | | `collection_id` | `string` | no (default `default`) | VideoDB collection ID. Defaults to "default" (every account has one). | | `font_name` | `string` | no | Font family, default Arial. | | `font_size` | `number` | no | Font size, default 18. | | `primary_colour` | `string` | no | Text colour. ASS colour string \&HAABBGGRR (alpha, blue, green, red hex), e.g. \&H00FFFFFF is opaque white. Default white. | | `secondary_colour` | `string` | no | Secondary (karaoke) colour. ASS colour string \&HAABBGGRR (alpha, blue, green, red hex), e.g. \&H00FFFFFF is opaque white. | | `outline_colour` | `string` | no | Outline colour. ASS colour string \&HAABBGGRR (alpha, blue, green, red hex), e.g. \&H00FFFFFF is opaque white. Default black. | | `back_colour` | `string` | no | Background/shadow colour. ASS colour string \&HAABBGGRR (alpha, blue, green, red hex), e.g. \&H00FFFFFF is opaque white. Default black. | | `bold` | `boolean` | no | Bold text. | | `italic` | `boolean` | no | Italic text. | | `underline` | `boolean` | no | Underlined text. | | `strike_out` | `boolean` | no | Strike-through text. | | `scale_x` | `number` | no | Horizontal scale factor, default 1.0. | | `scale_y` | `number` | no | Vertical scale factor, default 1.0. | | `spacing` | `number` | no | Extra spacing between letters in pixels, default 0. | | `angle` | `number` | no | Rotation angle in degrees, default 0. | | `border_style` | `'no_border' \| 'opaque_box' \| 'outline'` | no | Border style, default outline. | | `outline` | `number` | no | Outline thickness in pixels, default 1. | | `shadow` | `number` | no | Shadow depth in pixels, default 0. | | `alignment` | `'bottom_left' \| 'bottom_center' \| 'bottom_right' \| 'middle_left' \| 'middle_center' \| 'middle_right' \| 'top_left' \| 'top_center' \| 'top_right'` | no | Position of the subtitles on the frame, default bottom\_center. | | `margin_l` | `number` | no | Left margin in pixels, default 10. | | `margin_r` | `number` | no | Right margin in pixels, default 10. | | `margin_v` | `number` | no | Vertical margin in pixels, default 10. | **Prerequisites** * `add_subtitles` needs `index_spoken_words` on the video first. * `download_stream` takes a stream URL from `generate_clip`, `compile_clips`, `add_subtitles`, `create_highlight_clip` or `get_video`. * `generate_clip` takes `timeline` as `[start_seconds, end_seconds]` pairs, `[[10, 25], [60, 90]]`. `compile_clips` takes `clips` as a list of objects in playback order. * `reframe_video` takes `target` as a preset (`vertical`, `square`, `landscape`) or an explicit `{width, height}`. It comes back as `status: "processing"` with `retry_with: list_videos`. ## editor Multi-track timeline rendering. Tracks hold clips, and each clip carries a video, image, audio, text or caption asset. | Tool | Kind | Inputs | What it does | | -------------------------- | ------ | -------------------------------------- | ------------------------------------------------------------------- | | `render_timeline` | create | `tracks`, `background?`, `resolution?` | Render a multi-track editor timeline into a new stream in one call. | | `download_timeline_render` | create | `stream_url` | Request an MP4 download of a stream produced by `render_timeline`. | **Notes** * A caption asset with `src: "auto"` pulls from the video's spoken-word index. On an unindexed video the render succeeds with no captions, so run `index_spoken_words` first. * Text assets sized with `width`/`height` keep those dimensions only under `fit: "contain"`. The default `fit: "crop"` upscales the text box to fill the frame. * `tracks` carries the whole edit. It is a list of track objects, each holding its clips and their assets. ## rtstream Ingest live RTSP, RTMP and HLS streams, index them continuously, search them, and get alerts on events. All timestamps are Unix seconds. | Tool | Kind | Inputs | What it does | | ------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connect_rtstream` | create | `url`, `name`, `collection_id?=default`, `media_types?=["video"]`, `sample_rate?`, `store?`, `enable_transcript?` | Register a live RTSP/RTMP/HLS stream with VideoDB and start ingesting it. | | `list_rtstreams` | read | `limit?=10`, `offset?=0`, `status?`, `name?`, `ordering?` | List real-time streams in the account with IDs, names, status and media types. | | `get_rtstream` | read | `rtstream_id` | Get one real-time stream: name, status, sample rate, media types, creation time. | | `set_rtstream_status` | update | `rtstream_id`, `action` | Start (connect) or stop (disconnect) ingestion of a real-time stream. | | `get_rtstream_stream` | read | `rtstream_id`, `start`, `end` | Generate a playable stream and player URL for a time window of a real-time stream. | | `export_rtstream_recording` | create | `rtstream_id`, `name?` | Export the latest completed recording of a real-time stream as a regular VideoDB video or audio asset. | | `get_rtstream_transcript` | read | `rtstream_id`, `page?=1`, `page_size?=100`, `start?`, `end?`, `since?` | Read the real-time transcript of a stream. | | `set_rtstream_transcript_status` | update | `rtstream_id`, `action`, `mode?=graceful`, `engine?` | Start or stop real-time transcription on a stream. | | `index_rtstream_scenes` | create | `rtstream_id`, `prompt?`, `window_seconds?`, `frame_count?`, `model_name?`, `name?` | Start a continuous visual index on a real-time stream: every `window_seconds`, `frame_count` frames are described with the prompt. | | `index_rtstream_audio` | create | `rtstream_id`, `prompt?`, `segmenter?`, `segment_value?`, `model_name?`, `name?`, `auto_start_transcript?=true` | Start a continuous spoken-word index on a real-time stream: the live transcript is chunked by segmenter and summarized with the prompt. | | `list_rtstream_scene_indexes` | read | `rtstream_id` | List the scene (visual and audio) indexes on a real-time stream with their IDs, prompts and status. | | `get_rtstream_scenes` | read | `rtstream_id`, `scene_index_id`, `start?`, `end?`, `page?=1`, `page_size?=100` | Read the records a scene index has produced so far (Unix-second start/end plus description). | | `set_rtstream_scene_index_status` | update | `rtstream_id`, `scene_index_id`, `action` | Resume or pause a scene index on a real-time stream. | | `search_rtstream` | read | `rtstream_id`, `query`, `index_type?`, `scene_index_id?`, `result_threshold?`, `score_threshold?` | Semantic search over the indexed records of a real-time stream. | | `create_event` | create | `event_prompt`, `label` | Define a reusable event, a natural-language condition such as "a person enters the restricted area", that alerts can watch for on any stream index. | | `list_events` | read | none | List the events defined on the account (ID, label, prompt). | | `create_rtstream_alert` | create | `rtstream_id`, `index_id`, `index_kind?=scene_index`, `event_id`, `callback_url` | Attach an event to a stream index so VideoDB POSTs to `callback_url` each time the event is detected in a new window. | | `list_rtstream_alerts` | read | `rtstream_id`, `index_id`, `index_kind?=scene_index` | List the alerts attached to a stream index, with their event, callback and enabled state. | | `set_rtstream_alert_status` | update | `rtstream_id`, `index_id`, `index_kind?=scene_index`, `alert_id`, `action` | Enable or disable an alert on a stream index without deleting it. | | `understand_rtstream` | create | `rtstream_id`, `prompt`, `window_seconds?=5`, `frame_count?=2`, `output_name?=scene`, `store?=true` | Start a continuous vision-model analysis on a real-time stream: every `window_seconds`, `frame_count` frames are analyzed with the prompt and stored under `output_name`. | | `list_rtstream_understandings` | read | `rtstream_id` | List the continuous understanding jobs on a real-time stream with their status, segmentation, analyzers and output descriptors. | | `set_rtstream_understanding_status` | update | `rtstream_id`, `understanding_id`, `action` | Resume or pause a continuous understanding job on a real-time stream. | | `get_rtstream_understanding_records` | read | `rtstream_id`, `understanding_id`, `start`, `end`, `output?=scene`, `page?=1`, `page_size?=100` | Read the analysis records an understanding produced for a Unix-second time range (start and end required). | | `create_rtstream_index` | create | `rtstream_id`, `understanding_id`, `output?=scene`, `name?`, `use_for?` | Materialize an understanding output into a continuously updated searchable index. | | `list_rtstream_indexes` | read | `rtstream_id` | List the understanding-backed indexes on a real-time stream with their status, source understanding and capabilities. | | `set_rtstream_index_status` | update | `rtstream_id`, `index_id`, `action` | Resume or pause an understanding-backed index on a real-time stream. | | `get_rtstream_index_records` | read | `rtstream_id`, `index_id`, `start?`, `end?`, `page?=1`, `page_size?=100` | Read the records materialized into an understanding-backed index, optionally limited to a Unix-second start/end window. | **Prerequisites** * Everything here starts with `connect_rtstream`. Indexes, understandings and alerts attach to a stream that is already connected and ingesting. * `get_rtstream_transcript` needs transcription running, started either by `connect_rtstream` with `enable_transcript` or by `set_rtstream_transcript_status`. * `search_rtstream` needs a scene index or an understanding-backed index on the stream. * `create_rtstream_index` needs an `understand_rtstream` job started with `store=true`. * `create_rtstream_alert` needs an event from `create_event` and an index to attach it to. Alerts cannot be deleted, only disabled with `set_rtstream_alert_status`. * `list_rtstreams` is account-scoped, not per collection. Each row carries its own `collection_id`. * Alert tools take `index_kind` to say which index the `index_id` belongs to: `scene_index` for one built by `index_rtstream_scenes` or `index_rtstream_audio`, `index` for one built by `create_rtstream_index`. * A write that runs long comes back as `status: "processing"` with a `retry_with`: `connect_rtstream` names `list_rtstreams`, `export_rtstream_recording` names `get_video`, `index_rtstream_scenes` and `index_rtstream_audio` name `list_rtstream_scene_indexes`, `understand_rtstream` names `list_rtstream_understandings`, `create_rtstream_index` names `list_rtstream_indexes`, `create_event` names `list_events`, `create_rtstream_alert` names `list_rtstream_alerts`. ## meetings Send a recorder bot into a meeting and collect the recording. | Tool | Kind | Inputs | What it does | | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `record_meeting` | create | `meeting_url`, `collection_id?=default`, `bot_name?`, `bot_image_url?`, `meeting_title?`, `time_zone?=UTC`, `callback_url?` | Send a VideoDB recorder bot to a Zoom, Google Meet or Microsoft Teams meeting URL. | | `get_meeting` | read | `meeting_id`, `collection_id?=default` | Get the state of a recorder bot: status (initializing, joined, processing, done), the recorded `video_id` once done, and the speaker timeline when available. | **Prerequisites** * `record_meeting` comes back as soon as the bot is dispatched, with `status: "processing"` and `retry_with: get_meeting`. Poll `get_meeting` until `status` is `done`. Only then does `video_id` have a value. ## Not exposed | Feature | Why not | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | AI generation: image, music, sound effect, voice and video generation, dubbing, voice clones | Excluded by connector policy. Use the SDKs. | | Text generation | The client is already a language model. | | Local-path uploads and `play()` | These need your filesystem or a browser on your machine. | | Desktop capture, capture sessions and their client tokens | Capture runs through a native binary on your machine over a long-lived connection. A remote server cannot drive it. | For generation, use the [generative media guides](/pages/act/generative-media/index). For desktop capture and local files, use [VideoDB Agent Skills](/pages/getting-started/agent-skills), which run on your machine. What the hosted server is and what it connects to Add the server to Claude, Cursor and other MCP clients End-to-end recipes built from these tools