### Install subtitle.js

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Install the library using npm or yarn.

```bash
npm install subtitle
# or
yarn add subtitle
```

--------------------------------

### Subtitle Node Structure Example

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Illustrates the structure of subtitle nodes, including 'header' and 'cue' types. 'cue' nodes contain start and end timestamps in milliseconds, along with the subtitle text.

```typescript
[
  {
    type: 'header',
    data: 'WEBVTT - Header content'
  },
  {
    type: 'cue',
    data: {
      start: 150066, // timestamp in milliseconds,
      end: 158952,
      text: 'With great power comes great responsibility'
    }
  },
  ...
]
```

--------------------------------

### Create Subtitles Programmatically

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Demonstrates how to create subtitle data programmatically by pushing 'cue' objects with start time, end time, and text into a list, then converting this list into a subtitle string.

```typescript
import { stringifySync } from 'subtitle'

const list = []

list.push({
  type: 'cue',
  data: {
    start: 1200,
    end: 1300,
    text: 'Something'
  }
})

stringifySync(list)
```

--------------------------------

### parseTimestamps

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Parses a string containing start and end timestamps, supporting both SRT and VTT formats, and returns an object with start and end times in milliseconds, along with any additional settings.

```APIDOC
## parseTimestamps

### Description
It receives a timestamps string, like `00:01:00,500 --> 00:01:10,800`. It also supports VTT formats like `12:34:56,789 --> 98:76:54,321 align:middle line:90%`.

### Method Signature
`parseTimestamps(timestamps: string): Timestamp`

### Usage Example
```ts
import { parseTimestamps } from 'subtitle'

parseTimestamps('00:01:00,500 --> 00:01:10,800')
// => { start: 60500, end: 70800 }

parseTimestamps('12:34:56,789 --> 98:76:54,321 align:middle line:90%')
// => { start: 45296789, end: 357414321, settings: 'align:middle line:90%' }
```
```

--------------------------------

### parseTimestamps(value)

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Parse a timestamp range string from SRT/VTT files into start and end milliseconds.

```APIDOC
## parseTimestamps(value)

### Description
Accepts a full timestamp range line (e.g., `00:01:00,500 --> 00:01:10,800`) as used in SRT/VTT files, and returns a `Timestamp` object with `start`, `end`, and optional `settings` fields in milliseconds.

### Parameters
#### Timestamp Range String
- **value** (string) - Required - The timestamp range string (e.g., '00:01:00,500 --> 00:01:10,800').

### Returns
- (object) - An object containing `start` (number), `end` (number), and optional `settings` (string) in milliseconds.

### Example
```ts
import { parseTimestamps } from 'subtitle'

parseTimestamps('00:01:00,500 --> 00:01:10,800')
// => { start: 60500, end: 70800 }

parseTimestamps('12:34:56,789 --> 98:76:54,321 align:middle line:90%')
// => { start: 45296789, end: 357414321, settings: 'align:middle line:90%' }

// Useful for manually building cue nodes:
const { start, end, settings } = parseTimestamps('00:00:05,000 --> 00:00:10,000 position:50%')
const cueNode = {
  type: 'cue',
  data: { start, end, settings, text: 'Hello world' }
}
```
```

--------------------------------

### Parse timestamp range string to milliseconds with settings

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Parses a full timestamp range line (e.g., '00:01:00,500 --> 00:01:10,800') into start and end times in milliseconds. Also extracts optional VTT cue settings.

```typescript
import { parseTimestamps } from 'subtitle'

parseTimestamps('00:01:00,500 --> 00:01:10,800')
// => { start: 60500, end: 70800 }

parseTimestamps('12:34:56,789 --> 98:76:54,321 align:middle line:90%')
// => { start: 45296789, end: 357414321, settings: 'align:middle line:90%' }

// Useful for manually building cue nodes:
const { start, end, settings } = parseTimestamps('00:00:05,000 --> 00:00:10,000 position:50%')
const cueNode = {
  type: 'cue',
  data: { start, end, settings, text: 'Hello world' }
}
```

--------------------------------

### Filter and Map Subtitle Cues

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Manipulate subtitle nodes using filter and map streams. This example strips cues containing '𝅘𝅥𝅮' and converts other cue texts to uppercase. Ensure input and output streams are defined.

```typescript
import { parse, map, filter, stringify } from 'subtitle'

inputStream
  .pipe(parse())
  .pipe(
    filter(
      // strips all cues that contains "𝅘𝅥𝅮"
      node => !(node.type === 'cue' && node.data.text.includes('𝅘𝅥𝅮'))
    )
  )
  .pipe(
    map(node => {
      if (node.type === 'cue') {
        // convert all cues to uppercase
        node.data.text = node.data.text.toUpperCase()
      }

      return node
    })
  )
  .pipe(stringify({ format: 'WebVTT' }))
  .pipe(outputStream)
```

--------------------------------

### resync(time)

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Returns a Transform stream that offsets every cue's start and end timestamps by the given number of milliseconds. Use positive values to advance subtitles, negative values to delay them.

