Red5 Pro HLS Plugin

Red5 Pro HLS Supports h264 and AAC broadcasts

The HLS plugin {red5pro}/plugins/red5pro-mpegts-plugin-*.jar takes live streams from any application and transforms them into an 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.

If you do not require HLS playback, then you can remove this plugin to help optimize server performance.

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:

  • rtsp://server:8554/live/streamName

will be also playable at the following URI:

  • http://server:5080/live/streamName.m3u8


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

  • segment duration
  • segment count
  • allowed variance
  • where the segments are stored (RAM or Disk)


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:

  • itemCount - The number of segments in the sliding window
  • itemLength - The segment duration
  • itemThreshold - The HLS segmentation variance. It should be higher than 0.5 and less than 1
  • useDiskWrites - If you have a large duration and segment count, you may prefer to serve the HLS files from disk

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"/>


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.

Since Red5 Pro passes through the media 'as is', the first consideration to effective streaming is to set up the publisher to output HLS-friendly media. The live HLS experience is governed by the somewhat strict timing of the players, which check the playlist at a certain interval.

The dimensions of HLS are the segment duration, and the segment count in the playlist. Players are required to poll the playlist at an interval of half the segment duration. The server is required to update the playlist with a new segment so that players do not see a static playlist over 2 iterations. Critical notes: timely video key frames to segment on; One segment is assumed to be on the wire at all times; Safari typically require 3 segments to begin playback.

All that being said, the equation is derived: latency = ( ( segment_duration ) X ( playlist_count - 1 ) ) +/- ( fraction of segment_duration ).

Some test results using the iOS SDK publisher which is capable of producing a steady key frames per 2 seconds.

  • The Red5 Pro distribution hlsconfig.xml file is set at 5 items and 6 seconds and has average latency of 18-30 seconds.
  • HLS playlist configured with playlist count of 4 items, segment duration of 4 seconds, produced latency between 10-16 seconds.
  • HLS playlist configured with playlist count of 4 items, segment duration of 2 seconds, produced latency between 6-10 seconds.

The threshold variable sets the sensitivity of segmentation. When a key video frame is encountered after the segment_duration X threshold, HLS will segment. Values closer to 1 work well with steady frame rates. Lower values closer to .5 allow segmentation at half the duration and this can help with a very non-static frame rate. If your broadcasters output key frames every 2 to 3 seconds, the lower threshold would allow HLS settings of segment_duration to work for both cases. Segment duration of 6 and a threshold at 0.6.


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 true. The necessary settings to allow for writing to RAM are:

  • Define the useDistWrites bean property in conf/hlsconfig.xml as false.
  • Ensure that the servlet and servlet-mappings for hls and hls2 are defined in red5pro-server/webapps/live/WEB-INF/web.xml.

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



Enabling Disk Writes

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

  • Define the useDiskWrites bean property in conf/hlsconfig.xml as true
  • Remove or comment out the servlet and servlet-mapping nodes for hls and hls2 from _webapps/live/WEB-INF/web.xml

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:

  • rtsp://server:8554/live/streamName

will be also playable at the following URI:

  • http://server:5080/live/streamName.m3u8

The .ts files are written into the red5pro-server/webapps/live/streams directory. Each .ts file will be removed after approximately 30 seconds, and all .ts files, plus the .m3u8 file will be removed approximately 30 seconds after the stream has been stopped.

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:

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  ";
        // 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");


By default, all Red5 Pro recorded streams produce FLVs and HLS files.

The HLS recordings 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 VLC. To list the HLS recordings on the playback.jsp page of the server distribution, append the URL with &playlists=1 (e.g:

Red5 Pro HTML5 HLS Example

You can view the HLS live or VOD stream using our HTML5 example here. This example uses VideoJS, so that it can run in Chrome. It does not use the Red5 Pro HTML5 SDK.

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 12 and 30 seconds, so you will not be able to view your live video right away.