Getting started

📘

Before we start, you can find more information in the SDK Documentation, which contains more examples and descriptions of the available modules.

Importing the library

You can import the SDK through JSDELIVR CDN or via npm.

Import as script

Add this tag to your document's <head>:

<script src="https://cdn.jsdelivr.net/npm/@millicast/[email protected]/dist/millicast.umd.min.js"></script>

📘

For the latest version of the SDK and URL to use, check out the latest JSDELIVR CDN.

You can import in other formats like ESM besides UMD.

When the page loads and you import the script as UMD, the SDK modules become available to use through window.millicast variable.

Example of getting browser capabilities in UMD format:

const capabilities = window.millicast.PeerConnection.getCapabilities('video');
console.log(capabilities);

If you choose to import the script as ESM, you can use directly the modules with the import statement.

Example of getting browser capabilities in ESM format:

import { PeerConnection } from 'https://cdn.jsdelivr.net/npm/@millicast/[email protected]/dist/millicast.esm.js';

const capabilities = PeerConnection.getCapabilities('video');
console.log(capabilities);

Install as a dependency

Alternatively, if you are building an application with Node.js, you can install the SDK package:

npm i --save @millicast/sdk

And then using it with the import statement.

Example of getting browser capabilities using npm dependency:

import { PeerConnection } from '@millicast/sdk';

const capabilities = PeerConnection.getCapabilities('video');
console.log(capabilities);

Publish a stream

📘

You will need to find or create a new stream name with a token in your Dolby.io dashboard. You can do that following this link.

The main module to publish a stream is the Publish module.

Instance the Publish module

To create a new publisher, you have to instance the Publish class:

import { Director, Publish } from '@millicast/sdk';

const tokenGenerator = () => Director.getPublisher(
{
  token: 'my-publishing-token', 
  streamName: 'my-stream-name'
});
const publisher = new Publish('my-stream-name', tokenGenerator);

In order to create a Publish instance, you have to send two params.

  • The first one is the stream name ('my-stream-name') and it's used to set where do you want to publish your stream.
  • The second param is a callback (tokenGenerator) and it's used to get the necessary data of the stream name where you want to stream. Also, it's used to set auto reconnection if you are streaming and then lose connection. You have to set the stream name and the token of those.

More information here:

Get your media information

You should get the media information (camera/microphone) you want to stream with. To do that, the SDK uses MediaStream object.

In this example, we are going to get the default user camera and microphone:

const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });

This will ask permission in the browser to get the camera and microphone and it will save the mediaStream information if the user accepts.

More information about using user media here:

Initialize the stream

After all previous steps are completed, you can now initialize the stream using the .connect() method inside the Publish module.

Using the instanced Publisher and mediaStream, add the connect method:

//Publishing Options
const broadcastOptions = {
  mediaStream: mediaStream
};

//Start broadcast
try {
  await publisher.connect(broadcastOptions);
} catch (e) {
  console.log('Connection failed, handle error', e);
}

Once the .connect() promise resolves, the stream is initialized correctly, otherwise it'll throw an error.

The .connect() can optionally receive more params, all of these are described in the .connect() method.

For example:

  • If you want to start your stream with a bitrate limit, you can use the bandwidth option.
  • If your stream token in Dolby.io Real-time Streaming has the recording enabled, you can enable it with the record option. Once you have finished your stream, you can see the recording in the Dashboard Archive section.
  • You can start a stream without audio or video setting the disableAudio or disableVideo respectively.
  • You can select which codec you want to stream using the codec option. If you want to know the supported codecs of your browser, you can use .getCapabilities()
import { PeerConnection } from '@millicast/sdk';

const capabilities = PeerConnection.getCapabilities('video');
console.log(capabilities);

//Output:
//[
//    {
//        "codec": "vp8",
//        "mimeType": "video/VP8",
//    },
//     {
//         "codec": "vp9",
//         "mimeType": "video/VP9",
//     },
//     {
//         "codec": "h264",
//         "mimeType": "video/H264"
//     },
//     {
//         "codec": "av1",
//         "mimeType": "video/AV1",
//     }
//]

