Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
PUBLISHER_EVENTS.md
README.md
SUBSCRIBER_EVENTS.md
red5pro-publisher.swf
red5pro-sdk.min.js
red5pro-subscriber.swf
red5pro-video-js.swf

README.md

Red5 Pro Logo

publishersubscriber

-------

Red5 Pro HTML5 SDK

The Red5 Pro HTML5 SDK allows you to integrate live streaming video into your desktop and mobile browser.

Quickstart

To begin working with the Red5 Pro HTML5 SDK in your project:

Installation

In a browser:
download the latest release

<!-- *Recommended WebRTC Shim -->
<script src="http://webrtc.github.io/adapter/adapter-latest.js"></script>
<!-- Red5 Pro SDK -->
<script src="lib/red5pro/red5pro-sdk.min.js"></script>
<!-- video container -->
<div id="video-container">
  <video id="red5pro-subscriber" width="600" height="300" controls autoplay>
  </video>
</div>
<!-- Create subscriber -->
<script>
  (function(red5pro) {

    var rtcSubscriber = new red5pro.RTCSubscriber();
    var viewer = new red5pro.Red5ProPlaybackView();
    viewer.attachSubscriber(rtcSubscriber);

    rtcSubscriber.init({
      protocol: 'ws',
      host: 'localhost',
      port: 8081,
      app: 'live',
      streamName: 'mystream',
      iceServers: [{urls: 'stun:stun2.l.google.com:19302'}]
    })
    .then(rtcSubscriber.play)
    .then(function() {
      console.log('Playing!');
    })
    .catch(function(err) {
      console.log('Something happened. ' + err);
    });

  }(red5prosdk));
</script>

Note: The following installation process using npm is not supported at the time of this writing - August 16th, 2016. Please use the above method of adding the script from the release to the page.

As a client-side module to be later be deployed for the browser:
install the module

$ npm install red5pro-sdk
import { RTCSubscriber, Red5ProPlaybackView } from 'red5pro-sdk'

const subscriber = new RTCSubscriber()
const view = new Red5ProPlaybackView()
view.attachSubscriber(subscriber)

subscriber.init({
  protocol: 'ws',
  host: 'localhost',
  port: 8081,
  app: 'live',
  streamName: 'publisher1',
  iceServers: [{urls: 'stun:stun2.l.google.com:19302'}]
})
.then(() => {
  subscriber.play()
})
.then(() => {
  console.log('Playing!')
})
.catch(err => {
  console.log('Something happened. ' + err)
})

Included as post build of red5pro-sdk-example.js on a webpage:

<!doctype html>
<html>
  <head>
    <!-- * Recommended WebRTC Shim -->
    <script src="http://webrtc.github.io/adapter/adapter-latest.js"></script>
  </head>
  <body>
    <div id="video-container">
      <video id="red5pro-subscriber" width="600" height="300" controls autoplay>
      </video>
    </div>
    <!-- Red5 Pro SDK -->
    <script src="lib/red5pro-sdk-example.js"></script>
  </body>
</html>

Requirements

The Red5 Pro HTML SDK is intended to communicate with a Red5 Pro Server, which allows for broadcasting and consuming live streams utilizing WebRTC and various protocols, including RTMP and HLS.

As such, you will need a distribution of the Red5 Pro Server running locally or accessible from the web, such as Amazon Web Services.

Start using the Red5 Pro Server today!

Usage

This section describes using the Red5 Pro HTML SDK browser install to create sessions for a Publisher and a Subscriber.

Publisher

The following publisher types / protocols are supported:

Additionally, the Red5 Pro HTML SDK allows for automatic detection and failover to determine the correct publisher option to use based on desired order and browser support. To learn more, visit the Auto Failover section.

WebRTC

Utilizes WebSockets and WebRTC support in modern browsers.

It is recommended to include adapter.js when targeting the WebRTC subscriber.

Configuration Properties

Property Description Notes
protocol The protocol for the WebSocket communication; ws or wss. Required. If deployed remotely, browsers require communication over secure WebSockets.
host The IP or address that the WebSocket server resides on. Required
port The port on the host that the WebSocket server resides on; 8081 or 8083. Required
app The webapp name that the WebSocket is listening on. Required
streamName The name of the stream to subscribe to. Required
iceServers The list of ICE servers to use in requesting a Peer Connection. Required
streamMode The mode to broadcast; live, record or append. Optional. Default: live
bandwidth A configuration object to setup bandwidth setting in publisher. Optional. Default: {audio: 56, video: 512}.

