Add Subtitles
Learn how to add subtitles to your videos
Add Subtitles
Add professional subtitles to your videos with word-level highlighting and styling options.
Subtitle Modes
Video Schema supports two subtitle modes:
| Mode | Description | Use Case |
|---|---|---|
batch | Shows multiple words at once | Standard subtitles |
stream | Shows words one at a time | Karaoke-style, word-by-word |
Basic Subtitle Clip
{
"type": "subtitle",
"start": 0,
"duration": 10,
"words": [
{ "word": "Hello", "punctuated_word": "Hello,", "start": 0, "end": 0.5 },
{ "word": "world", "punctuated_word": "world!", "start": 0.5, "end": 1.0 }
],
"config": {
"mode": "batch",
"wordsPerBatch": 5,
"fontSize": 48,
"textColor": "#ffffff",
"highlightColor": "#ffff00",
"position": "bottom",
"paddingBottom": 100
}
}Word Data Structure
Each word in the subtitle has the following properties:
{
"word": "hello", // Raw word
"punctuated_word": "Hello,", // With punctuation
"start": 0.0, // Start time (seconds)
"end": 0.5, // End time (seconds)
"confidence": 0.95 // Optional: confidence score
}Subtitle Configuration
Position
| Position | Description |
|---|---|
bottom | Bottom of screen (default) |
top | Top of screen |
center | Center of screen |
Styling Options
{
"config": {
"fontSize": 48,
"fontFamily": "Arial",
"fontWeight": 700,
"textAlign": "center",
"textBoxWidth": "80%",
"textColor": "#ffffff",
"highlightColor": "#ffff00",
"backgroundColor": "rgba(0,0,0,0.5)",
"shadowColor": "#000000",
"shadowBlur": 10,
"borderColor": "#ffffff",
"borderWidth": 2,
"fadeInAnimation": true,
"position": "bottom",
"paddingBottom": 100
}
}Batch Mode Example
Shows multiple words at once, with the current word highlighted:
{
"type": "subtitle",
"start": 0,
"duration": 10,
"words": [
{ "word": "Welcome", "punctuated_word": "Welcome", "start": 0, "end": 0.5 },
{ "word": "to", "punctuated_word": "to", "start": 0.5, "end": 0.7 },
{ "word": "our", "punctuated_word": "our", "start": 0.7, "end": 0.9 },
{ "word": "video", "punctuated_word": "video", "start": 0.9, "end": 1.3 },
{ "word": "tutorial", "punctuated_word": "tutorial.", "start": 1.3, "end": 1.8 }
],
"config": {
"mode": "batch",
"wordsPerBatch": 5,
"fontSize": 56,
"textColor": "#ffffff",
"highlightColor": "#00ff88",
"backgroundColor": "rgba(0,0,0,0.7)",
"position": "bottom",
"paddingBottom": 120
}
}Stream Mode Example
Shows one word at a time, perfect for music videos or dramatic effect:
{
"type": "subtitle",
"start": 0,
"duration": 5,
"words": [
{ "word": "Dream", "punctuated_word": "Dream", "start": 0, "end": 0.5 },
{ "word": "big", "punctuated_word": "big", "start": 0.5, "end": 1.0 },
{ "word": "and", "punctuated_word": "and", "start": 1.0, "end": 1.3 },
{ "word": "never", "punctuated_word": "never", "start": 1.3, "end": 1.8 },
{ "word": "give", "punctuated_word": "give", "start": 1.8, "end": 2.2 },
{ "word": "up", "punctuated_word": "up!", "start": 2.2, "end": 2.8 }
],
"config": {
"mode": "stream",
"fontSize": 72,
"fontWeight": 900,
"textColor": "#ffffff",
"highlightColor": "#ff6b6b",
"position": "center",
"fadeInAnimation": true
}
}Using External Subtitle Files
You can reference external subtitle data:
{
"type": "subtitle",
"words": {
"$ref": "subtitles.main"
},
"config": {
"mode": "batch",
"wordsPerBatch": 8
}
}Or load from a URL:
{
"type": "subtitle",
"words": {
"src": "https://example.com/subtitles.json"
}
}Best Practices
- Font Size: Use 48-64px for readability on mobile
- Contrast: Ensure high contrast between text and background
- Timing: Match words to audio precisely
- Position: Keep subtitles away from important visual content
- Batch Size: 5-8 words per batch for comfortable reading