Riverside

Creates a new editable timeline from a recording session. The original recording is not modified. Returns an editId to use with transcript, timeline, and editing tools. The returned `editId` becomes the working edit for this flow. Use it for subsequent edits instead of creating another copy, unless the user explicitly asks for a separate version. This capability may be unavailable for the current Riverside account. If it returns `FAILED_PRECONDITION`, retrying will not help until availability changes; use an existing editId from `platform_list_edits`, or ask the user to open or create an edit in Riverside.

editing_create_edit_from_recording

Renders one revision of an edit to a video or audio file. This changes state: it creates a PENDING export and dispatches a Temporal compose workflow, so calling it twice renders the edit twice. It returns the new export immediately, including the revision it pinned — but not the rendered file: `s3Key` stays null until the compose job reports back, so poll `get_export` for the outcome (a full-length edit takes minutes, not seconds). Compose settings are normalized server-side and `export.useWatermark` plus `planFeatures` are overwritten from the account's plan, so the stored value can differ from what was sent. An edit with no saved RSTL cannot be exported.

exports_create_export

Upload a media file so it appears in the editor's "Your Media" library, ready to drop onto the timeline. Step 1 of 2: registers the media (as the authenticated caller) and returns an uploadUrl. The bytes are NOT sent through this tool — after calling it, upload the file directly to uploadUrl (e.g. `curl -T <path> -H "Content-Type: <mimeType>" "<uploadUrl>"`), then call finalize_media_upload. This requires a client with local filesystem access, such as a desktop app or CLI; a browser-only chat cannot read local files. Requires fileSizeBytes; files over 500 MB and unsupported types are rejected. For video, the poster thumbnail and display resolution are generated on the server at finalize — the caller never needs ffmpeg. Follow the returned instructions.

media_create_media_upload

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" to cut the selection, or intent="keep" to cut everything outside it, 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

Disconnects a social account from a studio, so Riverside can no longer post to it. This is the same action the Riverside web app offers. Every upload still scheduled on this account is cancelled, and nothing on this server can restore it. Say that to the user before calling. Call get_connected_platforms first, show the user the account's name or handle and its platform, and get an explicit yes. Reconnecting later is done with connect_social_account or from the Riverside web app. Facebook is not per-page: one Facebook login owns many Pages, and disconnecting any one of them disconnects EVERY Page under that same login, cancelling all of their scheduled uploads. Pages belonging to a different Facebook login stay connected. Name every Page the user is about to lose — get_connected_platforms lists them — before calling it on Facebook. Returns { platformAccountId, platform, disconnected, message }. An account that was already disconnected returns disconnected: false, which is not an error; platform is null in that case, because only connected accounts report one. Facebook is the exception: it reports disconnected: true whether or not anything was still connected, so it cannot tell you a Page was already gone.

social_disconnect_social_account

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

Returns one social post in full by its uploadId: its schedule, its destination account, and the caption, title and platform options it will publish with, under content. This is the read to do before updating or cancelling a post — it is how you show the user what is there now and confirm the change they want. Read editable, mediaEditable and cancellable rather than the status, and read them independently: they do not move together. editable is on for a scheduled or failed post. cancellable is on for a scheduled one, for one still rendering, and for a failed one that never went live, so a post can be cancellable but not editable. mediaEditable is the strictest: the video or images may only be swapped while a post is still scheduled. When all three are false the post is already out or mid-publish, and the user must edit or remove it on the platform itself. content shows the current values, for you to relay to the user before an edit. It is not the shape update_upload takes: it carries fields that tool does not accept, and a value it reports as null cannot be sent back. Send update_upload only the fields that are actually changing. It carries no preview image or video URL. Use get_upload_status instead when all you need is whether a publish finished; this tool is the full read. reasonCode and reason are set only for a failed post, and reason is Riverside-authored recovery text to relay, not the platform's. For an X thread, content.children holds the replies in order, each with its own id, and for LinkedIn content.comments holds the first comments in order. update_upload replaces either list wholesale, so send the whole thing back — anything left out is deleted. scheduledAt is null for an immediate publish, and is returned exactly as stored. postUrl links to the live post once it has published and is null before then; it is also null for TikTok, whose URL needs the account handle from get_connected_platforms (https://www.tiktok.com/@{handle}/video/{externalId}), and for Facebook, whose post ids are not addressable by URL. An unknown uploadId, one in another account, and one whose upload was cancelled all come back as the same authorization error, so a cancelled upload cannot be distinguished from one that never existed. Reads only and changes nothing.

social_get_upload

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. Each account also reports scopes, analyticsEnabled and, when analytics is off, analyticsDisabledReason and a message saying how to fix it. 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

Returns one export by id: its status, the edit and revision it renders, the compose settings, and the S3 keys of the output and its poster frame. `status` is PENDING, COMPLETED or FAILED — PENDING is not terminal, so keep polling; FAILED is terminal, and the render will not arrive. `s3Key` is null until the status is COMPLETED, and it is an S3 object key, not a URL — this tool returns no download link. An ID with no export is not an error: the result is `export: null`. Reads only and changes nothing.

exports_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