Example

...
<body>
  <div id="video-container">
    <video id="red5pro-publisher"></video>
  </div>
</body>
...
<!-- WebRTC Shim -->
<script src="http://webrtc.github.io/adapter/adapter-latest.js"></script>
<!-- Exposes `red5prosdk` on the window global. -->
<script src="lib/red5pro/red5pro-sdk.min.js"></script>
...
<script>
  var iceServers = [{urls: 'stun:stun2.l.google.com:19302'}];

  // Create a new instance of the WebRTC publisher.
  var publisher = new red5prosdk.RTCPublisher();

  // Create a view instance based on video element id.
  var view = new red5prosdk.PublisherView('red5pro-publisher');

  // Access user media.
  navigator.getUserMedia({
    audio: true,
    video: true
  }, function(media) {

    // Upon access of user media,
    // 1. Attach the stream to the publisher.
    // 2. Show the stream as preview in view instance.
    publisher.attachStream(media);
    view.preview(media);

  }, function(error) {
    console.error(error);
  });

  view.attachPublisher(publisher);

  // Initialize
  publisher.init({
      protocol: 'ws',
      host: '10.0.0.1',
      port: 8081,
      app: 'live',
      streamName: 'mystream',
      streamMode: 'live',
      iceServers: iceServers
    })
    .then(function() {
      // Invoke the publish action
      return publisher.publish();
    })
    .catch(function(error) {
      // A fault occurred while trying to initialize and publish the stream.
      console.error(error);
    });
</script>

Flash/RTMP

Embeds a SWF file, utilizing swfobject, to incorporate publishing over RTMP.

The Red5 Pro HTML SDK supports the following SWF integration:

  • A bare-bones RTMP publisher - included in the src directory as red5pro-publisher.swf - and distributed with the live webapp of the Red5 Pro Server install.
    • Note: You will need to provide a URL to the swfobject library which will be dynamically injected at runtime if not - by default - found relative to the page at lib/swfobject.
  • Your own custom Flash client, by specifying the swf property in the init configuration!

Configuration Properties

Property Description Notes
protocol The protocol of the RTMP streaming endpoint; rtmp or rtmps Required
host The IP or address that the stream resides on. Required
port The port that the stream is accessible on. (e.g., 1935) Required
app The application to locate the stream. Required
streamName The stream name to subscribe to. Required
streamMode The mode to broadcast; live, record or append. Optional. Default: live
swf The swf file location to use as the Flash client publisher. Optional. Default: lib/red5pro/red5pro-publisher.swf
width The width of the video element within the SWF movie. Optional. Default: 320
height The height of the video element within the SWF movie. Optional. Default: 240
embedWidth The width of the object element for the SWF movie embed. Optional. Default: 320
embedHeight The height of the object element for the SWF movie embed. Optional. Default: 240
minFlashVersion Minimum semversion of the target Flash Player. Optional. Default: 10.0.0
swfobjectURL Location of the swfobject dependency library that will be dynamically injected. Optional. Default: lib/swfobject/swfobject.js
productInstallURL Location of the playerProductInstall SWF used by swfobject. Optional. Default: lib/swfobject/playerProductInstall.swf

Example

...
<body>
  <div id="video-container">
    <video id="red5pro-publisher"></video>
  </div>
</body>
...
<!-- WebRTC Shim -->
<script src="http://webrtc.github.io/adapter/adapter-latest.js"></script>
<!-- Exposes `red5prosdk` on the window global. -->
<script src="lib/red5pro/red5pro-sdk.min.js"></script>
...
<script>
  var iceServers = [{urls: 'stun:stun2.l.google.com:19302'}];

  // Create a new instance of the WebRTC publisher.
  var publisher = new red5prosdk.RTMPPublisher();

  // Create a view instance based on video element id.
  var view = new red5prosdk.PublisherView('red5pro-publisher');
  view.attachPublisher(publisher);

  // Initialize
  publisher.init({
      protocol: 'rtmp',
      host: '10.0.0.1',
      port: 1935,
      app: 'live',
      streamName: 'mystream',
      swf: 'lib/red5pro/red5pro-publisher.swf'
    })
    .then(function() {
      // Invoke publish action.
      publisher.publish()
    })
    .catch(function(error) {
      // A fault occurred while trying to initialize and publish the stream.
      console.error(error);
    });

Auto Failover and Order

While you can specifically target a publisher - as described in the previous Player Flavors section - you may want to let the library select the optimal publisher based on browser compatibility per support flavors.

