TikTok Subtitle Generator

PHP script to generate TikTok-style subtitles with word-level highlighting from Whisper JSON files.

Features

• Smart Grouping: Groups words into 2-3 word phrases
• Perfect Sync: Uses exact word-level timing from Whisper JSON
• Adaptive Layout: Auto-detects video dimensions and adjusts font/margins
• Word Highlighting: Red background highlights each word as spoken with smooth fade
• Time Control: Adjustable timing offset and speed multiplier
• Fully Configurable: Every parameter configurable from command line
• Tight Box Fit: Boxes fit perfectly around words with configurable padding
• Text Shadow & Borders: Optional shadow and border effects

Requirements

• PHP 7.0+
• FFmpeg and FFprobe in PATH

Quick Start

# Basic usage
php tiktok_pro.php --video=input.MOV --json=words.json

# With fade effect and shadow
php tiktok_pro.php --video=input.MOV --json=words.json --style=fade --fade-ms=120 --text-shadow=2

# Fix timing offset
php tiktok_pro.php --video=input.MOV --json=words.json --offset=1.0

Input Format

Whisper-style JSON with word-level timestamps:

{
  "words": [
    {"word": "Hello", "start": 0.0, "end": 0.5},
    {"word": "world", "start": 0.5, "end": 1.0}
  ]
}

Parameters

Required

Parameter	Description
--video	Input video file path
--json	Whisper JSON file with word timings

Styling

Parameter	Description	Default
--bg-color	Background color hex (no #)	FF0000
--text-color	Text color hex (no #)	FFFFFF
--outline-color	Text outline color hex (no #)	000000
--text-outline	Outline width in pixels	3
--text-shadow	Shadow depth (0 = none)	0
--style	Animation: solid, fade, pulse	solid
--fade-ms	Fade duration in milliseconds	100

Layout

Parameter	Description	Default
--position	Position: top, center, bottom	center
--font-size	Font size in pixels	auto
--font-name	Font family	Arial
--margin-h	Horizontal margin in pixels	auto
--margin-v	Vertical margin in pixels	auto
--padding-x	Box horizontal padding	auto
--padding-y	Box vertical padding	auto
--border-radius	Box corner radius	15
--box-border	Box border width (0 = none)	0
--box-border-color	Box border color hex (no #)	000000
--extra-width	Extra box width padding	0

Grouping

Parameter	Description	Default
--max-words	Max words per group	4
--max-chars	Max characters per line	40
--gap-threshold	Gap to split groups (seconds)	auto

Timing & Output

Parameter	Description	Default
--output	Output video file path	auto
--offset	Shift all subtitles by seconds (+delay, -advance)	0
--min-duration	Min duration for zero-duration words	0.08
--no-burn	Generate ASS only, skip video	false

Encoding

Parameter	Description	Default
--video-codec	Video codec	libx264
--video-preset	Preset: ultrafast/fast/medium/slow	medium
--video-crf	Quality: 0-51 (lower = better)	23
--pixel-format	Pixel format	yuv420p

Usage Examples

TikTok Style

php tiktok_pro.php --video=input.MOV --json=words.json \
  --style=fade --fade-ms=120 --text-shadow=2 \
  --offset=1.0 --extra-width=0

Fix Timing Issues

# Subtitles appear early: add delay
php tiktok_pro.php --video=input.MOV --json=words.json --offset=1.0

# Subtitles appear late: reduce delay  
php tiktok_pro.php --video=input.MOV --json=words.json --offset=-0.3

Custom Colors

# Green background
php tiktok_pro.php --video=input.MOV --json=words.json --bg-color=00FF00

# Yellow background with black text
php tiktok_pro.php --video=input.MOV --json=words.json \
  --bg-color=FFFF00 --text-color=000000 --outline-color=FFFFFF

Box with Border

php tiktok_pro.php --video=input.MOV --json=words.json \
  --box-border=2 --box-border-color=FFFFFF --border-radius=20

Tight vs Loose Fit

# Tight fit (no extra space)
php tiktok_pro.php --video=input.MOV --json=words.json --extra-width=0

# Loose fit (more padding)
php tiktok_pro.php --video=input.MOV --json=words.json --extra-width=20

Custom Grouping

# Shorter groups (2 words max)
php tiktok_pro.php --video=input.MOV --json=words.json --max-words=2

# Custom gap threshold
php tiktok_pro.php --video=input.MOV --json=words.json --gap-threshold=0.5

Bottom Positioning

php tiktok_pro.php --video=input.MOV --json=words.json \
  --position=bottom --margin-v=50

High Quality Export

php tiktok_pro.php --video=input.MOV --json=words.json \
  --video-crf=18 --video-preset=slow

Generate ASS Only

php tiktok_pro.php --video=input.MOV --json=words.json --no-burn

How It Works

1. Detects video properties (resolution, FPS, duration) via FFprobe
2. Parses Whisper JSON and applies time offset and speed multiplier
3. Fixes zero-duration words (adds minimum 80ms visibility)
4. Groups words intelligently based on timing gaps and pauses
5. Generates ASS subtitle file with two layers:
   • Layer 1: White text visible for entire group duration
   • Layer 0: Red background highlight for each word with fade-out transition
6. Burns subtitles into video using FFmpeg with configurable encoding

Troubleshooting

Subtitles appear too early

Add positive offset: --offset=1.0

Subtitles appear too late

Add negative offset: --offset=-0.3

Boxes too wide

Use tight fit: --extra-width=0

Fade not visible

Increase fade duration: --fade-ms=150 with --style=fade

License

MIT License