Riverside

Creates cuts across all recording tracks for the given time ranges. Accepts integer times in milliseconds as startMs/endMs; do not pass {n,d} fractions. The server handles fraction conversion and reverse-chronological ordering internally. For transcript-derived cuts, call resolve_transcript_selection with intent="remove" and execute the resolver response's payload.input unchanged once readyToApply is true. Callers should use source="user" for agent-proposed and exact user-specified cuts. The "director" enum value remains only for backward compatibility with existing stored provenance. This is the recommended way to create cuts (instead of batch with create_cuts_from_collapsed_range).

editing_cut_time_ranges

Applies a batch of editing operations atomically. All succeed or all roll back. Input: { editId: string, operations: [{ type, params }] } Call get_editing_guide with section="operations" for per-operation parameters. Call get_editing_guide with section="usage" for time format, ordering, examples, and error recovery. Use set_visual_crop for one static normalized crop from a clip or track's first visible frame. Keep modify_crop for advanced or time-varying crops. Use set_color_correction for one static color-correction patch on a clip or track; keep modify_color_correction for advanced or time-varying color keyframes. For complex or multi-operation batches, optionally call validate_edit_plan immediately before this tool with exactly the same payload, then pass its planHash as validatedPlanHash. Do not preflight standalone write tools. Available categories: clip, cut, synced-cut, mute, track, scene, chapter, visual-transform, animation, caption-settings, layout, overlay, transcript, magic-audio, brand, aspect-ratio. Use get_editing_guide before composing destructive batches.

editing_batch

Exact-phrase search over recording/take transcript content across the caller's archive (higher precision than search_riverside's fuzzy matching). Returns compact per-session matches with sessionId, takeId, projectId and up to maxHighlightsPerSession ~200-character transcript fragments, with no word timestamps. Feed sessionId, projectId, and a title to editing_create_edit_from_recording, or use platform_get_transcript for prose. sessionId identifies the recording session rather than the individual take, so for a multi-take recording it may resolve to a sibling take: confirm the intended take with the user first, or start from platform_list_edits if the recording already has an edit. TAKES/recordings only — clip and project transcripts are not searched.

search_recording_transcripts_exact

Step 2 of 2. Call after the file bytes have been uploaded to the uploadUrl from create_media_upload. For video, pass the thumbnailUploadUrl too: the server pulls a poster frame from the uploaded file, derives the display resolution, and attaches the thumbnail — the caller never needs ffmpeg. Finalizes the media and returns its id, status, and a read URL. Once finalized, the media appears in the editor's "Your Media" library. Images finalize instantly; video/audio return status "processing" and transcode on the server.

media_finalize_media_upload

Returns name, type, duration, and resolution for a media asset by its ID. Use duration to choose overlay length for video/audio assets; duration is null for images. Resolution is returned as { width, height } in pixels. The dedicated insert_overlay tool resolves dimensions server-side; do not pass resolution to that tool. When calling batch insert_overlay directly, batch insert_overlay still requires resolution from get_asset_metadata for image/video overlays; omit it only for audio. For images without a stored resolution the dimensions are measured live from the file. Also returns externalSource (asset provenance — e.g. "hyperframes" for a rendered HyperFrame overlay or "pexels" for stock; null for user uploads) and externalSourceId. Fails with FAILED_PRECONDITION only when the resolution cannot be determined at all.

editing_get_asset_metadata

Fetch a studio/production brand kit (logo, colors, design, captions, intro/outro). Read-only — does not modify the kit or any edit.

editing_get_brand

Fetch the full pool of captions style presets available to a studio. Returns three fields. (1) brandCaptionsList — the brand-kit caption styles; THIS is the brand source of truth. To apply the brand style, pick the entry with isDefault=true, or the lowest sortOrder if none is marked. (2) brandCaptions — the SAME brand styles in the legacy per-ratio format. It is NOT an additional pool and may duplicate brandCaptionsList; read it ONLY when brandCaptionsList is empty (kit not yet migrated). Never merge or count the two lists together. (3) presets — the general catalog: studio-saved custom presets first (isBuiltIn=false), then built-in defaults (isBuiltIn=true); use these when not applying the brand. Always pick an existing preset style instead of inventing caption styling. Read-only — does not modify the kit, presets, or any edit.

editing_get_captions_presets

Returns editorial strategy, multi-pass review, and cut rationale guidance, plus operation params, time conversion, transcript/timeline workflows, and error recovery.

