HLS support in NGINX-RTMP

Recently I’ve added initial Apple’s HLS support to the module.

HLS stands for HTTP Live Streaming. It’s supported by iPhones & iPads to watch videos right from their browsers. The biggest benefit of the technology is the ability to stream data through HTTP which is great for passing proxies, mobile & corporate networks.

HLS is m3u8 playlist file plus a number of stream fragments in mpeg-ts format,

Recently I’ve added HLS support to nginx-rtmp-module. The module does not decode streams. It can be done asynchronously with ffmpeg (see exec directive). However RTMP stream should be reformatted into mpeg-ts fragments. FFmpeg’s libavformat is used for that. Please make sure ffmpeg is installed on your system before building nginx with HLS module.

To add HLS support to nginx one should add HLS module explicitly in addition to core nginx-rtmp-moduie when configuring

./configure ... --add-module=/path/to/nginx-rtmp-module/hls

The following lines should be added to nginx.conf.

application myapp {
    hls on;
    hls_path /tmp/app;
    hls_fragment 5s;

The path /tmp/app is where m3u8 playlist and *.ts fragments will be placed. The path should exist before starting nginx. For best results it should be located in tmpfs. To serve the HLS data use usual nginx settings within http{} block:

location /myapp {
    alias /tmp/app;

When you navigate your iPhone to playlist file within this location (for example: http://example.com/myapp/movie.m3u8) you’ll see live stream right in mobile browser.

Known issues:

When streaming in MP3 audio is choppy. However H264/AAC (the modern way to encode streams) works pretty good.

Please feel free to report issues. The HLS support is still in experimental state.

  1. #1 by DeweyOx on October 7, 2012 - 2:33 pm

    Can you post a sample config file please? Having issues getting this to work. thx.

    • #2 by rarut on October 8, 2012 - 11:56 am

      application foo {
      hls on;
      hls_path /tmp/app;
      hls_fragment 5s;

  2. #3 by Tony Wagner on November 9, 2012 - 10:46 pm

    Awesome module! Is there a way to get HLS working for VOD? I can send it manually using ffmpeg, but can I configure the HLS app to automatically grab the appropriate VOD stream through ffmpeg?

    • #4 by rarut on November 10, 2012 - 4:37 am

      At the moment that’s not possible. I will try to do that.

      • #5 by DeweyOx on November 10, 2012 - 11:41 am

        +1 for that feature. Would be great.

  3. #6 by statlust on January 30, 2013 - 4:11 am

    Hello, can you please elaborate on, “For best results it should be located in tmpfs.”

    Requesting the .m3us URL works from my ipad works but not reliably.

    The following is in the http section

    location /myapp {
    alias /home/auro/hls-media;

    The “application” is in the rtmp section. Is this what you intended?

    application myapp {
    live on;

    # sample HLS
    hls on;
    hls_path /tmp/app;
    #hls_sync 100ms;
    hls_fragment 5s;

    p.s. Good work!

    • #7 by rarut on January 30, 2013 - 4:43 am


      I see /home/auro/hls-media in http{}, but /tmp/app in rtmp{}.
      It should be the same directory.

      • #8 by statlust on January 30, 2013 - 7:02 am

        Thank you. Fixed that.

  4. #9 by statlust on January 30, 2013 - 7:05 am

    Hello Roman, any restrictions on how many clients can connect to this HLS server. My second connection from a iphone safari browser does not start. The first connection is from the ipad safari browser.

    Thank you for your help.


    • #10 by rarut on January 30, 2013 - 7:11 am

      HLS is HTTP. The number of clients is only limited by your network bandwidth. There’s probably a problem in server configuration.

      • #11 by statlust on January 30, 2013 - 7:56 am

        Thank you. the ngix server is runnig default configuration; didn’t change anything. Probably wireless bandwidth issues. I’ll investigate some more.

        I’m using the apple bipbop-gear files and I occasionally get disconnects.

        Thanks for your help.

  5. #12 by statlust on January 30, 2013 - 11:24 pm

    Hi Roman:

    Your comment, “HLS is HTTP” is quite correct. So I’m wondering why your implementation goes thru an RTMP module with an HLS extension.

    Why is a simple HTTP server not sufficient?


    • #13 by rarut on January 31, 2013 - 6:41 am

      nginx is a simple HTTP server. Rtmp module creates hls files from rtmp stream which are later served with nginx http engine.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: