v3_EN_HTTPCallback
HOME > EN > HTTP Callback
SRS does not support server-side scripting, instead it supports HTTP callbacks; read ServerSide script.
For token authentication based on HTTP callbacks, read Token Authentication
SRS always enable http callbacks.
For more information, read Build
The config for HTTP hooks is:
vhost your_vhost { http_hooks { # whether the http hooks enable. # default off. enabled on; # when client connect to vhost/app, call the hook, # the request in the POST data string is a object encode by json: # { # "action": "on_connect", # "client_id": 1985, # "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", # "tcUrl": "rtmp://video.test.com/live?key=d2fa801d08e3f90ed1e1670e6e52651a", # "pageUrl": "http://www.test.com/live.html" # } # if valid, the hook must return HTTP code 200(Status OK) and response # an int value specifies the error code(0 corresponding to success): # 0 # support multiple api hooks, format: # on_connect http://xxx/api0 http://xxx/api1 http://xxx/apiN on_connect http://127.0.0.1:8085/api/v1/clients http://localhost:8085/api/v1/clients; # when client close/disconnect to vhost/app/stream, call the hook, # the request in the POST data string is a object encode by json: # { # "action": "on_close", # "client_id": 1985, # "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", # "send_bytes": 10240, "recv_bytes": 10240 # } # if valid, the hook must return HTTP code 200(Status OK) and response # an int value specifies the error code(0 corresponding to success): # 0 # support multiple api hooks, format: # on_close http://xxx/api0 http://xxx/api1 http://xxx/apiN on_close http://127.0.0.1:8085/api/v1/clients http://localhost:8085/api/v1/clients; # when client(encoder) publish to vhost/app/stream, call the hook, # the request in the POST data string is a object encode by json: # { # "action": "on_publish", # "client_id": 1985, # "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", # "stream": "livestream" # } # if valid, the hook must return HTTP code 200(Status OK) and response # an int value specifies the error code(0 corresponding to success): # 0 # support multiple api hooks, format: # on_publish http://xxx/api0 http://xxx/api1 http://xxx/apiN on_publish http://127.0.0.1:8085/api/v1/streams http://localhost:8085/api/v1/streams; # when client(encoder) stop publish to vhost/app/stream, call the hook, # the request in the POST data string is a object encode by json: # { # "action": "on_unpublish", # "client_id": 1985, # "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", # "stream": "livestream", "param":"?token=xxx&salt=yyy" # } # if valid, the hook must return HTTP code 200(Status OK) and response # an int value specifies the error code(0 corresponding to success): # 0 # support multiple api hooks, format: # on_unpublish http://xxx/api0 http://xxx/api1 http://xxx/apiN on_unpublish http://127.0.0.1:8085/api/v1/streams http://localhost:8085/api/v1/streams; # when client start to play vhost/app/stream, call the hook, # the request in the POST data string is a object encode by json: # { # "action": "on_play", # "client_id": 1985, # "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", # "stream": "livestream", "param":"?token=xxx&salt=yyy", # "pageUrl": "http://www.test.com/live.html" # } # if valid, the hook must return HTTP code 200(Status OK) and response # an int value specifies the error code(0 corresponding to success): # 0 # support multiple api hooks, format: # on_play http://xxx/api0 http://xxx/api1 http://xxx/apiN on_play http://127.0.0.1:8085/api/v1/sessions http://localhost:8085/api/v1/sessions; # when client stop to play vhost/app/stream, call the hook, # the request in the POST data string is a object encode by json: # { # "action": "on_stop", # "client_id": 1985, # "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", # "stream": "livestream", "param":"?token=xxx&salt=yyy" # } # if valid, the hook must return HTTP code 200(Status OK) and response # an int value specifies the error code(0 corresponding to success): # 0 # support multiple api hooks, format: # on_stop http://xxx/api0 http://xxx/api1 http://xxx/apiN on_stop http://127.0.0.1:8085/api/v1/sessions http://localhost:8085/api/v1/sessions; # when srs reap a dvr file, call the hook, # the request in the POST data string is a object encode by json: # { # "action": "on_dvr", # "client_id": 1985, # "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", # "stream": "livestream", "param":"?token=xxx&salt=yyy", # "cwd": "/usr/local/srs", # "file": "./objs/nginx/html/live/livestream.1420254068776.flv" # } # if valid, the hook must return HTTP code 200(Status OK) and response # an int value specifies the error code(0 corresponding to success): # 0 on_dvr http://127.0.0.1:8085/api/v1/dvrs http://localhost:8085/api/v1/dvrs; # when srs reap a ts file of hls, call the hook, # the request in the POST data string is a object encode by json: # { # "action": "on_hls", # "client_id": 1985, # "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", # "stream": "livestream", "param":"?token=xxx&salt=yyy", # "duration": 9.36, // in seconds # "cwd": "/usr/local/srs", # "file": "./objs/nginx/html/live/livestream/2015-04-23/01/476584165.ts", # "url": "live/livestream/2015-04-23/01/476584165.ts", # "m3u8": "./objs/nginx/html/live/livestream/live.m3u8", # "m3u8_url": "live/livestream/live.m3u8", # "seq_no": 100 # } # if valid, the hook must return HTTP code 200(Status OK) and response # an int value specifies the error code(0 corresponding to success): # 0 on_hls http://127.0.0.1:8085/api/v1/hls http://localhost:8085/api/v1/hls; # when srs reap a ts file of hls, call this hook, # used to push file to cdn network, by get the ts file from cdn network. # so we use HTTP GET and use the variable following: # [app], replace with the app. # [stream], replace with the stream. # [param], replace with the param. # [ts_url], replace with the ts url. # ignore any return data of server. # @remark random select a url to report, not report all. on_hls_notify http://127.0.0.1:8085/api/v1/hls/[app]/[stream]/[ts_url][param]; } } Note: For more information, read the section hooks.callback.vhost.com in conf/full.conf
SRS can call HTTP callbacks for events:
| Event | Data | Description |
|---|---|---|
| on_connect | { "action": "on_connect", "client_id": 1985, "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", "tcUrl": "rtmp://x/x?key=xxx", "pageUrl": "http://x/x.html" } | When a client connects to the specified vhost and app. |
| on_close | { "action": "on_close", "client_id": 1985, "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", "send_bytes": 10240, "recv_bytes": 10240 } | When a client closes a connection, or the server drops a connection. |
| on_publish | { "action": "on_publish", "client_id": 1985, "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", "stream": "livestream" } | When a client publishes a stream, for example, using flash or FMLE to publish a stream to the server. |
| on_unpublish | { "action": "on_unpublish", "client_id": 1985, "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", "stream": "livestream" } | When a client stops publishing a stream. |
| on_play | { "action": "on_play", "client_id": 1985, "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", "stream": "livestream", "pageUrl": "http://a.com/i.html", "param":"?k=v" } | When a client starts playing a stream. |
| on_stop | { "action": "on_stop", "client_id": 1985, "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", "stream": "livestream" } | When a client stops playback. |
| on_dvr | { "action": "on_dvr", "client_id": 1985, "ip": "192.168.1.10", "vhost": "video.test.com", "app": "live", "stream": "livestream", "cwd": "/opt", "file": "./l.xxx.flv" } | When reap a DVR file. |
Notes:
- Event: When this event occurs, call back to the specified HTTP URL.
- HTTP URL: Can be multiple URLs, split by spaces, SRS will notify all one by one.
- Data: SRS will POST the data to specified HTTP API.
- Return Code: SRS requires that the response is an int indicating the error, 0 is success. SRS will disconnect the connection when the response is not 0, or HTTP status is not 200.
SRS provides a default HTTP callback server, using cherrypy.
To start it: python research/api-server/server.py 8085
[winlin@dev6 srs]$ python research/api-server/server.py 8085 [2014-02-27 09:42:25][trace] api server listen at port: 8085, static_dir: /home/winlin/git/srs/trunk/research/api-server/static-dir [2014-02-27 09:42:25][trace] start cherrypy server [27/Feb/2014:09:42:25] ENGINE Listening for SIGHUP. [27/Feb/2014:09:42:25] ENGINE Listening for SIGTERM. [27/Feb/2014:09:42:25] ENGINE Listening for SIGUSR1. [27/Feb/2014:09:42:25] ENGINE Bus STARTING [27/Feb/2014:09:42:25] ENGINE Started monitor thread '_TimeoutMonitor'. [27/Feb/2014:09:42:25] ENGINE Started monitor thread 'Autoreloader'. [27/Feb/2014:09:42:25] ENGINE Serving on 0.0.0.0:8085 [27/Feb/2014:09:42:25] ENGINE Bus STARTEDWhen publishing a stream to SRS, SRS will call the registered HTTP callback:
[2014-02-27 09:41:33][trace] post to clients, req={"action":"on_connect","client_id":4,"ip":"192.168.1.179","vhost":"__defaultVhost__","app":"live","pageUrl":""} [2014-02-27 09:41:33][trace] srs on_connect: client id=4, ip=192.168.1.179, vhost=__defaultVhost__, app=live, pageUrl= 127.0.0.1 - - [27/Feb/2014:09:41:33] "POST /api/v1/clients HTTP/1.1" 200 1 "" "srs(simple rtmp server)0.9.2"When playing a stream on SRS, SRS will call the registered HTTP callback:
[2014-02-27 09:41:50][trace] post to clients, req={"action":"on_connect","client_id":5,"ip":"192.168.1.179","vhost":"__defaultVhost__","app":"live","pageUrl":"http://dev.chnvideo.com:3080/players/rtmp/"} [2014-02-27 09:41:50][trace] srs on_connect: client id=5, ip=192.168.1.179, vhost=__defaultVhost__, app=live, pageUrl=http://dev.chnvideo.com:3080/players/rtmp/ 127.0.0.1 - - [27/Feb/2014:09:41:50] "POST /api/v1/clients HTTP/1.1" 200 1 "" "srs(simple rtmp server)0.9.2"The HttpCallback can used to snapshot, please read snapshot
Winlin 2015.1