More information here:

Managing your active stream

📘

The next samples use the publisher variable we created in the past steps. Please follow the tutorial.

The Publish instance internally uses most of the classes described in the documentation.
If the method is not static (which means you can access it without a Publish instance), you can access it through the Publish instance.

Example:

publisher.signaling //corresponds to the Signaling module.
publisher.webRTCPeer //corresponds to the Peerconnection module.

Most of the important methods are located directly in the Publisher module but some are not, like updating the bitrate or getting the WebRTC stats.

Change bitrate

During an active stream, you can limit the maximum bitrate in kbps.
To do that, you have to use the .updateBitrate() method of your Publish instance that is located inside a subclass called webRTCPeer.

Example:

publisher.webRTCPeer.updateBitrate(2000); //set the active stream with 2000 kbps limit.

publisher.webRTCPeer.updateBitrate(0); //set the active stream with no limit.

More information here:

Stop stream

If you want to stop an active stream, you can use the .stop() method of your Publish instance.

Example:

publisher.stop();

More information here:

Viewer

📘

In order to connect to a stream you'll need the account id and stream name of the broadcast. This information must be provided by the publish owner. For more information, see Publishing API.

The main module to view a stream is the View module.

Instance the View module

Creating a new View instance:

import { Director, View } from '@millicast/sdk';

//Create callback to generate a new token
const tokenGenerator = ()  => Director.getSubscriber({
  streamName: 'publish-stream-name',
  streamAccountId: 'publish-account-id',
  subscriberToken: 'subscriber-token' //Optional: This token is needed if you're subscribing to a secure stream,
                                      //this token should be provided by the publish owner.
});

//Create millicast instance
const millicastView = new View('publish-stream-name', tokenGenerator);

Like when creating a Publish instance, in order to create a View instance you need two params and there's also an optional param.

  • The first one is the stream name ('my-stream-name') and it's used to set the stream you want to connect.
  • The second param is a callback (tokenGenerator) and it's used to get the necessary data of the stream name where you want to connect. Also, it's used to set auto reconnection if you are streaming and then lose connection. You have to set the stream name and the token of those.
  • (Optional) mediaElement. This is the HTML media element where you want to mount the stream for example a video element.
  • (Optional) autoReconnect. The Default value is true, enabling auto reconnect to stream.

More information here:

Track event

In case the mediaElement param is not specified when creating a View instance a track event will be emitted when the stream starts containing the media track.

//...
millicastView.on('track', (event) => {
  addStreamToYourVideoTag(event.streams[0]); //Manage the track event.
});

Connecting to a stream

After the previous steps are done then you can connect to the stream using the .connect() method from the View instance.

try {
  await millicastView.connect(options);
} catch (e) {
  console.log('Connection failed, handle error', e);
  millicastView.reconnect();
}

We recommend using the .reconnect() method in the catch clause to make sure the View instance keeps trying to reconnect until the stream is live even when an error in the connect occurs.

Reconnect

Both the instances of Publish and View have a reconnect event. This event emits when the connection is lost with a timeout and error message in the callback. This event is emitted by the .reconnect() method that both Publish and View instances have, this method is automatically called by default except specified with the autoReconnect flag of the constructor. SDK Reconnect event

Example reconnect event in View instance:

import { View } from '@millicast/sdk';
//...
const millicastView = new View(streamName, tokenGenerator);
//...
millicastView.on('reconnect', ({timeout, error}) => {
  console.log(timeout);
  console.log(error);
});
  • The timeout is the time, in milliseconds, when is going to retry the connection. It starts at 2000 ms and then 4000 ms ... until 32000 ms (32 s). After it goes to 32 s then it keeps retrying in 32 s.
  • The error message contains the cause of failure.

More information here:

Logger

You can get the logs of the connection, SDP, errors, and more. It can be enabled through the Logger module and you can activate it at any time (before/after a new connection).

import { Logger } from '@millicast/sdk';

