# Media Editing agent skill (subclip-media-editing)

Add, place, trim, resize, crop, rotate, layer, and visually arrange video or image assets through Subclip MediaPanel, MediaLayer, CanvasInteraction, and UnifiedTimeline. Use when a request mentions video clips, images, B-roll, overlays, thumbnails, crop, fill, fit, scale, opacity, or visual media.

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

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

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

## Install this skill

```sh
npx -y @subclip/skills install --only subclip-media-editing
```

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-media-editing
description: Add, place, trim, resize, crop, rotate, layer, and visually arrange video or image assets through Subclip MediaPanel, MediaLayer, CanvasInteraction, and UnifiedTimeline. Use when a request mentions video clips, images, B-roll, overlays, thumbnails, crop, fill, fit, scale, opacity, or visual media.
---

# Subclip Media Editing

For cloud background removal of an existing MediaPanel image or video, route to `$subclip-background-removal`. Do not approximate that request with opacity, masking, generic generation, or an ordinary color-key effect on the unchanged source.

1. Call `list_editor_assets` and choose a `mediaFiles[].id`. Never guess IDs.
2. If the requested file is a supplied assistant attachment, call `import_attachment_to_timeline` with its exact path. For a video represented by `.subclip-video-context`, use the `originalPath` in `video-context.json`. Do not ask for a second MediaPanel import. If direct native import fails, call `import_attachment_clip_with_ffmpeg` once with the requested source in/out. When the undecodable original item is already placed, pass its ID as `replaceItemId`; this swaps the source in place instead of adding a duplicate black layer. The tool returns a background `jobId`; store it and end the in-app agent turn without polling. Subclip resumes the same conversation on completion, cancellation, or error. Never start another conversion merely because it is queued/running. External MCP clients may use `get_media_import_status`. The fallback preserves a full compatible source and applies those values as a native trim, so the user can extend the item later.
   - A saved Recorder recording: call `list_recordings` (from the editor, it lists the saved recordings with their ids, names and durations), then `import_recording_to_project` with that `recordingId`. The edited version on the timeline imports exactly as the Recorder's "Import to Timeline" does: callouts (including the liquid lens), zooms and effects stay editable as native tracks, so do not re-render it. The project must be open in the app for that; if the tool says so, ask the creator to open it. The raw version and Project Media imports are plain video files. Without `recordingId` it lists the saved recordings; with it, the recording is added to Project Media and (by default) the timeline. `version: "edited"` (default) is the finished recording with its cuts, speed changes and click zooms; `version: "raw"` is the untouched capture. `destination: "media"` adds it to Project Media only. Ask the creator which version they want when it is not clear.
   - A fresh screenshot: call `import_screenshot_to_project` (whole display, a display by id, or a region). The untouched PNG goes to Project Media and (by default) the timeline. Use `take_screenshot` instead when you only need to look at the screen.
   - Narration (text to speech): call `generate_speech` once per line, with `confirmed: true` when the creator asked for it, and `targetDurationSeconds` for the line's length. When it is completed (`get_ai_operation`), call `import_speech_to_timeline` with that `operationId` and the `startTime` (seconds) of the moment the line describes. Time each line to the event it talks about (for example a click), not to the start of the video. Never pass `targetDurationSeconds` for narration: it speeds the voice up to fit, which sounds rushed. Generate at `speed: 1`, read each clip's real length from `get_ai_operation`, and place the clips back to back (each starts when the previous one ends), so the narration is continuous. Write enough sentences to cover the whole timeline; do not leave silent gaps between short lines.
   - Audio levels: narration must sit clearly above the recording's audio. Measure both (ffmpeg volumedetect): set narration volume to about 1.8 and the system/recording audio to about 0.1, and check the difference is at least about 12 dB before delivering.
