Captions API

Caption parsing, rendering, and utilities for SRT and WebVTT formats

Helios provides utilities for working with video captions in SRT and WebVTT formats.

CaptionCue

Interface representing a single caption cue.

interface CaptionCue {
  id: string;
  startTime: number; // milliseconds
  endTime: number;   // milliseconds
  text: string;
}

parseSrt()

Parses SRT (SubRip) format caption files.

const cues = parseSrt(content);

content · string · required

SRT file content as string

cues · CaptionCue[]

Array of parsed caption cues

Example

import { parseSrt } from '@heliosvideo/core';

const srtContent = `
1
00:00:00,000 --> 00:00:02,000
Hello, world!

2
00:00:02,500 --> 00:00:05,000
Welcome to Helios.
`;

const cues = parseSrt(srtContent);
// [
//   { id: '1', startTime: 0, endTime: 2000, text: 'Hello, world!' },
//   { id: '2', startTime: 2500, endTime: 5000, text: 'Welcome to Helios.' }
// ]

parseWebVTT()

Parses WebVTT format caption files.

const cues = parseWebVTT(content);

content · string · required

WebVTT file content as string (must start with “WEBVTT”)

cues · CaptionCue[]

Array of parsed caption cues

Example

import { parseWebVTT } from '@heliosvideo/core';

const vttContent = `
WEBVTT

00:00.000 --> 00:02.000
Hello, world!

00:02.500 --> 00:05.000
Welcome to Helios.
`;

const cues = parseWebVTT(vttContent);

parseCaptions()

Automatically detects and parses SRT or WebVTT format.

const cues = parseCaptions(content);

content · string · required

Caption file content (SRT or WebVTT)

cues · CaptionCue[]

Array of parsed caption cues

Example

import { parseCaptions } from '@heliosvideo/core';

// Automatically detects format
const cues = parseCaptions(captionFileContent);

stringifySrt()

Converts caption cues to SRT format.

const srtContent = stringifySrt(cues);

cues · CaptionCue[] · required

Array of caption cues

content · string

SRT formatted string

Example

import { stringifySrt } from '@heliosvideo/core';

const cues = [
  { id: '1', startTime: 0, endTime: 2000, text: 'Hello' },
  { id: '2', startTime: 2500, endTime: 5000, text: 'World' },
];

const srtContent = stringifySrt(cues);
// Returns:
// "1\n00:00:00,000 --> 00:00:02,000\nHello\n\n2\n00:00:02,500 --> 00:00:05,000\nWorld"

findActiveCues()

Finds caption cues active at a specific time.

const activeCues = findActiveCues(cues, timeMs);

cues · CaptionCue[] · required

Array of caption cues

timeMs · number · required

Time in milliseconds

activeCues · CaptionCue[]

Array of cues active at the given time

Example

import { findActiveCues } from '@heliosvideo/core';

const cues = [
  { id: '1', startTime: 0, endTime: 2000, text: 'First caption' },
  { id: '2', startTime: 1500, endTime: 3500, text: 'Second caption' },
  { id: '3', startTime: 3000, endTime: 5000, text: 'Third caption' },
];

const active = findActiveCues(cues, 2000);
// Returns: [cues[1], cues[2]] (both active at 2000ms)

areCuesEqual()

Checks if two cue arrays are equal.

const equal = areCuesEqual(cuesA, cuesB);

a · CaptionCue[] · required

First array of cues

b · CaptionCue[] · required

Second array of cues

equal · boolean

True if arrays contain the same cue objects in the same order

Example

import { areCuesEqual } from '@heliosvideo/core';

const cues1 = [{ id: '1', startTime: 0, endTime: 1000, text: 'A' }];
const cues2 = [{ id: '1', startTime: 0, endTime: 1000, text: 'A' }];
const cues3 = cues1;

areCuesEqual(cues1, cues2); // false (different objects)
areCuesEqual(cues1, cues3); // true (same reference)

Complete example

import { Helios, parseCaptions, findActiveCues } from '@heliosvideo/core';

// Load captions from file
const response = await fetch('/captions.srt');
const captionContent = await response.text();
const cues = parseCaptions(captionContent);

// Create Helios instance with captions
const helios = new Helios({
  duration: 10,
  fps: 30,
  captions: cues,
});

// Subscribe to active captions
helios.activeCaptions.subscribe((activeCues) => {
  console.log('Active captions:', activeCues);
  
  // Render captions
  activeCues.forEach((cue) => {
    displayCaption(cue.text);
  });
});

// Or manually find active cues
const currentTimeMs = helios.currentTime.value * 1000;
const active = findActiveCues(cues, currentTimeMs);

Format specifications

SRT format

1
00:00:00,000 --> 00:00:02,000
First caption

2
00:00:02,500 --> 00:00:05,000
Second caption
With multiple lines

• Numeric ID (optional, will be auto-generated)
• Timecode format: HH:MM:SS,mmm
• Arrow separator: -->
• Text can span multiple lines
• Blocks separated by blank lines

WebVTT format

WEBVTT

00:00.000 --> 00:02.000
First caption

00:02.500 --> 00:05.000
Second caption

• Must start with WEBVTT
• Timecode format: HH:MM:SS.mmm or MM:SS.mmm
• Arrow separator: -->
• Supports cue settings (ignored by parser)
• NOTE blocks are ignored