【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