tiktok-forge

TikTok Forge

You are the editor; tooling does the mechanical work, you do the judgment work: clip order, phrase grouping, stinger copy, style. Pipeline: TRANSCRIBE, PLAN, APPROVE, BUILD, VERIFY, COVER, PACKAGE, DELIVER. Two hard gates: the user sees the plan before any render, and no video ships without frame verification.

Environment needs: ffmpeg, Python 3 with PIL and numpy, pip install faster-whisper. Fonts: a bold display face (Poppins or similar) plus a heavier stamp face (Bangers or similar). Emoji: a Noto emoji PNG set fetched per code point as needed.

1. Transcribe

Run faster-whisper on each clip with word_timestamps=True. Save per-clip word-level timestamps to work/words.json, plus auto-grouped caption pages (group words into pages, combining gaps under ~900ms). Print the transcript back to the user.

2. Plan (judgment)

Read references/hooks-and-conversion.md and references/caption-styles.md now, then build work/plan.json against references/plan-schema.md:

1. Clean the transcript. Fix mishearings from context. Strip filler (um, uh, you know) from caption text only. Never change timestamps, only text.
2. Order clips for retention. Score each opening line as a hook (rubric in the hooks reference). Strongest pattern interrupt first, most striking visual last.
3. Trim each clip to last word end + 0.3s.
4. Group captions into phrases: 2-4 words per page for pop styles, up to 5 for clean. Break at speech pauses. ALL CAPS for pop styles.
5. Keywords and emoji: 1-2 highlighted words per phrase (the meaning-carrying nouns and verbs), max 1 emoji per phrase popping right after its keyword, never the same emoji in consecutive phrases.
6. Stinger copy: one 0.8s card between each clip pair, two lines (line1 white 2-3 words, line2 on the accent stamp). Stingers open a loop ("BUT HERE'S / THE CATCH"), never close one.
7. End cards: recap card restates the thesis in two short lines plus a stamp punch, then a CTA card matching the user's goal. One CTA only.
8. Style and brand: bold-pop default (gold-karaoke, bounce, clean available). Brand colors from the user's kit or the defaults in the caption styles reference.
9. Budget the timeline to 20s (or the user's target): clips + 0.8s per stinger + 4-5s end cards. Trim clip tails first when over.

Copy rules everywhere: no em dashes, one specific number beats an adjective, on-screen hook text must not duplicate the first spoken words.

3. Approve

Present the plan compactly: clip order with hook scores, phrase and emoji map, stinger copy, end card copy, style, total duration. Ask only genuinely open questions (CTA goal, style). Never render before the user has seen the plan. Unattended runs: state assumptions, proceed, flag clearly.

4. Build

Execute the plan with ffmpeg + PIL: normalize clips (9:16 center crop, lanczos upscale, light grade, 30fps re-encode), render the overlay frame sequence (captions, emoji pops, stingers, end cards, white-flash cuts, progress bar), synthesize or source a low beat bed with risers into each cut, mix voice to -14 LUFS with the bed at least 15dB under speech, then encode: libx264, crf 18, preset slow, maxrate 10M, yuv420p, faststart, AAC 128k 44.1kHz.

5. Verify (mandatory)

Extract frames at: mid-clip captions, each stinger hold and slide-out, each cut boundary, both end cards. View every one. Check: captions inside safe zones, nothing covering the face at eye level, stinger text readable, emoji not overlapping text, progress bar on every frame. Anything off: fix the plan, rebuild, re-extract. Expect a clean pass before moving on.

6. Cover

Render a 1080x1920 cover: best freeze frame (expressive face, mid-gesture) + hook text + stamp + brand dot. Cover text 3-7 words, different from the spoken hook, kept in the vertical center 60% so it survives the 3:4 profile-grid crop.

7. Package copy

Posting caption per the hooks reference: first visible line earns the tap, one specific CTA, 3-5 mixed-reach hashtags at the end, under 300 characters. Note that the beat bed is mixed low so a trending sound can sit on top in the app.

8. Deliver

Send the mp4 and cover with a one-line summary each. Report duration and assumptions.

Hard rules

1. Safe zones: captions anchored 350px+ above frame bottom; nothing in bottom 320px, top 150px, right 120px (TikTok UI).
2. Timestamps are sacred. Clean text, never shift word times.
3. One emoji per phrase, one CTA per video, 3-5 hashtags. More is spam.
4. Landscape input: center-crop to 9:16 and warn about upscale softness.
5. After the first successful build, offer to save a reusable brand block (colors, handle, CTA).

Red flags (verbatim excuses, all invalid)

• "The plan is simple, I'll just render it."
• "I checked a couple frames, the rest will be fine."
• "The user is in a hurry, skipping approval."
• "The captions looked right in the plan, no need to view frames."

Any path that ends in a delivered video the user never planned or you never frame-checked violates both gates. There is no fast lane.

Completion checklist

• [ ] Transcript printed and cleaned, timestamps untouched
• [ ] Plan presented and approved (or assumptions flagged, unattended only)
• [ ] Frames extracted at all required points and visually checked
• [ ] Safe zones and audio balance verified
• [ ] Cover rendered with distinct text, center-60% safe
• [ ] Caption copy delivered under limits

Any box unchecked: not done. Fix or say so.

Good vs bad

• Bad stinger: "THAT'S / THE TRICK" (closes the loop, viewer leaves).
• Good stinger: "BUT HERE'S / THE CATCH" (opens a loop, viewer holds for the next clip).

Footguns

• Overlay/video desync: some clip was not re-encoded at exactly 30fps, or a trim differs from plan.json. Timeline math assumes exact trims.
• Black frames where a stinger belongs: stinger after_clip index wrong or duration mismatch with the timeline budget.
• Beat bed drowning speech: keep it 15dB+ under voice; TikTok viewers bail on muddy audio instantly.
• Caption pages over 4 words in pop styles wrap and cover the face. Regroup, do not shrink the font.