@ceeblue/videojs-plugin v1.0.1

videojs-plugin

Videojs plugin for playing streams from the Ceeblue cloud.

This plugin contains :

• WebRTCSource, a Videojs WebRTC playback source handler supporting WHEP and the Ceeblue WebSocket custom signaling,
• QualityButton, a plugin to select the video quality for any kind of source implementing videojs-contrib-quality-levels,
• SourceController, a utility class to switch automatically from one Ceeblue source to another (including WebRTC, HLS, LLHLS and DASH).

Table of Contents

• Installation
• WebRTCSource
  • Parameters
    • src
    • type
    • iceservers
    • audiobutton
    • data
  • Source Object
  • <source> HTML tag
• QualityButton
• SourceController
  • Example
  • Disabling QualityButton
• Examples
• License

Installation

Download the package from @ceeblue/videojs-plugin or build it manually from the github sources :

npm install
npm run build

Include @ceeblue/videojs-plugin on your website as usual with the link to this library.

Note that you need to include first Videojs.

Example :

<script src="https://vjs.zencdn.net/8.6.1/video.min.js"></script>
<script src="./dist/videojs-plugin.js"></script>

WebRTCSource

Parameters

src

The src field contains the URL of the WebRTC endpoint.

The protocol can be WebSocket (wss) to get the best of the custom Ceeblue signaling or HTTP (https) to use the standard WHEP signaling protocol.

Here is the expected format :

[wss|https]://<ceeblue-host>[/<pathname>]/<streamId>[?id=<token>][&audio=<audioTrackId>][&video=<videoTrackId>]

And here is an example of a complete WebSocket URL:

wss://la-8.live.ceeblue.tv/as+12346f7c-e5db-450b-9603-c3644274779b

The following options can be set in the query:

• id : The string token in case the stream is private.

• audio : the audio track ID or none to disable audio.

• video : the video track ID or none to disable video.

type

It is important for the mime-type to be empty to use the WebRTC source.

iceservers

Ice-servers (STUN, TURN) structure in JSON string format to establish a WebRTC connection.

Note: Do not enclose the object in an array.

Example:

'{ "urls": "stun:stun1.l.google.com:19302" }'

audiobutton

false to disable the WebRTC audio track selection button, true by default.

data

true to listen to all timed metadata tracks, false otherwise. true by default.

This has no effect on the player, to get the timed metadatas in your application you must use the textTracks() API of Videojs, you can check examples/player.html for an example of usage.

Source Object

Call the player.src() method with a WebRTC URL, for example :

<script type="module">
  import {} from "/path/to/video.min.js";
  import {} from "/path/to/ceeblue/videojs-plugin.min.js";
  ...
  const player = videojs('video-tag');
  player.src({
    src: 'wss://la-8.live.ceeblue.tv/as+12346f7c-e5db-450b-9603-c3644274779b',
    iceservers: '{ "urls": "stun:stun1.l.google.com:19302" }',
    audiobutton: true,
    data: false
  });
  player.start();
</script>

<source> HTML tag

The WebRTC source can be set directly in the source tag of the video like this:

<script src="//path/to/video.min.js"></script>
<script src="//path/to/ceeblue/videojs-plugin.min.js"></script>

<div id="video_container">
    <video id=video-player width=960 height=540 class="video-js vjs-default-skin" controls>
        <source src="wss://la-8.live.ceeblue.tv/webrtc/as+12346f7c-e5db-450b-9603-c3644274779b" 
            iceServers = '[ { "urls": "stun:stun1.l.google.com:19302" } ]'>
    </video>
</div>
<script>
  var player = videojs('video-player');
</script>

QualityButton

If you are not using the SourceController, the QualityButton plugin can be called with a simple command to create the video menu button using the qualityLevels of the current source (see videojs-contrib-quality-levels):

<script>
  var player = videojs('video-player');
  player.qualityButton();
</script>

SourceController

The SourceController allows to configure fallback sources when the current source is not working (for example if WebRTC is not supported in the browser). It is also suited to switch smoothly from one source to the other.

The constructor of SourceController takes a serie of arguments :

• The video.js player itself which must be initialized,
• The ConnectParams structure containing the host, the streamName, the accessToken (optional) and the query parameters (optional),
• The list of sources in order of priority. See SourceType object in SourceController.js which defines the list of possible sources,
• The WebRTCSource options if WebRTC is enabled.

Example

  const sourceController = new SourceController(
    player, 
    {
      host: 'localhost',
      streamName: 'test'
    }, 
    ['webrtc', 'llhls', 'dash', 'hls'], 
    {
      iceservers: { urls: 'stun:stun1.l.google.com:19302' },
      audiobutton: true,
      data: true
    }
  );
  sourceController.on('sourcechanged', (source) => {
    console.log('sourcechanged', source); // null means no more sources available
  });
  sourceController.start();

Disabling QualityButton

By default the SourceController creates a QualityButton for the current source but you can disable it in the player's options with the qualityButton option:

const player = videojs(videoEl, { qualityButton: false});

Examples

You can find examples of players in the examples/ directory :

• player.html : The most advanced example which use WebRTC, the SourceController, and the QualityButton, with a complete UI for setting parameters and showing timed metadatas.
• simple-player.html : A simple example with a WebRTC source configured with the HTML <source> tag.

Documentation

This monorepo also contains built-in documentation about the APIs in the library, which can be built using the following npm command:

npm run docs

You can access the documentation by opening the index.html file in the docs folder with your browser (./docs/api/index.html).

Contribution

All contributions are welcome. Please see our contribution guide for details.

License

By contributing code to this project, you agree to license your contribution under the GNU Affero General Public License.