```APIDOC
## resync(time)

### Description
Returns a Transform stream that offsets every cue's `start` and `end` timestamps by the given number of milliseconds. Use positive values to advance subtitles, negative values to delay them.

### Parameters
#### Time Offset
- **time** (number) - Required - The time in milliseconds to shift the timestamps. Positive values advance, negative values delay.

### Example
```ts
import fs from 'fs'
import { parse, resync, stringify } from 'subtitle'

// Advance subtitles by 1.5 seconds (fix early subtitles)
fs.createReadStream('./out-of-sync.srt')
  .pipe(parse())
  .pipe(resync(1500))
  .pipe(stringify({ format: 'SRT' }))
  .pipe(fs.createWriteStream('./synced.srt'))

// Delay subtitles by 250ms (fix subtitles that appear too early)
fs.createReadStream('./out-of-sync.srt')
  .pipe(parse())
  .pipe(resync(-250))
  .pipe(stringify({ format: 'WebVTT' }))
  .pipe(fs.createWriteStream('./synced.vtt'))
```
```

--------------------------------

### Manipulate Subtitle Nodes with Map Stream

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Use the `map` stream to transform subtitle nodes. This example converts the text of all 'cue' nodes to uppercase. Ensure input and output streams are defined.

```typescript
import { parse, map, stringify } from 'subtitle'

inputStream
  .pipe(parse())
  .pipe(
    map((node, index) => {
      if (node.type === 'cue') {
        node.data.text = node.data.text.toUpperCase()
      }

      return node
    })
  )
  .pipe(stringify({ format: 'SRT' }))
  .pipe(outputStream)
```

--------------------------------

### resync

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

A function that returns a Duplex stream for resynchronizing subtitle timestamps. It takes an offset in milliseconds to adjust the start and end times of all cues.

```APIDOC
## resync

### Description
Returns a Duplex stream for resynchronizing subtitle timestamps.

### Method
`resync(offset: number): DuplexStream`

### Usage Example
```ts
import fs from 'fs'
import { parse, resync, stringify } from 'subtitle'

fs.createReadStream('./my-subtitles.srt')
  .pipe(parse())
  .pipe(resync(-100)) // Adjusts timestamps by -100ms
  .pipe(stringify({ format: 'WebVTT' }))
  .pipe(fs.createWriteStream('./my-subtitles.vtt'))
```
```

--------------------------------

### Parse SRT or VTT Timestamps String

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Parses a string containing start and end timestamps, supporting both SRT and VTT formats. It can also extract additional settings like alignment and line position from VTT.

```typescript
import { parseTimestamps } from 'subtitle'

parseTimestamps('00:01:00,500 --> 00:01:10,800')
// => { start: 60500, end: 70800 }

parseTimestamps('12:34:56,789 --> 98:76:54,321 align:middle line:90%')
// => { start: 45296789, end: 357414321, settings: 'align:middle line:90%' }
```

--------------------------------

### Core TypeScript types for subtitle nodes and formats

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Defines the fundamental types used in the subtitle.js library, including Node (header/cue), Cue details (start, end, text, settings), Timestamp ranges, and supported Format options.

```typescript
import type { Node, NodeCue, NodeHeader, NodeList, Timestamp, Cue, Format, FormatOptions } from 'subtitle'

// A parsed node is either a header or a cue
type Node = NodeHeader | NodeCue

interface NodeHeader {
  type: 'header'
  data: string           // Raw WebVTT header content
}

interface NodeCue {
  type: 'cue'
  data: Cue
}

interface Cue {
  start: number          // Milliseconds
  end: number            // Milliseconds
  text: string           // Subtitle text content
  settings?: string      // Optional VTT cue settings (e.g., 'align:middle line:90%')
}

interface Timestamp {
  start: number
  end: number
  settings?: string
}

type Format = 'SRT' | 'WebVTT'

interface FormatOptions {
  format: Format
}
```

--------------------------------

### stringifySync(nodes, options) — Synchronous subtitle serializer

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Accepts a NodeList and format options, and returns the full subtitle content as a string. Useful when you already have nodes in memory and need a quick string output.

```APIDOC
## stringifySync(nodes, options)

### Description
Accepts a `NodeList` and format options, and returns the full subtitle content as a string. Useful when you already have nodes in memory and need a quick string output.

### Method
Synchronous Function

### Parameters
- **nodes** (NodeList) - Required - An array of `Node` objects to serialize.
- **options** (object) - Optional - Configuration for serialization.
  - **format** (string) - Optional - The desired output format ('SRT' or 'WebVTT'). Defaults to 'SRT'.

### Request Example
```ts
import { parseSync, stringifySync } from 'subtitle'
import fs from 'fs'

const nodes = parseSync(fs.readFileSync('./movie.srt', 'utf8'))
const vttOutput = stringifySync(nodes, { format: 'WebVTT' })
fs.writeFileSync('./output.vtt', vttOutput)
```

### Response
#### Success Response
- **string** - The complete subtitle content as a formatted string.

#### Response Example
```text
WEBVTT