Reports how one published post is doing — views, likes, comments and shares — by its uploadId. Use it to answer "how did my post do?"; list_uploads finds the uploadId when the user does not have one. The numbers are collected on a schedule, not read live, so always relay asOf and never present them as current. Newly published posts are polled every half hour at first and less often as they age. hasData false means nothing has been collected for this post yet; say so rather than reporting zeros. A null metric means the platform reports no such number for this post type — null is not zero. frozen true means the numbers will never change again: X is polled for 5 days after publishing and then retired. reasonCode MISSING_ANALYTICS_SCOPE means the account was connected before analytics permissions were required, so no numbers can exist for any of its posts until the user reconnects it — offer connect_social_account rather than retrying. This is only detected when studioId is passed. granularity "total" gives one number per metric. "daily" adds series, one entry per day with that day's own numbers, already differenced — report them as given and do not add them up or subtract them from each other. A null day in the series is a day with no data, not a zero. Reads only and changes nothing.

social_get_upload_analytics

Returns the current outcome of one social publish started by upload_create, by its uploadId. This is the only way to learn whether a post actually published: upload_create returns as soon as the publish is accepted, long before the platform has it. status is PENDING, SCHEDULED, COMPLETED or FAILED. Branch on the terminal flag rather than on the status: terminal means nothing further will change on its own. PENDING (still rendering, or being uploaded) and SCHEDULED (queued for scheduledAt) are not terminal. COMPLETED is. FAILED is terminal except in one case — a FAILED upload with reasonCode PLATFORM_CONNECTION_EXPIRED and a scheduledAt returns terminal false, because reconnecting the account can bring that post back; its reason says whether that happens on its own or only if the user accepts a prompt. Treat a post as live only when status is COMPLETED; do not infer it from externalId, which is the platform's own post id and can appear before the whole upload finishes. reasonCode and reason are set only when FAILED, and reason is Riverside-authored recovery text to relay, not the platform's. scheduledAt is null for an immediate publish. This tool returns no post URL and cannot construct one. platform is UPPER_SNAKE_CASE (YOUTUBE, YOUTUBE_SHORTS, TIKTOK, INSTAGRAM, FACEBOOK, LINKEDIN, X); get_connected_platforms uses mixed case and has no Shorts entry, so correlate an account by stripping a _SHORTS suffix and comparing case-insensitively. An unknown uploadId, one in another account, and one whose upload was cancelled all come back as the same authorization error, so a cancelled upload cannot be distinguished from one that never existed. Read access is not simply per-user: an upload this server created carries no production, so any user in its account can read it, while an upload created in the Riverside web app may be scoped to a production and is then readable only by users assigned to that production — an upload in your own account can still be denied. This tool only reads. A SCHEDULED or FAILED upload can be changed with update_upload, but only one that has not gone out yet can be stopped with cancel_upload, which also removes a FAILED upload that never went live — read get_upload and branch on its cancellable flag rather than on the status, since a FAILED upload that went partly live is editable but not cancellable. A COMPLETED one is neither, and an unpublish or delete is not possible through this MCP at all. A PENDING publish has no retry path and must be left to resolve, though one that has not started uploading yet can still be cancelled — get_upload's cancellable flag is what says which. A FAILED one can be rescheduled or republished in place from the Riverside web app, whatever its reasonCode, so before publishing again read this status once more and confirm the original is still FAILED. Reads only and changes nothing.

social_get_upload_status

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; that tool has no duration-range parameter. 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. When the user requests a duration, include durationRange in the matching CLIP or TAKE filter before pagination, with inclusive min, max, or both in seconds. A range applies to each matching entity, not the total duration of the results; PROJECT does not support a non-null range. Keep field and value present, using null when unused, and preserve requested project/production scope. Results expose compact public fields, identifiers, and short transcript fragments in highlights.transcription, with no word timestamps and no full transcript. Result duration values retain their source units: CLIP milliseconds and TAKE seconds. 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. Global search locates a TAKE result. To edit it, call editing_create_edit_from_recording(sessionId, projectId, title) to create a new editable timeline, 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. Repeat the same search term and filters, including durationRange and scope selectors, while paging. Filtering only the first page locally is incomplete. 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-library asset (sourceType=media, the default), or a completed recording session (sourceType=recording), as timeline content 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. For recording sources, assetId is the session ID from platform_get_recording.id, not an individual recording track ID or an edit/clip ID. Inserts all synchronized participant/content tracks from sourceStartMs for durationMs (default: the remaining raw session). Requires source read access and target edit write access. Live/in-progress recordings and importing edited clips with cuts/layouts/overlays are not supported. Recording results return sourceType, insertedRecordings, durationMs and saved revision; there is no single sceneId/clipId for a multi-track recording.

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

Search the media library of one production: the files the user sees in the editor's "Your Media" panel — their own uploads and AI-generated media. Stock, imported and shared library media are not listed. Use it when the user refers to a file by name ("the B-roll image of the letterboard") to get that file's media id, which the editing tools need in order to place it on the timeline. Pass search to match part of a file name, or omit it to browse newest first. Only media that finished processing and is ready to place is listed — to check on a file you just uploaded, call get_media with its id. Returns 20 items per page, with the total and the next page number when more exist.

media_list_media

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