Subtitle

Complete reference for adding captions and subtitles to your videos in the Zvid Package, including word-level timing, styling options, and animation modes.

Overview

The subtitle property allows you to add synchronized captions to your videos with precise word-level timing. It supports multiple display modes including progressive word reveals, karaoke-style highlighting, and various positioning options.

Subtitle Interface

interface Subtitle {
  captions: Caption[];
  styles?: SubtitleStyles;
}

interface Caption {
  start: number;
  end: number;
  text?: string;
  words: Word[];
}

interface Word {
  start: number;
  end: number;
  text: string;
}

interface SubtitleStyles {
  color?: string;
  background?: string;
  isBold?: boolean;
  isItalic?: boolean;
  fontSize?: number;
  fontFamily?: string;
  textTransform?: "uppercase" | "lowercase" | "capitalize";
  outline?: {
    width: number;
    color: string;
  };
  position?:
    | "top-left"
    | "top-right"
    | "bottom-left"
    | "bottom-right"
    | "center-center"
    | "center-left"
    | "center-right";
  marginV?: number;
  marginH?: number;
  mode?: "normal" | "one-word" | "karaoke" | "progressive";
  activeWord?: {
    color: string;
  };
}

Properties

Subtitle Properties

Property	Type	Required	Description
captions	Caption[]	Yes	Array of caption segments
styles	SubtitleStyles	No	Global styling configuration

Caption Properties

Property	Type	Required	Description
start	number	Yes	Caption start time in seconds
end	number	Yes	Caption end time in seconds
text	string	No	Full caption text (auto-generated from words if omitted)
words	Word[]	Yes	Array of individual words with timing

Word Properties

Property	Type	Required	Description
start	number	Yes	Word start time in seconds
end	number	Yes	Word end time in seconds
text	string	Yes	Word text content

SubtitleStyles Properties

Color and Background