1
00:00:20.000 --> 00:00:24.400
Bla Bla Bla Bla
```
```

--------------------------------

### Stream-based SRT/VTT Parsing

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Use `parse()` to create a stream that accepts raw subtitle text and emits parsed Node objects. Auto-detects format and handles BOM stripping.

```typescript
import fs from 'fs'
import { parse } from 'subtitle'

// Parse an SRT file and log each node
fs.createReadStream('./movie.srt')
  .pipe(parse())
  .on('data', (node) => {
    if (node.type === 'cue') {
      console.log(`[${node.data.start}ms --> ${node.data.end}ms] ${node.data.text}`)
    }
  })
  .on('error', (err) => console.error('Parse error:', err))
  .on('finish', () => console.log('Done parsing'))

// Output:
// [20000ms --> 24400ms] Bla Bla Bla Bla
// [24600ms --> 27800ms] Bla Bla Bla Bla
```

--------------------------------

### Stream-based Subtitle Serialization

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Use `stringify()` to create a stream that accepts Node objects and emits formatted subtitle strings. Supports 'SRT' and 'WebVTT' formats.

```typescript
import fs from 'fs'
import { parse, stringify } from 'subtitle'

// Convert SRT to WebVTT
fs.createReadStream('./source.srt')
  .pipe(parse())
  .pipe(stringify({ format: 'WebVTT' }))
  .pipe(fs.createWriteStream('./output.vtt'))
  .on('finish', () => console.log('Conversion complete'))

// Convert WebVTT back to SRT
fs.createReadStream('./source.vtt')
  .pipe(parse())
  .pipe(stringify({ format: 'SRT' }))
  .pipe(fs.createWriteStream('./output.srt'))
```

--------------------------------

### stringifySync

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Receives an array of captions and returns a string in SRT format by default, or VTT format when specified in the options. This synchronous function is less performant than the stream-based `stringify`.

