name: tiktok-clippers
description: This skill should be used when the user asks to "clip a YouTube video", "convert YouTube to TikTok", "make TikTok clips from a YouTube video", "split a video into short clips", "add captions to video clips", "make vertical video clips", "turn a YouTube video into shorts", or mentions wanting TikTok-style clips with gameplay like Subway Surfers or Minecraft in the background.
version: 1.0.0

TikTok Clipper Skill

Convert any YouTube video into TikTok-ready vertical clips — 1 minute each, with burned-in captions, vertical 9:16 format, and optional split-screen or corner gameplay overlay (Subway Surfers, Minecraft, etc.).

Prerequisites

Confirm these tools are available before running:

which yt-dlp ffmpeg python3
# Install if missing:
brew install yt-dlp ffmpeg          # macOS
# sudo apt install ffmpeg yt-dlp    # Linux
# pip install yt-dlp                # cross-platform yt-dlp fallback

Python 3.8+ is required. No additional pip packages needed — only stdlib + yt-dlp + ffmpeg.

Quick Start

Run the bundled script directly:

python3 ~/.claude/skills/tiktok-clippers/scripts/clip_video.py \
    "https://www.youtube.com/watch?v=VIDEO_ID" \
    -o ./my_clips

This creates ./my_clips/clip_01.mp4, clip_02.mp4, etc. — each 60 seconds (last clip uses the remainder), in 1080×1920 with auto-captions burned in.

Common Usage Patterns

Split-screen with gameplay (most popular TikTok style)

python3 clip_video.py "https://youtube.com/watch?v=..." \
    --gameplay subway_surfers.mp4 \
    --layout split

Main content plays in the top half; gameplay fills the bottom half.

Corner pip overlay

python3 clip_video.py "https://youtube.com/watch?v=..." \
    --gameplay minecraft.mp4 \
    --layout corner

Main video fills the full 9:16 frame; gameplay appears as a 320×568 pip in the bottom-right corner.

Shorter clips (e.g. 45 seconds)

python3 clip_video.py "https://youtube.com/watch?v=..." \
    --clip-length 45

No captions

python3 clip_video.py "https://youtube.com/watch?v=..." --no-captions

All Options

What the Script Does

1. Download — yt-dlp fetches the video (best MP4) and auto-generated English subtitles as SRT
2. Slice SRT — For each clip, extract the matching subtitle window and re-index timestamps to start at 0
3. Render each clip — ffmpeg processes each clip with:
4. Scale + crop to 1080×1920 (9:16)
5. Gameplay overlay (split or corner) if provided
6. subtitles filter burns captions with white bold text + black outline
7. H.264 output with +faststart for mobile streaming
8. Output — numbered clips saved to the output directory

Caption Styling

Default style: white bold text, black outline (3px), bottom-center alignment, 60px bottom margin.

To customize, edit the style string in scripts/clip_video.py at the make_clip function:

style = (
    "FontSize=18,"
    "Bold=1,"
    "PrimaryColour=&H00FFFFFF,"   # white
    "OutlineColour=&H00000000,"   # black
    "Outline=3,"
    "Shadow=1,"
    "Alignment=2,"                # bottom-center
    "MarginV=60"                  # px from bottom
)

See references/ffmpeg-filters.md for full style parameter reference.

Gameplay Video Tips

• Use a 9:16 (vertical) or at least 1:1 gameplay clip — the script scales it automatically
• Longer is better: the script offsets gameplay start based on clip position (start % 300) so different clips show different gameplay sections
• Good sources: record Subway Surfers / Minecraft on a phone, or use royalty-free gameplay recordings
• For split layout, horizontal (16:9) gameplay also works — it gets cropped to fit

Troubleshooting

No captions in output
- The video may not have auto-captions. Try adding --write-sub to the yt-dlp call in the script to grab manual captions instead.
- As a fallback, install Whisper: pip install openai-whisper then run whisper video.mp4 --output_format srt to generate an SRT, then pass it manually.

subtitles filter not found
- Your ffmpeg build may lack libass. On macOS: brew reinstall ffmpeg. On Ubuntu: sudo apt install ffmpeg (includes libass).

Black bars or wrong aspect ratio
- If the source is already vertical (portrait), the scale+crop chain still works but may over-crop. Check the source aspect ratio and adjust the filter in the script if needed.

Gameplay video too short
- Add -stream_loop -1 before the gameplay input in the ffmpeg command to loop it infinitely. See references/ffmpeg-filters.md.

Additional Resources

• scripts/clip_video.py — Full production script, ready to run
• references/ffmpeg-filters.md — FFmpeg filter details, layout recipes, subtitle styling, and troubleshooting