Content & Media Creation · iart-ai/tiktok-video-skills
caption-animation
This skill should be used when the user asks to "add animated captions", "make TikTok captions", "karaoke captions", "word-by-word subtitles", "auto subtitles", "highlight the active word", "burn in captions to a video", "sync captions to a voiceover/narration", or "turn an SRT/transcript into animated text". Covers word-level timing from Whisper, per-word pop/scale-in, active-word highlight, 9:16 safe-area placement, readable type, and burn-in vs sidecar SRT/VTT.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
Establishes "word-level timestamps" as a non-negotiable rule, explicitly rejecting the most common lazy shortcut (evenly dividing sentence duration across words).
skills/caption-animation/SKILL.md
1. **Word-level timing, not line-level.** Karaoke reads as magic only when each word lands on the syllable. Always transcribe to word timestamps; never fake them by splitting a line evenly over its duration — drift is instantly visible.
What is happening here: This discipline dictates that the entire pipeline must obtain per-word timestamps rather than sentence-level SRT cues. All downstream components consume the exact same flat token shape, making frame-accurate sync an architectural default rather than an afterthought of manual tuning.
Locks the pipeline into a six-stage table (transcription → normalization → pagination → animation → placement → export), designating specific tools for each stage to prevent agent improvisation.
skills/caption-animation/SKILL.md
| Transcribe | Audio → word-level timestamps | Whisper (`@remotion/install-whisper-cpp`), AssemblyAI |
What is happening here: The table forms the core "implementation principle"—capabilities are not built on ad-hoc code written by the model, but on converging every step into deterministic library functions (Remotion captions toolchain + whisper.cpp).
Enforces a single data shape across the entire lifecycle: `{text, startMs, endMs}`, normalizing all sources (Whisper / SRT / Cloud API) into it.
skills/caption-animation/SKILL.md
type Token = { text: string; startMs: number; endMs: number };
What is happening here: The data shape serves as the interface. Once normalized into tokens, downstream "active word highlighting" is reduced to a simple interval containment check, freeing the renderer from needing to know where the words originated.
Anchors each word's pop animation to its own startMs, utilizing Remotion spring overshoot to deliver a lively, organic feel.
skills/caption-animation/SKILL.md
const enter = (token.startMs / 1000) * fps; // word's own entrance frame
What is happening here: The entry frame is computed per-word (frame - enter) rather than derived from a global progress ratio. This is the technical foundation enabling word-level sync.
Defines pagination rules: 1–4 words per page, switching between two pacing dynamics using combineTokensWithinMilliseconds.
skills/caption-animation/SKILL.md
and tune `combineTokensWithinMilliseconds`: ~200–500ms for true word-by-word, ~1000–1500ms for short readable phrases.
What is happening here: Parameterizes "pacing" into a single numeric value, allowing the same component to deliver either raw word-by-word display or short-phrase grouping.
Specifies legibility and safe-area guidelines as concrete numeric tables (56–80px font size, stroke, 62–70% vertical center band, avoiding bottom ~280px) rather than qualitative adjectives.
skills/caption-animation/SKILL.md
| Size | 56–80px (≈8% of frame height), min 45px | Legible muted on a phone |
What is happening here: Constraints for vertical 9:16 (1080×1920) are fully quantified so the agent never places captions by guesswork; platform-by-platform safe area reference tables are also provided.
Delivery discipline: Burn in captions for social platforms while exporting SRT/VTT from the exact same tokens to satisfy accessibility requirements.
skills/caption-animation/SKILL.md
Emit both: burn the animated captions for social, and write a plain SRT/VTT from the same tokens for accessible/SEO playback.
What is happening here: Decouples "social media readiness" from "accessibility compliance" into two separate artifacts sharing identical timecodes, eliminating secondary alignment passes.
The deliver-and-verify loop relies on "human inspection of rendered still frames prior to encoding" rather than unit tests: frame-level checklist mandates that "the highlighted word at frame 90 must be the one covered by [startMs, endMs]".
skills/caption-animation/SKILL.md
the word highlighted at frame 90 is the word whose [startMs,endMs] contains 90/fps (no drift)
What is happening here: Converts hard-to-spot visual drift into a deterministically verifiable assertion (frame/fps falling inside the token interval) at the cost of merely three PNGs.
The reference provides complete, end-to-end runnable code (Whisper installation, SRT parsing, pagination, SRT/VTT export, platform safe areas, typographic specifications).
skills/caption-animation/references/word-timed-captions.md
# Word-Timed Captions — End-to-End Build
What is happening here: SKILL.md supplies discipline and architecture, while reference delivers copy-paste-ready implementations; this two-tier separation is the standardized pattern of this pack.
Offers both offline and cloud routes on the transcription side (cloud appears only as a single-line alternative in reference).
skills/caption-animation/references/word-timed-captions.md
npx @remotion/install-whisper-cpp # one-time: installs whisper.cpp + a model
What is happening here: The default path is local whisper.cpp (including model download), with cloud APIs remaining strictly an optional alternative—keeping this skill categorized as a local tooling profile.
2Core Capabilities
01Word-level timeline construction: Whisper (local whisper.cpp) or cloud API transcription → unified token array, with an SRT parser converting cues into ms
02Per-word pop/scale-in (span + spring) and active-word highlighting (single accent color or pill fill)
03Pagination (1–4 words/page) and pacing tuning to avoid overwhelming walls of text
04Pure Web/CSS fallback (for DOM players): one animation-delay = startMs per word
05Legible typography specs and 9:16 safe areas: bold sans-serif, 56–80px, 2–6px stroke + drop shadow, center band positioning, avoiding bottom UI zones
06Audio and captions share the exact same time base (re-recording VO requires re-transcription; manual offset nudging is strictly prohibited)
07Dual artifact export: burned-in MP4 + sidecar SRT/VTT; GIF reserved solely for README demonstration snippets
08Deliver-and-verify loop: stills (using actual shipped props) → visual inspection → encoding; query durationInFrames/fps via `npx remotion compositions`
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | npx remotion still / render / compositions |
| package | @remotion/captions（createTikTokStyleCaptions / Caption 类型） |
| cli | npx @remotion/install-whisper-cpp（一次性装 whisper.cpp + 模型） |
| api | AssemblyAI / Deepgram / OpenAI Whisper API（可选云转写替代，非默认路径） |
| cli | scripts/contact-sheet.sh + scripts/probe-mp4.sh（仓库根共享验证工具箱） |
| package | ffmpeg / ffprobe（系统依赖） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Local script or command execution: `npx @remotion/install-whisper-cpp`: One-time installation of whisper.cpp and model files into the project directory (offline transcription path)
- 网络端点: External network access declaration: (Optional, non-default) When selecting AssemblyAI / Deepgram / OpenAI Whisper API, user audio assets leave the local machine to third-party transcription services; re
- 本地工作目录: File I/O and artifact generation: Remotion projects (src/, Root/Composition, zod schema) constructed by the agent under this skill, along with out/capti
Audit Notes: . Three-tier self-attestation: ① Assessment target = this skill directory (running find inside skills/caption-animation/ confirms only three .md files: SKILL.md, references/word-timed-captions.md, and README.md, with zero non-.md files and zero executable scripts); ② Directory internal behavior = local writes (Remotion project, out/*.mp4, out/*.gif, out/f-*.png, sidecar .srt/.vtt) + local CLI (`npx remotion still/render/compositions`; ffmpeg/ffprobe executed via repo root scripts/contact-sheet.sh and probe-mp4.sh). Across skills/, `process.env` / `API_KEY` / `token` / `cookie` / `https?://` runtime endpoints return **0 hits** (the sole external link is an iart.ai UTM marketing link at the end of reference); ③ The only network exposure involves fetching packages via official npm channels (remotion / @remotion/*) and the one-time `npx @remotion/install-whisper-cpp` fetching whisper.cpp and models, aligned with site-wide Blue tier precedents (hyperframes, general-video: npx fetching packages via official npm channels does not elevate tier independently; motion-background: sharing the same scripts/ evaluated as Blue). No elevation to Yellow: no "fixed public endpoint query" behavior, no scraping. No elevation to Orange: no credential or environment variable reading; default path (local whisper.cpp) keeps assets entirely offline—while the cloud transcription alternative in reference §2 triggers Orange tier if chosen (assets egressing + user-supplied key), per Batch 4 Rule 2 ("appearing solely as an optional alternative → not rated"), Blue tier is maintained and documented in verdict.risks. Not Red tier: no TLS downgrade, no sandbox escapes, no anti-automation bypass, no arbitrary code execution surface.
5Second-Pass Verification
- [ok] skill 目录内是否真的没有可执行代码（档位判定的关键证据） — `find iart-tiktok-video-skills/skills/caption-animation -type f` 只列出 SKILL.md / references/word-timed-captions.md / README.md；目录内没有 .mjs/.sh/.ts 等可执行文件。SKILL.md 引用的 scripts/*.sh 实际位于**仓库根**（三仓库各一份），并非 skill 目录内资产——本报告按「SKILL.md 明列的使用路径」把它们计入 scripts_executed，但档位判定仍以 skill 目录内行为为主，两者结论一致（蓝）。
- [ok] 全部外链是否只是文档链接而非运行时端点 — 对 skills/ 全域 grep `https?://`（排除 iart.ai）零命中；唯二命中是 reference 与 README 末尾的 `https://iart.ai/?utm_source=github&utm_medium=…` 营销/引流链接，以及 skill 内代码里的 `file://`? 无。因此不存在「执行期外发」。
- [ok] 云转写替代路径是否构成现实风险（要不要升橙） — reference §2 原文只有一行：`- Cloud alternatives (AssemblyAI, Deepgram, OpenAI Whisper API) also return word timing — map their words[] into Token the same way.`，SKILL.md 管线表也只在工具列把 AssemblyAI 与 Whisper 并列。源码未规定任何 endpoint、key 读取方式或上传动作；默认路径是本地 whisper.cpp。按批4 细则2（可选的替代方案不判级）维持蓝档，但已在 risks 写明触发条件。
- [ok] 验收断言的措辞是否与 reference 的实现一致（防第一遍想当然） — SKILL.md 要求「第 90 帧高亮的词必须是覆盖 90/fps 的 token」；reference §5 的窗口组件正是 `active={now >= t.startMs && now < t.endMs}`（now = frame/fps×1000 系）；两侧同一判据，无漂移空间。
- [unlocatable] 性能声明「Whisper medium.en ≈ 2x faster than large」是否有据可查 — 仓库内无基准脚本、无数据文件、无引用来源；本次为只读侦查且不得运行转写，故不验证该倍数，仅作为文档声明记录，不作为结论。
- [discrepancy] light tier（seek-shot.sh + `?t=N` harness）对本 skill 是否可用 — scripts/README.md 把 seek-shot.sh 标为 Light tier（驱动页面的 `?t=N` seek harness），但 caption-animation 的 Web/CSS 路径（reference §6 的 renderTrack）只做 track 渲染，**没有提供 seek harness**；本 skill 的「Packaged helper」行也只点名 contact-sheet.sh 与 probe-mp4.sh（Heavy tier），未提 seek-shot.sh。结论：该脚本对本 skill 属仓库级通用件而非本 skill 承诺的能力，读者不应假定 light tier 可用——这是对 pin commit 有效的真实出入（非错误声明，因 SKILL.md 从未承诺）。
- [ok] 三仓库共享脚本是否同内容（跨包一致性） — 三仓库 scripts/ 逐字节相同：contact-sheet.sh b7dcc28034c9bf8fda5d48683e54d8b5、probe-mp4.sh 167b7977c50f492014e1a6fef8c9ed12、seek-shot.sh 24a4130cd1e64874154429b0b4af12da
6Verdict & Scenarios
Best for: Best for: Creators and video editing agencies needing to burn word-synchronized captions into vertical short-form videos (TikTok / Reels / Shorts) for themselves or clients; scenarios with clean voiceover tracks (or pre-existing SRT/transcripts) looking to turn captions into reusable Remotion components for batch re-rendering with new copy; projects requiring simultaneous delivery of social versions (burned-in) and web versions (.srt/.vtt). Ideal for users willing to let the agent run all the way to encoding while personally verifying three still frames.
Not for: Not suitable for: ① Users who simply want to "overlay subtitles" without word-by-word synchronization (standard ffmpeg caption burn-in is far simpler); ② Footage with heavy background music or cross-talk where users are unwilling to perform stem separation and noise reduction—word boundaries will be corrupted; ③ Long-form videos (reference notes local rendering of a 10-minute video takes 30–60 minutes; chunking or Lambda is recommended) where such render times are unacceptable; ④ Environments requiring fully self-contained offline operation that prohibit downloading remote packages or models; ⑤ Scenarios where users refuse to send audio to third parties yet also will not install local Whisper (the cloud route becomes the only viable path, triggering Orange tier); ⑥ Installation setups that copy only individual skill directories without installing the repository-level scripts/ directory.
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload caption-animation.tar.gz
sha256:
Option B · Copy Guide for Agent1b958f9e09758504…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 2a775336b5.