> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```typescript theme={null}
interface CaptionCue {
  id: string;
  startTime: number; // milliseconds
  endTime: number;   // milliseconds
  text: string;
}
```

## parseSrt()

Parses SRT (SubRip) format caption files.

```typescript theme={null}
const cues = parseSrt(content);
```

<ParamField path="content" type="string" required>
  SRT file content as string
</ParamField>

<ResponseField name="cues" type="CaptionCue[]">
  Array of parsed caption cues
</ResponseField>

### Example

```typescript theme={null}
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.

```typescript theme={null}
const cues = parseWebVTT(content);
```

<ParamField path="content" type="string" required>
  WebVTT file content as string (must start with "WEBVTT")
</ParamField>

<ResponseField name="cues" type="CaptionCue[]">
  Array of parsed caption cues
</ResponseField>

### Example

```typescript theme={null}
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.

```typescript theme={null}
const cues = parseCaptions(content);
```

<ParamField path="content" type="string" required>
  Caption file content (SRT or WebVTT)
</ParamField>

<ResponseField name="cues" type="CaptionCue[]">
  Array of parsed caption cues
</ResponseField>

### Example

```typescript theme={null}
import { parseCaptions } from '@heliosvideo/core';

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

## stringifySrt()

Converts caption cues to SRT format.

```typescript theme={null}
const srtContent = stringifySrt(cues);
```

<ParamField path="cues" type="CaptionCue[]" required>
  Array of caption cues
</ParamField>

<ResponseField name="content" type="string">
  SRT formatted string
</ResponseField>

### Example

```typescript theme={null}
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.

```typescript theme={null}
const activeCues = findActiveCues(cues, timeMs);
```

<ParamField path="cues" type="CaptionCue[]" required>
  Array of caption cues
</ParamField>

<ParamField path="timeMs" type="number" required>
  Time in milliseconds
</ParamField>

<ResponseField name="activeCues" type="CaptionCue[]">
  Array of cues active at the given time
</ResponseField>

### Example

```typescript theme={null}
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.

```typescript theme={null}
const equal = areCuesEqual(cuesA, cuesB);
```

<ParamField path="a" type="CaptionCue[]" required>
  First array of cues
</ParamField>

<ParamField path="b" type="CaptionCue[]" required>
  Second array of cues
</ParamField>

<ResponseField name="equal" type="boolean">
  True if arrays contain the same cue objects in the same order
</ResponseField>

### Example

```typescript theme={null}
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

```typescript theme={null}
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