---
name: clipmaster
description: How to drive ClipMaster through its MCP connector — turning long videos into posted clips, editing clips (captions, emojis, GIFs, stickers, reaction memes, sound effects, zooms, speed, logo), building compilations, rendering exports and scheduling YouTube posts. Use this skill whenever ClipMaster tools are connected (list_projects, list_clips, ingest_youtube, get_compilation…) or the user mentions ClipMaster, clipping a video or podcast, YouTube Shorts / Reels / TikTok clips from long footage, highlight reels, compilations, captions on clips, or scheduling clips — even if they don't name ClipMaster.
---

# ClipMaster

ClipMaster takes long footage and returns finished, scheduled posts. Its AI watches
every frame as well as the audio and transcript, so it finds moments where nobody is
talking (concerts, sports, cooking, silent screen recordings) that transcript-only
tools miss. The work happens in five stages:

1. **Find**: import a video, and the AI returns ranked clips with a hook line, clip type, topic and confidence.
2. **Finish**: trim, captions (15 styles, karaoke, word-by-word fixes, second-language line), emojis, GIFs, stickers, reaction memes, sound effects, zooms, screen effects, speed, logo, progress bar, vertical framing.
3. **Assemble**: compilations built from clips across the whole library, cut by the AI or scene by scene.
4. **Ship**: render exports, then schedule them to a connected YouTube channel with AI-drafted titles.
5. **Automate**: everything below, from chat.

## Connecting

The tools come from the hosted connector at `https://api.clipmaster.app/mcp`. It needs
a paid ClipMaster plan and a one-time approval in the browser.

- **Claude Code:** `claude mcp add --transport http clipmaster https://api.clipmaster.app/mcp`
- **Claude.ai / Claude Desktop:** Settings → Connectors → Add custom connector → paste the URL.

If the tools are missing, tell the user this instead of guessing at them. Setup guide:
https://clipmaster.app/docs/mcp

## Ground rules

These are the mistakes that cost the user money or work, so follow them every time.

**Tokens are real money.** 1 token = 1 minute of video. These spend tokens, priced by length:
`ingest_youtube`, `start_video_upload`, `trigger_export`, `export_compilation`,
`translate_clip_captions` (only for a language the clip doesn't have yet), and
`add_media_scene` with an uploaded video. Before spending, check `get_token_balance`
(`balance.available`), say roughly what it will cost, and get a yes when the amount is
non-trivial or the user didn't clearly ask for it. Suggestions, Auto-edit, layout analysis and
audio measurement spend no tokens; they're paid-plan features instead. Reading the analysis is free.

**Long jobs run in the background, so poll.** Processing a video takes minutes. Exports,
`auto_edit_clip`, `analyze_clip_layout`, `measure_clip_audio` and `transcribe_*` also run in
the background. Poll the matching status tool every 15–30 seconds, not in a tight loop, and
tell the user what's happening between checks. For the three clip analyses that's
`get_clip_analysis`, whose `analyses.layout` / `.audio_cues` / `.auto_edit` `status` turns
`completed` or `failed`. A 409 usually means a job is already running (or, for the layout and
audio, that the result is already current): re-read before retrying.

**Edits are read → change → write back the whole object.**
- `update_clip_settings`: start from `get_clip_settings` and send everything back. **Any key
  left out is cleared** (captions, emojis, gifs, sfx, zoom, framing, logo…).
- `update_clip_captions`: same, starting from `get_clip_captions`.
- `replace_compilation_plan`: start from `get_compilation`'s `arrangement_metadata.edit_plan`.
  Music left out is dropped; captions, emojis, GIFs and screen effects left out are kept
  (send `[]` to clear).
- Only to **add** overlays, use `add_clip_overlays` / `add_compilation_overlays`. They don't
  need a read and they can't wipe anything.

**Two clocks on a clip.** `add_clip_overlays`, every `suggest_clip_*` tool,
`get_clip_moments` and `get_clip_analysis` use the **viewer's time** (seconds from the scene's
start). The clip plays from 0 to `time.duration`; anything earlier or later is the padding
around the scene, where overlays can't go. Pass suggestions in exactly as they came.
`get_clip_moments` lists only what plays, so each `t` there can be placed as is;
`get_clip_analysis` still shows the padding, so place only its times between 0 and
`time.duration`. `get_video_analysis` is on video time instead
(seconds from the start of the upload). Times inside `update_clip_settings` are **stored
time** = viewer time + padding (`features.original_start_time − features.padded_start_time`
from `get_clip`). Prefer `add_clip_overlays` for anything new, so you never do that sum.

