譯序:截至 Jul 8th,2013 官方公布的最新 Nginx RTMP 模塊 nginx-rtmp-module 指令詳解。
指令
Core
rtmp
語法:rtmp { ... }
上下文:根
描述:保存所有 RTMP 配置的塊。
server
語法:server { ... }
上下文:rtmp
描述:聲明一個 RTMP 實例。
rtmp {
server {
}
}
listen
語法:listen (addr[:port]|port|unix:path) [bind] [ipv6only=on|off] [so_keepalive=on|off|keepidle:keepintvl:keepcnt]
上下文:server
描述:給 NGINX 添加一個監(jiān)聽端口以接收 RTMP 連接。
server {
listen 1935;
}
application
語法:application name { ... }
上下文:server
描述:創(chuàng)建一個 RTMP 應(yīng)用。application 名的模式并不類似于 http location。
server {
listen 1935;
application myapp {
}
}
timeout
語法:timeout value
上下文:rtmp, server
描述:Socket 超時。這個值主要用于寫數(shù)據(jù)時。大多數(shù)情況下,RTMP 模塊并不期望除 publisher 端口之外的其他端口處于活動狀態(tài)。如果你想要快速關(guān)掉 socket 可以用 keepalive 或者 RTMP ping 等。timeout 默認(rèn)值為 1 分鐘。
timeout 60s;
ping
語法:ping value
上下文:rtmp, server
描述:RTMP ping 間隔。零值的話將 ping 關(guān)掉。RTMP ping 是一個用于檢查活動連接的協(xié)議功能。發(fā)送一個特殊的包到遠(yuǎn)程連接,然后在 ping_timeout 指令指定的時間內(nèi)期待一個回復(fù)。如果在這個時間里沒有收到 ping 回復(fù),連接斷開。ping 默認(rèn)值為一分鐘。ping_timeout 默認(rèn)值為 30 秒。
ping 3m;
ping_timeout 30s;
ping_timeout
語法:ping_timeout value
上下文:rtmp, server
描述:請參考上文 ping 描述。
max_streams
語法:max_streams value
上下文:rtmp, server
描述:設(shè)置 RTMP 流的最大數(shù)目。數(shù)據(jù)流被整合到一個單一的數(shù)據(jù)流里。不同的頻道用于發(fā)送命令、音頻、視頻等。默認(rèn)值為 32,適用于大多數(shù)情況。
max_streams 32;
ack_window
語法:ack_window value
上下文:rtmp, server
描述:設(shè)置 RTMP 確認(rèn)視窗大小。這是對端發(fā)送確認(rèn)包到遠(yuǎn)端后應(yīng)該收到的字節(jié)數(shù)量。默認(rèn)值為 5000000。
ack_window 5000000;
chunk_size
語法:chunk_size value
上下文:rtmp, server
描述:流整合的最大的塊大小。默認(rèn)值為 4096。這個值設(shè)置的越大 CPU 負(fù)載就越小。這個值不能低于 128。
chunk_size 4096;
max_queue
語法:max_queue value
上下文:rtmp, server
描述:輸入數(shù)據(jù)報文最大尺寸。所有輸入數(shù)據(jù)會被分割成報文(然后進(jìn)一步分割為塊)。報文在處理結(jié)束之前會放在內(nèi)存里。理論上講,接收到的報文很大的話對于服務(wù)器的穩(wěn)定性可能會有影響。默認(rèn)值 1M 對于大多數(shù)情況就足夠了。
max_message 1M;
out_queue
out_cork
Access
allow
語法:allow [play|publish] address|subnet|all
上下文:rtmp, server, application
允許來自指定地址或者所有地址發(fā)布/播放。allow 和 deny 指令的先后順序可選。
allow publish 127.0.0.1;
deny publish all;
allow play 192.168.0.0/24;
deny play all;
deny
語法:deny [play|publish] address|subnet|all
上下文:rtmp, server, application
描述:參考 allow 的描述。
Exec
exec
語法:exec command arg*
上下文:rtmp, server, application
描述:定義每個流發(fā)布時要執(zhí)行的帶有參數(shù)的外部命令。發(fā)布結(jié)束時進(jìn)程終止。第一個參數(shù)應(yīng)該是二進(jìn)制可執(zhí)行文件的完整路徑。關(guān)于這個進(jìn)程將會做些什么事沒有任何假定。但這一特點在使用 ffmpeg 進(jìn)行流轉(zhuǎn)換時是很有用的。FFmpeg 被假定作為客戶端連接到 nginx-rtmp 然后作為發(fā)布者輸出轉(zhuǎn)換流到 nginx-rtmp。類似于 $var/${var} 形式的替換可以在命令行使用:
* $name - 流的名字。
* $app - 應(yīng)用名。
* $addr - 客戶端地址。
* $flashver - 客戶端 flash 版本。
* $swfurl - 客戶端 swf url。
* $tcurl - 客戶端 tc url。
* $pageurl - 客戶端頁面 url。
可以在 exec 指令中定義 Shell 格式的轉(zhuǎn)向符用于寫輸出和接收輸入。支持如下
* 截斷輸出 >file。
* 附加輸出 >>file。
* 重定向描述符類似于 1>&2。
* 輸入 <file。
以下 ffmpeg 調(diào)用將輸入流轉(zhuǎn)碼為 HLS-ready 流(H264/AAC)。運行這個示例,F(xiàn)Fmpeg 須編譯為支持 libx264 & libfaac。
application src {
live on;
exec 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;
}
exec_static
語法:exec_static command arg*
上下文:rtmp, server, application
描述:類似于 exec 指令,但在 nginx 啟動時將運行定義的命令。因為(啟動時)尚無會話上下文,不支持替換。
exec_static ffmpeg -i http://example.com/video.ts -c copy -f flv rtmp://localhost/myapp/mystream;
exec_kill_signal
語法:exec_kill_signal signal
上下文:rtmp, server, application
描述:設(shè)置進(jìn)程終止信號。默認(rèn)為 kill(SIGKILL)。你可以定義為數(shù)字或者符號名(POSIX.1-1990 信號)。
exec_kill_signal term;
exec_kill_signal usr1;
exec_kill_signal 3;
respawn
語法:respawn on|off
上下文:rtmp, server, application
描述:如果打開 respawn 子進(jìn)程,進(jìn)程終止時發(fā)布會仍然繼續(xù)。默認(rèn)為打開。
respawn off;
respawn_timeout
語法:respawn_timeout timeout
上下文:rtmp, server, application
描述:啟動新的子實例之前,設(shè)置 respawn 超時時間。默認(rèn)為五秒。
respawn_timeout 10s;
exec_publish
語法:exec_publish command arg*
上下文:rtmp, server, application
描述:指定發(fā)布事件觸發(fā)的帶有參數(shù)的外部命令。返回碼是未解析的。這里可以用 exec 替換。另外,args 變量支持持有查詢字符串參數(shù)。
exec_play
語法:exec_play command arg*
上下文:rtmp, server, application
描述:指定播放事件觸發(fā)的帶有參數(shù)的外部命令。返回碼是未解析的。替換列表同 exec_publish。
exec_play_done
語法:exec_play_done command arg*
上下文:rtmp, server, application
描述:指定播放結(jié)束事件觸發(fā)的帶有參數(shù)的外部命令。返回碼是未解析的。替換列表同 exec_publish。
exec_publish_done
語法:exec_publish_done command arg*
上下文:rtmp, server, application
描述:指定發(fā)布結(jié)束事件觸發(fā)的帶有參數(shù)的外部命令。返回碼是未解析的。替換列表同 exec_publish。
exec_record_done
語法:exec_record_done command arg*
上下文:rtmp, server, application, recorder
描述:指定錄制結(jié)束時觸發(fā)的帶有參數(shù)的外部命令。這里支持 exec_publish 的替代以及額外的變量 path 和 recorder。
# 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 $path.mp4;
Live
live
語法:live on|off
上下文:rtmp, server, application
描述:切換直播模式,即一對多廣播。
live on;
meta
語法:meta on|off
上下文:rtmp, server, application
描述:切換發(fā)送元數(shù)據(jù)到客戶端。默認(rèn)為 on。
meta off;
interleave
語法:interleave on|off
上下文:rtmp, server, application
描述:切換交叉模式。在這個模式下,音頻和視頻數(shù)據(jù)會在同一個 RTMP chunk 流中傳輸。默認(rèn)為 off。
interleave on;
wait_key
語法:wait_key on|off
上下文:rtmp, server, application
描述:使視頻流從一個關(guān)鍵幀開始。默認(rèn)為 off。
wait_key on;
wait_video
語法:wait_video on|off
上下文:rtmp, server, application
描述:在第一個視頻幀發(fā)送之前禁用音頻。默認(rèn)為 off??梢院?wait_key 進(jìn)行組合以使客戶端可以收到具有所有其他數(shù)據(jù)的視頻關(guān)鍵幀。然而這通常增加連接延遲。您可以通過在編碼器中調(diào)整關(guān)鍵幀間隔來減少延遲。
wait_video on;
publish_notify
語法:publish_notify on|off
上下文:rtmp, server, application
描述:發(fā)送 NetStream.Publish.Start 和 NetStream.Publish.Stop 給用戶。默認(rèn)為 off。
publish_notify on;
drop_idle_publisher
語法:drop_idle_publisher timeout
上下文:rtmp, server, application
描述:終止指定時間內(nèi)閑置(沒有音頻/視頻數(shù)據(jù))的發(fā)布連接。默認(rèn)為 off。注意這個僅僅對于發(fā)布模式的連接起作用(發(fā)送 publish 命令之后)。
drop_idle_publisher 10s;
sync
語法:sync timeout
上下文:rtmp, server, application
描述:同步音頻和視頻流。如果用戶帶寬不足以接收發(fā)布率,服務(wù)器會丟棄一些幀。這將導(dǎo)致同步問題。當(dāng)時間戳差超過 sync 指定的值,將會發(fā)送一個絕對幀來解決這個問題。默認(rèn)為 300 ms。
sync 10ms;
play_restart
語法:play_restart on|off
上下文:rtmp, server, application
描述:使 nginx-rtmp 能夠在發(fā)布啟動或停止時發(fā)送 NetStream.Play.Start 和 NetStream.Play.Stop 到每個用戶。如果關(guān)閉的話,那么每個用戶就只能在回放的開始和結(jié)束時收到這些通知了。默認(rèn)為 on。
play_restart off;
Record
record
語法:record [off|all|audio|video|keyframes|manual]*
上下文:rtmp, server, application, recorder
描述:切換錄制模式。流可以被記錄到 flv 文件。本指令指定應(yīng)該被記錄的:
* off - 什么也不錄制
* all - 音頻和視頻(所有)
* audio - 音頻
* video - 視頻
* keyframes - 只錄制關(guān)鍵視頻幀
* manual - 用不自動啟動錄制,使用控制接口來啟動/停止
在單個記錄指令中可以有任何兼容的組合鍵。
record all;
record audio keyframes;
record_path
語法:record_path path
上下文:rtmp, server, application, recorder
描述:指定錄制的 flv 文件存放目錄。
record_path /tmp/rec;
record_suffix
語法:record_suffix value
上下文:rtmp, server, application, recorder
描述:設(shè)置錄制文件后綴名。默認(rèn)為 '.flv'。
record_suffix _recorded.flv;
錄制后綴可以匹配 strftime 格式。以下指令
record_suffix -%d-%b-%y-%T.flv
將會產(chǎn)生形如 mystream-24-Apr-13-18:23:38.flv 的文件。所有支持 strftime 格式的選項可以在 strftime man page 里進(jìn)行查找。
record_unique
語法:record_unique on|off
上下文:rtmp, server, application, recorder
描述:是否添加時間戳到錄制文件。否則的話同樣的文件在每一次新的錄制發(fā)生時將被重寫。默認(rèn)為 off。
record_unique on;
record_append
語法:record_append on|off
上下文:rtmp, server, application, recorder
描述:切換文件附加模式。當(dāng)這一指令為開啟是,錄制時將把新數(shù)據(jù)附加到老文件,如果老文件丟失的話將重新創(chuàng)建一個。文件中的老數(shù)據(jù)和新數(shù)據(jù)沒有時間差。默認(rèn)為 off。
record_append on;
record_lock
語法:record_lock on|off
上下文:rtmp, server, application, recorder
描述:當(dāng)這一指令開啟時,當(dāng)前錄制文件將被 fcntl 調(diào)用鎖定。那樣可以在其他地方來核實哪個文件正在進(jìn)行錄制。默認(rèn)為 off。
record_lock on;
在 FreeBSD 上你可以使用 flock 工具檢查。在 Linux 上 flock 和 fcntl 無關(guān),因此你需要去寫一個簡單的腳本來檢查文件的鎖定狀態(tài)。以下 isunlocked.py 是一個這樣的腳本的示例。
[python]
view plaincopyprint?#!/usr/bin/python
import fcntl, sys
sys.stderr.close()
fcntl.lockf(open(sys.argv[1], "a"), fcntl.LOCK_EX|fcntl.LOCK_NB)
record_max_size
語法:record_max_size size
上下文:rtmp, server, application, recorder
描述:設(shè)置錄制文件的最大值。
record_max_size 128K;
record_max_frames
語法:record_max_frames nframes
上下文:rtmp, server, application, recorder
描述:設(shè)置每個錄制文件的視頻幀的最大數(shù)量。
record_max_frames 2;
record_interval
語法:record_interval time
上下文:rtmp, server, application, recorder
描述:在這個指令指定數(shù)量的(毫秒)秒之后重啟錄制。默認(rèn)為 off。設(shè)置為 0 的話意味著錄制中無延遲。如果 record_unique 為 off 的話所有記錄片段會被寫到同一個文件。否則(文件名)將附以時間戳以區(qū)分不同文件(給定的 record_interval 要大于 1 秒)。
record_interval 1s;
record_interval 15m;
recorder
語法:recorder name {...}
上下文:application
描述:創(chuàng)建錄制塊??梢栽趩蝹€ application 中創(chuàng)建多個記錄。上文提到的所有錄制相關(guān)的指令都可以在 recorder{} 塊中進(jìn)行定義。繼承高層次中的所有設(shè)置。
application {
live on;
# default recorder
record all;
record_path /var/rec;
recorder audio {
record audio;
record_suffix .audio.flv;
}
recorder chunked {
record all;
record_interval 15s;
record_path /var/rec/chunked;
}
}
record_notify
語法:record_notify on|off
上下文:rtmp, server, application, recorder
描述:切換當(dāng)定義錄制啟動或停止文件時發(fā)送 NetStream.Record.Start 和 NetStream.Record.Stop 狀態(tài)信息(onStatus)到發(fā)布者。狀態(tài)描述字段保存錄制的名字(默認(rèn)錄制的話為空)。默認(rèn)為 off。
recorder myrec {
record all manual;
record_path /var/rec;
record_notify on;
}
VOD
play
語法:lay dir|http://loc [dir|http://loc]*
上下文:rtmp, server, application
描述:播放指定目錄或者 HTTP 地址的 flv 或者 mp4 文件。如果此參數(shù)前綴是 http:// 那么就認(rèn)為文件可以在播放前從遠(yuǎn)程 http 地址下載下來。注意播放是在整個文件下載完畢之后才開始。你可以使用本地 nginx 在本地機器緩存文件。
同一個 play 指令可以定義多個播放地址。當(dāng)多個 play 指令定義時,地址列表將被合并,并進(jìn)行從更高域中繼承。嘗試播放每一個地址,直到發(fā)現(xiàn)一個成功的地址。如果沒有找到成功地址,將發(fā)送錯誤狀態(tài)到客戶端。
索引的 FLV 播放具有隨機查找能力。沒有索引的 FLV 則不具備查找/暫停能力(重播模式)。使用 FLV 索引器(比如 yamdi)來編索引。
mp4 文件只有在音頻和視頻編碼都被 RTMP 支持時才可以播放。最常見的情況是 H264/AAC。
application vod {
play /var/flvs;
}
application vod_http {
play http://myserver.com/vod;
}
application vod_mirror {
# try local location first, then access remote location
play /var/local_mirror http://myserver.com/vod;
}
播放 /var/flvs/dir/file.flv:
[plain]
view plaincopyprint?ffplay rtmp://localhost/vod/dir/file.flv
play_temp_path
語法:play_temp_path dir
上下文:rtmp, server, application
描述:在播放之前設(shè)置遠(yuǎn)程存儲的 VOD 文件路徑。默認(rèn)為 /tmp。
play_temp_path /www;
play http://example.com/videos;
play_local_path
語法:play_local_path dir
上下文:rtmp, server, application
描述:設(shè)置遠(yuǎn)程 VOD 文件完全下載之后復(fù)制于 play_temp_path 之后的路徑??罩档脑捊么斯δ?。默認(rèn)為控制。這個功能可以用于緩存遠(yuǎn)程文件在本地。
這一路徑應(yīng)該和 play_temp_path 處于同一設(shè)備。
# search file in /tmp/videos.
# if not found play from remote location
# and store in /tmp/videos
play_local_path /tmp/videos;
play /tmp/videos http://example.com/videos;
Relay
pull
語法:pull url [key=value]*
上下文:application
描述:創(chuàng)建 pull 中繼。流將從遠(yuǎn)程服務(wù)器上拉下來,成為本地可用的。僅當(dāng)至少有一個播放器正在播放本地流時發(fā)生。
Url 語法:[rtmp://]host[:port][/app[/playpath]]。如果 application 找不著那么將會使用本地 application 名。如果找不著 playpath 那么就是用當(dāng)前流的名字。
支持以下參數(shù):
* app - 明確 application 名。
* name - 捆綁到 relay 的本地流名字。如果為空或者沒有定義,那么將會使用 application 中的所有本地流。
* tcUrl - 如果為空的話自動構(gòu)建。
* pageUrl - 模擬頁面 url。
* swfUrl - 模擬 swf url。
* flashVer - 模擬 flash 版本,默認(rèn)為 'LNX.11,1,102,55'。
* playPath - 遠(yuǎn)程播放地址。
* live - 切換直播特殊行為,值:0,1。
* start - 開始時間。
* stop - 結(jié)束時間。
* static - 創(chuàng)建靜態(tài) pull,這樣的 pull 在 nginx 啟動時創(chuàng)建。
如果某參數(shù)的值包含空格,那么你應(yīng)該在整個 key=value 對周圍使用引號,比如:'pageUrl=FAKE PAGE URL'。
pull rtmp://cdn.example.com/main/ch?id=12563 name=channel_a;
pull rtmp://cdn2.example.com/another/a?b=1&c=d pageUrl=http://www.example.com/video.html swfUrl=http://www.example.com/player.swf live=1;
pull rtmp://cdn.example.com/main/ch?id=12563 name=channel_a static;
push
語法:push url [key=value]*
上下文:application
描述:push 的語法和 pull 一樣。不同于 pull 指令的是 push 推送發(fā)布流到遠(yuǎn)程服務(wù)器。
push_reconnect
語法:push_reconnect time
上下文:rtmp, server, application
描述:在斷開連接后,在 push 重新連接前等待的時間。默認(rèn)為 3 秒。
push_reconnect 1s;
session_relay
語法:session_relay on|off
上下文:rtmp, server, application
描述:切換會話 relay 模式。在這種模式下連接關(guān)閉時 relay 銷毀。當(dāng)設(shè)置為 off 時,流關(guān)閉,relay 銷毀,這樣子以后另一個 relay 可以被創(chuàng)建。默認(rèn)為 off。
session_relay on;
Notify
on_connect
語法:on_connect url
上下文:rtmp, server
描述:設(shè)置 HTTP 連接回調(diào)。當(dāng)客戶分發(fā)連接命令一個連接命令時,一個 HTTP 請求異步發(fā)送,命令處理將被暫停,直到它返回結(jié)果代碼。當(dāng) HTTP 2XX 碼(成功狀態(tài)碼)返回時,RTMP 會話繼續(xù)。返回碼 3XX (重定向狀態(tài)碼)會使 RTMP 重定向到另一個從 HTTP 返回頭里獲取到的 application。否則(其他狀態(tài)碼)連接丟棄。
注意這一指令在 application 域是不允許的,因為 application 在連接階段還是未知的。
HTTP 請求接收到一些參數(shù)。在 application/x-www-form-urlencoded MIME 類型下使用 POST 方法。以下參數(shù)將被傳給調(diào)用者:
* call=connect。
* addr - 客戶端 IP 地址。
* app - application 名。
* flashVer - 客戶端 flash 版本。
* swfUrl - 客戶端 swf url。
* tcUrl - tcUrl。
* pageUrl - 客戶端頁面 url。
除了上述參數(shù)以外,所有顯式傳遞給連接命令的參數(shù)也由回調(diào)發(fā)送。你應(yīng)該將連接參數(shù)和 play/publish 參數(shù)區(qū)分開。播放器常常有獨特的方式設(shè)置連接字符串不同于 play/publish 流名字。這里是 JWPayer 是如何設(shè)置這些參數(shù)的一個示例:
[plain]
view plaincopyprint?...
streamer: "rtmp://localhost/myapp?connarg1=a&connarg2=b",
file: "mystream?strarg1=c&strarg2=d",
...
Ffplay(帶有 librtmp)示例:
[plain]
view plaincopyprint?ffplay "rtmp://localhost app=myapp?connarg1=a&connarg2=b playpath=mystream?strarg1=c&strarg2=d"
使用例子:
on_connect http://example.com/my_auth;
重定向例子:
location /on_connect {
if ($arg_flashver != "my_secret_flashver") {
rewrite ^.*$ fallback? permanent;
}
return 200;
}
on_play
語法:on_play url
上下文:rtmp, server, application
描述:設(shè)置 HTTP 播放回調(diào)。每次一個客戶分發(fā)播放命令時,一個 HTTP 請求異步發(fā)送,命令處理會掛起 - 直到它返回結(jié)果碼。之后再解析 HTTP 結(jié)果碼。
* HTTP 2XX 返回碼的話繼續(xù) RTMP 會話。
* HTTP 3XX 返回碼的話 重定向 RTMP 到另一個流,這個流的名字在 HTTP 返回頭的 Location 獲取。如果新流的名字起始于 rtmp:// 然后遠(yuǎn)程 relay 會被創(chuàng)建。relay 要求 IP 地址是指定的而不是域名,并且只工作在 1.3.10 版本以上的 nginx。另請參考 notify_relay_redirect。
* 其他返回碼的話 RTMP 連接丟棄。
重定向例子:
http {
...
location /local_redirect {
rewrite ^.*$ newname? permanent;
}
location /remote_redirect {
# no domain name here, only ip
rewrite ^.*$ rtmp://192.168.1.123/someapp/somename? permanent;
}
...
}
rtmp {
...
application myapp1 {
live on;
# stream will be redirected to 'newname'
on_play http://localhost:8080/local_redirect;
}
application myapp2 {
live on;
# stream will be pulled from remote location
# requires nginx >= 1.3.10
on_play http://localhost:8080/remote_redirect;
}
...
}
HTTP 請求接收到一些個參數(shù)。在 application/x-www-form-urlencoded MIME 類型下使用 POST 方法。以下參數(shù)會被傳送給調(diào)用者:
* call=play。
* addr - 客戶端 IP 地址。
* app - application 名。
* flashVer - 客戶端 flash 版本。
* swfUrl - 客戶端 swf url。
* tcUrl - tcUrl。
* pageUrl - 客戶端頁面 url。
* name - 流名。
出了上述參數(shù)之外其他所有播放命令參數(shù)顯式地發(fā)送回調(diào)。例如如果一個流由 url rtmp://localhost/app/movie?a=100&b=face&foo=bar 訪問,然后呢 a,b 和 foo 發(fā)送回調(diào)。
on_play http://example.com/my_callback;
on_publish
語法:on_publish url
上下文:rtmp, server, application
描述:同上面提到的 on_play 一樣,唯一的不同點在于這個指令在發(fā)布命令設(shè)置回調(diào)。不同于遠(yuǎn)程 pull,push 在這里是可以的。
on_done
語法:on_done url
上下文:rtmp, server, application
描述:設(shè)置播放/發(fā)布禁止回調(diào)。上述所有適用于此。但這個回調(diào)并不檢查 HTTP 狀態(tài)碼。
on_play_done
語法:on_publish_done url
上下文:rtmp, server, application
描述:等同于 on_done 的表現(xiàn),但只適用于播放結(jié)束事件。
on_publish_done
語法:on_publish_done url
上下文:rtmp, server, application
描述:等同于 on_done 的表現(xiàn),但只適用于發(fā)布結(jié)束事件。
on_record_done
語法:on_record_done url
上下文:rtmp, server, application, recorder
描述:設(shè)置 record_done 回調(diào)。除了普通 HTTP 回調(diào)參數(shù)它接受錄制文件路徑。
on_record_done http://example.com/recorded;
on_update
語法:on_update url
上下文:rtmp, server, application
描述:設(shè)置 update 回調(diào)。這個回調(diào)會在 notify_update_timeout 期間調(diào)用。如果一個請求返回結(jié)果不是 2XX,連接禁止。這可以用來同步過期的會話。追加 time 參數(shù)即播放/發(fā)布調(diào)用后的秒數(shù)會被發(fā)送給處理程序。
on_update http://example.com/update;
notify_update_timeout
語法:notify_update_timeout timeout
上下文:rtmp, server, application
描述:在 on_update 回調(diào)之間的超時設(shè)置。默認(rèn)為 30 秒。
notify_update_timeout 10s;
on_update http://example.com/update;
notify_update_strict
語法:notify_update_strict on|off
上下文:rtmp, server, application
描述:切換 on_update 回調(diào)嚴(yán)格模式。默認(rèn)為 off。當(dāng)設(shè)置為 on 時,所有連接錯誤,超時以及 HTTP 解析錯誤和空返回會被視為更新失敗并導(dǎo)致連接終止。當(dāng)設(shè)置為 off 時只有 HTTP 返回碼不同于 2XX 時導(dǎo)致失敗。
notify_update_strict on;
on_update http://example.com/update;
notify_relay_redirect
語法:notify_relay_redirect on|off
上下文:rtmp, server, application
描述:使本地流可以重定向為 on_play 和 on_publish 遠(yuǎn)程重定向。新的流名字是 RTMP URL 用于遠(yuǎn)程重定向。默認(rèn)為 off。
notify_relay_redirect on;
notify_method
語法:notify_method get|post
上下文:rtmp, server, application, recorder
描述:設(shè)置 HTTP 方法通知。默認(rèn)是帶有 application/x-www-form-urlencoded 的 POST 內(nèi)容類型。在一些情況下 GET 更好,例如如果你打算在 nginx 的 http{} 部分處理調(diào)用。在這種情況下你可以使用 arg_* 變量去訪問參數(shù)。
notify_method get;
在 http{} 部分使用 GET 方法處理通知可以使用這種方法:
location /on_play {
if ($arg_pageUrl ~* localhost) {
return 200;
}
return 500;
}
HLS
hls
語法:hls on|off
上下文:rtmp, server, application
描述:在 application 切換 HLS。
hls on;
hls_path /tmp/hls;
hls_fragment 15s;
在 http{} 段為客戶端播放 HLS 設(shè)置在以下位置設(shè)置:
http {
...
server {
...
location /hls {
types {
application/vnd.apple.mpegurl m3u8;
}
alias /tmp/hls;
}
}
}
hls_path
語法:hls_path path
上下文:rtmp, server, application
描述:設(shè)置 HLS 播放列表和分段目錄。這一目錄必須在 NGINX 啟動前就已存在。
hls_fragment
語法:hls_fragment time
上下文:rtmp, server, application
描述:設(shè)置 HLS 分段長度。默認(rèn)為 5 秒鐘。
hls_playlist_length
語法:hls_playlist_length time
上下文:rtmp, server, application
描述:設(shè)置 HLS 播放列表長度。默認(rèn)為 30 秒鐘。
hls_playlist_length 10m;
hls_sync
語法:hls_sync time
上下文:rtmp, server, application
描述:設(shè)置 HLS 時間戳同步閾值。默認(rèn)為 2 ms。這一功能可以防止由低分辨率 RTMP (1KHz) 轉(zhuǎn)換到高分辨率 MPEG-TS (90KHz) 之后出現(xiàn)噪音。
hls_sync 100ms;
hls_continuous
語法:hls_continuous on|off
上下文:rtmp, server, application
描述:切換 HLS 連續(xù)模式。這一模式下 HLS 序列號由其上次停止的最后時間開始。老的分段保留下來。默認(rèn)為 off。
hls_continuous on;
hls_nested
語法:hls_nested on|off
上下文:rtmp, server, application
描述:切換 HLS 嵌套模式。這一模式下為每個流創(chuàng)建了一個 hls_path 的子目錄。播放列表和分段在那個子目錄中創(chuàng)建。默認(rèn)為 off。
hls_nested on;
hls_cleanup
語法:hls_cleanup on|off
上下文:rtmp, server, application
描述:切換 HLS 清理。這一功能默認(rèn)為開啟的。在這一模式下 nginx 緩存管理進(jìn)程將老的 HLS 片段和播放列表由 HLS 清理掉。
hls_cleanup off;
Access log
access_log
語法:access_log off|path [format_name]
上下文:rtmp, server, application
描述:設(shè)置訪問日志參數(shù)。日志默認(rèn)是開啟的。關(guān)閉日志可以使用 access_log off 指令。默認(rèn)情況下訪問日志和 HTTP 訪問日志 logs/access.log 放到同一文件。你也可以使用 access_log 指令將其定義到其他日志文件。第二個參數(shù)是可選的??梢愿鶕?jù)名字來定義日志格式。請參考 log_format 指令來獲取更多關(guān)于格式的詳細(xì)信息。
log_format new '$remote_addr';
access_log logs/rtmp_access.log new;
access_log logs/rtmp_access.log;
access_log off;
log_format
語法:log_format format_name format
上下文:rtmp
描述:創(chuàng)建指定的日志格式。日志格式看起來很像 nginx HTTP 日志格式。日志格式里支持的幾個變量有:
* connection - 連接數(shù)。
* remote_addr - 客戶端地址。
* app - application 名。
* name - 上一個流名。
* args - 上一個流播放/發(fā)布參數(shù)。
* flashver - 客戶端 flash 版本。
* swfurl - 客戶端 swf url。
* tcurl - 客戶端 tcUrl。
* pageurl - 客戶端頁面 url。
* command - 客戶端發(fā)送的播放/發(fā)布命令:NONE、PLAY、PUBLISH、PLAY+PUBLISH。
* bytes_sent - 發(fā)送到客戶端的字節(jié)數(shù)。
* bytes_received - 從客戶端接收到的字節(jié)數(shù)。
* time_local - 客戶端連接結(jié)束的本地時間。
* session_time - 持續(xù)連接的秒數(shù)。
* session_readable_time - 在可讀格式下的持續(xù)時間。
默認(rèn)的日志格式叫做 combined。這里是這一格式的定義:
$remote_addr [$time_local] $command "$app" "$name" "$args" -
$bytes_received $bytes_sent "$pageurl" "$flashver" ($session_readable_time)
Limits
max_connections
語法:max_connections number
上下文:rtmp, server, application
描述:為 rtmp 引擎設(shè)置最大連接數(shù)。默認(rèn)為 off。
max_connections 100;
Statistics
statistics 模塊不同于本文列舉的其他模塊,它是 NGINX HTTP 模塊。因此 statistics 指令應(yīng)該位于 http{} 塊內(nèi)部。
rtmp_stat
語法:rtmp_stat all
上下文:http, server, location
描述:為當(dāng)前 HTTP location 設(shè)置 RTMP statistics 處理程序。RTMP statistics 是一個靜態(tài)的 XML 文檔??梢允褂?rtmp_stat_stylesheet 指令在瀏覽器中作為 XHTML 頁面查看這個文檔。
http {
server {
location /stat {
rtmp_stat all;
rtmp_stat_stylesheet stat.xsl;
}
location /stat.xsl {
root /path/to/stat/xsl/file;
}
}
}
rtmp_stat_stylesheet
語法:rtmp_stat_stylesheet path
上下文:http, server, location
描述:添加 XML 樣式表引用到 statistics XML 使其可以在瀏覽器中可視。更多信息請參考 rtmp_stat 描述和例子。
Multi-worker live streaming
多 worker 直播流是通過推送流到剩余的 nginx worker 實現(xiàn)的。
rtmp_auto_push
語法:rtmp_auto_push on|off
上下文:root
描述:切換自動推送(多 worker 直播流)模式。默認(rèn)為 off。
rtmp_auto_push_reconnect
語法:rtmp_auto_push_reconnect timeout
上下文:root
描述:當(dāng) worker 被干掉時設(shè)置自動推送連接超時時間。默認(rèn)為 100 毫秒。
rtmp_socket_dir
語法:rtmp_socket_dir dir
上下文:root
描述:設(shè)置用于流推送的 UNIX 域套接字目錄。默認(rèn)為 /tmp。
rtmp_auto_push on;
rtmp_auto_push_reconnect 1s;
rtmp_socket_dir /var/sock;
rtmp {
server {
listen 1935;
application myapp {
live on;
}
}
}
Control
control 模塊是 NGINX HTTP 模塊,應(yīng)該放在 http{} 塊之內(nèi)。
rtmp_control
語法:rtmp_control all
上下文:http, server, location
描述:為當(dāng)前 HTTP location 設(shè)置 RTMP 控制程序。
http {
server {
location /control {
rtmp_control all;
}
}
}