thanmaiashok/shortcut-clips

What does shortcut-clips do?

A local pipeline does the mechanical work (transcribe, find candidate windows, reframe, caption, render). Your job is the judgment step: read candidate moments as text, pick the best ones, and write clips.json. You never see or need video frames.

0. Inputs

• Video: a local file path. If the user gives a URL instead, explain that shortcut-clips only works on files they provide (content they own or have rights to) and ask for a file. Don't download anything.
• Number of clips: use the user's number; otherwise 3.
• Options (only if the user asks): --language hi|kn|en|…, --min-len/--max-len (default 20-60 s), style bold-pop (default), minimal or karaoke-highlight.

1. Prepare (transcribe + candidates)

shortcut-clips prepare "<video>"

• It prints the output folder, then one line per chunk file. Note both.
• A first run downloads the speech model. A 1-hour video takes roughly 15-25 min on CPU and 5-10 min on a GPU. For videos longer than about 10 minutes, run the command in the background and wait for it to finish. Tell the user it's working. Re-running is safe: finished stages are cached.
• On failure, show the user the error's fix-it advice. shortcut-clips doctor checks the install.

2. Pick the moments

1. Read <output folder>/work/candidates.txt, then every chunk file it lists, in order. Each chunk lists sentences (s0012 [68.3] text) and candidates (c004 s0012-s0021 68.2-108.6 (40s)), each candidate a range of those sentences. Don't read transcript.json or candidates.json: the chunks contain everything you need, in far fewer tokens.
2. Score each candidate with reference/rubric.md. As you go, keep a shortlist of about 3× the requested number: candidate id, five criterion scores, one-line note. Drop the rest.
3. Improve the winners. You may move a clip's edges to other sentence boundaries, for example starting at the sentence with the strongest hook or ending right after the payoff:
   • start = the chosen first sentence's time.
   • end = the time of the sentence after the last one you keep, or the candidate's end time if you keep its last sentence.
   • Stay inside the length range. The validator snaps edges to whole words.
4. Choose the final set: highest overall scores, no two clips sharing more than a few seconds, and different topics where possible.

3. Write clips.json

Write <output folder>/clips.json following reference/clips-format.md. Write hook_text, title and caption in the transcript's language and script unless the user asks otherwise. Order clips best first. Then run:

shortcut-clips validate "<output folder>/clips.json" --write

Fix every error and re-run until it prints ✓. Fix warnings when it's easy. info lines report automatic adjustments (snapped edges) and need no action.

4. Render

shortcut-clips render "<output folder>/clips.json"

Then report to the user: for each clip, its number, title, length, score and video path, plus the gallery <output folder>/index.html. Add one sentence on why the top clip works. Mention that they can ask for changes.

Edits and re-runs

• "Make clip 2 shorter", "new title", "use karaoke style": edit clips.json (per-clip style/layout override defaults), validate with --write, render again. Unchanged clips are reused from the cache.
• "Find different moments": go back to step 2 with the same chunks. Don't re-run prepare.
• Wrong language detected: re-run prepare with --language <code>. Only transcription and later stages redo.
• No candidate windows: the video is short or has little speech. Re-run prepare with a smaller --min-len (for example 10).