Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us