@ceeblue/videojs-plugins v1.0.1
videojs-plugins
Set of Videojs plugins 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
Download the package from @ceeblue/videojs-plugins or build it manually from the github sources :
npm install
npm run build
Include @ceeblue/videojs-plugins in your HTML code as usual with the link to Videojs and this library.
Example :
<script src="https://vjs.zencdn.net/8.7.0/video.min.js"></script>
<script src="./dist/videojs-plugins.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.
iceserver
Ice-server structure in JSON string format with TURN URL used to establish the WebRTC connection, mainly for TCP fallback.
Do not enclose the object in an array. If you have multiple TURN servers, you can add them in the
urls
array. If not set, the plugin will use the default TURN server of the Ceeblue Cloud.
Example:
Replace
<ceeblue-host>
by your endpoint hostname
{
"urls": ["turn:<ceeblue-host>?transport=tcp", "turn:<ceeblue-host>:3478"],
"username": "csc_demo",
"credential": "UtrAFClFFO"
}
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.
Example:
Replace
<ceeblue-host>
by your endpoint hostname and<streamId>
by your stream name.
<script type="module">
import {} from "/path/to/video.min.js";
import {} from "/path/to/ceeblue/videojs-plugins.min.js";
...
const player = videojs('video-tag');
player.src({
src: 'wss://<ceeblue-host>/<streamId>',
iceserver: '{
"urls": ["turn:<ceeblue-host>?transport=tcp", "turn:<ceeblue-host>:3478"],
"username": "csc_demo",
"credential": "UtrAFClFFO"
}',
audiobutton: true,
data: false
});
player.start();
</script>
<source>
HTML tag
The WebRTC source can be set directly in the HTML Source tag.
Example:
Replace
<ceeblue-host>
by your endpoint hostname and<streamId>
by your stream name.
<script src="//path/to/video.min.js"></script>
<script src="//path/to/ceeblue/videojs-plugins.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://<ceeblue-host>/webrtc/<streamId>"
iceserver='{"urls": ["turn:<ceeblue-host>?transport=tcp", "turn:<ceeblue-host>:3478"], "username": "csc_demo", "credential": "UtrAFClFFO"}'>
</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
only takes one argument : the videojs player.
To start the SourceController
call the start()
function with the following arguments :
- The
ConnectParams
structure containing the host, the stream name, the access token (optional) and the query parameters (optional), - The list of sources in order of priority. A source can be a string from the
SourceType
list or a Source Object in order to set custom options.
See
SourceType
object in SourceController.js which defines the list of possible sources, The Source Object must contain thesrc
field and thetype
field set to the MIME-type of the source (empty for WebRTC, see WebRTCSource).
Example:
Replace
<ceeblue-host>
by your endpoint hostname and<streamId>
by your stream name.
const sourceController = new SourceController(
player
);
sourceController.on('sourcechanged', (source) => {
console.log('sourcechanged', source); // null means no more sources available
});
sourceController.start(
{
host: '<ceeblue-host>',
streamName: '<streamId>'
query: 'id=<accessToken>'
},
[
{
// A WebRTC source with custom options
src: 'wss://<ceeblue-host>/<streamId>',
iceserver: '{"urls": ["turn:<ceeblue-host>?transport=tcp", "turn:<ceeblue-host>:3478"], "username": "csc_demo", "credential": "UtrAFClFFO"}',
},
'llhls',
'dash',
{
// A fallback source with a custom type
src: 'http://vjs.zencdn.net/v/oceans.mp4',
type: 'video/mp4'
}
]);
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 using SourceController with default parameters.
- webrtc-player.html : A simple example with a WebRTC source configured with the HTML
<source>
tag.
In all examples you can find the HTML code to include the library and the player, and the JavaScript code to configure the player. You can set query parameters in the URL to test the different options. For example :
Replace
<ceeblue-host>
by your endpoint hostname,<streamId>
by your stream name and replace<accessToken>
by the viewer access token given by Ceeblue Cloud API (optional, only if the stream is private).
https://localhost:8080/examples/player.html?host=<ceeblue-host>&stream=<streamId>&token=<accessToken>
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.