Video API legacy

in English | [[{{{de}}}|deutsch]] | [[{{{fr}}}|français]] | по-русски | автоперевод | 中文版 | 机械翻译

Anyone who has even the slightest skill at writing HTML pages can use the Axis Video API. And with additional software installed, it is possible to create a powerful video observation system with the capabilities of recording video archives, journalizing, viewing of archives, etc. Note Change API an how to enable the Video API.

Information about image dimensions

Some default parameters and some which are transferred when the image is obtained can change the image dimensions. For example parameters such as resolution, e_dcm_hor, e_dcm_vert, e_woi_width, e_woi_height, e_woi_left, e_woi_top. Sometimes a client application needs to know about the dimensions of the received image in advance (for example, for reserving a necessary area in a browser page or application window). You can obtain this information at the address:

http://192.168.0.9/var/axis-cgi/view/imagesize.cgi?

It is possible to transfer with this script any of the parameters which are supported by image.cgi and video.cgi. For example:

http://192.168.0.9/var/axis-cgi/view/imagesize.cgi?e_dcm_vert=2&e_dcm_hor=2&e_woi_width=1800

The server response is:

image width  = 896
image height = 768

Static images

To retrieve an image from the camera it is enough to type the following path in the browser's address field:

http://192.168.0.9/jpg/image.jpg 

Note 192.168.0.9 - this is the default camera IP-address. If you have changed the camera IP-address, please, type your variant.

It is also possible to ask the camera to send the image with a certain set of parameters. The path which can be used for this:

http://192.168.0.9/axis-cgi/jpg/image.cgi?param1=xxx&param2=yyy&.....

See the list of accessible parameters below.

resolution=<string> Specify the resolution of the returned image, for example 800x600. Product-dependent. You can check what values are supported by your camera using the address: http://192.168.0.9/axis-cgi/admin/param.cgi?action=list&group=Properties.Image.Resolution

compression=<int> Adjusts the compression level of the image. Higher values correspond to higher compression, i.e. lower quality and smaller image size. It can take a value from 0 to 100. In many cases 30 is optimal.

colorlevel=<int> Sets level of color or grey-scale. It can have value from 0 to 100. 0 = grey-scale, 100 = full color.

color=<int> Enables/disables color. It can have value 0 or 1. 0 = black and white, 1 = color.

rotation=<int> Rotates the image clockwise. Product-dependent. You can check what values are supported by your camera at the address: http://192.168.0.9/axis-cgi/admin/param.cgi?action=list&group=Properties.Image.Rotation

Apart from the standard parameters, enumerated above, there are some extensions, which make it possible to use the Elphel cameras more flexibly. You can read more detailed information about these extensions at Video API Extensions.

Example of obtaining an image with the assigned set of parameters:

http://192.168.0.9/axis-cgi/jpg/image.cgi?resolution=1024x768&colorlrvel=45&compression=30
 

If some parameters are not assigned, the default value is used. You can see the default values at the address:

http://192.168.0.9/axis-cgi/admin/param.cgi?action=list&group=Image.I0.Appearance
  

You can change the default values. For this it is necessary to specify the parameter action=update. For example:

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&Image.I0.Appearance.Resolution=512x384&Image.I0.Appearance.Rotation=180&ColorEnabled=no&Image.I0.Appearance.Compression=50

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&ImageSource.I0.Sensor.ColorLevel=60
  

Video stream

The cameras can be used to receive a continuous video stream. This stream can be transferred by two protocols - HTTP and RTP.

HTTP

Jpeg

The stream is a sequence of jpeg-files, separated by a special marking line. This transfer format is named Multipart Jpeg or MPJPG. For receiving a stream in this format you can use the following path:

http://192.168.0.9/mjpg/video.mjpg

As with static images, you can also assign parameters for the video stream. For this you can use the following path:

http://192.168.0.9/axis-cgi/mjpg/video.cgi?param1=xxx&param2=yyy&.....

Apart from the parameters, enumerated above, such as resolution, compression, colorlevel, color, rotation, you can also assign:

duration=<int> Specifies for how many seconds the video will be generated and pushed to the client. 0 = unlimited.

nbrofframes=<int> Specifies how many frames the server will generate and push. 0 = unlimited.

fps=<int> Using fps it is possible to specify the frame rate from the server. 0 = unlimited.

By default all these parameters are assigned to 0. You can change the default settings, for example, in this way:

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&Image.I0.Stream.Duration=100&Image.I0.Stream.FPS=5&Image.I0.Stream.NbrOfFrames=1000

Apart from the standard parameters, enumerated above, there are extensions, which allow you to use the Elphel cameras more flexibly. More detailed information about these extensions can be found at Video API Extensions.

On the page Video API And Client Applications you can find some information about players, which can play the MPJPG video stream.

RTP

Video Parameters

Note that due to obscure reasons, parameters set via

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&root.ImageSource.I0.Sensor...=...

will not take effect for RTP streams until the camera is restarted, although they will take effect immediately for videos are streamed directly via HTTP.

You can access the list of parameters used for RTP streaming, by accessing the following URL:

http://192.168.0.9/axis-cgi/admin/param.cgi?action=list&group=ImageSource.I0.E_CurrentState

Jpeg

