plethoralabs / subtitle.js

Parse and manipulate SRT (SubRip)

subtitle.js

Parse, manipulate and stringify SRT (SubRip) format. WebVTT as input is also supported.

"Thanks for this rad package!"
John-David Dalton, creator of Lodash

Installation

npm install subtitle --save

Usage

// ES2015 modules
import * as Subtitle from 'subtitle'
import { parse, stringify, stringifyVtt, resync, toMS, toSrtTime, toVttTime } from 'subtitle'

// ES6 CommonJS
const Subtitle = require('subtitle')
const { parse, stringify, stringifyVtt, resync, toMS, toSrtTime, toVttTime } = require('subtitle')

// ES5 CommonJS
var Subtitle = require('subtitle')
Subtitle.parse
Subtitle.stringify
Subtitle.stringifyVtt
Subtitle.resync
Subtitle.toMS
Subtitle.toSrtTime
Subtitle.toVttTime

Browser

If you don't use a bundler like Webpack or Browserify, you can just copy the script subtitle.bundle.js from the dist folder and link it to your page.

<script src="path/to/subtitle.bundle.js"></script>
<script>
  // `Subtitle` will be globally available
  console.log(window.Subtitle)
  /*
    {
      parse: function parse()
      resync: function resync()
      stringify: function stringify()
      stringifyVtt: function stringifyVtt()
      toMS: function toMS()
      toSrtTime: function toSrtTime()
      toVttTime: function toVttTime()
  */
</script>

API

The API is minimal and provide only five functions, two of which have SRT and WebVTT variants:

• parse
• stringify
• stringifyVtt
• resync
• toMS
• toSrtTime
• toVttTime

parse(srt: String) -> Array

Parses a SRT or WebVTT string and returns an array:

parse(mySrtOrVttContent)
[
  {
    start: 20000, // time in ms
    end: 24400,
    text: 'Bla Bla Bla Bla'
  },
  {
    start: 24600,
    end: 27800,
    text: 'Bla Bla Bla Bla',
    settings: 'align:middle line:90%' // WebVTT only
  }
]

stringify(captions: Array) -> String

The reverse of parse. It gets an array with subtitles and converts it to a valid SRT string.

The stringifyVtt(captions: Array) -> String function is also available for converting to a valid WebVTT string.

const subtitles = [
  {
    start: '00:00:20,000',
    end: '00:00:24,400',
    text: 'Bla Bla Bla Bla'
  },
  {
    start: 24600, // timestamp in milliseconds is supported as well
    end: 27800,
    text: 'Bla Bla Bla Bla',
    settings: 'align:middle line:90%' // Ignored in SRT format
  }
]

const srt = stringify(subtitles)
// returns the following string:
/*
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
*/

const vtt = stringifyVtt(subtitles)
// returns the following string:
/*
WEBVTT

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

2
00:00:24.600 --> 00:00:27.800 align:middle line:90%
Bla Bla Bla Bla
*/

resync(captions: Array, time: Number) -> Object

Resync all captions at once.

const subtitles = [
  {
    start: '00:00:20,000',
    end: '00:00:24,400',
    text: 'Bla Bla Bla Bla'
  },
  {
    start: 24600, // timestamp in millseconds is supported as well
    end: 27800,
    text: 'Bla Bla Bla Bla'
  }
]

// Advance 1s
const newSubtitles = resync(subtitles, 1000)

// Delay 250ms
const newSubtitles = resync(subtitles, -250) //

// Then, you can stringify your new subtitles:
stringify(newSubtitles)

toMS(timestamp: String) -> Number

Convert a SRT or WebVTT timestamp to milliseconds:

toMS('00:00:24,400')
// 24400

toMS('00:24.400')
// 24400

toSrtTime(timestamp: Number) -> String

Convert a time from milliseconds to a SRT timestamp:

toSrtTime(24400)
// '00:00:24,400'

toVttTime(timestamp: Number) -> String

Convert a time from milliseconds to a WebVTT timestamp:

toVttTime(24400)
// '00:00:24.400'

Tests

Subtitle.js uses AVA for running tests and nyc for code coverage.

If you want to run these tests, you need to install all devDependencies:

npm install

Now you can run the tests with the following command:

npm test

Code Coverage

You can check the code coverage by running the following command:

npm run coverage

If you want a pretty HTML report, run the following:

npm run report

Your report will be available in the coverage folder.

License

MIT