Red5 Pro HLS Plugin

Red5 Pro HLS Supports h264 and AAC broadcasts

The plugin takes live streams from any application and transforms them into the mpeg live transport stream with a m3u8 playlist.

The HLS playlist represents a sliding window containing several short segments of media which play as one continuous stream. Red5 Pro passes through the media as-is without re-encoding or producing multi-bitrate variants.

URI Info

Every live stream is transformed to HLS

The URI of the HLS stream mimics the context path of the publisher stream.

The publisher with a stream consumable at the following URI:

will be also playable at the following URI:


Configuration

The HLS plugin provided with the Red5 Pro Server allows you to configure the sliding window parameters of the m3u8 playlist:

hlsconfig.xml

The HLS Plugin included in the Red5 Pro Server distribution reads the configuration file at conf/hlsconfig.xml.

The following properties are defined to configure the HLS playlist:

Property defaults from conf/hlsconfig.xml

<!--
The number of items in the m3u8 playlist.

Minimum latency is calculated by itemLength times ( itemCount minus one ).

With 4 items of 4 seconds length, average latency for HLS subscribers would be 4 X (4-1), or 12 seconds minimum.
-->
<property name="itemCount" value="5"/>

<!--
The length in seconds desired for each segment.

A segment is started on a key frame, so your encoder should output key frames in the range of 2 to 5 seconds apart, for item lengths 4 to10 seconds.

A guideline would be key video frames at half the desired item length.
-->
<property name="itemLength" value="6"/>

<!--
The segmentation engine will begin a new segment with a key frame.

The itemThreshold is the point in time in writing the segment that a key frame triggers this.

The actual segment lengths in the playlist will be a minimum of itemLength times itemThreshold seconds.

Encoders which output a constant key framerate at half of the itemLength can use a higher threshold.

Using lower thresholds may require higher item counts to avoid stalling the players.

A live m3u8 playlist should contain enough segments which equal 3 to 4 times the target segment duration, so lower thresholds which may produce shorter segments should have 4 or 5 as itemCount.
-->
<property name="itemThreshold" value="0.7"/>

<!--
The HLS function can operate from memory or from disk.

If you are using Disk based reads, you must de-activate the HLS servlet in the web.xml file of your app adapter.
-->
<property name="useDiskWrites" value="false"/>

Latency

The typical HLS player will have latency of about the total duration of the playlist sliding window. Latency can be roughly determined by multiplying the segment duration by the segment count; a stream with a segment count of 5 and duration of 6 seconds will typically result in a latency of 30 seconds.

Segmentation

The segmentation engine relies on key frames provided by the publisher.

You can configure the threshold point at which the key frame creates a new segment. A lower threshold allows shorter duration in the segments; with a target duration of 10 seconds and a threshold of 0.7, the HLS plugin will start a new segment at the next key frame occuring at or after the 7 second mark:

10 X 0.7 = 7.0 seconds minimum segment duration

Use the threshold variable to prevent stalling the HLS subscribers when the broadcaster key frame interval does not match the segment duration.

The segment duration should not be shorter than the expected minimum keyframe interval

Enabling RAM Writes

By default, disk writes of the video are set to false. The necessary settings to allow for writing to RAM are:

The hls and hls2 definitions in red5pro-server/webapps/live/web.xml:

    <servlet>
        <servlet-name>hls</servlet-name>
        <servlet-class>com.red5pro.stream.transform.mpegts.server.TSServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>hls</servlet-name>
        <url-pattern>*.m3u8</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>hls2</servlet-name>
        <servlet-class>com.red5pro.stream.transform.mpegts.server.TSServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
      <servlet-mapping>
        <servlet-name>hls2</servlet-name>
        <url-pattern>*.ts</url-pattern>
    </servlet-mapping>

Enabling Disk Writes

In order for disk writes to happen, you will need to:

The behavior of the server is the same when publishing a stream. The URI of the HLS stream mimics the context path of the publisher stream.

The publisher with a stream consumable at the following URI:

will be also playable at the following URI:

Not the additon of hls in the path between live and the stream name value.

The files are written into the red5pro-server/webapps/live/hls directory. They will be deleted a few seconds after the stream ends.

NOTE: this property does not have anything to do with HLS VOD.


Metadata and NetStreamSends

You can respond to stream events and access metadata using JavaScript.

A service is available from Red5 Pro to receive the script data tags within the live stream. The service is accessed via websockets:

JavaScript
var service = "ws://SERVER_IP:6262/metadata";
var context = "/live"
var stream = "/stream1";
var request = service + context + stream;
var metasocket;

function connect(uri){
    metasocket = new WebSocket(uri);
    metasocket.onopen = function(evt){
        console.log("on open");
    };
    metasocket.onclose =  function(evt){
        console.log("on close");
    };
    metasocket.onmessage = function(evt){
        console.log("on message  "+evt.data);
        // json {"name":"onMetaData", "data":{"orientation":90,"otherstuff":"blablabla"}}
        // * metadata client will continue to receive script data tags other than metadata from publishers until socket is closed.
        // * metadata client can reveive server initiated calls.
        // * metadata client cannot initiate other service calls to server yet.
        // * Second Screen host sdk can initiate arbitrary RPC to server.
        // * Clients will receive periodic pings to check if IO is active. You can ignore `data` if it does not have a `name` property.
    };
    metasocket.onerror =  function(evt){
        console.log("on error");
    };
}
connect(request);

HLS VOD

By default, Red5 Pro mobile clients record FLVs and HLS files; Flash clients record FLVs only. If you want to record HLS for Flash VOD as well, modify (red5pro)\conf\hlsconfig.xml

Change the forceVODRecord value from "false" to "true".

    <!-- Force VOD recording -->
    <property name="forceVODRecord" value="false"/>

This will create, in (red5pro)\webapps\live\streams, a streamname.m3u8 file and a number of streamname_#.ts files. In addition, if you are copying up to a storage bucket, then in the live directory, there will be a streamname sub-directory which contains the m3u8 and ts files.

If you are using Amazon S3 Cloud storage, you can subscribe directly to the URL of the m3u8 file with Safari browser or with a tool like VNC.

Red5 Pro HTML5 HLS Example

You can view the HLS live or VOD stream using our HTML5 example here.

To use this example:

  1. Stream URL or IP - Enter your server IP or URL (if your solution is clustered then enter the Origin IP address).
  2. Stream Port - enter port if using a different one than the Red5 Pro default 5080.
  3. Stream Websocket Port - enter port if using a different one than the Red5 Pro default 6262.
  4. Stream Context - enter if using different webapp than the default live.
  5. Stream Name - enter the stream name you want to subscribe to (do not incude the m3u8 extension), or leave blank for VOD.
  6. Subscribe via Red5 Pro Cluster? - check here if your servers are clustered.
  7. Subscribe to Red5 Pro VOD? - check here to initiate playlists search for your VOD. The Stream Name box will change to a drop-down list of available HLS VOD streams.
  8. Click on the Save button. This will generate the Stream URL and Stream WebSocket URL for the stream you've selected.
  9. Click on the PLAY button that will appear at the top left of the black video preview.

Note that HLS latency is generally between 10 and 12 seconds, so you will not be able to view your live video right away.