3. Call `place_editor_asset` with `kind: media` to create the timeline and canvas item. When no explicit position or container size is supplied, new imports use a full-canvas container at the top-left origin plus `cover`; switch to `contain` only when the user wants the entire source visible.
4. Use `set_media_framing` for contain/cover requests. `cover` places a full-canvas media box at the top-left origin and crops the source around its center; `contain` preserves the whole source.
5. For a tutorial/screen recording plus talking-head request, call `apply_screenstudio_layout` once with the exact two item IDs. Do not approximate this with separate raw path updates. The named tool atomically creates a rounded tutorial stage and a circular, muted, bottom-right presenter above it while preserving both items' existing timeline durations.
6. Keep the talking-head/presenter clip at its natural saved duration. A ScreenStudio-style layout does not imply that the presenter should continue through the tutorial, so never loop, repeat, or extend it to the tutorial end automatically. Use `set_media_loop_and_duration` only when the user explicitly asks to loop or extend that exact item; do not infer this from "ScreenStudio," "talking head," "presenter bubble," or picture-in-picture wording.
7. Use `adjust_media_transform` for position or container-size changes. Prefer `sizeMultiplier` plus an explicit anchor for relative requests such as "14% larger"; use `deltaX`/`deltaY` for nudges. Layout resizing must change `size.width/height` and keep `scale: 1` so the selection box, crop viewport, and visible pixels share one container. Reserve `scale` for an intentional animated visual transform, not ordinary canvas sizing. Do not use `update_editor_state` for ordinary transforms.
8. Plan compositing order before placement. Use `set_media_layer_order` to choose the native composition plane (`media`, `above-motion`, `above-text`, or `above-captions`) and put the main scene behind while picture-in-picture, logos, or B-roll overlays sit in front. Higher `zIndex` means visually in front within the selected plane and, while items overlap, the visually higher timeline lane; never rely on item-array order. Lane 0 is the top row. Sequential items that do not overlap must reuse the same compact lane--do not create a diagonal staircase or assign a new lane for every cut. Extra lanes are only for simultaneous layers.
9. Use `set_media_source_focus` for requests that move a subject inside an existing crop. Do not move the frame and do not use a broad state mutation for this common adjustment.
10. Use `add_media_keyframe` for position, editable container width/height, scale, rotation, opacity, crop focus, source zoom, shape roundness, and either the legacy blur/brightness/saturation values or an ordered `effects` snapshot inside one already-isolated timeline item. Use `add_media_effect`, `update_media_effect`, and `delete_media_effect` for the base Effects stack, selecting types from `list_element_catalog`. For a subject outline, add `outline` after `colorKey` or another effect that creates transparency; its controls are width, edge simplification, color, opacity, and outline-only. A simple move or resize needs a start point and a destination point; the destination automatically holds, so do not add a duplicate terminal keyframe. Add further points only for further changes. For a discrete layout scene such as a two-way split, call `apply_two_way_split_scene`: it must split both sources at the scene start and end before changing the canvas containers. Transform only the middle segments, keep the tutorial audible, keep the presenter muted, and leave the before/after segments unchanged. Do not keyframe a full-duration item into another layout because its canvas selection bounds and unrelated copies can diverge. Do not escape to a separate Remotion workspace merely because a pasted prompt mentions TSX.
11. Use `update_media_item` for the complete MediaPanel control surface: timeline/source trim, mute/volume, loop, playback speed, contain/cover, crop/focus, position, editable container size, rotation, scale, opacity/fades, roundness/shadow/border, visual effects, transition type and the same `animationSpeed` value shown in the UI, `layerPlacement`, lane, and z-order. Only pass fields the user asked to change. Use `set_all_video_audio` when a separate AudioPanel track is the master and all video items must be silent.
12. Use `trim_media_item` for non-destructive source trimming, extending an agent-trimmed clip, changing playback speed while preserving source timing, or restoring the whole original file. Pass `restoreFullSource: true` to expose the full source again. Never shorten or overwrite `mediaData.files[].duration`: it is the original-file ceiling that lets a person extend the clip later.
13. For "replace clip A with clip B," call `replace_media_item_source` with the exact target and source item IDs from `list_editor_assets`. This changes the target `fileId` atomically while preserving its timeline slot, framing, style, sound policy, lane, and z-order. When the new source is a completed Subclip AI operation that has not been imported yet, use `import_ai_operation_to_timeline` with its stable operation ID and the exact target `replaceItemId` instead; do not create a duplicate just to obtain a source item ID. These are checkpointed local edits, so an explicit replace request is sufficient authorization and must not be reported as blocked by a separate approval policy. Do not simulate replacement by renaming the item, copying trim metadata, or calling `update_media_item`, because that tool intentionally cannot change a source file. Re-read the target and inspect a frame inside its time range before claiming the replacement worked.

## Media processing boundary

- In renderer React/TypeScript and web workers, use the installed `mediabunny` package for metadata, demuxing, audio extraction, and WebCodecs-compatible processing. Do not add FFmpeg WASM.
- In Electron main-process tools or explicit shell workflows, use native FFmpeg/FFprobe. Subclip prefers an authorized environment/system executable and falls back to its bundled native binary; this is never WASM. Call `get_media_runtime` when diagnosing which runtime is active.
- Do not install system software automatically. If no native executable or bundled fallback is available, report the concrete check and offer the platform command (on macOS, `brew install ffmpeg`) for the user to run or approve.
- Compatibility imports are queued one at a time, hardware-accelerated when available, cached, and capped to a 1920px proxy. In-app agents should rely on the host's terminal callback instead of polling or emitting repetitive chat updates. External clients can respect the returned `retryAfterMs`. If the user stops or supersedes the work, call `cancel_media_import`.