Logger.setLevel(Logger.DEBUG); //Set level visibility to DEBUG and prior

The Logger is always logging, even if the .setLevel() is disabled.
You can access the latest logs history using the .getHistory() method.

Logger.getHistory();
// Outupt
// [
//   "[Director] 2021-04-05T14:09:26.625Z - Getting publisher connection data for stream name:  1xxx2",
//   "[Director] 2021-04-05T14:09:27.064Z - Getting publisher response",
//   "[Publish]  2021-04-05T14:09:27.066Z - Broadcasting"
// ]

More information and examples here:

WebRTC Stats

Stream stats can be accessed by both Publish and View instances. In order to capture them, you have to initialize the stats and then listen for the event through the webRTCPeer attribute.

🚧

Stats might defer between different web browsers.

Example of usage:

import View from '@millicast/sdk';
// Initialize and connect your Viewer
const millicastView = new View(streamName, tokenGenerator);
await millicastView.connect();

// Initialize stats
millicastView.webRTCPeer.initStats();

// Capture new stats from event every second
millicastView.webRTCPeer.on('stats', (stats) => {
  console.log('Stats from event: ', stats);
})
import Publish from '@millicast/sdk'
//Initialize and connect your Publisher
const millicastPublish = new Publish(streamName, tokenGenerator)
await millicastPublish.connect()

//Initialize stats
millicastPublish.webRTCPeer.initStats()

//Capture new stats from event every second
millicastPublish.webRTCPeer.on('stats', (stats) => {
   console.log('Stats from event: ', stats)
})

We highly recommend stopping the stats when they're not being used.

Example of stopping stats:

millicastView.webRTCPeer.stopStats();
millicastView.webRTCPeer.removeAllListeners('stats'); //Removes listeners if it has any

More information here:

Broadcast events

In the connect method, you can send the events that you want to subscribe to, when the connection is done the SDK starts to emit an event called broadcastEvents to catch the data of each event:

await millicastView.connect({
  events: ['active', 'inactive', 'layers', 'viewercount']
})
  • Active: Fires when the live stream is, or has started broadcasting.
  • Inactive: Fires when the stream has stopped broadcasting but is still available.
  • Stopped: Fires when the live stream has been disconnected and is no longer available.
  • Viewercount: Fires when the number of viewers changes in the stream published.

Managing online/offline status

The broadcastEvents can be used to detect when a stream is live or offline. There are two approaches to do this, it depends if you are contemplating multisource or not.

  • If you are publishing without multisource, the broadcastEvent could be active which means that the stream is live. When it's inactive means that the stream is offline.

  • If it's a multisource stream you have the same events but you are going to receive a source ID in the data payload. If you receive it as an active event, it means that a new source ID is available and the stream is active.
    To detect if the stream is inactive, you have to receive an inactive event and remove the incoming source ID from your active ones.
    If you don't have active source IDs, it means that the stream is offline.

More information here:

Example of usage (contemplating both cases):

// Instance the Viewer module as usual
const view = new View(streamName, tokenGenerator, video);
const activeSources = new Set();
view.on('broadcastEvent', (event) => {
  const {name, data} = event;
  switch (name) {
    //You have an active Source
    case 'active':
      activeSources.add(data.sourceId);
      console.log('Active Stream.');
      break;
    //You have an inactive Source
    case 'inactive':
      activeSources.delete(data.sourceId);
      if (activeSources.size === 0) {
        console.log('No active Stream.');
      }
      break;
    default:
      break;
  }
})

try {
  await view.connect();
} catch (e) {
  console.log('Connection failed, handle error', e);
}

User count

Also with the broadcastEvent you can manage the number of active viewers in the stream. When receive the event with the name 'viewercount' in it you can get the updated viewercount info.

Example of usage:

view.on('broadcastEvent', (event) => {
  const {name, data} = event;
    //...
    case 'viewercount':
      updateViewerCount(event.data.viewercount);
      break;
    default:
      break;
  }
})

Did this page help you?