Property	Type	Default	Description
color	string	"#FFFFFF"	Text color in hex format with optional alpha (e.g., #000000, #00000030)
background	string	null	Background color in hex format with optional alpha

Typography

Property	Type	Default	Description
fontSize	number	50	Font size in pixels
fontFamily	string	"Poppins"	Font family name
isBold	boolean	false	Bold text weight
isItalic	boolean	false	Italic text style
textTransform	"uppercase" | "lowercase" | "capitalize"	null	Text case transformation

Outline

Property	Type	Description
outline	object	Text outline/stroke configuration
outline.width	number	Outline width in pixels
outline.color	string	Outline color in hex format with optional alpha

Positioning

Property	Type	Default	Description
position	"top-left" | "top-right" | "bottom-left" | "bottom-right" | "center-center" | "center-left" | "center-right"	"bottom-center"	Caption position on screen
marginV	number	5% of the video Height	Vertical margin in pixels (integer only)
marginH	number	5% of the video Width	Horizontal margin in pixels (integer only)

Display Modes

Property	Type	Default	Description
mode	"normal" | "one-word" | "karaoke" | "progressive"	"normal"	Caption display animation mode
activeWord	object	null	Active word styling (for karaoke mode)
activeWord.color	string	null	Color for active/highlighted word

Display Modes Explained

Normal Mode

Displays the entire caption segment at once, showing all words simultaneously.

mode: "normal";

One-Word Mode

Shows one word at a time, replacing the previous word with the current word.

mode: "one-word";

Karaoke Mode

Displays all words in the caption, highlighting the current word being spoken.

mode: "karaoke",
activeWord: {
  color: "#FF0000"  // Highlight current word in red
}

Progressive Mode

Reveals words progressively, adding each new word while keeping previous words visible.

mode: "progressive";

Basic Examples

Simple Captions

{
  subtitle: {
    captions: [
      {
        start: 0.5,
        end: 2.0,
        text: "Welcome to our video",
        words: [
          { start: 0.5, end: 0.9, text: "Welcome" },
          { start: 0.9, end: 1.1, text: "to" },
          { start: 1.1, end: 1.4, text: "our" },
          { start: 1.4, end: 2.0, text: "video" },
        ],
      },
    ];
  }
}

Styled Captions

{
  subtitle: {
    captions: [
      {
        start: 0.49,
        end: 1.48,
        text: "Welcome to Zvid",
        words: [
          { start: 0.49, end: 0.87, text: "Welcome" },
          { start: 0.87, end: 1.029, text: "to" },
          { start: 1.029, end: 1.48, text: "Zvid" }
        ]
      }
    ],
    styles: {
      color: "#FFFFFF",
      background: "#000000",
      fontSize: 45,
      fontFamily: "Poppins",
      isBold: true,
      position: "center-center"
    }
  }
}

Advanced Examples

Karaoke-Style Captions

{
  subtitle: {
    captions: [
      {
        start: 0,
        end: 3,
        words: [
          { start: 0, end: 0.5, text: "Let's" },
          { start: 0.5, end: 1.0, text: "create" },
          { start: 1.0, end: 1.5, text: "amazing" },
          { start: 1.5, end: 3.0, text: "videos" }
        ]
      }
    ],
    styles: {
      color: "#FFFFFF",
      background: "#000000CC",
      fontSize: 50,
      fontFamily: "Montserrat",
      isBold: true,
      position: "center-center",
      mode: "karaoke",
      activeWord: {
        color: "#FFD700"  // Gold color for active word
      }
    }
  }
}

Progressive Captions with Outline

{
  subtitle: {
    captions: [
      {
        start: 1,
        end: 4,
        words: [
          { start: 1, end: 1.5, text: "Professional" },
          { start: 1.5, end: 2, text: "video" },
          { start: 2, end: 2.5, text: "editing" },
          { start: 2.5, end: 4, text: "simplified" }
        ]
      }
    ],
    styles: {
      color: "#FFFFFF",
      fontSize: 55,
      fontFamily: "Roboto",
      isBold: true,
      textTransform: "uppercase",
      outline: {
        width: 3,
        color: "#000000"
      },
      mode: "progressive"
      activeWord: {
        color: "#FFD700"
      }
    }
  }
}

Top-Positioned Captions

{
  subtitle: {
    captions: [
      {
        start: 0,
        end: 5,
        words: [
          { start: 0, end: 1, text: "This" },
          { start: 1, end: 2, text: "appears" },
          { start: 2, end: 3, text: "at" },
          { start: 3, end: 4, text: "the" },
          { start: 4, end: 5, text: "top" }
        ]
      }
    ],
    styles: {
      color: "#000000",
      background: "#FFFFFFEE",
      fontSize: 40,
      fontFamily: "Inter",
      position: "top-center",
      mode: "normal"
    }
  }
}

Font Handling

The package automatically downloads and caches Google Fonts when specified in the fontFamily property. Popular fonts for captions include:

• Sans-serif: Roboto, Open Sans, Montserrat, Poppins, Lato
• Bold Display: Anton, Bebas Neue, Oswald
• Clean Modern: Inter, Work Sans, Nunito

styles: {
  fontFamily: "Montserrat",  // Automatically downloaded from Google Fonts
  fontSize: 50,
  isBold: true
}

Color Format

All color properties support hex format with optional alpha channel:

• Standard hex: #FFFFFF (white), #000000 (black)
• Hex with alpha: #00000080 (50% transparent black), #FFFFFF30 (light transparent white)

Alpha values range from 00 (fully transparent) to FF (fully opaque).

Best Practices

Styling Guidelines

1. Contrast: Ensure text color contrasts well with video content
2. Backgrounds: Use semi-transparent backgrounds for better readability
3. Font Size: Use 40-60px for standard videos, adjust based on resolution
4. Positioning: Bottom captions are most common and expected by viewers

Mode Selection

1. Normal: Best for standard subtitles and accessibility
2. One-Word: Good for emphasis and minimal designs
3. Karaoke: Ideal for sing-along content and language learning
4. Progressive: Great for dynamic reveals and modern aesthetics

Accessibility

1. Use high contrast colors (white text on dark background or vice versa)
2. Avoid very small font sizes (minimum 35-40px, but it depends on the Font Family)
3. Position captions where they won't obscure important visual content

Related Pages

• API Reference - Main API documentation
• Video Elements - Video clip configuration