# Recorder agent skill (subclip-recorder)

Edit a saved Subclip Recorder screen recording, including source clips, captions, speech context, callouts, zooms, webcam layout, appearance, audio, and reset. Use for the Recorder workspace.

Canonical URL: https://www.subclip.app/agent-skills/subclip-recorder

Raw SKILL.md: https://www.subclip.app/agent-skills/subclip-recorder/SKILL.md

Source: https://github.com/subclip-app/subclip-skills/tree/main/skills/subclip-recorder

## Install this skill

```sh
npx -y @subclip/skills install --only subclip-recorder
```

Install all skills with `npx @subclip/skills install`. The skills call tools that the Subclip app serves over its local MCP server. Open the app, go to Desktop settings > Connect AI client, and add the server to your agent. The app must be running while the agent works.

## Full SKILL.md

```markdown
---
name: subclip-recorder
description: Edit a saved Subclip Recorder screen recording, including source clips, captions, speech context, callouts, zooms, webcam layout, appearance, audio, and reset. Use for the Recorder workspace.
---
# Subclip Recorder

Starting a recording (`start_recording`):
- Always pass `name`: a short title of what is being recorded. Do not leave the default date and time name.
- Record one window with `windowId` (from `list_app_windows` or `open_app`). The window is recorded even while it is behind the creator's own app, and a hidden app is shown again without being brought to the front.
- Pass `systemAudio: true` when the recording should include the computer's sound (music, video audio; on Linux this is the system output, not per-app). It is off by default.
- Check the result: if it is an error (for example the capture source is not available), fix that before doing the steps. Do not carry on with nothing recording; `recording_status` shows phase `recording` when it is running.
- Clicks made through accessibility (`click_element`, `type_into`, `mouse_click` with `windowId`) are stored with the recording like real clicks, so click zoom follows them. Controls below the fold are scrolled into view first.
- `autoCallouts` is OFF by default. Turn it on (`autoCallouts: true`) only when the creator asks for callouts. When on, each control you press through accessibility gets a liquid callout with 1.8x magnification on its exact rectangle: it appears just before the press and goes right after it. The callouts are normal annotations: adjust or remove them with `edit_recording_annotation`.
- Waiting time is cut only where the agent decides its next step (dead time between actions). Page loads and music playing are kept. Nothing is ever sped up, and nothing is cut when system audio is recorded.
- If you are blocked on something only the creator can do, leave the recording running, tell them what you need, and wait. Stop only when the task is done or they say so.
- To use a recording in an editor project, see `import_recording_to_project` (raw or edited, to the timeline or Project Media).

Recorder projects retain original capture media and source cursor telemetry. Recordings started by agents (`start_recording`, or `pick_recording_area` then `start_recording`) are saved in the same Recorder project list the creator uses: name them in your reply and find them again with `list_recordings`. For screen capture and desktop actions, see the `subclip-desktop-control` skill. Edits change a saved draft. Use the Recorder tools; the assistant conversation workspace is not an AI Editor timeline.

Attached image and file snapshots are listed in the agent's trusted request context. Inspect a referenced snapshot before interpreting phrases such as "this image" or "make it look like this." A reference image may describe a desired screen, annotation, or layout without requesting a file import. If the request explicitly asks to import attached media, first inspect it and report the Recorder tool limitation accurately rather than saying no attachment was provided.

An attached folder is a selective snapshot: caches, build output, and oversized files are skipped and listed with their read-only original paths in the snapshot's `subclip-folder-index.json`. Read only the files the request needs, open a skipped original only when the request depends on it, and never treat a skipped entry as a missing attachment.

Discover schemas with `mcp_editor__list_tools` using `domain: "recorder"` and `includeSchemas: true`. Invoke reads through `mcp_editor__call_read_tool` and edits through `mcp_editor__call_tool`. External MCP clients may expose the named tools directly.

- `list_recordings`: discover exact IDs for saved recordings owned by the signed-in user.
- `get_recording`: inspect the exact recording, draft, source duration, output duration, clips, and revision. A Recorder assistant is bound to its recording; external clients supply `recordingId`.
- `get_recording_context`: read the live output-timeline playhead, selected item IDs, and active clip, zooms, camera layouts, motions, and annotations. Use for "here", "this clip", or "where I am" requests; it reports no playhead when the recording is closed.
- `get_recording_annotation_types`: inspect the full Recorder annotation catalog before choosing between text, shapes, highlighter, spotlight, blur, magnifier, and the real Callout kind.
- `capture_recording_frame`: inspect a PNG at an output timeline time. Choose `canvas` for the composed frame, `screen` for the original screen, or `webcam` for the source camera. Set `save=true` to save a screenshot PNG. Canvas capture requires the recording to be open in Recorder.
- `export_recording`: render a saved recording to an MP4 file (default folder Documents/Subclip Exports). It exports the recording as captured, with its crop. Edits made with `edit_recording_clip` (split, trim, speed, delete) are not applied to this file.
- `edit_recording_clip`: split, copy, move, trim, change speed, or delete a screen clip. Work part by part: split at the time, edit each clip, then re-read with `get_recording` before the next edit.
- `capture_recording_frame` with `target: "screen"`: the raw screen frame at any time, saved with `save: true` to Pictures/Subclip Recorder. `target: "canvas"` needs the recording open in the Recorder window.
- `get_recording_clicks`: read click times and positions for a bounded output timeline range. Click data has no control names; inspect nearby frames before labeling a clicked control.
- `add_recording_callout_cards`: create an actual `kind=callout` annotation near each exact recorded click. Supply `targetDescription`, an explicit normalized `region` (`x`, `y`, `width`, `height`), `startOffsetSeconds`, and `durationSeconds`. A negative offset shows a visible target before the click; a positive offset waits for a resulting panel. Choose both timing values from inspected frames so viewers can recognize and read the target. The tool supplies no fixed timing or region. Optional text creates a separate `kind=text` glass label.
- `edit_recording_clip`: split, copy to the nearest timeline clip boundary, move by insertion index, trim or expand an edge, change playback rate, or delete. Copy includes the clip's overlapping zooms, camera layouts, 3D motion, and annotations. Copy at zero makes a teaser. Split around the desired source section first, then copy that clip. Pasting never implicitly splits the destination clip. Clip IDs come from the current read.
- `update_recording`: submit the complete draft returned by the read, preserving unrelated fields. Change only the settings requested. The optional name renames the recording.
- `reset_recording`: restore default edits only when requested. Original media and cursor telemetry are retained.
- `set_recording_screen`: change canvas aspect, background, screen frame, border, shadow, position, flips, and static tilt.
- `crop_recording_screen`: set screen crop edges and aspect. Supply only changed edges.
- `set_recording_camera`: change camera layout, visibility, crop, position, size, shape, frame, shadow, and source zoom.
- `set_recording_cursor`: change cursor visibility, size, style, click effect and sound, smoothing, motion, and fixed zoom.
- `set_recording_audio`: set per-track volume and mute values for screen, webcam, microphone, and system sound.
- `reset_recording_settings`: remove edits from just `screen`, `crop`, `camera`, `cursor`, or `audio` settings. This restores that section's defaults while preserving captured tracks, screen clips, click telemetry, and every other section. To remove a visible component instead, delete its screen clips, hide the camera/cursor, or mute audio using the corresponding edit tool.
- `set_recording_timeline`: adjust the global trim range or playback rate. Use `edit_recording_clip` for individual clip speed, split, copy/paste, reorder, trim/extend, and delete.
- `edit_recording_zoom`: add, update, or delete zooms; `scale` is magnification, `x`/`y` are normalized focus, and `mode` selects auto cursor follow or manual focus.
- `edit_recording_annotation`: add, update, trim, or delete callouts, highlighters, text, arrows, and other supported annotations. An add requires explicit start/end and normalized `x`, `y`, `width`, and `height` from inspected pixels; the tool rejects arbitrary default placement.
- `edit_recording_3d_motion`: add, update, or delete a timed tilt with a named preset (`left`, `right`, `up`, `down`, corner combinations, `none`, or `custom`).
- `edit_recording_camera_layout`: add, update, or delete a timed camera layout and its visibility, position, size, flip, or roundness.
- `transcribe_recording`: reuse existing captions or a saved transcript before speech recognition. Call only if `get_recording_transcript` reports that neither exists. Use `purpose=reference` for understanding, summaries, cut decisions, and auto-focus planning; it leaves visible captions unchanged. Use `purpose=captions` only when visible subtitles are requested, with the latest revision. The recording must be open for new speech recognition.
- `get_recording_transcript`: first choice for speech understanding on every prompt. Read or search existing captions or the saved reference transcript in edited timeline time. It follows trimmed, copied, sped-up, and reordered source clips. Read in bounded pages with `offset` and `limit`; never retranscribe just because a new assistant prompt started.
- `list_recording_caption_presets`: read the available caption preset IDs before selecting a style.
- `get_recording_captions`: read paginated sentences, exact `pageIndex` and `wordId` values, the current style, and the latest revision. Search by sentence text when needed.
- `edit_recording_captions`: use `apply-preset` with a listed `presetId`; `update-style` for shared typography, color, animation, size, position, or width; `update-word` for exact text, timing, priority, or `hidden`; `update-word-style` for one word's typography and colors; `delete-word` to remove one word; `update-sentence-style` for one page's style, animation, position, size, or width; `clear-sentence-style` to restore that sentence's previous styling; `set-sentence-visibility` to hide or restore all words in one page; or `delete-sentence` to remove the whole page. Use `wordId` for word actions and `pageIndex` for sentence actions. Read the current revision first and reread after structural edits because page indices can change.

Every mutation requires the latest `revision`. A stale revision means another edit occurred: reread and reconcile. Mutations save immediately and refresh the Recorder; the open Recorder keeps an undo entry for assistant changes.

## Speech, captions, and focus

Reference transcription is for understanding the recording. It must not create a visible caption track unless the creator asks for captions, subtitles, or on-screen speech text. Use timed words to identify likely moments, then inspect nearby screen/canvas frames and recorded clicks to decide where a zoom or highlight should focus. Speech alone does not establish screen coordinates. If a user describes a visual action, inspect frames on both sides of that moment and choose the actual visible target.

Dynamic captions are a separate top timeline layer. The Recorder uses the AI Editor's editable word/page caption style and preset controls. The default caption block is centered, near the bottom, and limited to 65% canvas width to leave room for webcam faces near the left and right edges. Keep that compact placement unless the creator requests a wider treatment or the text demonstrably does not fit. Style `position.x` and `position.y` are percentages of the canvas; `maxWidthPercent` controls text-block width. Per-word styles affect appearance and font size; position, scale, width, and sentence animation belong to a sentence or the shared style. Hide words or sentences when the creator wants them absent but recoverable; delete only when removal is requested. Place captions above the video controls in a captured browser or YouTube frame; inspect a composed frame before claiming the placement works. The user can drag the block and its width handle on the Recorder canvas. Captions imported to the AI Editor remain editable.

## Timing and annotations

`start`/`end` are timeline seconds; `sourceStart`/`sourceEnd` are original media seconds. A clip's timeline duration is `(sourceEnd - sourceStart) / playbackRate`. Reordering must preserve those source bounds. Use the clip tool so dependent effects ripple correctly.

Annotations use normalized source coordinates (`x`, `y`, `width`, `height` in 0-1), timeline start/end, hex color, opacity, and roundness. Supported kinds include `text`, `arrow`, `rectangle`, `spotlight`, `blur`, `magnifier`, `callout`, and `highlighter`. Add an annotation with a unique ID to `draft.annotations`. A useful highlighter starts with yellow `#ffe34d` and opacity `0.45`. Callouts support `marquee`, `marqueeColor`, `strokeWidth`, `scale`, `popup`, horizontal `tiltY`, and vertical `tiltX` in degrees. The marquee border uses output time, independently of clip speed.

