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