# matroska-subtitles

> Streaming parser for embedded .mkv subtitles.

Latest version **3.3.2** (published 2021-09-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install matroska-subtitles
pnpm add matroska-subtitles
yarn add matroska-subtitles
bun add matroska-subtitles
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.3.2 |
| Published | 2021-09-20 |
| First published | 2016-06-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 922.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 46 |
| Author | Mathias Rasmussen |
| Maintainers | mathiasvr |
| Keywords | mkv, srt, matroska, subtitle, extract, parse, stream |

## Links

- npm: https://www.npmjs.com/package/matroska-subtitles
- Repository: https://github.com/mathiasvr/matroska-subtitles
- Homepage: https://github.com/mathiasvr/matroska-subtitles#readme
- Issues: https://github.com/mathiasvr/matroska-subtitles/issues
- npm.io page: https://npm.io/package/matroska-subtitles

## Dependencies (3)

- [pako](https://npm.io/package/pako.md) ^2.0.4
- [ebml-stream](https://npm.io/package/ebml-stream.md) ^1.0.3
- [readable-stream](https://npm.io/package/readable-stream.md) ^3.6.0

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 3.3.2 (latest) — 2021-09-20
- 3.3.1 — 2020-12-16
- 3.3.0 — 2020-11-22
- 3.2.3 — 2020-11-14
- 3.2.2 — 2020-11-10
- 3.2.1 — 2020-11-08
- 3.2.0 — 2020-10-25
- 3.1.0 — 2020-10-02
- 3.0.1 — 2020-09-27
- 3.0.0 — 2020-09-23
- 2.0.4 — 2020-09-10
- 2.0.3 — 2017-12-27
- 2.0.2 — 2017-12-27
- 2.0.1 — 2016-08-30
- 2.0.0 — 2016-08-20
- … 5 more at https://npm.io/package/matroska-subtitles/versions

## README

# matroska-subtitles

[![NPM](https://img.shields.io/npm/v/matroska-subtitles.svg?style=for-the-badge)](https://npm.im/matroska-subtitles)
![Downloads](https://img.shields.io/npm/dt/matroska-subtitles.svg?style=for-the-badge)
![Dependency status](https://img.shields.io/librariesio/release/npm/matroska-subtitles?style=for-the-badge)
[![License](https://img.shields.io/:license-MIT-blue.svg?style=for-the-badge)](https://mvr.mit-license.org)
[![forthebadge](https://forthebadge.com/images/badges/powered-by-coffee.svg)](https://forthebadge.com)

Streaming parser for embedded .mkv subtitles.

Supported formats: `.srt`, `.ssa`, `.ass`.

## install

```shell
$ npm install matroska-subtitles
```

or include it directly:
```html
<script src="https://cdn.jsdelivr.net/npm/matroska-subtitles@3.x/dist/matroska-subtitles.min.js"></script>
```

## example

```js
const fs = require('fs')
const { SubtitleParser } = require('matroska-subtitles')

const parser = new SubtitleParser()

// first an array of subtitle track information is emitted
parser.once('tracks', (tracks) => console.log(tracks))

// afterwards each subtitle is emitted
parser.on('subtitle', (subtitle, trackNumber) =>
  console.log('Track ' + trackNumber + ':', subtitle))

fs.createReadStream('Sintel.2010.720p.mkv').pipe(parser)
```

See [examples](https://github.com/mathiasvr/matroska-subtitles/tree/master/examples) folder for more examples.

### `tracks` event response format

```js
[
  { number: 3, language: 'eng', type: 'utf8', name: 'English(US)' },
  { number: 4, language: 'jpn', type: 'ass', header: '[Script Info]\r\n...' }
]
```

- The `language` attribute can be `undefined` if the mkv track does not specify it, this is often interpreted as `eng`.
- The `name` attribute is not standard but may provide language info.

### `subtitle` event response format

```js
{
  text: 'This blade has a dark past.',
  time: 107250,  // ms
  duration: 1970 // ms
}
```

## attached files
The parser now also has a `file` event that emits embedded mkv files, mainly to be used to extract embedded subtitle fonts.

```js
parser.on('file', file => console.log('file:', file))
```

Output:
```js
{
  filename: 'Arial.ttf',
  mimetype: 'application/x-truetype-font',
  data: Buffer() [Uint8Array]
}
```

## random access
This module also includes a `SubtitleStream` class for intercepting subtitles
in mkv streams with support for seeking.

```js
const { SubtitleStream } = require('matroska-subtitles')

let subtitleStream = new SubtitleStream()

subtitleStream.once('tracks', (tracks) => {
  // close the old subtitle stream and open a new at a different stream offset
  subtitleStream = new SubtitleStream(subtitleStream)
})
```

See [examples/random-access.js](examples/random-access.js) for a detailed example.

## see also 

[mkv-subtitle-extractor](https://npm.im/mkv-subtitle-extractor)

## license

MIT

---
_Source: https://npm.io/package/matroska-subtitles · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
