API, HTTP - Interface
Specification
Revision: 3.0
Date: 2011-August-12
TABLE OF CONTENTS
DOCUMENT
HISTORY
Version
|
Date
|
Comment
|
3.0
|
2011-Aug-12
|
Initial
version
|
1
OVERVIEW
This document specifies the external
RTSP-based application programming interface of the IP camera and video
servers with M2 firmware version and above.
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.1.99¡¨
or ¡§example.dyndns.org¡¨
http port: 80
B. Video Connections check
Get the server allowed maximum video connections by
"/cgi-bin/view/param?action=list&group=Image.MaxViewers"
For example, the return message "root.Image.MaxViewers=10"
means the host maximum support video connections is 10.
C. Get Compress Type
We support H264, MPEG4 and MJPEG
Get the RTSP Compress Type
"/cgi-bin/view/param?action=list&group=StreamProfile.I0.Video.Codec¡¨
Example of response:
root.StreamProfile.I0.Video.Codec=H264
D. Get Video Frame Resolution
Get the RTSP resolution
In:
"/cgi-bin/view/param?action=list&group=Image.In.Resolution".
Example of response:
root.Image.I0.Resolution=1920x1080
E. Get viewer port corresponding to video format
Get the RTSP port
"/cgi-bin/view/param?action=list&group=General.Network.RTSP.Port"
if the host is behind the NAT,
Send the CGI to check the port forward activated or not
"/cgi-bin/view/param?action=list&group=General.Network.UPnP.NATTraversal.Enabled"
Then get the RTSP forward port by sending the CGI
"/cgi-bin/view/param?action=list&group=General.Network.UPnP.NATTraversal.RTSPPort"
F. Get Media File Name
Get profile media file name
ProfileN unicast media file name,
default is ¡§video.proN¡¨, get by sending the CGI
"/cgi-bin/view/param?action=list&group=General.Network.RTSP.R(N-1).UMEDIA"
ProfileN multicast media
file name, default is ¡§multi.proN¡¨, get by sending the CGI
"/cgi-bin/view/param?action=list&group=General.Network.RTP.R(N-1).MMEDIA "
Example of response:
get profile1 unicast name:
root.General.Network.RTSP.R0.UMEDIA=video.pro1
get profile1 multicast name:
root.General.Network.RTP.R0.MMEDIA=multi.pro1
G. Start RTSP connection
Get the unicast RTSP stream by sending the RTSP Describe COMMAND with
URL:
rtsp://host_IP:rtsp_Port/unicast_media_name "
Get the multicast RTSP stream by sending the RTSP Describe COMMAND
with URL:
rtsp://host_IP:rtsp_Port/multicast_media_name "
4. RTSP API
4.1 RTSP URL
4.1.1 Unicast
request
Syntax:
rtsp://<servername>:<rtsp
port>/<unicast name>
|
Example:
rtsp://myserver:554/video.pro1
|
4.1.2. Multicast
request
Syntax:
rtsp://<servername>:<rtsp
port>/<multicast name>
|
Example:
rtsp://myserver:554/multicast.pro1
|
4.2
RTSP Command
The
Supported RTSP commands are DESCRIBE, SETUP, OPTIONS, PLAY, PAUSE and
TEARDOWN methods. The RTSP protocol is described in RFC 2326.
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.
|
4.2.1 RTSP DESCRIBE
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://10.0.0.23/video.pro1 RTSP/1.0 CSeq: 1 Accept: application/sdp Authorization: Basic YWRtaW46YWRtaW4= |
Response example:
RTSP/1.0 200 OK CSeq: 1 Content-base: rtsp://10.0.0.23/video.pro1/ Content-Type: application/sdp Content-Length: 309 v=0 o=RTSP 1101513929 0 IN IP4 10.0.0.23 s=RTSP Server c=IN IP4 0.0.0.0 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=000001b001000001b58913000001000000012000c48d8800f516043c1463 a=control:streamid=0 m=audio 0 RTP/AVP 0 a=control:streamid=1 |
4.2.2 RTSP OPTIONS
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 |
4.2.3 RTSP SETUP
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:
RTP/AVP;unicast;client_port=port1-port2
RTP/AVP;multicast;client_port=port1-port2
RTP/AVP/TCP;unicast
|
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://10.0.0.23/video.pro1/streamid=0 RTSP/1.0 CSeq: 3 Transport: RTP/AVP;unicast;client_port=6970-6971 Authorization: Basic YWRtaW46YWRtaW4= |
Response example:
RTSP/1.0 200 OK CSeq: 3 Session: 6b68079a4e6afb66 Reconnect: true Transport: RTP/AVP;unicast;client_port=6970-6971;server_port=5008-5009 |
4.2.4 RTSP PLAY
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://10.0.0.23/video.pro1 RTSP/1.0 CSeq: 4 Range: npt=0.000000- Session: 6b68079a4e6afb66 Authorization: Basic YWRtaW46YWRtaW4= |
Response example:
RTSP/1.0 200 OK CSeq: 4 Date: Fri Nov 16 19:34:05 2007 GMT Session: 6b68079a4e6afb66 RTP-Info: url=rtsp://10.0.0.23/video.pro1/streamid=0;seq=0;rtptime=0 Range: npt=now- |
4.2.5 RTSP PAUSE
The PAUSE command pauses the data delivery from the server.
Example:
PAUSE rtsp://10.0.0.23/video.pro1 RTSP/1.0 CSeq: 5 Session: 6b68079a4e6afb66 Authorization: Basic YWRtaW46YWRtaW4= |
Response example:
RTSP/1.0 200 OK CSeq: 5 Session: 6b68079a4e6afb66 |
4.2.6 RTSP TEARDOWN
The TEARDOWN command
terminates the data delivery from the server.
Example:
TEARDOWN rtsp://10.0.0.23/video.pro1 RTSP/1.0 CSeq: 6 Session: 6b68079a4e6afb66 Authorization: Basic YWRtaW46YWRtaW4= |
Response example:
RTSP/1.0 200 OK CSeq: 6 Session: 6b68079a4e6afb66 |
4.2.7 RTSP over HTTP
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.pro1 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://10.0.0.23/video.pro1 RTSP/1.0 CSeq: 1 Accept: application/sdp |
Command response (plain-text
on the GET connection):
RTSP/1.0 200 OK CSeq: 1 Content-base: rtsp://10.0.0.23/video.pro1/ Content-Type: application/sdp Content-Length: 309 v=0 o=RTSP 1125898167 0 IN IP4 10.0.0.23 s=RTSP Server c=IN IP4 0.0.0.0 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=000001b001000001b58913000001000000012000c48d8800f516043c1463 a=control:streamid=0 m=audio 0 RTP/AVP 0 a=control:streamid=1 |
|