reel-editor-th

name

reel-editor-th

description

Turn a talking-head clip (a single person to camera, usually shot on a phone) into a finished vertical 9:16 Thai-subtitled Instagram Reel that is built to go viral: word-by-word Thai captions with green keyword highlights, a 3-second hook, optional on-screen demo cards (SKILL.md editor, Claude Code chat, Excel, etc.), a follow + link-in-bio CTA, sound-effect accents, and a matching Reel cover. Use this whenever you have an .mp4 of a single person talking and want subtitles, a reel, "ตัดคลิป", "ทำ reel", "ใส่ซับ", "subtitle", captions, or a viral IG/TikTok video — even if the ask is just "ทำให้ หน่อย" with a clip attached. Also use it when editing or re-rendering a reel already made with this pipeline (color, captions, CTA, cover tweaks). Do NOT use it for building a video from scratch with no footage (that is HyperFrames), for non-Thai narration, or for multi-person edits.

IG Reel (Thai talking-head)

A repeatable pipeline that turns one talking-head clip into a polished, viral-shaped 9:16 Thai reel. The hard parts (HDR color, Thai word segmentation, caption motion, compositing) are solved in bundled scripts. Your job per clip is to author one file — timeline.py — from the transcript, then run build.sh.

Default preferences (override per project)

• Style = clean (translucent pill + green underline on the active word). It reads premium. bold (loud TikTok) and terminal (coder) also exist.
• No color filter — true colors. Graded footage often looks unnatural. The pipeline does NOT grade; it only fixes HDR→SDR so colors are correct (see below). Do not add an eq/colorbalance grade unless explicitly asked.
• No em dashes anywhere in copy — they read as an AI tell. Grep your text.
• Accent green #0BDE85 on near-black. Highlight only payload words (nouns, numbers, the product name), not everything, or the highlight stops meaning anything.
• CTA points to the BIO, not "comment a keyword" (edit the offer text). Plus a "กดติดตาม" chip. Keep a follow CTA.
• Hook is provocative/"เสียดสุด" and lands on-screen text within the first second (most viewers watch muted).
• Font is Sukhumvit Set (bundled on macOS). No Kanit/Prompt installed.

The HDR trap — read this first (it caused wrong skin/shirt color once)

Modern phones record HDR (HLG, BT.2020, 10-bit). The local Homebrew ffmpeg has no zimg/zscale/tonemap/libplacebo, so any plain ffmpeg pass mis-decodes HDR and the skin goes green and the shirt goes grey. build.sh fixes this in step 1 by tonemapping HDR→SDR bt709 with a tiny Swift/AVFoundation tool (scripts/tonemap.swift, the same tone map QuickTime uses). Always build on the tonemapped master, never the raw HDR file. Ground-truth check for any frame: qlmanage -t -s 1080 <clip>.mp4 -o <dir>.

Captions are rendered as PNG overlays (PIL) then composited, because this ffmpeg has no libass/drawtext. That is expected — do not try to burn subtitles with ffmpeg.

Workflow

Work in a fresh per-clip directory (e.g. ~/Desktop/ig/<clip-name>/).

1. Transcribe (Thai, word-level). Use mlx-whisper (fast on Apple Silicon). Turn OFF conditioning or the tail loops into garbage:

python3 -c "import mlx_whisper,json; r=mlx_whisper.transcribe('audio.wav', \
 path_or_hf_repo='mlx-community/whisper-large-v3-turbo', language='th', \
 word_timestamps=True, condition_on_previous_text=False, verbose=False); \
 [print(f\"[{s['start']:.1f}-{s['end']:.1f}] {s['text'].strip()}\") for s in r['segments']]"

Extract audio first: ffmpeg -i source.mp4 -vn -ar 16000 -ac 1 audio.wav. If a stretch still garbles, re-transcribe just that window (-ss/-t). Fix obvious ASR errors (Claude, Skill.md, brand names) by hand.

2. Author timeline.py. Copy scripts/timeline_template.py into the workdir as timeline.py and fill it: chunk captions into short 2-3 word phrases on the real segment timings, write the hook and punch lines, mark green emphasis words, and (optionally) place demo cards. Full guidance + examples: references/authoring-guide.md. A complete real example is scripts/timeline_example.py.

3. (Optional) Customize demo cards. If you use INSERTS, the card CONTENT in scripts/render_cards.py is topic-specific — edit the text to match this clip, or leave INSERTS = [] to ship captions-only. See the authoring guide.

4. Build:

bash ~/.claude/skills/reel-editor-th/scripts/build.sh <source.mp4> <workdir> clean

Output: <workdir>/out/reel_clean.mp4 + cover_*.jpg.

5. Verify before delivering. Sample a few frames (ffmpeg -ss <t> -i out/reel_clean.mp4 -frames:v 1 f.jpg) and actually LOOK: colors natural (skin not green), Thai tone marks intact, no tofu boxes (PIL has no emoji/glyph fallback — draw shapes, never render ⚡📌▌→ as text), captions clear of the bottom ~15% (IG UI) and not covering the face during hook/punch, CTA legible. Fix in timeline.py / the render scripts and re-run.

6. Deliver. Copy the mp4 + a cover + a caption doc into a clearly-named folder on the Desktop. macOS may block overwriting existing Desktop files from the shell — write to a new folder / new filename instead (the Write tool can overwrite Desktop text files; ffmpeg/cp often cannot). Include an IG caption + hashtags file alongside the mp4.

What each script does

• tonemap.swift — HDR(HLG)→SDR bt709 via AVFoundation. Compiled on first build.
• render_lib.py — fonts, easing, text drawing helpers.
• render_captions.py — caption styles (STYLES: clean/bold/terminal), hook, punch, CTA. Edit draw_cta to change the bio offer text.
• render_cards.py — the 4 demo cards (skillmd/arrow/claudechat/excel). Content is editable per clip.
• render_overlay_video.py — renders the full RGBA overlay to a ProRes4444 alpha .mov.
• render_cover.py — 3 Reel covers from a true-color frame.
• build_audio.py — derives SFX from the timeline and mixes them under the voiceover.
• build.sh — orchestrates the whole thing.

Common tweaks

• Different caption look → change the style arg (clean/bold/terminal).
• Reposition/resize captions → STYLES[...]["y"] and ["size"] in render_captions.py.
• Change the CTA offer/number → draw_cta in render_captions.py.
• More/less energy in audio → gains in build_audio.py or set SFX_EVENTS in timeline.
• If a flatter/brighter look is wanted or (rarely) graded → add an eq/colorbalance after the tonemap in build.sh's composite step, and show him an A/B still first.