Subtitles & chapters

Enhance your video content with subtitles, captions, and chapter markers using ImageKit Video Player. This guide covers both manual configuration and AI-powered auto-generation features that make your videos more accessible and navigable.

Subtitles and captions

Add subtitles and captions using the textTracks array when setting up your video source. ImageKit supports standard WebVTT files or AI-powered auto-generation with advanced features like word highlighting and multi-language translation.

Why use subtitles? Subtitles improve accessibility, boost engagement, and help with SEO. They make your content accessible to viewers who are deaf or hard of hearing, watching in sound-sensitive environments, or speak different languages.

Auto-generated subtitles

Auto-generate subtitles using ImageKit's AI transcription. This approach creates a custom transcript file (.transcript) that supports advanced features unavailable in standard VTT files, including word-level highlighting and automatic multi-language translation.

Note: AI transcription costs 2 extension units per minute of source video duration. When you enable auto-generated subtitles or chapters for a video, both features are generated together automatically—you're billed once, not separately. Each language translation costs an additional 2 units per minute for that language's subtitles and chapters. Learn about extension unit pricing here.

Copy

import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  textTracks: [
    {
      autoGenerate: true,
      default: true,
      maxChars: 60, // Control subtitle pace
      highlightWords: true, // Enable word-level highlighting
      translations: [
        { langCode: 'fr', label: 'French' },
        { langCode: 'de', label: 'German' },
        { langCode: 'hi', label: 'Hindi' }
      ]
    }
  ]
});

Copy

import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
    textTracks: [
      {
        autoGenerate: true,
        default: true,
        maxChars: 60,
        highlightWords: true,
        translations: [
          { langCode: 'fr', label: 'French' },
          { langCode: 'de', label: 'German' },
          { langCode: 'hi', label: 'Hindi' }
        ]
      }
    ]
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}

Copy

<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  textTracks: [
    {
      autoGenerate: true,
      default: true,
      maxChars: 60,
      highlightWords: true,
      translations: [
        { langCode: 'fr', label: 'French' },
        { langCode: 'de', label: 'German' },
        { langCode: 'hi', label: 'Hindi' }
      ]
    }
  ]
};
</script>

Try the video player with auto-generated subtitles and translations:

Loading video player...

Standard WebVTT track

Use your own pre-created subtitle files by providing the ImageKit-powered URL to your WebVTT (.vtt) file. Upload VTT files to ImageKit as raw files, then reference them in your player configuration.

Copy

import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  textTracks: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-en.vtt',
      kind: 'subtitles',
      srclang: 'en',
      label: 'English',
      default: true
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-es.vtt',
      kind: 'subtitles',
      srclang: 'es',
      label: 'Spanish'
    }
  ]
});

Copy

import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
    textTracks: [
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-en.vtt',
        kind: 'subtitles',
        srclang: 'en',
        label: 'English',
        default: true
      },
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-es.vtt',
        kind: 'subtitles',
        srclang: 'es',
        label: 'Spanish'
      }
    ]
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}

Copy

<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  textTracks: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-en.vtt',
      kind: 'subtitles',
      srclang: 'en',
      label: 'English',
      default: true
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-es.vtt',
      kind: 'subtitles',
      srclang: 'es',
      label: 'Spanish'
    }
  ]
};
</script>

Standard WebVTT track options

Parameter	Description
src `string`	ImageKit-powered URL to `.vtt` file
kind `'subtitles' \| 'captions'`	Type of text track. Default: `'subtitles'`
srclang `string`	Language code (e.g., 'en', 'fr')
label `string`	Display label for the text track in the subtitle menu
default `boolean`	Whether to activate this track by default

Combining auto-generated and manual tracks

You can mix auto-generated subtitles with manual WebVTT files in the same textTracks array, giving viewers more subtitle options:

Copy

textTracks: [
  {
    autoGenerate: true, // AI-generated with word highlighting
    default: true,
    maxChars: 60,
    highlightWords: true
  },
  {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-custom.vtt',
    kind: 'subtitles',
    srclang: 'en',
    label: 'English (Professional)'
  }
]

Auto-generated text track options

