Skill Video Caption Overlay

Render TikTok-style animated pill captions onto short-form videos using MoviePy + PIL. Takes a base MP4, a captions JSON, and optional background audio — out...

Security Scan

The skill does what it claims (renders pill-style captions using MoviePy/Pillow); the code and runtime instructions are mostly consistent, with a small mismatch in font fallback paths that looks like an author hardcoding rather than malicious behavior.

Purpose & Capability

Name/description match the included Python script. The single required binary 'uv' is consistent with the documented 'uv run' usage. Dependencies (moviepy, pillow) are exactly what the task needs.

Instruction Scope

SKILL.md instructs the agent to run the included script on a user-supplied video, captions JSON, and optional audio only — which matches the code. However, SKILL.md claims fallback to fonts in '~/.local/share/fonts/', while the script defaults to the absolute path '/home/aladdin/.local/share/fonts/...'. This hardcoded user home path is an inconsistency (likely an author oversight) and could cause the script to fail or attempt to read another user's files on multi-user systems.

Install Mechanism

No install spec is provided (instruction-only), and the script relies on well-known Python packages via 'uv --with' flags. There are no downloads from external URLs or archive extraction steps in the skill bundle.

Credentials

The skill requires no environment variables or credentials. It only reads files the user passes as arguments (video, captions JSON, optional audio, optional font paths).

Persistence & Privilege

always is false and the skill does not request persistent/system-wide privileges or modify other skills. Model invocation is permitted (the platform default) but, given the script's local-file nature, autonomous invocation would simply run the overlay on files the agent is given.

Assessment

This skill appears to be what it says: a local Python script that overlays animated pill captions on videos. Things to check before running: 1) Fix the hardcoded font defaults — the script uses '/home/aladdin/.local/share/fonts/...' even though the README says '~/.local/share/fonts/'; change those defaults to use os.path.expanduser('~/.local/...') or pass --font-black/--font-bold with absolute paths. 2) Run the script on sample files first to confirm behavior and avoid pointing it at sensitive system files. 3) Confirm you trust the source before running — although no network calls or credential access are present, the script will read any file path you give it and write the output file. 4) Ensure you have uv, moviepy, and pillow installed in a controlled environment (virtualenv/container) if you want to limit side effects.

Video Caption Overlay

Animated pill-style caption overlays for short-form video. No Premiere, no CapCut — pure Python.

Usage

uv run --with moviepy --with pillow scripts/overlay.py \
  --video base.mp4 \
  --output final.mp4 \
  --captions scripts/example_captions.json \
  --audio music.mp3 \
  --audio-start 8 \
  --audio-vol 0.5

No --audio if you want to keep the original video audio.

Custom fonts

--font-black /path/to/Montserrat-Black.ttf \
--font-bold  /path/to/Montserrat-Bold.ttf

Falls back to Montserrat from ~/.local/share/fonts/ if not specified.

captions.json format

Array of phases — each phase is a time window with one or more pill lines stacked vertically.

[
  {
    "start": 0,
    "end": 3.2,
    "y_frac": 0.06,
    "lines": [
      {
        "text": "POV:",
        "size": 28,
        "bold": true,
        "bg": [0, 195, 255],
        "fg": [0, 0, 0],
        "bg_opacity": 0.9,
        "px": 20, "py": 9, "r": 12
      },
      {
        "text": "drink more water",
        "size": 50,
        "bg": [255, 255, 255],
        "fg": [0, 0, 0]
      }
    ]
  }
]

Field	Type	Default	Description
start	float	required	Phase start time (seconds)
end	float	required	Phase end time (seconds)
y_frac	float	0.06	Vertical position as fraction of video height
lines[].text	string	required	Caption text
lines[].size	int	50	Font size (px)
lines[].bold	bool	false	Use bold font (vs black/heavy)
lines[].bg	[R,G,B]	[255,255,255]	Pill background color
lines[].fg	[R,G,B]	[0,0,0]	Text color
lines[].bg_opacity	float	0.93	Pill background opacity (0–1)
lines[].px	int	26	Horizontal padding
lines[].py	int	13	Vertical padding
lines[].r	int	18	Border radius

PIL textbbox fix

PIL's textbbox((0,0), text, font) returns (x0, y0, x1, y1) where y0 is a non-zero offset (typically 7–15px depending on font size). Drawing text at (x, y) without compensating for this offset causes text to appear below the pill's visual center.

Fix implemented in pill():

bb    = draw.textbbox((0, 0), text, font=font)
x_off, y_off = bb[0], bb[1]
vis_w = bb[2] - bb[0]   # actual visual width
vis_h = bb[3] - bb[1]   # actual visual height

# Compensate offsets when drawing text
tx = cx - vis_w // 2 - x_off
ty = y - y_off
draw.text((tx, ty), text, font=font, fill=fg)

Emoji note

NotoColorEmoji.ttf fails with PIL at arbitrary sizes (bitmap font with limited supported sizes). Use text alternatives ("Free delivery" instead of "Free delivery 🚚") for reliable rendering.

Example output

See scripts/example_captions.json for the full 3-phase TikTok ad structure:

• Phase 1 (0–3.2s): Hook — top-screen pill stack
• Phase 2 (2.8–5.8s): Product claim — overlapping fade
• Phase 3 (5.3–8.0s): CTA — bottom-screen price + delivery + bio link