```APIDOC
## stringifySync

### Description
It receives an array of captions and returns a string in SRT (default), but it also supports VTT format through the options.

### Method
`stringifySync(nodes: Node[], options: { format: 'SRT' | 'WebVTT }): string`

### Note
For better performance, consider using the stream-based `stringify` function.

### Usage Example
```ts
import { stringifySync } from 'subtitle'

// returns a string in SRT format
stringifySync(nodes, { format: 'SRT' })

// returns a string in VTT format
stringifySync(nodes, { format: 'WebVTT' })
```
```

--------------------------------

### Parse, Resync, and Stringify Subtitles

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Use this stream-based approach to parse an SRT file, resync its timings, and output it as a VTT file. Requires 'fs' for file stream operations.

```typescript
import fs from 'fs'
import { parse, resync, stringify } from 'subtitle'

fs.createReadStream('./my-subtitles.srt')
  .pipe(parse())
  .pipe(resync(-100))
  .pipe(stringify({ format: 'WebVTT' }))
  .pipe(fs.createWriteStream('./my-subtitles.vtt'))
```

--------------------------------

### Convert SRT to WebVTT File

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Reads an SRT file, parses its content, converts it to WebVTT format, and writes the output to a new file using Node.js streams.

```typescript
import fs from 'fs'
import { parse, stringify } from 'subtitle'

fs.createReadStream('./source.srt')
  .pipe(parse())
  .pipe(stringify({ format: 'WebVTT' }))
  .pipe(fs.createWriteStream('./dest.vtt'))
```

--------------------------------

### formatTimestamp(timestamp, options?)

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Format milliseconds to a timestamp string in SRT or WebVTT format.

```APIDOC
## formatTimestamp(timestamp, options?)

### Description
Accepts a timestamp in milliseconds and returns a formatted string in SRT (`HH:MM:SS,mmm`) or WebVTT (`HH:MM:SS.mmm`) format. Defaults to SRT format.

### Parameters
#### Timestamp (milliseconds)
- **timestamp** (number) - Required - The timestamp value in milliseconds.
#### Options
- **options** (object) - Optional - Formatting options.
  - **format** (string) - Optional - The desired output format, either 'SRT' or 'WebVTT'. Defaults to 'SRT'.

### Returns
- (string) - The formatted timestamp string.

### Example
```ts
import { formatTimestamp } from 'subtitle'

formatTimestamp(142542) 
// => '00:02:22,542'  (SRT format, default)

formatTimestamp(142542, { format: 'WebVTT' })
// => '00:02:22.542'  (WebVTT format, uses '.' instead of ',')

formatTimestamp(0)
// => '00:00:00,000'

formatTimestamp(3661000)
// => '01:01:01,000'

// Combine with parseTimestamp for round-trip conversion:
import { parseTimestamp } from 'subtitle'
const ms = parseTimestamp('01:30:45,123')  // => 5445123
formatTimestamp(ms, { format: 'WebVTT' })  // => '01:30:45.123'
```
```

--------------------------------

### Synchronous SRT/VTT Parsing

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Use `parseSync()` for small files or when streaming is not required. It accepts a full subtitle string and returns an array of Node objects.

```typescript
import fs from 'fs'
import { parseSync } from 'subtitle'

const input = fs.readFileSync('./movie.srt', 'utf8')
const nodes = parseSync(input)

// nodes is a NodeList:
// [
//   { type: 'cue', data: { start: 20000, end: 24400, text: 'Bla Bla Bla Bla' } },
//   { type: 'cue', data: { start: 24600, end: 27800, text: 'Bla Bla Bla Bla', settings: 'align:middle line:90%' } }
// ]

const cues = nodes.filter(n => n.type === 'cue')
console.log(`Total cues: ${cues.length}`)
```

--------------------------------

### parseSync(input) — Synchronous SRT/VTT parser

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Accepts a full subtitle string and synchronously returns an array of Node objects. Use for small files or when streaming is not required.

```APIDOC
## parseSync(input)

### Description
Accepts a full subtitle string (SRT or WebVTT) and synchronously returns an array of `Node` objects. Use for small files or when streaming is not required.

### Method
Synchronous Function

### Parameters
- **input** (string) - Required - The complete subtitle content as a string.

### Request Example
```ts
import fs from 'fs'
import { parseSync } from 'subtitle'

const input = fs.readFileSync('./movie.srt', 'utf8')
const nodes = parseSync(input)

console.log(`Total cues: ${nodes.filter(n => n.type === 'cue').length}`)
```

### Response
#### Success Response
- **nodes** (NodeList) - An array of `Node` objects representing the parsed subtitle content.

#### Response Example
```json
[
  { "type": "cue", "data": { "start": 20000, "end": 24400, "text": "Bla Bla Bla Bla" } },
  { "type": "cue", "data": { "start": 24600, "end": 27800, "text": "Bla Bla Bla Bla", "settings": "align:middle line:90%" } }
]
```
```

--------------------------------

### stringify(options) — Stream-based subtitle serializer

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Returns a Duplex stream that accepts parsed Node objects and emits formatted subtitle strings in either 'SRT' or 'WebVTT' format.

```APIDOC
## stringify(options)

### Description
Returns a Duplex stream that accepts parsed `Node` objects and emits formatted subtitle strings in either `'SRT'` or `'WebVTT'` format. Automatically adds the `WEBVTT` header when outputting WebVTT without a header node.

### Method
Stream Transform

### Parameters
- **options** (object) - Optional - Configuration for serialization.
  - **format** (string) - Optional - The desired output format ('SRT' or 'WebVTT'). Defaults to 'SRT'.

### Request Example
```ts
import fs from 'fs'
import { parse, stringify } from 'subtitle'

// Convert SRT to WebVTT
fs.createReadStream('./source.srt')
  .pipe(parse())
  .pipe(stringify({ format: 'WebVTT' }))
  .pipe(fs.createWriteStream('./output.vtt'))
```

### Response
#### Success Response
Emits formatted subtitle strings.

#### Response Example
```text
WEBVTT

1
00:00:20.000 --> 00:00:24.400
Bla Bla Bla Bla
```
```

--------------------------------

### parse() — Stream-based SRT/VTT parser

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Returns a Duplex stream that accepts raw subtitle text and emits parsed Node objects. It auto-detects the format and supports streaming input.

```APIDOC
## parse()

### Description
Returns a Duplex stream in object mode that accepts raw subtitle text (SRT or WebVTT) and emits parsed `Node` objects. It auto-detects the format, handles BOM stripping, and supports streaming input line by line.

### Method
Stream Transform

### Parameters
None

### Request Example
```ts
import fs from 'fs'
import { parse } from 'subtitle'

fs.createReadStream('./movie.srt')
  .pipe(parse())
  .on('data', (node) => {
    if (node.type === 'cue') {
      console.log(`[${node.data.start}ms --> ${node.data.end}ms] ${node.data.text}`)
    }
  })
  .on('error', (err) => console.error('Parse error:', err))
  .on('finish', () => console.log('Done parsing'))
```

### Response
#### Success Response
Emits `Node` objects representing parsed subtitle cues or metadata.

#### Response Example
```json
{
  "type": "cue",
  "data": {
    "start": 20000,
    "end": 24400,
    "text": "Bla Bla Bla Bla"
  }
}
```
```

--------------------------------

### parseSync

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Receives a string containing SRT or VTT content and returns an array of nodes. This function is synchronous but less performant than the stream-based `parse` function.

```APIDOC
## parseSync

### Description
It receives a string containing a SRT or VTT content and returns an array of nodes.

### Method
`parseSync(input: string): Node[]`

### Note
For better performance, consider using the stream-based `parse` function.

### Usage Example
```ts
import { parseSync } from 'subtitle'
import fs from 'fs'

const input = fs.readFileSync('awesome-movie.srt', 'utf8')

const nodes = parseSync(input)

// returns an array like this:
// [
//   {
//     type: 'cue',
//     data: {
//       start: 20000, // milliseconds
//       end: 24400,
//       text: 'Bla Bla Bla Bla'
//     }
//   },
//   // ...
// ]
```
```

--------------------------------

### Extract Subtitles from Video to WebVTT

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Uses the 'rip-subtitles' library to extract subtitle tracks from a video file (e.g., MKV), parses them, converts them to WebVTT format, and saves the output.

```typescript
import extract from 'rip-subtitles'
import { parse, stringify } from 'subtitle'

extract('video.mkv')
  .pipe(parse())
  .pipe(stringify({ format: 'WebVTT' }))
  .pipe(fs.createWriteStream('./video.vtt'))
```

--------------------------------

### Synchronous Subtitle Serialization

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Use `stringifySync()` to convert a `NodeList` to a subtitle string. Useful when nodes are already in memory.

```typescript
import { parseSync, stringifySync } from 'subtitle'
import fs from 'fs'

const nodes = parseSync(fs.readFileSync('./movie.srt', 'utf8'))

// Serialize back as SRT
const srtOutput = stringifySync(nodes, { format: 'SRT' })
fs.writeFileSync('./output.srt', srtOutput)

// Serialize as WebVTT
const vttOutput = stringifySync(nodes, { format: 'WebVTT' })
fs.writeFileSync('./output.vtt', vttOutput)

console.log(vttOutput)
// WEBVTT
//
// 1
// 00:00:20.000 --> 00:00:24.400
// Bla Bla Bla Bla
//
// 2
// 00:00:24.600 --> 00:00:27.800
// Bla Bla Bla Bla
```

--------------------------------

### resync

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

A Duplex stream that resynchronizes all cues in the stream by a specified time offset. Positive values advance subtitles, while negative values delay them.

```APIDOC
## resync

### Description
Resync all cues from the stream.

### Method Signature
`resync(time: number): DuplexStream`

### Usage Example
```ts
import { parse, resync, stringify } from 'subtitle'

// Advance subtitles by 1s
readableStream
  .pipe(parse())
  .pipe(resync(1000))
  .pipe(outputStream)

// Delay 250ms
stream.pipe(resync(captions, -250))
```
```

--------------------------------

### Stream Subtitle Parsing and Stringifying to WebVTT

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Pipe subtitle data through a parser and then a stringifier to convert it to WebVTT format. Requires input and output streams to be defined.

```typescript
import { parse, stringify } from 'subtitle'

inputStream.pipe(parse()).pipe(stringify({ format: 'WebVTT' }))
```

--------------------------------

### Synchronous Subtitle Parsing and Stringifying

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Use synchronous functions for parsing and stringifying subtitles when stream-based operations are not necessary. Note that stream-based functions are recommended for better performance.

```typescript
import { parseSync, stringifySync } from 'subtitle'

const nodes = parseSync(srtContent)

// do something with your subtitles
// ...

const output = stringify(nodes, { format: 'WebVTT' })
```

--------------------------------

### Format milliseconds to SRT or WebVTT timestamp string

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Converts a timestamp in milliseconds into a formatted string. Defaults to SRT format ('HH:MM:SS,mmm'), but can be configured for WebVTT ('HH:MM:SS.mmm').

```typescript
import { formatTimestamp } from 'subtitle'

formatTimestamp(142542) 
// => '00:02:22,542'  (SRT format, default)

formatTimestamp(142542, { format: 'WebVTT' })
// => '00:02:22.542'  (WebVTT format, uses '.' instead of ',')

formatTimestamp(0)
// => '00:00:00,000'

formatTimestamp(3661000)
// => '01:01:01,000'

// Combine with parseTimestamp for round-trip conversion:
import { parseTimestamp } from 'subtitle'
const ms = parseTimestamp('01:30:45,123')  // => 5445123
formatTimestamp(ms, { format: 'WebVTT' })  // => '01:30:45.123'
```

--------------------------------

### parse

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Returns a Duplex stream for parsing subtitle contents (SRT or WebVTT). It emits 'data' events for each parsed node, and can handle 'error' and 'finish' events.

```APIDOC
## parse

### Description
It returns a Duplex stream for parsing subtitle contents (SRT or WebVTT).

### Method
`parse(): DuplexStream`

### Usage Example
```ts
import { parse } from 'subtitle'

inputStream
  .pipe(parse())
  .on('data', node => {
    console.log('parsed node:', node)
  })
  .on('error', console.error)
  .on('finish', () => console.log('parser has finished'))
```
```

--------------------------------

### parseTimestamp(timestamp)

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Parse a single timestamp string to milliseconds. Accepts SRT or VTT format and returns milliseconds. Throws an error on invalid input.

```APIDOC
## parseTimestamp(timestamp)

### Description
Parse a single SRT-format (`HH:MM:SS,mmm`) or VTT-format (`HH:MM:SS.mmm` or `MM:SS.mmm`) timestamp string and returns its value in milliseconds as a number. Throws an error on invalid input.

### Parameters
#### Timestamp String
- **timestamp** (string) - Required - The timestamp string to parse (e.g., '00:00:24,400' or '00:24.400').

### Returns
- (number) - The timestamp value in milliseconds.

### Example
```ts
import { parseTimestamp } from 'subtitle'

parseTimestamp('00:00:24,400')   // => 24400
parseTimestamp('00:02:22,542')   // => 142542
parseTimestamp('00:24.400')      // => 24400 (VTT short format)
parseTimestamp('01:00:00,000')   // => 3600000

try {
  parseTimestamp('invalid')
} catch (err) {
  console.error(err.message)
  // => 'Invalid SRT or VTT time format: "invalid"'
}
```
```

--------------------------------

### stringify

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Returns a Duplex stream that receives parsed nodes and transmits them formatted in SRT or WebVTT. It's useful for transforming subtitle data between formats within a stream pipeline.

```APIDOC
## stringify

### Description
It returns a Duplex that receives parsed nodes and transmits the node formatted in SRT or WebVTT.

### Method
`stringify({ format: 'SRT' | 'WebVTT' }): DuplexStream`

### Usage Example
```ts
import { parse, stringify } from 'subtitle'

inputStream.pipe(parse()).pipe(stringify({ format: 'WebVTT' }))
```
```

--------------------------------

### Synchronous SRT/VTT Parsing

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Parse a string containing SRT or VTT content synchronously. Returns an array of nodes, each representing a subtitle cue with start/end times and text. For performance, prefer the stream-based `parse` function.

```typescript
import { parseSync } from 'subtitle'
import fs from 'fs'

const input = fs.readFileSync('awesome-movie.srt', 'utf8')

parseSync(input)

// returns an array like this:
// [
//   {
//     type: 'cue',
//     data: {
//       start: 20000, // milliseconds
//       end: 24400,
//       text: 'Bla Bla Bla Bla'
//     }
//   },
//   {
//     type: 'cue',
//     data: {
//       start: 24600,
//       end: 27800,
//       text: 'Bla Bla Bla Bla',
//       settings: 'align:middle line:90%'
//     }
//   },
//   // ...
// ]
```

--------------------------------

### Synchronous Subtitle Stringifying

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Convert an array of subtitle nodes into a string format (SRT or WebVTT) synchronously. For performance, prefer the stream-based `stringify` function.

```typescript
import { stringifySync } from 'subtitle'

stringifySync(nodes, { format: 'SRT' })
// returns a string in SRT format

stringifySync(nodes, { format: 'WebVTT' })
// returns a string in VTT format
```

--------------------------------

### map(callback) — Transform nodes in a stream

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Returns a Transform stream that applies a callback to every Node in the stream, similar to Array.map. Receives the node and its index.

```APIDOC
## map(callback)

### Description
Returns a Transform stream that applies a callback to every `Node` in the stream, similar to `Array.map`. Receives the node and its index. The returned value from the callback is passed downstream.

### Method
Stream Transform

### Parameters
- **callback** (function) - Required - A function that takes a `node` and its `index` and returns a transformed `Node` or the original `Node`.
  - **node** (Node) - The current subtitle node being processed.
  - **index** (number) - The index of the current node.

### Request Example
```ts
import fs from 'fs'
import { parse, map, stringify } from 'subtitle'

fs.createReadStream('./movie.srt')
  .pipe(parse())
  .pipe(
    map((node, index) => {
      if (node.type === 'cue') {
        return {
          ...node,
          data: {
            ...node.data,
            text: node.data.text.toUpperCase()
          }
        }
      }
      return node
    })
  )
  .pipe(stringify({ format: 'SRT' }))
  .pipe(fs.createWriteStream('./uppercase.srt'))
```

### Response
#### Success Response
Emits transformed `Node` objects downstream.

#### Response Example
```json
{
  "type": "cue",
  "data": {
    "start": 20000,
    "end": 24400,
    "text": "BLA BLA BLA BLA"
  }
}
```
```

--------------------------------

### formatTimestamp

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Formats a timestamp given in milliseconds into a string representation, supporting both SRT and WebVTT formats.

```APIDOC
## formatTimestamp

### Description
It receives a timestamp in milliseconds and returns it formatted as SRT or VTT.

### Method Signature
`formatTimestamp(timestamp: number, options?: { format: 'SRT' | 'WebVTT' }): string`

### Usage Example
```ts
import { formatTimestamp } from 'subtitle'

formatTimestamp(142542)
// => '00:02:22,542'

formatTimestamp(142542, { format: 'WebVTT' })
// => '00:02:22.542'
```
```

--------------------------------

### parseTimestamp

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Parses a timestamp string in either SRT or VTT format and returns its value in milliseconds.

```APIDOC
## parseTimestamp

### Description
Receives a timestamp (SRT or VTT) and returns its value in milliseconds.

### Method Signature
`parseTimestamp(timestamp: string): number`

### Usage Example
```ts
import { parseTimestamp } from 'subtitle'

parseTimestamp('00:00:24,400')
// => 24400

parseTimestamp('00:24.400')
// => 24400
```
```

--------------------------------

### Resync Subtitle Stream

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Resync all cues in a subtitle stream by a specified time offset. Positive values advance subtitles, while negative values delay them.

```typescript
import { parse, resync, stringify } from 'subtitle'

// Advance subtitles by 1s
readableStream
  .pipe(parse())
  .pipe(resync(1000))
  .pipe(outputStream)

// Delay 250ms
stream.pipe(resync(captions, -250))
```

--------------------------------

### formatTimestamp

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Formats a timestamp in milliseconds into a string representation (e.g., 'HH:MM:SS.ms').

```APIDOC
## formatTimestamp

### Description
Formats a timestamp in milliseconds into a string representation.

### Method
`formatTimestamp(milliseconds: number): string`
```

--------------------------------

### Filter subtitle nodes using a callback

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Use this stream to filter out subtitle nodes based on a condition. Nodes for which the callback returns false are dropped. Ensure all necessary modules are imported.

```typescript
import fs from 'fs'
import { parse, filter, stringify } from 'subtitle'

// Remove all cues containing music notes and keep only spoken dialogue
fs.createReadStream('./movie.srt')
  .pipe(parse())
  .pipe(
    filter((node) => {
      if (node.type === 'cue') {
        // Exclude music/song cues
        return !node.data.text.includes('♪') && !node.data.text.includes('𝅘𝅥𝅮')
      }
      return true // always keep header nodes
    })
  )
  .pipe(stringify({ format: 'SRT' }))
  .pipe(fs.createWriteStream('./dialogue-only.srt'))
```

--------------------------------

### parseTimestamp

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Parses a timestamp string (e.g., '00:01:23,456') into milliseconds.

```APIDOC
## parseTimestamp

### Description
Parses a timestamp string into milliseconds.

### Method
`parseTimestamp(timestamp: string): number`
```

--------------------------------

### Parse Subtitle Nodes with Event Handlers

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Parse subtitle content using the stream-based `parse` function and attach event listeners for 'data', 'error', and 'finish' events to process each node as it arrives.

```typescript
import { parse } from 'subtitle'

inputStream
  .pipe(parse())
  .on('data', node => {
    console.log('parsed node:', node)
  })
  .on('error', console.error)
  .on('finish', () => console.log('parser has finished'))
```

--------------------------------

### Resync subtitle timestamps by a specified time offset

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Apply a time offset to all cue timestamps. Positive values advance subtitles, negative values delay them. Supports different output formats like SRT and WebVTT.

```typescript
import fs from 'fs'
import { parse, resync, stringify } from 'subtitle'

// Advance subtitles by 1.5 seconds (fix early subtitles)
fs.createReadStream('./out-of-sync.srt')
  .pipe(parse())
  .pipe(resync(1500))
  .pipe(stringify({ format: 'SRT' }))
  .pipe(fs.createWriteStream('./synced.srt'))

// Delay subtitles by 250ms (fix subtitles that appear too early)
fs.createReadStream('./out-of-sync.srt')
  .pipe(parse())
  .pipe(resync(-250))
  .pipe(stringify({ format: 'WebVTT' }))
  .pipe(fs.createWriteStream('./synced.vtt'))
```

--------------------------------

### parseTimestamps

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Parses multiple timestamp strings from a given input string into milliseconds.

```APIDOC
## parseTimestamps

### Description
Parses multiple timestamp strings from a given input string into milliseconds.

### Method
`parseTimestamps(input: string): number[]`
```

--------------------------------

### Format Timestamp from Milliseconds

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Formats a timestamp given in milliseconds into a string representation. Supports both SRT and WebVTT formats.

```typescript
import { formatTimestamp } from 'subtitle'

formatTimestamp(142542)
// => '00:02:22,542'

formatTimestamp(142542, { format: 'WebVTT' })
// => '00:02:22.542'
```

--------------------------------

### Parse SRT or VTT timestamp string to milliseconds

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Converts a single timestamp string (e.g., 'HH:MM:SS,mmm' or 'HH:MM:SS.mmm') into milliseconds. Throws an error for invalid formats. Handles both SRT and VTT formats, including VTT's short format.

```typescript
import { parseTimestamp } from 'subtitle'

parseTimestamp('00:00:24,400')   // => 24400
parseTimestamp('00:02:22,542')   // => 142542
parseTimestamp('00:24.400')      // => 24400 (VTT short format)
parseTimestamp('01:00:00,000')   // => 3600000

try {
  parseTimestamp('invalid')
} catch (err) {
  console.error(err.message)
  // => 'Invalid SRT or VTT time format: "invalid"'
}
```

--------------------------------

### filter(callback)

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Returns a Transform stream that passes only nodes for which the callback returns true, similar to Array.filter. Nodes returning false are dropped from the stream.

```APIDOC
## filter(callback)

### Description
Returns a Transform stream that passes only nodes for which the callback returns `true`, similar to `Array.filter`. Nodes returning `false` are dropped from the stream.

### Parameters
#### Callback Function
- **callback** (function) - Required - A function that accepts a node and returns a boolean. `true` to keep the node, `false` to drop it.

### Example
```ts
import fs from 'fs'
import { parse, filter, stringify } from 'subtitle'

// Remove all cues containing music notes and keep only spoken dialogue
fs.createReadStream('./movie.srt')
  .pipe(parse())
  .pipe(
    filter((node) => {
      if (node.type === 'cue') {
        // Exclude music/song cues
        return !node.data.text.includes('♪') && !node.data.text.includes('𝅘𝅥𝅮')
      }
      return true // always keep header nodes
    })
  )
  .pipe(stringify({ format: 'SRT' }))
  .pipe(fs.createWriteStream('./dialogue-only.srt'))
```
```

--------------------------------

### Transform Nodes in a Stream with `map()`

Source: https://context7.com/gsantiago/subtitle.js/llms.txt

Use `map()` to apply a callback function to each Node in a stream, similar to `Array.map`. The callback receives the node and its index.

```typescript
import fs from 'fs'
import { parse, map, stringify } from 'subtitle'

// Convert all subtitle text to uppercase
fs.createReadStream('./movie.srt')
  .pipe(parse())
  .pipe(
    map((node, index) => {
      if (node.type === 'cue') {
        return {
          ...node,
          data: {
            ...node.data,
            text: node.data.text.toUpperCase()
          }
        }
      }
      return node
    })
  )
  .pipe(stringify({ format: 'SRT' }))
  .pipe(fs.createWriteStream('./uppercase.srt'))
```

--------------------------------

### map

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

A Duplex stream utility for manipulating parsed nodes, similar to `Array.map`. It applies a callback function to each node in the stream, allowing for transformations.

```APIDOC
## map

### Description
A useful Duplex for manipulating parsed nodes. It works similar to the `Array.map` function, but for streams.

### Method
`map(callback: function): DuplexStream`

### Usage Example
```ts
import { parse, map, stringify } from 'subtitle'

inputStream
  .pipe(parse())
  .pipe(
    map((node, index) => {
      if (node.type === 'cue') {
        node.data.text = node.data.text.toUpperCase()
      }
      return node
    })
  )
  .pipe(stringify({ format: 'SRT' }))
  .pipe(outputStream)
```
```

--------------------------------

### Parse SRT or VTT Timestamp to Milliseconds

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Converts a timestamp string from SRT or VTT format into milliseconds. Handles both common timestamp formats.

```typescript
import { parseTimestamp } from 'subtitle'

parseTimestamp('00:00:24,400')
// => 24400

parseTimestamp('00:24.400')
// => 24400
```

--------------------------------

### filter

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

A Duplex stream for filtering parsed subtitle nodes, similar to Array.filter but for streams. It allows for conditional removal of nodes based on a callback function.

```APIDOC
## filter

### Description
A useful Duplex for filtering parsed nodes. It works similar to the `Array.filter` function, but for streams.

### Method Signature
`filter(callback: function): DuplexStream`

### Usage Example
```ts
import { parse, filter, stringify } from 'subtitle'

inputStream
  .pipe(parse())
  .pipe(
    filter((node, index) => {
      return !(node.type === 'cue' && node.data.text.includes('𝅘𝅥𝅮'))
    })
  )
  .pipe(stringify({ format: 'SRT' }))
  .pipe(outputStream)
```
```

--------------------------------

### filter

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

A Duplex stream utility for filtering parsed nodes. It works similarly to `Array.filter`, allowing nodes to be selectively passed through the stream based on a condition.

```APIDOC
## filter

### Description
A Duplex stream for filtering parsed nodes based on a provided condition.

### Method
`filter(callback: function): DuplexStream`

### Usage Example
```ts
import { parse, filter, stringify } from 'subtitle'

inputStream
  .pipe(parse())
  .pipe(
    filter(
      // strips all cues that contains "𝅘𝅥𝅮"
      node => !(node.type === 'cue' && node.data.text.includes('𝅘𝅥𝅮'))
    )
  )
  .pipe(stringify({ format: 'WebVTT' }))
  .pipe(outputStream)
```
```

--------------------------------

### Filter Subtitle Nodes

Source: https://github.com/gsantiago/subtitle.js/blob/master/README.md

Use this Duplex stream to filter parsed subtitle nodes, similar to Array.filter. It's useful for removing specific cues, like those containing musical notes.

```typescript
import { parse, filter, stringify } from 'subtitle'

inputStream
  .pipe(parse())
  .pipe(
    filter((node, index) => {
      return !(node.type === 'cue' && node.data.text.includes('𝅘𝅥𝅮'))
    })
  )
  .pipe(stringify({ format: 'SRT' }))
  .pipe(outputStream)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.