As you may have noticed form the previous section, the source configuration for each publisher has differing property requirements. This is due simply to the technologies and broadcast strategies that each use:

  • The WebRTC player utilizes WebSockets, WebRTC and getUserMedia to publish a video and to be displayed in an HTML5 video element.
  • The Flash/RTMP player utilizes a SWF file to broadcast and view streaming video from the Flash Player plugin.

As such, the init configuration provided to the library to allow for auto-failover player selection should be provided with attributes defining the target source(s) - i.e., rtc and/or rtmp:

...
<body>
  <div id="video-container">
    <video id="red5pro-publisher"></video>
  </div>
</body>
...
<!-- WebRTC Shim -->
<script src="http://webrtc.github.io/adapter/adapter-latest.js"></script>
<!-- Exposes `red5prosdk` on the window global. -->
<script src="lib/red5pro/red5pro-sdk.min.js"></script>
...
<script>
  var iceServers = [{urls: 'stun:stun2.l.google.com:19302'}];

  // Create a new instance of the failover publisher.
  var publisher = new red5prosdk.Red5ProPublisher();

  // Create a view instance based on video element id.
  var view = new red5prosdk.PublisherView('red5pro-publisher');
  view.attachPublisher(publisher);

  // Set publish order and initialize
  publisher
    .setPublishOrder(['rtc', 'rtmp'])
    .init({
      "rtmp": {
        // See above documentation for RTMP source option requirements.
      },
      "rtc": {
        // See above documentation for WebRTC source option requirements.
      }
    })
    .then(function(selectedPublisher) {
      // Publisher implementation determined based on order and browser support.

      // If determined publisher implementation is WebRTC,
      //  set up preview and establish stream.
      if (selectedPublisher.getType().toLowerCase() === publisher.publishTypes.RTC) {
        navigator.getUserMedia({
            audio: true,
            video: true
          }, function (media) {
            selectedPublisher.attachStream(media)
            publisherView.preview(media);
          }, function (error) {
            console.error(error);
          });
      }
      return selectedPublisher.publish();
    })
    .then(function() {
      // Publishing has initiated successfully.
    })
    .catch(function(error) {
    });

</script>

Lifecycle Events

Please refer to the [Publisher Events](PUBLISHER_EVENTS.md) documentation regarding the events API.

Subscriber

The following player types / protocols are supported:

Additionally, the Red5 Pro HTML SDK allows for automatic detection and failover to determine the correct playback option to use based on desired order and browser support. To learn more, visit the Auto Failover section.

WebRTC

Utilizes WebSockets and WebRTC support in modern browsers.

It is recommended to include adapter.js when targeting the WebRTC subscriber.

Configuration Properties

Property Description Notes
protocol The protocol for the WebSocket communication. Required
host The IP or address that the WebSocket server resides on. Required
port The port on the host that the WebSocket server resides on. Required
app The webapp name that the WebSocket is listening on. Required
streamName The name of the stream to subscribe to. Required
subscriptionId A unique string representing the requesting client. Optional. Default generated by library.
iceServers The list of ICE servers to use in requesting a Peer Connection. Required
bandwidth A configuration object to setup playback. Optional
autoplay Flag to autoplay the stream when received upon negotiation. Optional. Default: true

Example

...
<body>
  <div id="video-container">
    <video id="red5pro-video"></video>
  </div>
</body>
...
<!-- WebRTC Shim -->
<script src="http://webrtc.github.io/adapter/adapter-latest.js"></script>
<!-- Exposes `red5prosdk` on the window global. -->
<script src="lib/red5pro/red5pro-sdk.min.js"></script>
...
<script>
  var iceServers = [{urls: 'stun:stun2.l.google.com:19302'}];

  // Create a view instance based on video element id.
  var viewer = new red5prosdk.PlaybackView('red5pro-video');

  // Create a new instance of the WebRTC subcriber.
  var subscriber = new red5prosdk.RTCSubscriber();
  // Attach the subscriber to the view.
  viewer.attachSubscriber(subscriber);

  // Initialize
  subscriber.init({
    protocol: 'ws',
    host: '10.0.0.1',
    port: 8081,
    app: 'live',
    subscriptionId: 'subscriber-' + Math.floor(Math.random() * 0x10000).toString(16),
    streamName: 'mystream',
    iceServers: iceServers,
    bandwidth: {
      audio: 56,
      video: 512
    }
  })
  .then(function(player) {
    // `player` is the WebRTC Player instance.
    // Invoke the play action.
    player.play();
  })
  .catch(function(error) {
    // A fault occurred while trying to initialize and playback the stream.
    console.error(error)
  });