The Recorder Annotations library groups `text` styles (plain, label, pill, glass, outline, badge), shapes (line, dashed line, arrow, rectangle, rounded rectangle, circle, ellipse, down arrow, pointer, highlighter), and masks (spotlight, blur, magnifier, Callout). A Callout magnifies a screen region while dimming outside it; it does not itself render a text caption. When the creator says "add a callout," create `kind=callout`. Add `kind=text` separately only if the creator also asks for words. Do not describe a text label as a Callout.

For a click-related Callout or highlighter, inspect raw screen frames just before and after the recorded click. Decide whether the creator means the clicked control or the panel revealed by the click. Read the returned frame dimensions, estimate the visible target's pixel rectangle, then normalize each edge to source-frame width and height. Include the whole relevant control or panel with a small margin; never use a fixed-size rectangle centered on the click. A Callout's `scale` enlarges the chosen region in the composed canvas. If a Callout already exists at that click and the creator is correcting it, update its rectangle through `edit_recording_annotation` rather than adding a duplicate. Re-read the saved annotation and inspect a composed frame during it; if the target is clipped or the region includes unrelated UI, update the rectangle before reporting completion. The default Callout tilt is the first preset, None (`tiltX=0`, `tiltY=0`).

Treat the click as a timing clue, not the whole display interval. Inspect screen frames on both sides of it and farther ahead until you can tell when the target first becomes relevant, when it appears or changes, and when the next action makes it stale. Choose a lead-in when the clicked control is already visible so viewers can locate it; if the intended target is a panel revealed by the click, begin when that panel becomes visible so the Callout does not magnify unrelated pre-click pixels. Hold through the meaningful result long enough to read, then end before unrelated content or the next edit. Choose `startOffsetSeconds` and `durationSeconds` from that sequence; do not reuse a fixed short duration for every click. When correcting an existing Callout, update its start and end as well as its region instead of adding a duplicate. Verify composed frames near the start, middle, and end of the interval, plus a frame after it ends.

