@clockworkdog/media-stream-library-browser

Media Stream Library JS

Media Stream Library JS is an open-source JavaScript library to handle media stream transforms for Node & the Web. The primary purpose is to deal with RTP streams in a browser without the need to use plugins or Flash, but relying on the Media Source Extensions standard, which is supported in all modern browsers.

Although RTP streams is the main focus, the library is not limited to handling RTP streams, or to the browser. It is suited to handle streams of messages of any kind, and makes it easier to stitch together transformations from one message type to another. Contributions of new components/pipelines are always welcome.

Note for IE11 users: there is a legacy build available on the ie11 branch, where the bundle media-stream-library.legacy.min.js can be found. Although we don't support or test IE11, it should work. Note that the ie11 branch is maintenance only (dependencies will be kept up-to-date as much as possible). You can also bundle it yourself and be aware that certain dependencies (e.g. debug) have to be transpiled as they no longer ship es5 code. You can look at the webpack.legacy.config.js to see how we build the legacy bundle. Since IE11 is not supported or tested at all, you might run into different issues as well. We welcome contributions keeping the legacy bundle working, as long as it's limited to the webpack configuration.

Installation

Make sure you have Node installed on your machine.

Then, to install the library:

npm install media-stream-library

or if you are using yarn:

yarn add media-stream-library

Usage

This library is not a full media player: the framework provides no video controls, progress bar, or other features typically associated with a media player. For a simple React-based player we refer to the Media Stream Player library, which is built around this library.

However, getting video to play in the browser is quite easy (check the browser example). There are currently no codecs included either, we rely on browser support for that.

Although RTP streams is the main focus, the library is not limited to handling RTP streams, or to the browser. Its main focus is to handle streams of messages, and make it easier to stitch together transformations from one message type to another. Contributions of new components/pipelines are always welcome.

Importing

script tag You can directly include the media-stream-library.min.js file (located in the package dist folder) in your browser (check the browser example):

<script src="media-stream-library.min.js"></script>

in which case a global variable mediaStreamLibrary will exist that contains all the necessary functions.

bundler Alternatively, you can import it into your javascript code if you are going to bundle it yourself:

import {components, pipelines} from 'media-stream-library';

Note that we expose entry points for both node and the browser. Any bundler should be able to pick up the correct entry point from package.json. If not, then you can try importing from media-stream-library/dist/browser-esm instead. Since we no longer pre-bundle external dependencies, your bundler will have to handle this. It might be that you need to replace references to global with window because readable-streams (imported via stream-browserify) still refers to global.

Components and pipelines

The library contains a collection of components that can be connected together to form media pipelines. The components are a low-level abstraction on top of Node streams to allow two-way communication, while media pipelines are sets of connected components with methods that allow you to control the pipeline, and easily add/remove components.

Components can be categorized as:

• sources (socket, file, ...)
• transforms (parsers, depay, muxers, ...)
• sinks (HTML5 element, file, ...)

To build a pipeline, you can connect the required components. A number of common pipelines are exported directly for convenience.

Check the examples section to see how these can be used in your own code. To run the examples yourself, you'll need to clone this repository loccally and follow the developer instructions.

Debugging

In the browser, you can set localStorage.debug = 'msl:*' to log everything related to just this library (make sure to reload the page after setting the value).

Contributing

Please read our contributing guidelines before making pull requests.