editing_get_editing_guide

Before publishing to YouTube, returns any Content-ID/copyright codes for the edit's media. A non-null `youtubeCode` flags a potential copyright match.

editing_get_export_publish_data

Returns the full layout plan for a single layout id, including undescribed layouts. layoutPlan is a large opaque blob; list_layouts' summary usually suffices.

editing_get_layout

Returns the current revision identifier for an edit without fetching the full timeline or transcript. Use this to cheaply verify that a cached revision is still current before issuing other tool calls. The returned revision matches the value reported by read_aligned_transcript, batch, and cut_time_ranges. Pass the returned value directly as `expectedRevision` on revision-aware writes.

editing_get_revision

Searches the stock library (Pexels) for images or videos matching a natural-language query and returns a list of options to choose from — it does NOT modify the timeline. Call this first when the user asks for a stock photo or clip (e.g. "add a photo of a city skyline"), review the results, then call insert_stock_media with the chosen option's externalSourceId. Returns an empty list if nothing matches. Each option also carries the Pexels `url` (its path is descriptive) and `tags` (often empty). `description` is the library alt text: present for images, null for videos — so for videos lean on the `url` and the query.

editing_get_stock_media

Browses the FREE built-in music library (the editor’s "ready-made collections") and returns tracks to choose from — it does NOT modify the timeline, and it is free for all users. Call this first when the user wants background music (e.g. "add an intro jingle for an education video"), then place the chosen track with insert_audio: pass the track's mediaId as assetId (durationMs defaults to the full track; volume/fades optional). Tracks are organized by COLLECTION (content genre) and SECTION (where it plays); within each, pick a variant by name — High/Low = intensity, Short/Long = length. Collections: lifestyle, newsPolitics, educational, gaming, artsEntertainment, businessTech, trueCrime, sportsRecreation. Sections: intro, outro, transition, underscore. (This is the free library; the larger paid library is separate.)

editing_get_stock_music

List the social media platforms (YouTube, TikTok, Instagram, Facebook, LinkedIn, X) connected to a studio, including posting details such as platformAccountId, YouTube accounts[].channelId for upload_create youtubeData.channelId, X characterLimit for xData.text, TikTok privacyLevelOptions for tiktokData.privacyLevel, postingAvailable, and maxVideoPostDurationSec. If an upstream account-detail fetch fails, an account can return accounts: []; empty accounts does not always mean no accounts are connected.

social_get_connected_platforms

Get a single edit by id, including its parent project and source recording. In the JSON response, `take` is the source recording. The `riversideUrl` field is the canonical link to open this edit in the Riverside editor (the editor preview URL) — return it directly when the user wants the link, rather than constructing a URL yourself.

platform_get_edit

Get a single export by id, including its parent edit. Returned `status`, `format`, and `resolution` are backend strings; observed status values include `pending` and `ready`, where `ready` means the export artifact is finished/downloadable. This is artifact readiness, not `social_upload_create` publish-readiness; publish checks the clip status, which this tool does not expose. The `riversideUrl` field is the canonical link to open this export in Riverside — return it directly when the user wants the link, rather than constructing a URL yourself.

platform_get_export

Fetch a media item's current state by id. Use it to check whether processing finished: for video/audio status is "processing" while transcoding, then becomes "transcoded" (or "done") when complete, or "failed" on error (processingComplete/failed booleans summarise this). Also returns duration, resolution, the source url, and thumbnailUrl once ready, plus per-artifact fileStatuses (e.g. hls, thumbnail). The media lives in the editor's "Your Media" library.

media_get_media

Return per-platform publishing guidelines: metadata fields and their limits, character caps, video duration/size/aspect-ratio constraints, the publishing workflow and its preconditions, and error-code recovery. Call this before composing upload_create metadata so the post passes backend validation. Pass platform to filter to a single platform; omit it to get every platform.

social_get_publishing_guidelines

Get a single production by id, including its child studios.

platform_get_production

Get a single project by id, including its parent studio, recordings and edits. Use as the recommended fan-out: one call returns recordings and edits with ids, cheaper than separate list_recordings/list_edits calls. The `riversideUrl` field is the canonical link to open this project in Riverside — return it directly when the user wants the link, rather than constructing a URL yourself.

platform_get_project