Parameter	Description
autoGenerate `true`	Must be `true` to enable auto-generated subtitles
showAutoGenerated `boolean`	Whether to display auto-generated subtitles in the subtitle menu. Default: `true`
autoGeneratedLabel `string`	Custom display label for auto-generated subtitles in the subtitle menu. Default: `<detected language> (auto-generated)`, e.g., `English (auto-generated)`
default `boolean`	Whether to activate this track by default
maxChars `number`	Maximum characters per subtitle line. Controls the pace of subtitles by defining how many characters appear on each subtitle frame. Default: `60`
highlightWords `boolean`	Enable word-level highlighting to show exactly when each individual word gets spoken in the video, similar to karaoke. Default: `false`
translations `object[]`	Array of translation options. Each translation object has: Copy { // Language code (e.g., 'en', 'es', 'fr', 'de', 'hi', 'ja', 'zh') // See supported languages for the complete list langCode: string; // Custom display label in subtitle menu label?: string; // Activate this track by default default?: boolean; } Note: `maxChars` and `highlightWords` only apply to original transcription, not translations. See the complete list of supported languages for all available language codes.

Chapters

Chapters divide your video into sections with visual markers on the progress bar. Users can click the chapter button in the player control bar to view a list of chapters and quickly navigate to key sections, improving content discoverability and user experience.

Why use chapters? Chapters help viewers navigate long-form content, skip to relevant sections, and understand video structure at a glance. They're especially useful for tutorials, webinars, and educational content.

Chapter configuration options

Configure chapters using the chapters parameter when setting up your video source. You can configure chapters in three ways:

1. Auto-generate with AI

Set chapters: true to automatically generate chapter markers using ImageKit's AI analysis. Chapters are generated in the video's original language. If you have added translations in your textTracks configuration, chapters are also generated in those translated languages. See extension unit pricing for details.

Copy

import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: true // AI-powered chapter generation
});

Copy

import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
    chapters: true // AI-powered chapter generation
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}

Copy

<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: true // AI-powered chapter generation
};
</script>

Loading video player...

2. Manual chapter definition

Define chapters directly by specifying start times (in seconds) as keys and chapter titles as values:

Copy

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: {
    0: 'Introduction',
    146: 'Main Content',
    302: 'Advanced Topics',
    443: 'Q&A Session',
    563: 'Conclusion'
  }
});

Copy

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: {
    0: 'Introduction',
    146: 'Main Content',
    302: 'Advanced Topics',
    443: 'Q&A Session',
    563: 'Conclusion'
  }
};

Copy

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: {
    0: 'Introduction',
    146: 'Main Content',
    302: 'Advanced Topics',
    443: 'Q&A Session',
    563: 'Conclusion'
}
};

Loading video player...

3. Load from WebVTT file

Load chapters from an external WebVTT file for easier management and reusability:

Copy

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: { 
    url: 'https://ik.imagekit.io/<your-imagekit-id>/chapters.vtt' 
  }
});

Copy

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: { 
    url: 'https://ik.imagekit.io/<your-imagekit-id>/chapters.vtt' 
  }
};

Copy

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: { 
    url: 'https://ik.imagekit.io/<your-imagekit-id>/chapters.vtt' 
  }
};

Your WebVTT file should follow the standard format. Here's a sample:

Copy

WEBVTT

00:00:00.000 --> 00:02:26.470
Introduction

00:02:26.470 --> 00:05:02.140
Main Content

00:05:02.140 --> 00:07:23.060
Advanced Topics

00:07:23.060 --> 00:09:22.810
Q&A Session

00:09:22.810 --> 00:11:43.120
Conclusion

Loading video player...

Best practices

For subtitles and captions

Use auto-generation for quick deployment: ImageKit's AI transcription is accurate and supports 50+ languages, making it ideal for rapid content deployment.
Combine methods for professional content: Use auto-generated subtitles for quick turnaround, then add professionally edited VTT files for critical business content.
Enable word highlighting for engagement: The highlightWords feature creates a karaoke-like experience that boosts viewer engagement, especially for educational content.
Optimize reading pace: Adjust maxChars (default: 60) based on your audience—fewer characters per line for younger viewers or complex content.
Provide multiple language options: Use the translations array to reach global audiences without manual translation work.

For chapters

Keep chapter titles concise: Use short, descriptive titles that fit well in the chapter menu (aim for 3-6 words).
Strategic timing: Place chapter markers at natural content transitions, not in the middle of sentences or actions.
Use auto-generation first: Let AI analyze your video structure, then refine manually if needed.
Consider viewer intent: For tutorials, chapter at each major step. For presentations, chapter at topic changes.

Supported Languages: Complete list of languages supported for AI translation
Playlist & Recommendations: Create playlists and show video recommendations
Video Player Overview: Complete guide to ImageKit's video player features
Adaptive Bitrate Streaming: Learn about HLS and MPEG-DASH support
Video Transformations: Apply transformations to your videos

Subtitles & chapters

Subtitles and captions

Auto-generated subtitles

Standard WebVTT track

Standard WebVTT track options

Combining auto-generated and manual tracks

Auto-generated text track options

Chapters

Chapter configuration options

1. Auto-generate with AI

2. Manual chapter definition

3. Load from WebVTT file

Best practices

For subtitles and captions

For chapters

Related features