**Ask before anything destructive or public.** The tools that delete or replace are the
deletes, `arrange_compilation` (rebuilds the scenes from scratch), `replace_compilation_plan`,
`transcribe_clip` / `transcribe_video` (replace edited words), `reset_compilation_to_plain_cut`,
the `remove_*` tools, `cancel_scheduled_post` and the `set_*_from_upload` tools. Confirm with
the user before calling them. Before deleting a compilation, run `preview_compilation_deletion`.
`schedule_post` is **public by default**: say so, and offer unlisted/private.

**Paid features refuse on free plans.** A `subscription_required` answer means the feature needs
an upgrade. Tell the user it's a paid feature and that they can upgrade at clipmaster.app/pricing.
Don't retry and don't hunt for a workaround.

**What only the web app can do**: buying tokens or changing the plan, connecting a social
channel, watching a clip (send the `open_in_app` link from `list_clips`, since a preview render
would spend tokens), picking a per-shot vertical layout template, and uploading a file from a
**web chat** (claude.ai can't send files to another service). Point the user to
https://clipmaster.app for these rather than attempting them.

## Workflows

### 1. Get a video in

- **YouTube link:** `ingest_youtube`. It's a paid feature; free plans upload the file instead.
  Useful options: `user_query` ("only the pricing moments"), `min_duration`, `orientation`,
  `include_captions` / `karaoke_captions` / `karaoke_color`, `processing_mode`,
  `gemini_analysis`, and `compilation_format` / `compilation_prompt` to get a compilation
  built at the end. Restyle captions per clip afterwards.
- **File on this computer** (Claude Code / Desktop only; it needs a shell):
  1. Get the size in bytes, `shasum -a 256 <file>` and the duration from
     `ffprobe -v error -show_entries format=duration -of csv=p=0 <file>`. Never guess the
     sha256: it identifies the file.
  2. Call `start_video_upload`, then run the `upload_command` it returns, as given.
  3. Call `finish_video_upload`.
- Then poll `get_status` until `completed` (or `failed`, whose message says why). Use
  `get_project_steps` to see what's running now.

### 2. Pick the clips

`list_projects` → `list_clips` (name, time range, hook line, clip type, confidence,
`scene_id`, `open_in_app`) → `get_clip` for the scene's description, hook, score, badge and
virality, and `get_clip_analysis` for its words (with speakers) and everything else. When the
user asks for "the best ones", rank by hook strength and confidence, say why each one made the
cut, and suggest posting a few strong clips rather than all of them. `get_project_scenes` /
`get_project_timeline` show everything the AI found, including moments that didn't become clips;
`get_video_analysis` gives the whole video's transcript with speakers, tagged sounds, scored
visual moments and talk scenes (add `words` to `include` only when you need every word).

### 3. Finish a clip

**Read before you place.** Before putting a zoom, effect, sticker or sound on a time yourself
("on the laugh", "at every cut", "on the beat"), call `get_clip_moments`: one time-sorted list of
`{t, kind, …}` — `cut`, `shot`, `faces`, `speaker`, `sound` (laughter, applause, music), `loud`,
`quiet`, `beat`, `singing` and the vision pass's scored `moment`s with descriptions. Every `t` is
inside the clip as it plays, so it goes to `add_clip_overlays` as is. Never guess a
second. Its `available` and `analyses` say what hasn't run, and what runs it; `stale` names a
layout or audio analysis that no longer matches the clip (left out of the list — run it again):
- no faces or layout → `analyze_clip_layout` (paid, no tokens)
- no audio cues → `measure_clip_audio` (paid, no tokens)
- want a whole edit planned → `auto_edit_clip` (paid, no tokens)

Then poll `get_clip_analysis` and read the moments again. `get_clip_analysis` is the full
version (face boxes and panels per frame, every word, the scene's evidence); use `include` to
keep it small.

| The user wants | Do this |
|---|---|
| Trim | `update_scene_boundaries` (the clip's `scene_id`, new `start_time` / `end_time` in the source video's seconds) |
| Caption style, position, colours, karaoke, uppercase | `list_caption_styles` → `update_clip_settings` (`captions`) |
| Fix or highlight a word | `get_clip_captions` → `update_clip_captions` |
| Second caption line in another language | `list_clip_translations` → `translate_clip_captions` → set `captions.secondary` with `update_clip_settings` |
| "Edit it for me" | `auto_edit_clip` → poll `get_clip_analysis` (`include: ["auto_edit"]`) until `analyses.auto_edit.status` is `completed` → pass the `auto_edit` section's pieces to `add_clip_overlays` as they came (`auto_edit.speed` goes in as `speed_ranges`); if `auto_edit.current` is false, the clip was trimmed or re-cut since, so run it again first |
| Effects on what happens ("zoom on the laughs", "a whoosh at each cut") | `get_clip_moments` (cuts need `analyze_clip_layout` first when `available.layout` is false) → `add_clip_overlays` at each entry's `t`, as is |
| Emojis, GIFs, stickers, sounds, zooms, screen effects, reaction memes where they fit | the matching `suggest_clip_*` tool → `add_clip_overlays` |
| A specific one ("🔥 at 12 s", "mind-blown GIF at 8 s", "whoosh at 3 s") | `search_gifs` / `search_stickers` / `search_reaction_clips` / `list_sound_effects` → `add_clip_overlays` |
| Speed | `suggest_clip_speed_ranges`, or `update_clip_settings` (`speed` 0.25–4 for the whole clip; `speedRanges` `{start, end, speed}` win inside them) |
| Square / landscape | `update_clip_settings` (`orientation`) |
| Show the whole frame, no crop | `update_clip_settings` (`framing: {"choice": "fit", "segments": []}`); anything else in `framing` stays as read |
| Stickers that follow a face, face zooms | paid; `get_clip` → `layout_summary.can_follow_faces` must be true (run `analyze_clip_layout` first if not) |
| Logo | `start_file_upload` → `set_clip_logo_from_upload` / `set_brand_logo_from_upload`; position, size and opacity via `update_clip_settings` (`logo`) |
| Move or remove an overlay | `update_clip_settings`, or `remove_clip_stickers` / `remove_clip_reaction_clips` |

Limits per clip: 5 GIFs, 5 stickers, 5 reaction clips and 10 sound effects. A reaction clip on
a single clip pauses the video, plays full screen with its sound, then the video carries on, so
the export gets longer by the reaction clip's length.

### 4. Export and post

1. `trigger_export` → poll `get_export_status` until it carries the download link.
2. `list_social_accounts`. With no account connected, the user connects YouTube in the web app.
3. `suggest_post_metadata` for the title, description and hashtags. Show them to the user.
4. `schedule_post` with `clip_id` + `export_id` (or `compilation_id` + `compilation_export_id`).
   `scheduled_at` is ISO-8601 **UTC**, at least 10 minutes ahead, so convert from the user's
   time zone and say both times back. Privacy defaults to public.
5. `list_scheduled_posts`, `update_scheduled_post` and `cancel_scheduled_post` manage the calendar.

### 5. Compilations

A compilation is one video built from several clips (from any of the user's videos), played as
a **plan of scenes** in order. Scene ids are text (`"3"`, `"added-2"`).

**Build it**
- From a description: `suggest_compilation_bundles` ("a 45-second reel of the funniest
  moments") → `create_compilation_from_suggestion`.
- By hand: `create_compilation` → `list_available_clips` / `suggest_compilation_clips` →
  `add_clip_to_compilation`.
- Output size: `update_compilation` (`output`, e.g. 1080×1920 for Shorts/Reels).

**Cut it**
- `arrange_compilation` lets the AI cut it. `format`: `custom` (a montage from your `prompt`,
  required), `best_of`, `countdown`, `trailer`, `hook_loop`, `tutorial`, `qa_highlights`, `auto`.
  `effects` toggles transitions, speed and split screens. It **rebuilds every scene**, so confirm
  first if the user has hand edits.
- `regenerate_compilation_scene` re-cuts one scene. `place_added_clips` fits newly added clips
  in without touching the rest.
- `set_scene_beat_pattern` gives one scene a beat pattern (`peak_stutter`, `stutter`, `quick_stutter`,
  `build_up`, `jump_cut`, `teaser`): short muted repeats of its clip on the music's beats, right
  before it. The repeats are scenes of their own (`beat_part_of`); leave them alone and change the
  pattern on the scene that carries `beat_pattern`. Needs measured music: on 409
  `music_not_measured`, wait a minute and retry. `auto_edit_compilation` also moves hard cuts onto
  the beat by itself.
- `undo_compilation_edit` goes back to before the last arrange / place / reset (call it again to
  redo). `reset_compilation_to_plain_cut` plays every clip whole, in order.

**Refine it** with `replace_compilation_plan` (read-modify-write): order, trims
(`start_offset_sec` / `end_offset_sec`), `speed` and `speed_ranges` per source, `audio` (mute a
clip), `clip_effects` (true plays the clip's own GIFs, emojis, sounds and zooms on that pane; off by
default, so keep what each source came with), `transition_in`, `text` cards (`suggest_scene_text`), music, and the **split** layout of
a scene:

| Split | Panes |
|---|---|
| `full` | 1 |
| `stack2` / `cols2` | 2 (top/bottom, side by side) |
| `stack3` / `cols3` | 3 |
| `pip` | 2 (one small over the other) |

A clip keeps its own vertical **view** (follow a face, screen + cam…) inside a full-screen scene.
In a split pane it plays as one simple framing instead. A split lasts as long as its longest clip;
one that ends earlier shrinks away while the others grow into its space, over the scene's
`pane_exit_ms` (0-1000, 0 is instant, default 400).

**Dress it up**
- "Edit it for me": `auto_edit_compilation` fills what the edit leaves empty (how each scene
  arrives, text cards with their font, size and place, a library track, speed ranges on clips
  at normal speed, the progress bar) and applies zooms, screen effects, stickers, GIFs,
  floating emojis, sounds and up to 2 reaction-meme scenes in one write (10–40 s). Pass the
  creator's wish as `direction` ("hype energy, big bold text"); it is kept for the next run.
  Keep the returned `take`:
  pass it to `undo_compilation_auto_edit` to take exactly that back, or call again with
  `replace_take=take` for a different take. Its effects land on the edit's measured audio.
- "Party lights on the beat", "a flash on every hit": `get_compilation_audio` gives the edit's
  beat (the music's, `clock: "edit"`, else an audible clip's), loud moments and quiet stretches on
  the edit's own seconds. A party screen effect takes a beat's `first_beat`, `period` and `clock`
  as `beat_first`, `beat_period` and `beat_clock`. `measuring: true` → read it again shortly.
- Overlays across the edit: `suggest_compilation_emojis` / `_gifs` / `_stickers` →
  `add_compilation_overlays`, which also takes `zooms` and `sfx` (from `list_sound_effects`) on
  the edit's own seconds. An edit's zoom never follows a face, and a scene whose clip zooms itself
  plays the clip's zoom instead. Captions, and moving or removing zooms and sounds, go through
  `update_plan_overlays`.
- Music: `suggest_compilation_music` or `search_music` → `select_music_track` → put it in the
  plan's `music` with `replace_compilation_plan`.
- Voiceover: `start_file_upload` (shell needed) → `set_narration_from_upload`; then
  `update_narration_settings` (volume, ducking the clips under it) / `remove_narration`.

**Files as scenes: memes, evidence, screenshots** (`add_media_scene`, paid plans)
- A reaction meme after a scene: `search_reaction_clips` → `add_media_scene` with `klipy`
  (the item's id as `source_id`, its slug, title and `mp4.url`) and `after_scene_id`. It plays
  whole up to 6 s, otherwise its first 6 s. Free.
- The user's own image or video: `start_file_upload` (purpose `scene_image`: PNG/JPEG/WebP under
  10 MB; `scene_video`: H.264/VP8/VP9 MP4, MOV or WebM, ≤1080p, ≤10 min, under 200 MB) → run the
  command → `add_media_scene` with `upload_key`. An image plays 3 s by default; uploaded video is
  billed like footage.
- **Proof beside the explanation**: `add_media_scene` with `into_scene_id` puts the file in that
  scene as one more pane (a split), while the person keeps talking. It's muted when the scene
  already has sound, and an image lasts as long as the scene. A 409 means the scene is full,
  unknown, or at its pane limit.

**Render**: `export_compilation` → poll `get_compilation_export_status`.

## Tool index

- **Videos:** `ingest_youtube`, `start_video_upload`, `finish_video_upload`, `list_projects`, `get_status`, `get_project_steps`, `get_project_scenes`, `get_project_timeline`, `get_video_analysis`, `transcribe_video`, `delete_project`
- **Clip analysis:** `get_clip_moments`, `get_clip_analysis`, `analyze_clip_layout`, `measure_clip_audio`
- **Clips:** `list_clips`, `get_clip`, `rename_clip`, `get_clip_settings`, `update_clip_settings`, `add_clip_overlays`, `get_clip_captions`, `update_clip_captions`, `update_scene_boundaries`, `transcribe_clip`, `list_clip_translations`, `translate_clip_captions`, `auto_edit_clip`
- **Clip suggestions:** `suggest_clip_gifs`, `suggest_clip_emojis`, `suggest_clip_stickers`, `suggest_clip_reaction_clips`, `suggest_clip_sfx`, `suggest_clip_effects`, `suggest_clip_speed_ranges`
- **Clip removals and logo:** `remove_clip_stickers`, `remove_clip_reaction_clips`, `remove_clip_logo`, `set_clip_logo_from_upload`
- **Exports:** `trigger_export`, `get_export_status`, `list_exports`
- **Compilations:** `list_compilations`, `get_compilation`, `create_compilation`, `update_compilation`, `delete_compilation`, `preview_compilation_deletion`, `list_available_clips`, `add_clip_to_compilation`, `remove_clip_from_compilation`, `suggest_compilation_bundles`, `create_compilation_from_suggestion`
- **Compilation editing:** `arrange_compilation`, `regenerate_compilation_scene`, `set_scene_beat_pattern`, `place_added_clips`, `replace_compilation_plan`, `update_plan_overlays`, `add_compilation_overlays`, `reset_compilation_to_plain_cut`, `undo_compilation_edit`, `auto_edit_compilation`, `undo_compilation_auto_edit`, `get_compilation_audio`, `add_media_scene`, `remove_compilation_stickers`
- **Compilation suggestions:** `suggest_compilation_clips`, `suggest_compilation_music`, `suggest_compilation_gifs`, `suggest_compilation_emojis`, `suggest_compilation_stickers`, `suggest_scene_text`
- **Narration:** `set_narration_from_upload`, `update_narration_settings`, `remove_narration`
- **Compilation exports:** `export_compilation`, `list_compilation_exports`, `get_compilation_export_status`
- **Posting:** `list_social_accounts`, `disconnect_social_account`, `suggest_post_metadata`, `schedule_post`, `list_scheduled_posts`, `update_scheduled_post`, `cancel_scheduled_post`
- **Library:** `list_caption_styles`, `get_caption_style`, `list_sound_effects`, `search_gifs`, `trending_gifs`, `search_stickers`, `trending_stickers`, `search_reaction_clips`, `trending_reaction_clips`, `search_music`, `select_music_track`
- **Account and files:** `get_user_settings`, `get_token_balance`, `start_file_upload`, `set_brand_logo_from_upload`, `remove_brand_logo`

Every tool's own schema lists its exact fields. When this file and a tool's description
disagree, the tool is newer, so trust it.