Each jpeg-file is divided into many files with a size less than 1500 bytes which are transferred by RTP/UDP protocol through the network. In this case the data transmission is substantially accelerated, but the reliability of transfer falls, which can overload some networks and lead to the loss of a certain amount of video data.

On the page Video API And Client Applications you can find information about players, which can play the RTP/JPEG stream.

Multicast

To obtain a video stream using RTP/Multicast it is sufficient to set the special variable:

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&Network.RTP.R0.MulticastAlways=yes

The video stream will be generated with the default settings of variables for Multicast address, destination port and TTL. These variables can be changed by the following way:

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&Network.RTP.R0.VideoAddress=224.21.23.44&Network.RTP.R0.VideoPort=22222&Network.RTP.R0.TTL=90

SDP

This video stream can be received, recorded or played back by MPlayer, QuickTime, vic (from the mush package). For this it is necessary to obtain the SDP-file from camera:

http://192.168.0.9/mjpg/media.sdp

The saved file should be transferred to your preferred player. For example:

mplayer sdp://media.sdp

RTSP

The original Axis Video API specification does not support RTSP in Multicast mode. In the Elphel cameras this possibility has been added as a protocol extension.

Obtaining information about system functioning

You can obtain information about the system at the address:

http://192.168.0.9/axis-cgi/admin/systemlog.cgi

or more detailed information at the address:

http://192.168.0.9/axis-cgi/admin/serverreport.cgi

Date and Time

Retrieving the Date and Time

To see the time which is stored inside the camera you can use the address:

http://192.168.0.9/axis-cgi/admin/date.cgi?action=get

Setting Date and Time

For setting the date and time you must use the following parameters:

action	-	set
year	-	1970 - 2031	Current year.
month	-	1 - 12	Current month.
day	-	1 - 31	Current day.
hour	-	0 - 23	Current hour.
minute	-	0 - 59	Current minute.
second	-	0 - 59	Current second.

For example:

http://192.168.0.9/axis-cgi/admin/date.cgi?action=set&year=2006&month=4&day=15&hour=14&minute=20&second=40

User administration

The Video API allows:

• registration and deleting of users
• changing user passwords
• adding users to special groups

Deleting a user

http://192.168.0.9/axis-cgi/admin/pwdgrp.cgi?action=remove&user=joe

Creating a new user

http://192.168.0.9/axis-cgi/admin/pwdgrp.cgi?action=add&user=joe&pwd=PASSWD&grp=axuser&sgrp=axview&comment=JOE

Creating a new user is slightly different for Elphel and Axis cameras. All created users which will have the access to camera through Video API MUST belong to the axoper group. Also these users must belong to one or more secondary groups:

axview	-	access is permitted to scripts which are placed in directory /axis-cgi/view/
axoper	-	access is permitted to scripts which are placed in directory /axis-cgi/operator/
axadmin	-	access is permitted to scripts which are placed in directory /axis-cgi/admin/

At the same time it is necessary to pay special attention, because users who have Administrator rights must be entered into all three groups, users who have Operator rights must be entered into the axoper and axview groups, users who have Unprivileged user rights must be entered into the axview group only. Creating of three users with different rights, for example:

• Administrator:

http://192.168.0.9/axis-cgi/admin/pwdgrp.cgi?action=add&user=administrator&pwd=foo&grp=axuser&sgrp=axadmin:axoper:axview&comment=Administrator

• Operator:

http://192.168.0.9/axis-cgi/admin/pwdgrp.cgi?action=add&user=operator&pwd=foo&grp=axuser&sgrp=axoper:axview&comment=Operator

• Unprivileged user:

http://192.168.0.9/axis-cgi/admin/pwdgrp.cgi?action=add&user=administrator&pwd=foo&grp=axuser&sgrp=axview&comment=Viewer

Password changing

http://192.168.0.9/axis-cgi/admin/pwdgrp.cgi?action=update&user=joe&pwd=pass

Changing the access rights for secondary group

http://192.168.0.9/axis-cgi/admin/pwdgrp.cgi?action=update&user=joe&sgrp=axview:axoper

Rebooting the camera

For camera rebooting, you should use the following address:

http://192.168.0.9/var/axis-cgi/admin/restart.cgi

Exposure control

The Elphel cameras support exposure control with the standard and advanced interface. You can read about Advanced Settings on the page Video_API_Extensions

Autoexposure

To enable autoexposure you can use the following command:

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&ImageSource.I0.Sensor.Exposure=auto

Autoexposure parameters

It is possible to assign the area for autoexposure calculation. You can do this using the following command:

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&ImageSource.I0.Sensor.ExposureWindow=full

The ExposureWindow can have the values full, center, lower, upper, right and left.

Also it possible set a maximum exposure time (number of micro seconds) :

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&root.ImageSource.I0.Sensor.MaxExposureTime=150000

Manual control of exposure

To enable manual control of exposure you can use the following command:

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&ImageSource.I0.Sensor.Exposure=manual

Also you can set the time an image is exposed (0.1 msec step):

http://192.168.0.9/axis-cgi/admin/param.cgi?action=update&root.ImageSource.I0.Sensor.Shutter=50

For example Shutter=50 means 5000 microseconds or 5 miliseconds.

Troubleshooting

If your attempts to access images fail with 500 Server Error, you may have to explicitely enable the Video API.