AgentAlley

Home · Skills

muapi-ai-clipping

Turn a long video into N viral-ready short clips with a single managed API call.

Paste into Claude, ChatGPT or Cursor.

Read the source194 lines
muapi-ai-clipping/SKILL.md194 lines6.7 KBpushed 100d agoRawView on GitHub
1---
2slug: muapi-ai-clipping
3name: muapi-ai-clipping
4version: "1.0.0"
5description: Turn a long video into N viral-ready short clips with a single managed API call. Wraps muapi.ai's `/ai-clipping` endpoint, which handles transcription, highlight ranking through a virality framework (hook / emotional peak / opinion bomb / revelation / conflict / quotable / story peak / practical value), overlap dedupe, and vertical face-tracking auto-crop server-side. No local Whisper, no local LLM, no GPU.
6acceptLicenseTerms: true
7---
8 
9# AI Clipping
10 
11**One API call: long video in → ranked vertical short clips out.**
12 
13Each clip ships with a viral score (0–100), an opening hook line, a one-sentence "why it works" reason, and a hosted mp4 URL.
14 
15Underlying API: https://muapi.ai/playground/ai-clipping
16Reference implementation (open source): https://github.com/SamurAIGPT/AI-Youtube-Shorts-Generator
17 
18---
19 
20## When to Use
21 
22- Auto-clip a podcast, interview, lecture, vlog, or stream into TikTok / Reels / Shorts.
23- Extract the best 30–75s moments from any hosted video URL.
24- Get face-tracked vertical (9:16), square (1:1), or portrait (4:5) crops without running ffmpeg locally.
25 
26If you only need raw timestamps for your own renderer, set `--coords-only` to skip cropping and just get the highlight ranges.
27 
28---
29 
30## Agent Execution Protocol
31 
32### Step 1 — Collect Inputs
33 
34| Input | Required | Default | Notes |
35|:---|:---|:---|:---|
36| `--video` | yes | — | Hosted mp4 URL, or local file path (auto-uploaded), or YouTube URL (if backend supports it) |
37| `--num-clips` | no | `3` | Number of highlights to extract |
38| `--aspect-ratio` | no | `9:16` | `9:16` \| `1:1` \| `4:5` |
39| `--coords-only` | no | off | Return just the highlight time ranges, skip cropping |
40 
41If the user gave only a video URL, run with defaults — don't block on questions.
42 
43---
44 
45### Step 2 — Verify Prerequisites
46 
47- `muapi-cli` installed and authed (`muapi auth configure`)
48- `MUAPI_API_KEY` available (env var or `muapi auth status` passes)
49 
50That's it. No `ffmpeg`, no Python, no Whisper install, no LLM keys. Everything runs server-side.
51 
52---
53 
54### Step 3 — Run the Skill
55 
56```bash
57bash library/edit/ai-clipping/scripts/run-ai-clipping.sh \
58 --video "https://example.com/podcast.mp4" \
59 --num-clips 5 \
60 --aspect-ratio 9:16 \
61 --view
62```
63 
64The script:
651. Resolves `--video` to a hosted URL (uploads local files via `muapi upload file` if needed).
662. Calls `muapi edit clipping` with the supported parameters.
673. Polls until the job is done (or returns the `request_id` immediately under `--async`).
684. Prints a ranked summary and, if `--output-json` is set, writes the full result.
69 
70---
71 
72## What Happens Server-Side
73 
74The `/ai-clipping` endpoint internally runs the full pipeline so the agent doesn't have to:
75 
76- **Transcribe** with Whisper.
77- **Classify content type** (podcast / interview / tutorial / vlog / lecture / monologue).
78- **Rank highlights** through the virality framework:
79 - **Hook moments** — strong opening line that stops the scroll
80 - **Emotional peaks** — laughter, anger, vulnerability, awe
81 - **Opinion bombs** — spicy, contrarian, debate-bait takes
82 - **Revelation moments** — "wait, what?" reframes
83 - **Conflict** — disagreement, tension, callouts
84 - **Quotable lines** — tight, screenshot-worthy phrasing
85 - **Story peaks** — climax of a narrative arc
86 - **Practical value** — actionable insight a viewer will save
87- **Dedupe** overlapping candidates by score.
88- **Top-N select** and **face-track auto-crop** to the requested aspect ratio.
89 
90This is why the skill is small: the heavy lifting is on the API.
91 
92---
93 
94## Quick Invocation Patterns
95 
96**Defaults — three 9:16 clips:**
97```bash
98bash run-ai-clipping.sh --video "https://example.com/long.mp4"
99```
100 
101**Podcast — more clips, view in player:**
102```bash
103bash run-ai-clipping.sh --video "<URL>" --num-clips 8 --view
104```
105 
106**Square clips for Instagram feed:**
107```bash
108bash run-ai-clipping.sh --video "<URL>" --aspect-ratio 1:1 --num-clips 3
109```
110 
111**Just the timestamps (build your own renderer):**
112```bash
113bash run-ai-clipping.sh --video "<URL>" --coords-only --output-json result.json
114```
115 
116**Async submit (returns request_id, poll later):**
117```bash
118REQUEST_ID=$(bash run-ai-clipping.sh --video "<URL>" --async --output-json - | jq -r '.request_id')
119muapi predict wait "$REQUEST_ID" --download ./outputs
120```
121 
122**Local file:**
123```bash
124bash run-ai-clipping.sh --video ./recording.mp4 --num-clips 5 --view
125```
126 
127**Batch — `urls.txt` with one URL per line:**
128```bash
129xargs -a urls.txt -I{} bash run-ai-clipping.sh --video "{}"
130```
131 
132---
133 
134## Aspect Ratio Picker
135 
136| Platform | Ratio | Sweet-spot duration |
137|:---|:---|:---|
138| TikTok / Reels / YouTube Shorts | `9:16` | 30–75s |
139| Instagram Feed | `1:1` | 15–45s |
140| Pinterest / portrait | `4:5` | 30–60s |
141 
142Default to `9:16` unless the platform is specified.
143 
144---
145 
146## Output Schema
147 
148```json
149{
150 "source_video_url": "...",
151 "shorts": [
152 {
153 "title": "The one mistake that cost me $50K",
154 "start_time": 124.3,
155 "end_time": 187.6,
156 "score": 92,
157 "hook_sentence": "Nobody talks about this, but it killed my first startup...",
158 "virality_reason": "Opens with a number + regret, peaks on a contrarian lesson",
159 "clip_url": "https://.../short_1.mp4"
160 }
161 ]
162}
163```
164 
165When `--coords-only` is set, each entry has `start_time`/`end_time` but no `clip_url` — render locally with ffmpeg.
166 
167When reporting back to the user, surface for each clip: rank, score, time range, title, hook, and clip URL.
168 
169---
170 
171## Common Mistakes to Avoid
172 
1731. **Wrong aspect ratio for the platform** — Shorts / TikTok / Reels are `9:16`. Default to that.
1742. **Padding to hit `num_clips`** — if the API returns fewer survivors than requested, return what you have. Don't pretend.
1753. **Re-running on a 404'd clip URL** — the same `request_id` can be re-fetched with `muapi predict wait <id>` rather than re-clipping.
1764. **Trying to tune Whisper / chunk size / LLM prompts** — those knobs aren't exposed; the endpoint handles them.
177 
178---
179 
180## Failure Modes
181 
182- **API key missing or rejected** — surface the exact error; never fabricate a key.
183- **Job timed out** — bump poll timeout (`--poll-timeout`) and retry.
184- **Source URL not reachable from the backend** — upload locally with `muapi upload file <path>` first, then pass the returned URL.
185- **Fewer clips returned than requested** — the source had fewer rankable highlights. Return what came back with a note.
186 
187---
188 
189## Done Criteria
190 
191The skill is done when:
1921. `result.shorts` has up to `num_clips` entries, each with a working `clip_url` (or `start_time`/`end_time` under `--coords-only`).
1932. The user has been shown the ranked list (score, time range, title, hook, URL).
1943. If `--output-json` was set, the file exists and parses.

Discussion