Cursor samples returned in the draft are empty to keep context small; the host preserves the original samples on save. Source files must not be rewritten. After edits, verify the returned timings, source bounds, requested settings, and duration. Describe visual review only if a frame was actually inspected. Export remains available in the Recorder UI.

## Observing and scripted takes

- `wait_for_recording` (until `recording`, `stopped` or `ready`): read-only; use it instead of polling `recording_status`, for example after `stop_recording` and before `get_frames` or `export_recording`.
- `get_frames`: up to 8 frames of a take in one call, from the saved edit (never from an exported file, so never stale); `savedAt` says when the edit was saved, and an export made before that time is out of date.
- `set_pointer_track`: for takes made by a script (Playwright, CDP) that never moves the real pointer, give `points` `{at, x, y, click}` (x and y are fractions 0-1 of the recorded surface). Subclip glides the pointer between points, stores it like real cursor data and plans the click zooms. It is also the route for agent takes where the real pointer cannot be read (Wayland).
- `list_recording_devices`: the cameras and microphones this computer offers (id, name, `preferred`). An empty list means that kind is not connected: record without it. Pass an id to `start_recording` as `cameraId` or `microphoneId`, or `"default"` for the creator's remembered choice. Call it before every take that should have a webcam or a chosen microphone.
- `propose_idle_cuts` then `apply_idle_cuts`: the preview is read-only and returns the ranges and the time saved. Apply only with the `revision` from that preview and `confirm: true`. Cursor data has no keyboard, so silent typing can look idle: review the ranges first. Undo with `undo_idle_cuts` while the recording is unchanged.
- `export_recording_status`: state of an export started with `export_recording` (rendering, ready with the path, or error with the reason). Poll every 10 seconds while rendering, and use the path only when it says ready.
- `get_recording_contact_sheet`: one image (or a few) with many labelled frames of the EDITED timeline, like the video editor's contact sheet. Pick moments with `count` (evenly spread), `everySeconds` or `timesSeconds`. Tiles show `#index m:ss.s fFRAME`, a CLICK badge near a recorded click and a ZOOM badge inside a zoom; the reply lists each tile's time. Use it first to review a take, then `capture_recording_frame` or `get_frames` for the moments that matter.

## Running the recorder from tools, like a person

- `open_recorder` (mode studio or quick): opens the floating bar. `start_recording` starts a take (give `quick: true` for a share-link recording). `pause_recording` and `resume_recording` pause and resume.
- `stop_recording` with `showShare: true` stops the way the creator's stop button does: a Quick recording opens its share window, a Studio take opens in the Recorder editor. Without it the stop is the agent's and nothing opens.
- `get_share_link`: for a Quick recording, the link (`url`), upload progress and size. Poll it after the stop until `url` appears. Never read the link off a screenshot.
- Do every step with these tools. Do not click the bar by screen coordinates and do not drive anything over ssh.
```