Use normalized media coordinates: `position.x/y` use 0-1 and `size.width/height` are canvas fractions. Use `fitMode: contain` to show the full source and `cover` to fill a frame. Keep `opacity` within 0-1, `scale` around 1, and rotation in degrees.

For timing, maintain `startTime < endTime` and `0 <= sourceStartTime < sourceEndTime <= original file duration`. Source duration is `sourceEndTime - sourceStartTime`; timeline duration is that source duration divided by `playbackRate`. Do not confuse timeline `endTime` with the source out point. Use `split_timeline_item` for cuts and `delete_timeline_item` for removal. After placement or transforms, inspect representative frames with `view_current_frame`. Correct framing defects and inspect again before reporting completion.

`delete_timeline_item` removes only a placed clip and deliberately keeps its source in MediaPanel. When the user explicitly asks to remove media from the project library as well, call `list_editor_assets`, identify the exact `mediaFiles[].id` values, then call `delete_project_assets` with those IDs and `confirmed: true`. That operation also removes every linked timeline placement. Do not imitate it with `update_editor_state`, do not guess from filenames, and re-list assets to verify both the file IDs and returned linked item IDs are absent.

For looping overlays, inspect at least one frame after the overlay source's original `sourceEndTime`, not only near time zero. A visible selection rectangle is not proof that the media pixels rendered.

Never replace an existing source destructively when adding an overlay or B-roll would satisfy the request.
Prefer native, panel-editable media and canvas properties. Do not synthesize a coded background or HTML layer for an ordinary visual treatment; use canvas color plus native media/text layers so manual and agent editing remain interchangeable.

Large pasted prompts may describe a standalone Remotion source-code project. Inside Subclip, translate supported visual requirements into native editor layers and tools; do not imply that arbitrary TSX files, Remotion Studio, word alignment, or a new composition were created unless those artifacts actually exist. For ScreenStudio prompts, first identify which timeline item is the tutorial and which is the presenter, set a landscape canvas when requested, apply `apply_screenstudio_layout`, then inspect a composed frame.

## Folder montage selection

When a folder supplies many source videos, selection is a visual evidence task--not a filename task.

1. Inspect every relevant storyboard and its `video-context.json`; do not stop after the first plausible file.
2. For lifting or workout requests, choose moments where the load, exertion, and action are clearly identifiable. Prefer the strongest readable action over a dark or merely adjacent moment.
3. Reject near-black, obstructed, unreadable, duplicate, idle, transitional, or ambiguous samples. Storyboard extraction filters unusably dark and duplicate samples, but you must still judge the remaining pixels.
4. Use exact manifest timestamps for source trims. If the source is incompatible with native import, call `import_attachment_clip_with_ffmpeg` with that range; it retains the complete compatible source behind the native in/out points.
5. Inspect each chosen cut on the composed canvas. Replace any cut whose visible content does not match the requested action.

## Perspective tilt

Use `update_media_item` with optional `tiltX`, `tiltY`, and `tiltZ` fields in degrees, each from -88 to +88. X tilts vertically, Y tilts horizontally, and Z rotates in the image plane. These static appearance controls preserve existing animation and are editable under Perspective tilt in the layer settings. Use small angles for legibility; never add a back face or substitute a 3D model. Set all three to 0 to reset. For text overlays use update_text_item with the exact itemId; update_caption_style changes project-wide captions.

Keyframes: use `add_media_keyframe` for animated `tiltX`, `tiltY`, `tiltZ` (-88..88 degrees) and `scale` (multiplier). These values interpolate with the keyframe easing, preserve omitted settings, and remain editable in the keyframe UI.

## Tilt troubleshooting and scope

- Supply only finite numeric degrees for `tiltX` (vertical), `tiltY` (horizontal), and `tiltZ` (in-plane), within -88..88. Never send NaN, Infinity, or unit-suffixed strings.
- Reset with numeric zero on all three axes. Do not replace native layers with a 3D model.
- Use `add_media_keyframe` on the exact existing item ID and absolute project time to animate tilt and scale. Omitted tilt inherits the previous keyframe or base style; missing base tilt is zero. Keep existing scale unless the user requests a change.
- Changing base tilt alone will not override explicit tilt keyframes. Update the relevant keyframes instead. Older media keyframes need no recreation merely because they lack tilt fields; the sampler provides defaults.
- Distinguish saving settings from visually confirming the effect. Do not claim preview/export validation unless it was performed.
```