flussonic-webrtc-player
Flussonic WebRTC Player is a JavaScript library for publishing and playing video via WebRTC. It relies on Flussonic backend, HTML5 video and WebRTC.
Install it in your project and use in your website or application to exchange video via WebRTC with Flussonic.
The library contains classes:
-
Publisher
for video publication from your app to Flussonic Media Server. -
Player
for playback of published video in your app.
Installation
Install flussonic-webrtc-player
from NPM by running the command:
npm install --save @flussonic/flussonic-webrtc-player
Publisher
Used to stream video via WebRTC from a client app to other clients through Flussonic.
Usage
With webpack
import {
Publisher,
PUBLISHER_EVENTS,
PUBLISHER_STATUSES,
} from '@flussonic/flussonic-webrtc-player';
// ...
const publisher = new Publisher(url, opts, shouldLog);
With script tag:
<script type="text/javascript" src="../../dist/index.js"></script>
<script>
const { Publisher, PUBLISHER_EVENTS, PUBLISHER_STATUSES } =
window.FlussonicWebRTCPlayer;
// ...
const publisher = Publisher(url, opts, shouldLog);
</script>
Where:
url
- a stream's URL.
opts
- a plain object, it can include:
-
preview?: HTMLMediaElement
- if passed, then shows preview before the stream is loaded. This is an element in which you can output a published stream without creating a separate player listening to the same stream. -
previewOptions?: object
- preview options object. -
previewOptions?.autoplay?
- iftrue
, the playback of the preview will start automatically. -
previewOptions?.controls?
- iftrue
, the preview will have controls. -
previewOptions?.muted?
- iftrue
, the preview will be muted. -
constraints
- MediaStreamConstraints. -
onWebsocketClose()
- triggered when the WebSocket connection is closed. -
shouldLog
- if passed, internal events will be logged to console (true
|false
). -
returnCapabilities()
- callback for getting video device capabilities. -
whipwhap
- enables WHIP/WHAP protocol (true
|false
). -
password
- pass a stream password. -
authTokenName
- set a custom password token name -
tokenValue
- set a token value -
canvasCallback
- callback function than enables both canvas preview and canvas publish. Returns a canvas html element that you can modify in realtime to add some video effects to publishing video stream. -
radeonCheck
- Enable workaround for the issue when some AMD Radeon(tm) publish with a low bitrate. This is experimental option, will be redesigned.
Fields
-
status - the status of a current publisher, possible values are
'initializing'|'streaming'|'stopped'
.
Methods
-
start(opts) - starts publication and sets the current publisher's
status
tostreaming
.
start(opts?: {
openPeerConnectionOptions?: {
getMediaOptions?: {
// Called if mediaDevices.getUserMedia fails
onGetUserMediaError: (error: Error) => void
}
}
}) => void
-
stop() - stops stream's tracks; closes a WebSocket connection; sets the current publisher status to
stopped
. -
on(event, cb) - subscribes for
event
with the callbackcb
. Events are listed below:-
STREAMING
- runs when an ICE candidate is received and the streaming is started.
-
-
onEvent() - Publisher events callback. For tracking connection states and player workflow. Events are listed below:
-
{ type: 'started', started_at: #Date# }
- runs when the streaming is started. -
{ type: 'closed', closed_at: #Date# }
- runs when the streaming is closed. -
{type: 'connection state', connection: 'connected' }
- runs when connection state changes. States are listed below:-
opened
- when connection is opened -
connected
- when ICE candidates is connected -
closed
- when user performed connection close -
disconnected
- when server side closed ICE candidates connection
-
-
Example
import {
Publisher,
PUBLISHER_EVENTS,
PUBLISHER_STATUSES,
} from '@flussonic/flussonic-webrtc-player';
const publisher = new Publisher(
// The URL to a Flussonic stream that has a published source
'https://FLUSSONIC_IP/STREAM_NAME',
{
// A <video> or <audio> element for previewing a published stream
preview: document.getElementById('preview'),
previewOptions: {
autoplay: true,
controls: true,
muted: false,
},
constraints: {
video: {
width: { min: 320, ideal: 1920, max: 4096 },
height: { min: 240, ideal: 1080, max: 2160 },
},
audio: true,
},
onWebsocketClose: () => console.log('Publishing socket closed'),
},
// Log to console the Publisher's internal debug messages?
true,
);
publisher.on(PUBLISHER_EVENTS.STREAMING, () => {
console.log('Streaming started');
});
publisher.start();
// ...
publisher.stop();
Player
Used for playing back video from Flussonic via WebRTC on a client.
Usage
With webpack
import { Player, PLAYER_EVENTS } from '@flussonic/flussonic-webrtc-player';
// ...
const player = new Player(element, url, opts, shouldLog);
With script tag:
<script type="text/javascript" src="../../dist/index.js"></script>
<script>
const { Player, PLAYER_EVENTS } = window.FlussonicWebRTCPlayer;
// ...
const player = new Player(element, url, opts, shouldLog);
</script>
Where:
element
- a <video>
DOM element used for viewing a stream.
url
- the stream's URL.
opts
- a plain object, it can include options:
-
autoplay
- starts playback automatically (true
|false
). -
shouldLog
- if passed, internal events will be logged to console (true
|false
). -
onMediaInfo(tracks, abr)
- returns MediaInfo object with tracks information, and ABR(Adaptive Bitrate Streaming) indication flag -
onTrackInfo(trackInfo)
- returns a track info on track change, useful for ABR mode info -
onEvent()
- Player events callback. -
whipwhap
- enables WHIP/WHAP protocol (true
|false
). -
authTokenName
- set a custom password token name -
tokenValue
- set a token value
Methods
-
play() - starts the playback.
-
changeTracks(['v1','a1']) - manualy change tracks. Can be [] or 'auto', if source has ABR. Tracklist and abr flag can be achieved by using onMediaInfo callback.
-
stop() - stops the playback, closes the WebSocket connection, sets
srcObject
of<video>
to null. -
destroy() - calls
stop()
and unbinds all listeners. -
on(event, cb) - subscribes for
event
with the callbackcb
. Events are listed below:-
FAIL
- when an error occurs, runs with the message that describes this error. -
PLAY
- runs when playback starts. -
DEBUG
- for development puproses.
-
Example
import { Player, PLAYER_EVENTS } from '@flussonic/flussonic-webrtc-player';
const player = new Player(
// A <video> or <audio> element to playback the stream from Flussonic
document.getElementById('player'),
// The URL of the stream from Flussonic
'https://FLUSSONIC_IP/STREAM_NAME',
// Options
{ autoplay: true },
// Log to console the Player's internal debug messages?
true,
);
player.on(PLAYER_EVENTS.PLAY, (msg) => console.log(`Play: ${msg}`));
player.on(PLAYER_EVENTS.DEBUG, (msg) => console.log(`Debug: ${msg}`));
player.play();
player.changeTracks('auto');
// ...
player.stop();
// ...
player.destroy();