</script>

Flash/RTMP

Embeds a SWF file, utilizing swfobject, to incorporate playback over RTMP.

The Red5 Pro HTML SDK supports the following SWF integration:

  • A customized videojs swf - included in src directory as red5pro-videojs.swf - and utilizing the RTMP playback support from videojs.
    • Note: You will need to also include the videojs script on the page as it is not bundled in the Red5 Pro HTML SDK.
  • A bare-bones RTMP playback viewer - included in the src directory as red5pro-subscriber.swf - and distributed with the live webapp of the Red5 Pro Server install.
    • Note: You will need to provide a URL to the swfobject library which will be dynamically injected at runtime if not - by default - found relative to the page at lib/swfobject.
  • Your own custom Flash client, by specifying the swf property in the init configuration!

Configuration Properties

Property Description Notes
protocol The protocol of the RTMP streaming endpoint. (e.g., rtmp, rtmps) Required
host The IP or address that the stream resides on. Required
port The port that the stream is accessible on. Required
app The application to locate the stream. Required
streamName The stream name to subscribe to. Required
mimeType The mimeType to assign the source added to the video element Optional. Default: rtmp/flv
swf The swf file location to use as the Flash client playback. Optional. Default: lib/red5pro/red5pro-video-js.swf
width The width of the video element within the SWF movie. Optional. Default: 320
height The height of the video element within the SWF movie. Optional. Default: 240
embedWidth The width of the object element for the SWF movie embed. Optional. Default: 320
embedHeight The height of the object element for the SWF movie embed. Optional. Default: 240
useVideoJS Flag to utilize the videojs library.
minFlashVersion Minimum semversion of the target Flash Player. Optional. Default: 10.0.0
swfobjectURL Location of the swfobject dependency library that will be dynamically injected. Optional. Default: lib/swfobject/swfobject.js
productInstallURL Location of the playerProductInstall SWF used by swfobject. Optional. Default: lib/swfobject/playerProductInstall.swf

Example

...
<body>
  <div id="video-container">
    <video id="red5pro-video" width="600" height="300"
      class="video-js vjs-default-skin"
      controls autoplay data-setup="{}">
    </video>
  </div>
</body>
...
<!-- Optional VideoJS support. -->
<link href="lib/videojs/video-js.min.css" rel="stylesheet">
<script src="lib/videojs/video.min.js"></script>
<script src="lib/videojs/videojs-media-sources.min.js"></script>

<!-- Exposes `red5prosdk` on the window global. -->
<script src="lib/red5pro/red5pro-sdk.min.js"></script>
...
<script>
  // Create a view instance based on video element id.
  var viewer = new red5prosdk.PlaybackView('red5pro-video');

  // Create a new instance of the Flash/RTMP subcriber.
  var subscriber = new red5prosdk.RTMPSubscriber();
  // Attach the subscriber to the view.
  viewer.attachSubscriber(subscriber);

  // Initialize
  subscriber.init({
    protocol: 'rtmp',
    host: '10.0.0.1',
    port: 1935,
    app: 'live',
    streamName: 'mystream',
    mimeType: 'rtmp/flv',
    swf: 'lib/red5pro-video-js.swf'
  })
  .then(function(player) {
    // `player` is the WebRTC Player instance.
    // Invoke the play action.
    player.play();
  })
  .catch(function(error) {
    // A fault occurred while trying to initialize and playback the stream.
    console.error(error)
  });

The above example defaults to integrating with the videojs library and the custom player build created for the Red5 Pro HTML SDK.

This is the default behavior when the useVideoJS property of the init configuration is set or left as the default value of true.

By setting useVideoJS: false on the init configuration, you can allow the library to load the default red5pro-subscriber.swf, or specify your own custom SWF!

HLS

Utilizes the HLS support for videojs.

Configuration Properties

Property Description Notes
protocol The protocol uri that the stream source resides on. Required
host The IP or address uri that the stream source resides on. Required
port The port uri that the stream source resides on. Required
app The webapp name that the stream source resides in. Required
streamName The stream name to subscribe to. Required
mimeType The mime-type of the stream source. Optional. Default: application/x-mpegURL
swf The fallback SWF file to use if HTML5 video element is not supported. Optional. Default: lib/red5pro/red5pro-video-js.swf

Example

...
<body>
  <div id="video-container">
    <video id="red5pro-video" width="600" height="300"
      class="video-js vjs-default-skin"
      controls autoplay data-setup="{}">
    </video>
  </div>
