Tuesday, October 8, 2013

Exec pull feature in nginx-rtmp-module

I'm proud to announce the most wanted feature by module users - exec_pull. The old exec (now renamed to exec_push) runs external process when a client starts publishing. The new exec_pull starts external process when first subscriber connects to the stream and kills it when the last one disconnects. It's extremely useful if you don't want the stream to be always pulled and transcoded (exec_static) but only do that when there's at least one client.

Imagine you have many video sources and want to be able to watch those in browser. The sources have different formats and codecs so transcoding and reformatting is required. That's done by ffmpeg. With the current master you can use exec_static to run ffmpeg's all the time even when no one is watching. The best solution is setting up your system to keep ffmpeg running when there's at least one client. The new exec_pull directive does that.

The directive supports only the following substitutions
  • name - stream name
  • app - application name
All other variables supported by exec/exec_push are not supported in exec_pull because they are session-dependent.

The feature has the following limitations
  • It works properly only in single-worker mode. Nginx worker cannot make child ffmpeg connect to the same worker. If it connects to a different worker streaming will not be stable. To overcome the limitation please set up two nginx instances with the first one having only a single worker with exec_pull and pull the stream from it by the second nginx.
  • There's no way to pull/exec_pull the stream when HLS client connects.

The following example shows how to pull data from remote mpeg-ts stream with transcoding.
application myapp {
    live on;
    exec_pull ffmpeg -i http://example.com/video.ts -c:v copy 
                     -c:a libfaac -ar 44100 -ac 1 
                     -f flv rtmp://localhost/$app/$name;

The code is in exec-pull branch of nginx-rtmp-module.


  1. I compile new nginx and new rtmp module but if I use exec_pull in config nginx say unknown directive "exec_pull", is there any other nginx-rtmp-module branch, with this new function?

  2. Sorry, I found branch called exec-pull and all work fine
    Thank you for Your greate work!

  3. Any plans to have something like exec_pull , when HLS client connects ?