Subforge

High-performance subtitle toolkit for parsing, converting, and authoring across 20+ formats.

Highlights

• Unified document model with explicit feature loss tracking
• Parsers and serializers for text, XML, binary, and broadcast formats
• Fast paths for large subtitle collections
• Universal ESM build for browsers, Node, and Bun

Installation

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)

Use subpath entry points to keep imports small:

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

Parsing

All parsers return a ParseResult so you can choose strict or best-effort flows:

import { parseSRT } from 'subforge/srt'
import { unwrap } from 'subforge/core'

const result = parseSRT(srtText)
const doc = unwrap(result)

Conversion

import { convert } from 'subforge/core'

const result = convert(doc, {
  to: 'vtt',
  karaoke: 'strip',
  positioning: 'strip',
  reportLoss: true
})

console.log(result.lostFeatures)

Bitmap formats

PGS, DVB, and VobSub store image payloads on event.image and 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)

Browser usage

Build the universal ESM bundle:

bun run build

Then import from dist/:

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

Formats

Subpath entry points: core, ass, ssa, srt, vtt, sbv, lrc, microdvd, ttml, sami, realtext, qt, stl, pgs, dvb, vobsub, pac, scc, cap, teletext.

Commands

bun test
bun run build
bun run bench

Documentation

Live docs: subforge.pages.dev

VitePress source is in docs/:

bun run docs:dev
bun run docs:build
bun run docs:preview

License

MIT