【nginx-rtmp】07、指令（Directives）之 執行命令（Exec）

三、執行命令（Exec）

01、exec_push

語法：exec_push command arg*

上下文：rtmp, server, application

指定帶參數的外部命令，它會在每個流發佈的時候執行，當發佈停止時這個命令進程也會終止；第一個參數應該是完整的可執行文件路徑；

至於這個進程能做什麼事我假定不了，但這個功能在流媒體轉碼的時候非常有用，

FFmpeg支持以客戶端身份連接到nginx-rtmp獲取流，然後轉碼處理後又以發佈者的身份推送流到nginx-rtmp，

在命令行內可以使用 $var/${var} 這類變量來替換相關內容：

Specifies external command with arguments to be executed on every stream published. When publishing stops the process is terminated.

Full path to binary should be specified as the first argument. There are no assumptions about what this process should do.

However this feature is useful with ffmpeg for stream transcoding.

FFmpeg is supposed to connect to nginx-rtmp as a client and output transcoded stream back to nginx-rtmp as publisher.

Substitutions of form $var/${var} can be used within command line:

• $name  - stream name
• $app  - application name
• $addr  - client address
• $flashver  - client flash version
• $swfurl  - client swf url
• $tcurl  - client tc url
• $pageurl  - client page url

可以在exec_push指令中指定輸出和輸入的重定向符，支持下面幾個：

Shell-style redirects can be specified in exec_push directive for writing output and accepting input. Supported are :

• truncating output  >file   （覆蓋式的輸出）
• appending output  >>file   （追加式的輸出）
• descriptor redirects like  1>&2  （？？）
• input  <file    （從文件獲取輸入）

注意：在重定向符和流名稱或者序號之間是沒有空格的。

Make sure there's no space between redirection character and stream name/number.

你可以指定全路徑給這個命令來執行，或者指定短命令名稱（環境變量中可找得到執行程序的命令），

默認情況下nginx會清掉環境變量，所以通常nginx的模塊運行程序要在本地的標準路徑，如 /bin 和 /usr/bin。

你可以用下面的指令來保留原來的 PATH變量：

You can specify full path to the command to execute or short command name.

In the latter case binary is looked up in directories specified by the PATH environment variable.

By default nginx clears the environment which will usually make rtmp module run only binaries located in standard directories like /bin and /usr/bin.

To make this always work please keep the original PATH variable value with the following nginx directive.

env PATH;

下面是使用 ffmpeg來將輸入流轉碼爲HLS支持的流（H264/AAC），在這個例子中，FFmpeg要編譯爲支持 libx263 和 libfaac 。

The following ffmpeg call transcodes incoming stream to HLS-ready stream (H264/AAC).

FFmpeg should be compiled with libx264 & libfaac support for this example to work.

application src {
    live on;
    exec_push ffmpeg -i rtmp://localhost/src/$name -vcodec libx264 -vprofile baseline -g 10 -s 300x200 -acodec libfaac -ar 44100 -ac 1 -f flv rtmp://localhost/hls/$name 2>>/var/log/ffmpeg-$name.log;
}

application hls {
    live on;
    hls on;
    hls_path /tmp/hls;
    hls_fragment 15s;
}

02、exec_pull

語法：exec_pull 

上下文：rtmp, server, application

指定帶參數的外部命令，它在播放事件（客戶端播放）時候執行，

這個命令會在第一個客戶連接拉流時執行，並且在最後一個連接斷開時中止，這個指令讓從遠程拉取各種格式的流再提供給本地播放客戶端成爲可能！

Specifies external command with arguments to be executed on play event.

The command is executed when first client connects to the stream and is killed when the last one disconnects.

This directive makes it possible to pull remote stream in any format for local clients.

這個功能只對在單個工作者模式（single-worker mode）下提供可靠性，原因是我們不能確定外部處理程序總會連接到正確的worker，它顯然會隨機連接一個；

這在大多數情況下會正常工作，但不建議用這樣架構，會不穩定和出現bug。

The feature works reliably only in single-worker mode. The reason for this is we cannot make sure external process always connects to the right worker.

It will obviously connect to a random one. While this will still work in most cases it's not a recommended architecture, it will be unstable and buggy.

指令的參數跟上面 exec_push 的一樣。

Directive arguments are the same as for exec_push.

application myapp {
    live on;
    exec_pull ffmpeg -i http://example.com/video_$name.ts -c copy -f flv rtmp://localhost/$app/$name;
}

上面這個 exec_pull 的配置，會對所有的流起作用，這對遠程流名稱格式有一定的限制，如果有可能，它應該使用一些可用的變量如 $app、$name等來構造遠程鏈接；

若不可能，你可以添加 exec_options on 這個指令來允許在exec_family指令中額外設置流的選項，但目前只支持 name 這個選項。

In the above configuration exec_pull directive serves all streams. That leads to certain limitations on remote stream name format.

It should be possible to construct the remote url using available variables like $app, $name etc.

When it's not possible you can add exec_options on directive which permits setting additional stream options in exec-family directives.

The only option supported now is name option.

application myapp {
    live on;
    exec_options on;
    exec_pull ffmpeg -i http://example.com/tv1.ts -c copy -f flv rtmp://localhost/$app/$name name=mystream;
    exec_pull ffmpeg -i http://another.example.com/video_plus.ts -c copy -f flv rtmp://localhost/$app/$name name=anotherstream;
}

（上面示例，留意後面的name）

03、exec

語法：exec command arg*

上下文：rtmp, server, application

（exec是exec_push 的別名）

exec is an alias of exec_push

04、exec_options

語法：exec_options on|off

上下文：rtmp, server, application

這個指令用於切換 exec 選項模式，默認值爲關（off），當它設置爲開的時候，你可以添加exec_family指令選項，目前只支持 name 這個選項，這個選項可以讓exec 只針對指定的名稱的流起作用。

The directive toggles exec options mode. When activated you can add exec-family directive options.

The only exec option supported is name. This option makes it possible to apply exec only to specified stream. Default if off.

exec_options on;
# call on_publish only for "mystream"
exec_publish http://localhost/on_publish name=mystream;

# call on_play only for "another"
exec_play http://localhost/on_play name=another;

# execute different ffmpeg's for different streams
exec_pull http://example.com/abc.ts -c copy -f flv rtmp://localhost/$name/$app name=mystream;
exec_pull http://my.example.com/tele.ts -c copy -f flv rtmp://localhost/$name/$app name=tv;
exec_pull http://enother.example.com/hello/f.ts -c copy -f flv rtmp://localhost/$name/$app name=fun;

05、exec_static

語法：exec_static command arg*

上下文：rtmp, server, application

類似 exec 但在nginx啓動的時候就執行指定命令，不支持替代（使用變量），因爲沒有session 上下文。

Similar to exec but runs specified command at nginx start. Does not support substitutions since has no session context.

exec_static ffmpeg -i http://example.com/video.ts -c copy -f flv rtmp://localhost/myapp/mystream;

06、exec_kill_signal

語法：exec_kill_signal signal

上下文：rtmp, server, application

設置處理過程的終止信號，默認是 kill（SIGKILL），你可指定序號或者標識符（參考 POSIX.1-1990 信號）。

Sets process termination signal. Default is kill (SIGKILL). You can specify numeric or symbolic name (for POSIX.1-1990 signals).

exec_kill_signal term;
exec_kill_signal usr1;
exec_kill_signal 3;

07、respawn

語法：respawn on|off

上下文：rtmp, server, application

設置當終止時但發佈還在繼續時是否啓動重生子進程，默認值爲 on。

If turned on respawns child process when it's terminated while publishing is still on. Default is on;

respawn off;

08、respawn_timeout

語法：respawn_timeout timeout

上下文：rtmp, server, application

設置重生時等待子實例啓動的超時時間，默認是5秒。

Sets respawn timeout to wait before starting new child instance. Default is 5 seconds.

respawn_timeout 10s;

09、exec_publish

語法：exec_publish command arg*

上下文：rtmp, server, application

指定帶參數的外部命令，它在publish事件時執行；返回碼不解析（？），變量替換跟exec指令一樣支持，另外，args變量支持傳遞查詢參數。

Specifies external command with arguments to be executed on publish event. Return code is not analyzed.

Substitutions of exec are supported here as well. In addition args variable is supported holding query string arguments.

10、exec_play

語法：exec_play command arg*

上下文：rtmp, server, application

指定帶參數的外部命令，它在play事件時執行；返回碼不解析（？），變量替換跟 exec_publish 支持的一樣。

Specifies external command with arguments to be executed on play event. Return code is not analyzed. Substitution list is the same as for exec_publish.

11、exec_play_done

語法：exec_play_done command arg*

上下文：rtmp, server, application

指定帶參數的外部命令，它在play_done事件時執行；返回碼不解析（？），變量替換跟 exec_publish 支持的一樣。

Specifies external command with arguments to be executed on play_done event. Return code is not analyzed. Substitution list is the same as for exec_publish.

12、exec_publish_done

語法：exec_publish_done command arg*

上下文：rtmp, server, application

指定帶參數的外部命令，它在publish_done事件時執行；返回碼不解析（？），變量替換跟 exec_publish 支持的一樣。

Specifies external command with arguments to be executed on publish_done event. Return code is not analyzed. Substitution list is the same as for exec_publish.

13、exec_record_done

語法：exec_record_done command arg*

上下文：rtmp, server, application, recorder

指定帶參數的外部命令，它在記錄停止時執行；exec_publish支持的變量替換這裏也支持，另外還有一些附加的如下：

Specifies external command with arguments to be executed when recording is finished. Substitution of exec_publish are supported here as well as additional variables

• recorder  -  recorder name
• path   -  recorded file path (/tmp/rec/mystream-1389499351.flv)
• filename  -  path with directory omitted (mystream-1389499351.flv)
• basename  -  file name with extension omitted (mystream-1389499351)
• dirname  -  directory path (/tmp/rec)

例子：

# track client info
exec_play bash -c "echo $addr $pageurl >> /tmp/clients";
exec_publish bash -c "echo $addr $flashver >> /tmp/publishers";

# convert recorded file to mp4 format
exec_record_done ffmpeg -y -i $path -acodec libmp3lame -ar 44100 -ac 1 -vcodec libx264 $dirname/$basename.mp4;

參考：https://github.com/arut/nginx-rtmp-module/wiki/Directives