niruvai/storytelling

/storytelling

┌──────────────────────┐
│ [4:12] [cover] [comments] │  three cards, all at once
│  I made this carousel │  black-box title, 1-2 lines
│   in a few minutes    │
│ and it's doing well   │  small white subtitle
│        (face)         │  one continuous take, punched in a little
│     entire carousel   │  TikTok captions
└──────────────────────┘

First use

This skill's folder is the "Base directory" Claude Code shows when it loads it.

SKILL_DIR="<base directory of this skill>"   # the path Claude Code printed as "Base directory for this skill"
KIT=$(python3 -c 'import os,sys;print(os.path.realpath(os.path.join(sys.argv[1],"..","..","kit")))' "$SKILL_DIR")
PY="$KIT/.venv/bin/python"; [ -x "$PY" ] || bash "$KIT/setup.sh"

Bangla clips. If the speaker talks in Bangla, make sure REEL_LANGUAGE=bn is set before the first words call (export it, or prefix the command) so Whisper transcribes in Bangla instead of translating. Write every on-screen text (titles, labels, items) in Bangla too, and anchor times on the Bangla words exactly as words prints them. Bangla runs wider than English at the same size, so keep headlines to 2–4 words and check the contact sheet for overflow. Whisper often misspells Bangla (e.g. "ধাকার মেওর" for "ঢাকার মেয়র"): before writing the spec, read the words of the stretch you picked and fix wrong spellings directly in <clip>.transcript.json (change only word, keep start/end), then run words again so captions and anchors use the corrected words. If a long stretch of speech is missing from words, delete the transcript and run words again; the transcriber re-checks skipped stretches. If the clip is not 9:16 (a square 1080x1080 phone video, say), check the first frame: a straight crop can make the face fill the screen and cover the visuals, so tell the user and suggest a 9:16 recording.

GROQ_API_KEY must be set to transcribe. Needs ffmpeg and Node.

Steps

1. Clip. Any 9:16 talking head.
2. Words. Run "$PY" "$KIT/reel.py" words <video>. It prints one sentence per line with [ends …] (when its last word ends), so use that as end. Pick ONE continuous stretch of 4 to 8 seconds that tells a small story or shows proof. Don't stitch pieces together, because the jump cuts read as weird here.
3. Spec. Write <clip>.storytelling.json (below). Paths in a spec are relative to the spec file. The three cards are the story in pictures: the effort, the thing and the result.
4. Build. Run "$PY" "$SKILL_DIR/build.py" <spec.json>.
5. Check. Look at <out>.sheet.jpg:
   • The cards and title clear the top 220 px.
   • The captions don't cover the mouth (move caption_top, 1385 by default).
   • The title fits on its lines.
6. Hand over the mp4 path.

Spec

{
  "video": "my-clip.mp4", "start": 42.3, "end": 47.8,
  "zoom": 1.3,
  "cards": [
    {"type": "stat", "label": "TIME SPENT", "value": "4:12", "unit": "minutes"},
    {"type": "cover", "image": "my-photo.jpg", "text": "the best *ai tools*\nto use when\nyou're *young and broke*"},
    {"type": "comments", "title": "Comments", "rows": [["sarah.creates", "CAROUSEL"], ["mike.builds", "CAROUSEL!!"]]}
  ],
  "title": ["I made this carousel", "in a few minutes"],
  "subtitle": "and it's doing extremely well"
}

cards takes exactly 3, each one of:

• image: {"src": "photo.jpg"}, a square photo.
• cover: a carousel cover, image plus text (*word* turns yellow, \n breaks the line). It drifts slowly.
• stat: label, value, unit and a ring.
  • The value counts up when it is a number ("250", "10,000") or a time ("4:12").
  • ring (0 to 1) is how full the ring gets.
• comments: up to 4 [handle, text] rows.
• text: {"big": "3×", "small": "more saves"}.

The other fields:

• title: 1 or 2 lines, each about 22 characters at most.
• subtitle: one short line.
• zoom: how far the take is punched in. 1.3 by default, 1 for none.

Taste

• Everything lands at once, in the first third of a second. Never one at a time.
• The title is the story in one breath. The subtitle is the payoff.
• Cards show real things: the user's own post, numbers, screenshots. Comment rows and handles must be real ones the user gave you. If they have none, use a text or stat card instead of inventing people.