API, HTTP - Interface Specification Revision: 1.0 TABLE
OF CONTENTS
DOCUMENT HISTORY
1
OVERVIEW
This document specifies the external RTSP-based
application programming interface of IP cameras and video servers with
firmware version 1.1 Product and firmware versions
The support for the RTSP API is product and firmware dependent. Please refer to the Release Notes for the actual product for compliance information.
2
REFERENCES
RTSP protocol SDP protocol RTP protocol HTTP protocol 3. SAMPLE RTSP STREAM GET
FLOW
A. Decide device IP address and HTTP port number Remote
device IP address or host name. Ex:
“192.168. http port: 80
B. Decide video streaming format Check RTSP
Enabled by sending cgi: "/cgi-bin/view/param?action=list&group=General.Network.RTSP.Enabled" Return: General.Network.RTSP.Enabled=1 (1: RTSP enable,
0: RTSP disable)
C. Video Connections check Get the
server allowed maximum video connections by For
example, the return message is "Image.MaxViewer=5"
means the host maximum support video connections is 5. Get how
many video connections right now by For
example, the return message is "connection=5" means the host
already have 5 video connections. p.s. the
video connections don’t count "Multicast" in.
D. Get Video Frame Resolution Get the
RTSP resolution (the RTSP VIDEO compress type is MPEG4)
E. Get viewer port corresponding to video format Get the RTSP
port (R# could
be R0 or R1, R0 is Computer View, R1 is if the host
is behind the NAT, Send the
CGI to check the port forward activated or not Then get
the Computer View RTSP forward port by sending the CGI And get the
"/cgi-bin/view/param?action=list&group=General.Network.UPnP.NATTraversal.HTTPViewerPort4"
F. Start RTSP connection In Computer
View Get the unicast RTSP stream by sending the RTSP Describe COMMAND
with URL: Get the
multicast RTSP stream by sending the RTSP Describe COMMAND with URL: In Get the unicast RTSP stream by sending the RTSP Describe COMMAND
with URL: Get the
multicast RTSP stream by sending the RTSP Describe COMMAND with URL: 4. RTSP API
4.1
RTSP URL
|
rtsp://<servername>:<rtsp port>/video.mp4 |
rtsp://myserver:554/video.mp4
|
rtsp://<servername>:<rtsp port>/multicast.mp4 |
rtsp://myserver:554/multicast.mp4
|
rtsp://<servername>:<rtsp port>/video.3gp |
rtsp://myserver:5454/video.3gp
|
rtsp://<servername>:<rtsp port>/multicast.3gp |
rtsp://myserver:5454/multicast.3gp
|
Request syntax:
COMMAND URI
RTSP/1.0<CRLF> Headerfield1:
val1<CRLF> Headerfield2:
val2<CRLF> ... <CRLF> |
Response:
RTSP/1.0 ResultCode ResultString<CRLF> Headerfield3:
val3<CRLF> Headerfield4:
val4<CRLF> ... <CRLF> |
The following header fields are accepted by all commands. Other header fields are silently ignored (unless stated otherwise in the sections below).
Field |
Description |
Authorization |
Authorization information from the client. |
CSeq |
Request sequence number. |
Session |
Session identifier (returned by server in SETUP response). |
Content-Length |
Length of content. |
The following header fields can be generated for all responses
by the RTSP server:
Field |
Description |
CSeq |
Response sequence number (matches the sequence number of the
request). |
Session |
Session identifier. |
The DESCRIBE command returns the SDP (RFC 2327) description for the URI. The DESCRIBE command accepts the following additional header field:
Accept |
List of content types that client supports (application/sdp is the only supported type). |
The DESCRIBE command generates the following additional header fields:
Content-Type |
Type of content (application/sdp). |
Content-Length |
Length of SDP description. |
Content-Base |
If relative URLs are used in the SDP description, then this
is the base URL. |
Example:
DESCRIBE rtsp:// CSeq: 1 Accept: application/sdp Authorization: Basic YWRtaW46YWRtaW4= |
Response example:
RTSP/1.0 200 OK CSeq: 1 Content-base: rtsp:// Content-Type: application/sdp Content-Length: 309
v=0 o=RTSP 1101513929 s=RTSP Server c=IN IP4 t=0 0 a=range:npt=0- a=control:* m=video 0 RTP/AVP 96 b=AS:2048 a=rtpmap:96 MP4V-ES/90000 a=fmtp:96 config=000001b001000001b58913000001000000012000c48d a=control:streamid=0 m=audio 0 RTP/AVP 0 a=control:streamid=1 |
The OPTIONS command returns a list of supported RTSP commands.
Example:
OPTIONS * RTSP/1.0 CSeq: 2 |
Response example:
RTSP/1.0 200 OK CSeq: 2 Public: DESCRIBE, PAUSE, PLAY, SETUP, TEARDOWN |
The SETUP command configures the delivery method for the data. The SETUP command requires and generates the following additional header field:
Transport |
Specifies how the data stream is transported. Supported
variants: |
The response returns a session identifier that should be used with stream control commands to the server (PLAY, PAUSE, TEARDOWN). The RTSP server does not support reconfiguring of the transport parameters.
Example:
SETUP rtsp:// CSeq: 3 Transport: RTP/AVP;unicast;client_port=6970-6971 Authorization: Basic YWRtaW46YWRtaW4= |
Response example:
RTSP/1.0 200 OK CSeq: 3 Session: 6b Reconnect: true Transport: RTP/AVP;unicast;client_port=6970-6971;server_port=5008-5009 |
The PLAY command starts (or restarts if paused) the data delivery to the client. The PLAY command generates the following additional header fields:
Range |
Specifies the range of time being played. Since only live
streams are used, the specified time will always begin now and have no stop
time. |
RTP-Info |
Information about the RTP stream. More specifically, it
includes the next RTP sequence number that will be used. |
Example:
PLAY rtsp:// CSeq: 4 Range: npt=0.000000- Session: 6b Authorization: Basic YWRtaW46YWRtaW4= |
Response example:
RTSP/1.0 200 OK CSeq: 4 Date: Fri Nov 16 19:34:05 2007 GMT Session: 6b RTP-Info: url=rtsp:// Range: npt=now- |
The PAUSE command pauses the data delivery from the server.
Example:
PAUSE rtsp:// CSeq: 5 Session: 6b Authorization: Basic YWRtaW46YWRtaW4= |
Response example:
RTSP/1.0 200 OK CSeq: 5 Session: 6b |
The TEARDOWN command terminates the data delivery from the server.
Example:
TEARDOWN rtsp:// CSeq: 6 Session: 6b Authorization: Basic YWRtaW46YWRtaW4= |
Response example:
RTSP/1.0 200 OK CSeq: 6 Session: 6b |
It is possible to tunnel RTSP through HTTP to get through firewalls etc. This is achieved by setting up two sessions, one GET (for command replies and stream data) and one POST (for commands). RTSP commands sent on the POST connection are base64 encoded, but replies on the GET connection are plain text. To bind the two sessions together the server needs a unique ID (conveyed in the x-sessioncookie header). The GET and POST request are accepted both on the HTTP port (default 80).
The RTSP/HTTP URL is: http://<server name>/video.mp4 for computer view and http://<server name>/video.3gp for mobile view. Supported methods are GET and POST.
GET example:
GET /video.mp4 HTTP/1.0 x-sessioncookie: dgJEfRF6AAA1EhYAIoAAAA Accept: application/x-rtsp-tunnelled Pragma: no-cache Cache-Control: no-cache |
Response example:
HTTP/1.0 200 OK Content-Type: application/x-rtsp-tunnelled |
Note that the returned Content-Length is an arbitrary number and does not indicate the size of any data.
POST example:
POST /video.mp4 HTTP/1.0 x-sessioncookie: dgJEfRF6AAA1EhYAIoAAAA Content-Type: application/x-rtsp-tunnelled Pragma: no-cache Cache-Control: no-cache Content-Length: 32767 |
Note that the x-sessioncookie present in the POST content is the same as the x-sessioncookie in the corresponding GET request. Also note that the POST request must be sent on a separate connection to the server (i.e. it cannot be sent on the same connection as the GET request). No response is sent for the POST request.
Command example (base 64 encoded DESCRIBE on the POST connection):
REVTQ1JJQkUgcnRzcDovLzEwLjAuMC4yMy92aWRlby5tcDQgUlRTUC8xLjANCkNTZXE6IDENCkFj Y2VwdDogYXBwbGljYXRpb24vc2Rw |
Which corresponds to this command:
DESCRIBE rtsp:// CSeq: 1 Accept: application/sdp |
Command response (plain-text on the GET connection):
RTSP/1.0 200 OK CSeq: 1 Content-base: rtsp:// Content-Type: application/sdp Content-Length: 309
v=0 o=RTSP 1125898167 s=RTSP Server c=IN IP4 t=0 0 a=range:npt=0- a=control:* m=video 0 RTP/AVP 96 b=AS:2048 a=rtpmap:96 MP4V-ES/90000 a=fmtp:96 config=000001b001000001b58913000001000000012000c48d a=control:streamid=0 m=audio 0 RTP/AVP 0 a=control:streamid=1 |