Monday, June 25, 2012

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.

14 comments:

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

    ReplyDelete
  2. application foo {
    hls on;
    hls_path /tmp/app;
    hls_fragment 5s;
    }

    ReplyDelete
  3. 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?

    ReplyDelete
  4. At the moment that's not possible. I will try to do that.

    ReplyDelete
  5. +1 for that feature. Would be great.

    ReplyDelete
  6. 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!

    ReplyDelete
  7. Hello,

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

    ReplyDelete
  8. 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.

    -Auro

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

    ReplyDelete
  10. 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.

    ReplyDelete
  11. 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?

    -Auro

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

    ReplyDelete
  13. Hi Roman,
    I tried to install rtmp server with hls on centOS 5 (x86_64) but it show error:
    https://dl.dropbox.com/u/11090063/hls-error.txt
    if I remove --add-module=/usr/build/nginx-rtmp-module/hls in configure command, it works fine. But I need hls for iPhone. Do you have any idea?

    Thank you for your great work
    Neo Khuat

    ReplyDelete