Get a single recording by id, including its parent project and studio. For uploads and single-take recordings, use `id` as `sessionId` for `platform_get_transcript` and `editing_create_edit_from_recording`. The returned `status` is a backend string, not a closed enum in this schema. `riversideUrl` is the dashboard/project recording link. The token-bearing `previewUrl` is omitted by default; set `includePreviewUrl: true` only after a shareable preview link is explicitly requested, and return the server-provided URL directly rather than constructing a URL. If the opted-in `previewUrl` is null, no share link is currently available.

platform_get_recording

Get a single studio by id, including its parent production. The `riversideUrl` field is the canonical link to open this studio in Riverside — return it directly when the user wants the link, rather than constructing a URL yourself.

platform_get_studio

Get the transcript of a recording by session id. For uploads and single-take recordings, use `id` as `sessionId`; the same value feeds `editing_create_edit_from_recording`. This returns dialogue prose, each line headed by `Speaker (m:s.mmm)` — one timestamp per sentence, measured from the start of the recording session. Note minutes and seconds are not zero-padded (`1:5.000` is 1m5s). Exception: when a recording exposes no offset for a speaker, that speaker is timed from their own track start instead, so their times are not comparable with the other speakers. For word-level times, or for cutting, use `editing_read_aligned_transcript`.

platform_get_transcript

Search Riverside projects, clips, and recording takes with fuzzy matching, including spoken-word transcript content for takes. Use search_recording_transcripts_exact when the wording must match exactly. For spoken moments, pass a filters entry whose entity is TAKE. Transcript/content matching applies only to takes/recordings. Projects and clips match by title; studios and productions are not searchable entities. Results expose compact public fields, identifiers, and short transcript fragments in highlights.transcription, with no word timestamps and no full transcript. No tool has a parameter named takeId or entityId; takeId is display-only, while the entityId on a CLIP result is the clip ID that social_upload_create accepts as clipId. To locate or edit a TAKE result, call editing_create_edit_from_recording(sessionId, projectId, title), then editing_read_aligned_transcript(editId) for word-level times; platform_get_transcript(sessionId) returns dialogue prose instead. A take's sessionId identifies its recording session, not the individual take, so for a multi-take recording it may resolve to a sibling take: confirm the intended take with the user first, or start from platform_list_edits if the recording already has an edit. Results page 10 at a time via nextSearchAfter; there is no limit parameter. Pass explicit null for unused nullable parameters.

search_riverside

Inserts an AUDIO asset (music track, sound effect, voiceover, uploaded audio) onto the timeline as an audio layer, with optional volume and fade-in/fade-out — the audio-specific controls image/video overlays do not have. This is how a built-in music track from get_stock_music is placed: pass its mediaId as assetId (durationMs defaults to the asset's full length). For image/video assets use insert_overlay instead.

editing_insert_audio

Inserts an existing IMAGE or VIDEO media asset as a new FULLSCREEN scene at a timestamp. Unlike insert_overlay, which layers a clip on top of existing content without changing length, this GROWS the timeline: it adds a whole scene, increasing total duration and rippling all later content to the right. Use insert_overlay for layered/PiP or lower-third placement that leaves duration unchanged; for AUDIO (music, sound effects, voiceovers) use insert_audio. Returns BAD_REQUEST if startMs is outside the current playable timeline (past the end, or inside a removed/cut region), and requires durationMs when inserting a video whose media duration is unknown.

editing_insert_media_as_scene

Inserts a VISUAL media asset (image or video) as a timeline overlay, placed on top of existing content. Resolves the asset type and pixel dimensions server-side — pass just the assetId and timing. This is the recommended way to insert uploaded images/videos as an overlay (instead of batch with insert_overlay, which requires the caller to supply resolution). For AUDIO assets (music, sound effects, voiceovers) use insert_audio instead, which adds volume and fade controls. To place an image/video as a NEW FULLSCREEN scene that GROWS the timeline (shifting later content right) instead of layering on top, use insert_media_as_scene. Fails with FAILED_PRECONDITION if the asset's dimensions cannot be determined.

editing_insert_overlay

Inserts a chosen stock-library item (from get_stock_media) onto the timeline as an overlay: it imports the item into the project media, then places it — all server-side. First call get_stock_media to search and pick an option, then call this with that option's externalSourceId and matching mediaType. Returns NOT_FOUND if the chosen item no longer resolves.

editing_insert_stock_media

Given an `editId`, returns the recording `sessionId`(s) behind its clips; feed these to `platform_get_transcript` or `search_riverside`. Throws if any source is unresolvable.

editing_list_edit_recording_asset_sessions

Lists described layout templates in bounded pages, sorted by id. Only layouts with a textDescription are included. Filters use explicit backend metadata only: aspect ratio, match criteria, and true capability attributes; no ids or prose are inferred. Use to discover available layouts before applying one with batch/change_layout.

editing_list_layouts

List edits. Pass `projectId` to scope to a single project when the request is about that project; omit it for broad requests. Results may include soft-deleted edits (`deleted: true`) — filter these out unless the request is specifically about deleted edits. Returns a compact `{total, offset, limit, items}` envelope; `total` is the full unpaged count, so page with `limit`/`offset` while `total` exceeds `offset + items.length`. Each item's `riversideUrl` is its canonical link to open that edit in the Riverside editor; return it directly rather than constructing a URL.

platform_list_edits

List exports; pass `editId` to scope to a single edit when the request is about that edit. Returned `status`, `format`, and `resolution` are backend strings; observed status values include `pending` and `ready`, where `ready` means the export artifact is finished/downloadable. This is artifact readiness, not `social_upload_create` publish-readiness; publish checks the clip status, which this tool does not expose. Returns a compact `{total, offset, limit, items}` envelope; `total` is the full unpaged count, so page with `limit`/`offset` while `total` exceeds `offset + items.length`. Each item's `riversideUrl` is its canonical link to open that export in Riverside; return it directly rather than constructing a URL.

platform_list_exports

List all productions the authenticated user has access to. Start here: productions -> projects -> recordings/edits, via studios when needed. Returns a compact `{total, offset, limit, items}` envelope; `total` is the full unpaged count, so page with `limit`/`offset` while `total` exceeds `offset + items.length`.

platform_list_productions

List projects; pass `studioId` to scope to a single studio when the request is about that studio. Returns a compact `{total, offset, limit, items}` envelope; `total` is the full unpaged count, so page with `limit`/`offset` while `total` exceeds `offset + items.length`. Each item's `riversideUrl` is its canonical link to open that project in Riverside; return it directly rather than constructing a URL.

platform_list_projects

List recordings. Omit `projectId` for broad requests like "my videos" or "all recordings"; only pass it when the current request explicitly scopes to a project, and do not reuse a cached project id for an unscoped request. For uploads and single-take recordings, use `id` as `sessionId` for `platform_get_transcript` and `editing_create_edit_from_recording`. The returned `status` is a backend string, not a closed enum in this schema. Returns a compact `{total, offset, limit, items}` envelope; `total` is the full unpaged count, so page with `limit`/`offset` while `total` exceeds `offset + items.length`. Each item's `riversideUrl` is the dashboard/project recording link; return that field directly rather than constructing a URL. This list never returns the token-bearing `previewUrl`; use `platform_get_recording` with `includePreviewUrl: true` only when a shareable preview link is explicitly needed.

platform_list_recordings

List studios; pass `productionId` to scope to a single production when the request is about that production. Returns a compact `{total, offset, limit, items}` envelope; `total` is the full unpaged count, so page with `limit`/`offset` while `total` exceeds `offset + items.length`. Each item's `riversideUrl` is its canonical link to open that studio in Riverside; return it directly rather than constructing a URL.

platform_list_studios

This action publishes or schedules a post on an external social media platform. Supports YouTube, TikTok, Instagram, Facebook, LinkedIn, and X (Twitter). Use get_connected_platforms first to discover platform accounts and required per-account limits/options. Call get_publishing_guidelines first for per-platform metadata constraints, video limits, and publish error recovery. This MCP cannot cancel a scheduled upload or edit, delete, undo, or unpublish a created post. Before asking for final confirmation, tell the user that any correction or removal must be handled outside this MCP. Before calling this tool, show the user a final summary with the destination platform and human-readable account or channel name or handle (not internal IDs); the exact final post content and applicable platform options, including privacy or visibility settings; and whether it will publish immediately or at the scheduled date, time, and timezone. For a non-exported clip, also show the export settings. Obtain explicit confirmation of this summary. Match each platform value to its data object: "YouTube" requires youtubeData with channelId, title, description, and privacyStatus (youtubePlatform is optional); "TikTok" requires tiktokData with title and privacyLevel; "Instagram" requires instagramData with caption; "Facebook" requires facebookData (description is optional); "LinkedIn" requires linkedinData with visibility (description is optional); "X" requires xData with text. For a non-exported clip (a draft / "magic clip" not yet exported), also provide composeSettings to export-then-publish it (tell the user the export defaults and ask if they want to change any; pass {} to accept them); omit composeSettings for an already-exported clip. Returns { success, results: [{ platform, platformAccountId, success, uploadId, status, scheduledAt, error }] }. A status of WAITING_FOR_GREENLIGHT means the clip is still exporting and will publish automatically once ready — do NOT show that raw status to the user; instead tell them the clip is processing and will be published once it's ready (relay the accompanying message field).

social_upload_create

Defaults to compact rows in the `sentences` response field. Rows are returned in chronological order on one global playable timeline shared by every speaker. Rows may overlap when speakers interrupt or talk over one another. In detail="words" without a window, playable rows sort by first playable word start, then end; deleted/unplayable word-detail rows sort last. Bounded word reads omit words without positive-duration overlap with the requested half-open window. Compact sentence mode omits rows with no playable words. Rounding rules apply only to `*Ms` fields: `playableStartMs` uses floor and `playableEndMs` uses ceil; `{n, d}` fields are unchanged. In word mode, assetStart/assetEnd/playableStart/playableEnd are `{n, d}` fractions of seconds. Rows are acoustic segments, not a grammatical sentence; use them for locating, never as final cut points. startsMidSentence/endsMidSentence mark continuations; extend kept spans past flagged rows. For cut-grade timestamps, request detail="words" with startMs/endMs and use the intended phrase's true first and last word; see get_editing_guide. Treat word-mode output as working data; report only selected ranges with short evidence snippets. Rows and words include opaque edit/revision-scoped spanIds/wordIds; pass them to resolve_transcript_selection, not reconstructed timestamps. Word-mode word `clipId` values are opaque strings; keep them round-trippable. Use playable timestamps for the edited timeline; do not substitute asset/source timestamps. For transcript edits, pass spanId/wordId and explicit intent to resolve_transcript_selection; execute payload.input only when readyToApply is true, never when payload is null. Word mode clips to the half-open window and returns bounded wordDetail metadata; maxWords/maxBytes defaults and caps are in their schemas. Pass the returned revision as `expectedRevision` only to write tools whose input schema exposes that field. See get_editing_guide for the full revision-safe workflow.

editing_read_aligned_transcript

Returns a filtered view of the timeline data scoped to a requested time range. This is the primary read API for agents to understand what exists at a given point in the timeline — which tracks, clips, scenes, layouts, keyframes, and transforms are active in that window. The response is a self-contained cut of the full timeline, scoped to the requested range. All time values in the response (trackTime, timeRange, duration, scene times) are {n, d} fractions of seconds (time = n/d). Pass them directly to fraction-based batch operation params. For source-time millisecond tools such as reorder_timeline, add_lower_third, add_text_overlay, and insert_overlay, convert first with Math.round(1000 * n / d). cut_time_ranges.startMs/endMs and insert_audio.startMs are playable time; do not pass raw source timestamps because each tool converts playable placement back to source time. All returned times are source time, not the effective/playable (post-cut) axis — once cuts exist, do not compare them 1:1 against playableStartMs/playableEndMs from read_aligned_transcript. On each clip, trackTime is its position on the timeline and timeRange.start is the in-point into its source asset. Structural details — where clip/track uniqueIds live, and collapsed-clip detection by matching trackTime+timeRange across tracks — are in get_editing_guide section "usage".

editing_read_timeline_in_range

Removes transcript-labeled disfluency regions across the edit: filler words, noise, and word-level disfluencies. Classification comes from the transcript; this tool does not analyze audio. `method` chooses how: "Cut" deletes eligible regions when safe, "Mute" silences them while preserving timing, and "Smart" is duration-based, not content-adaptive: it mutes eligible regions shorter than 500 ms and cuts regions 500 ms or longer when safe; crosstalk is muted. This is the recommended way to remove transcript-labeled disfluencies (instead of batch with remove_fillers). Pass `expectedRevision` from your last read. Use restore_audio_cleanup with cleanup="fillers" to undo the remove_fillers cleanup (batch restore_fillers is the low-level fallback). Fails with FAILED_PRECONDITION when the edit has no loadable transcript (filler detection requires it); `context.reason` says why.

editing_remove_fillers