Getting Started

Subforge is a high-performance TypeScript subtitle library. It provides a common document model, fast parsers, and serializers for a wide range of subtitle formats.

Install

bun add subforge

npm install subforge

pnpm add subforge

Quickstart

import { parseSRT, toASS } from 'subforge'
import { unwrap } from 'subforge/core'

const doc = unwrap(parseSRT('1\n00:00:01,000 --> 00:00:02,000\nHello\n'))
const ass = toASS(doc)

Bitmap formats

For bitmap formats (PGS, DVB, VobSub), image payloads live on event.image with metadata on event.pgs or event.vobsub.

import { parseVobSub, parseIdx } from 'subforge/vobsub'
import { unwrap } from 'subforge/core'

const idx = await fetch('/subs.idx').then(r => r.text())
const sub = new Uint8Array(await fetch('/subs.sub').then(r => r.arrayBuffer()))
const index = parseIdx(idx)
const doc = unwrap(parseVobSub(index, sub))

const first = doc.events[0]
console.log(first.image?.width, first.image?.height)

Use only what you need

Subpath entry points keep imports small:

import { parseASS } from 'subforge/ass'
import { parseSRT } from 'subforge/srt'
import { SubtitleDocument, unwrap } from 'subforge/core'

Build for browsers

The repository ships a Bun build pipeline that produces a universal ESM bundle in dist/.

bun run build

Then import from dist/ in the browser:

<script type="module">
  import { parseSRT } from './dist/index.js'
  const result = parseSRT('1\n00:00:01,000 --> 00:00:02,000\nHello\n')
  console.log(result.document.events.length)
</script>

Where to go next

• Document model: see Document Model
• Parsing: see Parsing
• Serialization: see Serialization
• Supported formats: see Formats