</body>
...
<!-- Required VideoJS support for HLS playback. -->
<link href="lib/videojs/video-js.min.css" rel="stylesheet">
<script src="lib/videojs/video.min.js"></script>
<script src="lib/videojs/videojs-media-sources.min.js"></script>
<script src="lib/videojs/videojs.hls.min.js"></script>

<!-- Exposes `red5prosdk` on the window global. -->
<script src="lib/red5pro/red5pro-sdk.min.js"></script>
...
  // Create a view instance based on video element id.
  var viewer = new red5prosdk.PlaybackView('red5pro-video');

  // Create a new instance of the HLS subcriber.
  var subscriber = new red5prosdk.HLSSubscriber();
  // Attach the subscriber to the view.
  viewer.attachSubscriber(subscriber);

  // Initialize
  subscriber.init({
    protocol: 'http',
    host: '10.0.0.1',
    port: 5080,
    app: 'live',
    streamName: 'mystream',
    mimeType: 'application/x-mpegURL',
    swf: 'lib/red5pro/red5pro-video-js.swf'
  })
  .then(function(player) {
    // `player` is the WebRTC Player instance.
    // Invoke the play action.
    player.play();
  })
  .catch(function(error) {
    // A fault occurred while trying to initialize and playback the stream.
    console.error(error)
  });

In the above example, the SWF fallback - used when the videojs library determines that HLS support is not sufficient - is the custom videojs client developed for the Red5 Pro HTML SDK.

You can provide your own custom SWF, just as you can for the Flash/RTMP playback, by setting the swf init configuration property.

Auto Failover and Order

While you can specifically target a player - as described in the previous Player Flavors section - you may want to let the library select the optimal player based on browser compatibility per support flavors.

As you may have noticed form the previous section, the source configuration for each player has differing property requirements. This is due simply to the technologies and playback strategies that each use:

  • The WebRTC player utilizes WebSockets and WebRTC to subscribe to a video to be displayed in an HTML5 video element.
  • The Flash/RTMP player utilizes a SWF file to playback streaming video in the Flash Player plugin.
  • The HLS player utilizes the HTTP Live Streaming protocol to subscribe to a stream and VideoJS to provide playback with optional fallback of SWF.

As such, the init configuration provided to the library to allow for auto-failover player selection should be provided with attributes defining the target source(s) - i.e., rtc, rtmp and/or hls:

...
<body>
  <div id="video-container">
    <video id="red5pro-video" width="600" height="300"
      class="video-js vjs-default-skin"
      controls autoplay data-setup="{}">
    </video>
  </div>
</body>
...
<!-- WebRTC Shim -->
<script src="http://webrtc.github.io/adapter/adapter-latest.js"></script>

<!-- VideoJS support for HLS playback. -->
<link href="lib/videojs/video-js.min.css" rel="stylesheet">
<script src="lib/videojs/video.min.js"></script>
<script src="lib/videojs/videojs-media-sources.min.js"></script>
<script src="lib/videojs/videojs.hls.min.js"></script>

<!-- Exposes `red5prosdk` on the window global. -->
<script src="lib/red5pro/red5pro-sdk.min.js"></script>
...
<script>
  // Create a view instance based on video element id.
  var viewer = new red5prosdk.PlaybackView('red5pro-video');

  // Create a new instance of the HLS subcriber.
  var subscriber = new red5prosdk.Red5ProSubscriber();
  // Attach the subscriber to the view.
  viewer.attachSubscriber(subscriber);

  subscriber
    .setPlaybackOrder(['rtc', 'rtmp', 'hls'])
    .init({
       "rtmp": {
          // See above documentation for RTMP source option requirements.
        },
        "rtc": {
          // See above documentation for WebRTC source option requirements.
        },
        "hls": {
          // See above documentation for HLS source option requirements
        }
    })
    .then((player) => {
      // `player` has been determined from browser support.
      // Invoke play action
      player.play()
    })
    .then(function() {
      // Playback has initiated successfully.
    })
    .catch(function(error) {
      // A fault occurred in finding failover player and playing stream.
      console.error(error)
    });
</script>

Important things to note:

  • Only rtc, rtmp and hls are supported values for order and are also accessible as enums on Red5ProVidepPlayer.playbackTypes

Lifecycle Events

Please refer to the [Subscriber Events](SUBSCRIBER_EVENTS.md) documentation regarding the events API.

Contributing

Please refer to the Contributing Documentation to learn more about contributing to the development of the Red5 Pro HTML SDK.