| 1 | # node-m3u8stream
|
| 2 |
|
| 3 | Reads segments from a [m3u8 playlist][1] or [DASH MPD file][2] into a consumable stream.
|
| 4 |
|
| 5 | [1]: https://tools.ietf.org/html/draft-pantos-http-live-streaming-20
|
| 6 | [2]: https://dashif.org/docs/DASH-IF-IOP-v4.2-clean.pdf
|
| 7 |
|
| 8 | [](https://david-dm.org/fent/node-m3u8stream)
|
| 9 | [](https://codecov.io/gh/fent/node-m3u8stream)
|
| 10 |
|
| 11 |
|
| 12 | # Usage
|
| 13 |
|
| 14 | ```js
|
| 15 | const fs = require('fs');
|
| 16 | const m3u8stream = require('m3u8stream')
|
| 17 |
|
| 18 | m3u8stream('http://somesite.com/link/to/the/playlist.m3u8')
|
| 19 | .pipe(fs.createWriteStream('videofile.mp4'));
|
| 20 | ```
|
| 21 |
|
| 22 |
|
| 23 | # API
|
| 24 |
|
| 25 | ### m3u8stream(url, [options])
|
| 26 |
|
| 27 | Creates a readable stream of binary media data. `options` can have the following
|
| 28 |
|
| 29 | * `begin` - Where to begin playing the video. Accepts an absolute unix timestamp or date, and a relative time in the formats `1:23:45.123` and `1m2s`.
|
| 30 | * `liveBuffer` - How much buffer in milliseconds to have for live streams. Default is `20000`.
|
| 31 | * `chunkReadahead` - How many chunks to preload ahead. Default is `3`.
|
| 32 | * `highWaterMark` - How much of the download to buffer into the stream. See [node's docs](https://nodejs.org/api/stream.html#stream_constructor_new_stream_writable_options) for more. Note that the actual amount buffered can be higher since each chunk request maintains its own buffer.
|
| 33 | * `requestOptions` - Any options you want to pass to [miniget](https://github.com/fent/node-miniget), such as `headers`.
|
| 34 | * `parser` - Either "m3u8" or "dash-mpd". Defaults to guessing based on the playlist url ending in `.m3u8` or `.mpd`.
|
| 35 | * `id` - For playlist containing multiple media options. If not given, the first representation will be picked.
|
| 36 |
|
| 37 | ### Stream#end()
|
| 38 |
|
| 39 | If called, stops requesting segments, and refreshing the playlist.
|
| 40 |
|
| 41 | #### Event: progress
|
| 42 | * `Object` - Current segment with the following fields,
|
| 43 | - `number` - number
|
| 44 | - `number` - size
|
| 45 | - `number` - duration
|
| 46 | - `string` - url
|
| 47 | * `number` - Total number of segments.
|
| 48 | * `number` - Bytes downloaded up to this point.
|
| 49 |
|
| 50 | For static non-live playlists, emitted each time a segment has finished downloading. Since total download size is unknown until all segment endpoints are hit, progress is calculated based on how many segments are available.
|
| 51 |
|
| 52 | ### Limitations
|
| 53 |
|
| 54 | Currently, it does not support [encrypted media segments](https://tools.ietf.org/html/draft-pantos-http-live-streaming-20#section-4.3.2.4). This is because the sites where this was tested on and intended for, YouTube and Twitch, don't use it.
|
| 55 |
|
| 56 | This does not parse master playlists, only media playlists. If you want to parse a master playlist to get links to media playlists, you can try the [m3u8 module](https://github.com/tedconf/node-m3u8).
|
| 57 |
|
| 58 |
|
| 59 | # Install
|
| 60 |
|
| 61 | npm install m3u8stream
|
| 62 |
|
| 63 |
|
| 64 | # Tests
|
| 65 | Tests are written with [mocha](https://mochajs.org)
|
| 66 |
|
| 67 | ```bash
|
| 68 | npm test
|
| 69 | ```
|