AXIS Media Control

Version 4.0

Introduction

This documentation lists the functionality included in AXIS Media Control and explains how the component can be integrated and used in containing applications.

Please read the License Agreement carefully before proceeding.

Microsoft, Windows, Internet Explorer, DirectX, DirectShow, Visual C++, VisualBasic, .NET, Visual Studio are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

AXIS Media Control includes licensed software from Intel Corporation and when running MPEG-2 also from Moonlight Cordless Ltd.

Overview

AXIS Media Control (AMC) is an ActiveX component whose main purpose is to play media streams originating from Axis cameras and video servers.

AMC supports the following main features:

  • plays live media streams from a networked Axis device (live view)
  • recording MPEG-2 and MPEG-4 video and audio
  • plays media files originating from an Axis device and stored on disk (file view)
  • interactive PTZ control of devices
  • motion detection configuration
  • access to the image currently being displayed
  • live audio streaming from an Axis device with audio capability
  • transmitting audio to an Axis device with two-way audio capability
  • recording unsynchronized audio stream from and to an Axis device with audio capability

For a complete reference of the properties, methods and events provided by AMC, please see the AMC API Reference.

AXIS Media Control uses DirectShow technology for handling of MPEG-based media streams. For more information on DirectShow, please refer to the Microsoft DirectX SDK, which may help you better understand and use AMC in your own applications.


What's New

This version supports the following media formats generated by Axis products:

  • Motion JPEG (with non-synchronized audio for audio capable devices)
  • MPEG-2
  • MPEG-4 (with synchronized audio for audio capable devices)

What's New in AMC

Version 4.0

Includes version 4.0 of the AXIS Media Control ActiveX component and its subcomponents.

The following features have been added since 3.32:

  • Video and audio recording in MPEG-4
  • Support for AXIS MPEG-4 video decoder
  • New JPEG encoder for snapshots integrated in AxisMediaControl.dll
  • Advanced reconnection functionality
  • New methods:
    • SetReconnectionStrategy
  • Updated methods:
    • StartRecordMedia

Version 3.30

Includes version 3.32 of the AXIS Media Control ActiveX component and its subcomponents.

The following features have been added since 3.21:

  • Audio recording in Motion JPEG.
  • Audio file transmit to Axis device.
  • Video and audio streams are restarted once when the connection is broken if the EnableReconnect property is set to True. The stream is not restarted if "Limited stream length" is configured in the server.
  • Changed installation folder for files previously in Program Files\Axis Communications\AXIS Media Control to Program Files\Axis Communications\Components.
  • new methods:
    • StartRecordMedia
    • StopRecordMedia
    • StartTransmitMedia
    • StopTransmitMedia
    • AudioReceiveStart
    • AudioReceiveStop
    • AudioTransmitStart
    • AudioTransmitStop

Version 3.21

Includes version 3.32 of the AXIS Media Control ActiveX component and its subcomponents. Some components are partly prepared for coming enhancements in audio handling, but no support or documentation will be available until next official AMC SDK release.

Improvements in this release are

  • AMC:
    • - RTSP over HTTP using other than default port 80 works.
    • - GetCurrentImage does not crash on continuos calling.
    • - Improved Event handling.
    • - Both video and audio streams are restarted once when the connection is broken. The stream is not restarted if "Limited stream length" is configured in the server.
    • - Shutdown AMC with Stop method is improved.
    • - Setting AudioTransmitVolume problem is corrected.
    • - Problems with double-click on Play or Stop are corrected.
  • RTP Source Filter:
    • - Memory leak and resource leak fixes.
    • - RTSP over HTTP crash fixed (happened on rare occasions).
    • - UDP restart fix. Generate different seeds for all source filters loaded in one process.

Version 3.20

The following features and improvements have been added since 3.1:

  • MPEG4 support via RTP using Multicast.
  • MPEG4 support via RTP using Unicast.
  • MPEG4 support via RTSP.
  • MPEG4 support via RTSP over HTTP.
  • addition to property:
    • MediaType
    • MediaURL
  • new properties:
    • EnableContextMenu

Version 3.1

The following features and improvements have been added since 3.0:

  • Audio support via HTTP
  • addition to property:
    • ToolbarConfiguration
  • new properties:
    • AudioConfigURL
    • AudioReceiveURL
    • AudioTransmitURL

Version 3.0

The following features and improvements have been added since 2.0:

  • MPEG-4 support via multicast
  • new properties:
    • MPEG4VideoDecodingMode
    • DisplayMessages

Version 2.0

The following features and improvements have been added since 1.1:

  • Motion JPEG support
  • motion detection configuration functionality and GUI
  • configurable toolbar
  • new properties:
    • MotionConfigURL
    • MotionDataURL
    • ToolbarConfiguration

Version 1.1

The following features and improvements have been added since 0.1 Beta:

  • new user interface features: toolbar, status bar, control panel applet
  • support for multicast MPEG-2 streams
  • new media type: mpeg2-multicast
  • new modes for UIMode: ptz-absolute, ptz-relative
  • new value range for Volume : 0-100
  • new properties:
    • MPEG2VideoDecodingMode
    • PTZControlURL
    • ShowStatusBar
    • ShowToolbar
    • Status
    • StretchToFit
  • new methods:
    • GetCurrentImage
    • SaveCurrentImage
  • new events:
    • OnStatusChange

What's New in this SDK

Version 3.20

The following features and improvements have been added since 3.1:

  • documentation for new features in AMC 3.20
  • samples for MPEG-4 using RTP, RTSP and HTTP as transport protocols.

Version 3.1

The following features and improvements have been added since 3.0:

  • documentation for new features in AMC 3.13
  • audio support for Axis devices that have audio capability
  • samples for audio

Version 3.0

The following features and improvements have been added since 2.0:

  • documentation for new features in AMC 3.0
  • samples for MPEG-4

Version 2.0

The following features and improvements have been added since 1.0:

  • documentation for new features in AMC 2.0
  • samples for Motion JPEG.

Version 1.0

The following features and improvements have been added since 0.1 Beta:

  • improved documentation structure
  • new samples
  • redistribution files
  • MPEG-2 licensing details


Limitations and Considerations

Limitations

This SDK does NOT include an MPEG-2, MPEG-4 or AAC decoder. To enable displaying of MPEG-2 or MPEG-4 streams, the target computer must have MPEG-2 and/or MPEG-4 video decoders installed from an Axis device supporting MPEG-2 or MPEG-4 since these decoders are not redistributed with the AMC SDK.

A list over the current major limitations and known issues of AMC follows below:

  • the StartRecord method only works with unicast MPEG-2 streams

  • MPEG-2 files saved using the StartRecord method may get wrong duration

  • Properties CurrentPosition and Duration do not work with audio files
  • the StartRecordMedia method cannot record video in MJPEG
  • AXIS MPEG-4 video decoder, AxMP4Dec.dll, must be installed to enable playback of MPEG-4 recordings

Considerations

  • if you are familiar with the AXIS Camera Control ActiveX, refer to the AMC vs AXIS Camera Control section for information on the differences between the two components

  • AMC has a series of requirements on the target installation platform. The most up to date requirements are listed in the INSTALLATION section of the AMC readme file ({SDK}\Doc\readme.txt)

  • redistribution of AMC in your application is subject to a number of technical considerations, as listed in the redistribution section

  • redistribution of AMC in your applications with MPEG-2 or MPEG-4 functionality is subject to the licensing conditions listed in the MPEG-2 license section and the MPEG-4 license section.


AMC vs. AXIS Camera Control

AXIS Media Control vs. AXIS Camera Control

If you are not familiar with the AXIS Camera Control ActiveX component, this section may be skipped.

AXIS Camera Control (ACC) is an ActiveX component that has now been available for several years embedded in all Axis video products. AMC is a newer component that can complement or replace ACC in containing applications.

The major differences between AMC and ACC are:

  • Different API:s. The AMC API aims at consistency with the ACC API, although improvements have been made where appropriate.
  • ACC does not support other video streaming formats than Motion JPEG.
  • ACC is discountinued, i.e., it will not be improved or further developed.
  • ACC supports audio streams from the AXIS 2191 Audio Module. AMC supports audio capable devices with firmware version 4.11 and above.
  • AMC supports synchronized live video and audio streaming in MPEG-4.


Redistributing AMC

Redistributing AXIS Media Control

If your application requires AMC, the ActiveX control and any additional files providing the required functionality must be installed on the target computer.

Important note: parts of AMC (such as MPEG-2 and MPEG-4 video decoding) are subject to specific licensing conditions. See the Limitations and Considerations section for further details.

There are several choices available for distributing AMC with your application:

  • Installation from web page
  • Redistribution installation program
  • Custom redistribution


Installation from Axis products

Installation from web page

Axis camera and video products that support the embedded version of AMC include a .cab file in their firmware which is where the AMC installation resides. This installation executes when the user accesses a web page that uses AMC for displaying media (e.g., the live view page).

The ADP version of this .cab file is included in this SDK and can be used by web based applications to redistribute AMC.

To access the AMC services from a Web page, use the HTML <OBJECT> tag within the <BODY> element of the page, specifying the class identifier (CLSID) for the control. The class identifier of the AXIS Media Control component is 745395C8-D0E1-4227-8586-624CA9A10A8D.

The CODEBASE parameter is used to specify the location of the installation file and its version number. When the user accesses a Web page that has the <OBJECT> tag with the AMC CLSID, the browser will check if a component of the given version is installed. If the component is not installed, the browser will automatically attempt to download the control from the specified site. Then, the user will be asked whether or not to proceed with the installation.

The following example illustrates how to use the CODEBASE parameter to automatically download the version 3,32,20,0 of AMC.

<OBJECT ID="AMC" WIDTH=352 HEIGHT=240
        CLASSID="CLSID:745395C8-D0E1-4227-8586-624CA9A10A8D"
        CODEBASE="http://myserver/mypath/AMC.cab#VERSION=3,32,20,0">
   <PARAM NAME="AutoStart" VALUE=1>
   <PARAM NAME="MediaURL" VALUE="http://10.13.16.177/axis-cgi/mjpg/video.cgi?resolution=352x288">
</OBJECT>

Note: The version of AMC included in the .cab file does not have support for MPEG-2 or MPEG-4 streaming.

This installation will place the AMC files in the following directory:

{Program Files}\Axis Communications\Components

Advantages

  • easy to implement.
  • the installation is automatically run when the user is accessing a web page containing AMC
  • all AMC registry settings are automatically generated

Disadvantages

  • if the AMC Control Panel Applet should not appear, it must be deactivated manually. Upgrading AMC on the user's computer will activate it again


Redistribution installation program

This SDK includes redistributable installation packages for AMC, which will install and register files necessary for AMC to work properly. The redistributables can be found in the {SDK}\Redist directory.

The preferred choice is to call the installation package from your own installation program. The package can be run silently, so that it is transparent to your users. You can also select to require your users to run the installation manually.

This installation will place the AMC files in the following directory:

{Program Files}\AXIS Communications\Components

Advantages

  • easy implementation
  • better controls that the correct version of AMC is actually installed on the target computer
  • better controls that only the necessary functionality is actually installed on the target computer

Disadvantages

  • the MPEG-2 and MPEG-4 video decoders are not installed from the redistribution package. See the Limitations and Considerations section for further details.
  • not all AMC registry settings are automatically generated
  • AMC files not required by your application may still be installed on the target computer
  • launching an external installation program in your setup process may pose problems when unexpected erroneous conditions occur during installation

How to launch an installation package

To launch an AMC installation package from your own installation, simply call the .exe file and add '/s' to run it silently (no choices for the user). For example:

amc_redist.exe /s

You should call the AMC uninstallation process if your application installed it. Note however, that this may force your users to reinstall AMC when accessing Axis products by means other than your application. To uninstall AMC, use the following call in the directory where AMC was installed:

unwise.exe /s /a install.log

'/a install.log' is mandatory. '/s' specifies silent uninstallation.


Custom redistribution

AMC may be redistributed by including the redistributable files required by your application in the application's installation program.

This redistribution method requires special care however, since you must avoid conflicts with other current or future installations of AMC. For each redistributable file with an associated CLSID, your application setup process MUST check that there is no newer version already present in the target computer. See the Safe redistribution section below for instructions on how to do this using AMC.

Your installation may place the AMC files in any directory of your choice. Bear in mind however, that if the user accesses an Axis product with a newer version of AMC, the files that will be used may actually reside in another directory, e.g. the default {Program Files}\AXIS Media Control

Advantages

  • better controls that the correct version of AMC is actually installed on the target computer
  • redistribute only the files required by your application
  • full control over which registry settings are generated

Disadvantages

  • requires more intricate and careful implementation
  • the MPEG-2 and MPEG-4 video decoders can not be distributed this way. See the Limitations and Considerations section for further details.

Safe redistribution

A custom redistribution of AMC must take into account any previous AMC installations already present in the target computer.

This is a critical issue for all redistributable files that have an associated CLSID. These include ActiveX components and DirectShow filters. For a list of the CLSIDs associated with each AMC redistributable file, see the {SDK}\Bin directory file list.

In a custom installation, this CLSID must be used to verify in the Windows registry that a previously installed file associated with that CLSID is not of a higher version that the one you are installing.

The easiest way to perform the check is to use an auxiliary function exported by the AMC ActiveX dll ({SDK}\Bin\AxisMediaControl.dll). Most installation tools on the market allow you to call functions in a dll and use their return values during the setup process. The specific function is called CheckMustRegisterDLL and has the following signature:

BOOL WINAPI CheckMustRegisterDLL(LPCTSTR theCLSID, LPCTSTR theNewDLL)

theCLSID contains the CLSID of the file to check, the string format is as specified in the file list, with open and close curly braces.

theNewDLL specifies the name of the file you are distributing to check. The function retrieves the version of the file and compares it with the one in the registry for the specified CLSID.

The function returns TRUE if the file needs to be registered, or if an error occurs. FALSE is returned if a newer file is already registered. Beware the default TRUE value. Under unexpected circumstances (an incorrect parameter, unreadable registry, ...) you would still be told that the file you are distributing must be registered. This may cause problems with previous installations, so be extremely careful and ensure the right parameters are given to the function.

The function does not perform the actual registration. You must use your installation tool's own self-registration activation, or manually call regsvr32.


AMC Usage

AXIS Media Control Usage

Integration in development tools

AMC is an ActiveX component, and as such, can easily be integrated in your development tool.

Follow your specific tool's instructions on how to integrate ActiveX controls. This should make all properties, methods and events provided by AMC accessible to your own application.

Take a look at the Sample Code and Descriptions section to get a better understanding of how to integrate AMC and how to take advantage of its features.

Using AMC with Axis devices

AMC interacts with Axis cameras and video servers by means of the HTTP API. See the Axis Video API, HTTP section for a complete reference of this API.

Use the HTTP API when, for example, setting the MediaURL property for a live view media stream. The API provides the proper syntax for the URL for the device your application will connect to.


DirectShow & AMC

DirectShow

DirectShow is a subset of the DirectX architecture providing functionality for the capture and playback of multimedia streams. For more information on DirectX and DirectShow, please refer to the Microsoft DirectX development pages

AMC makes use of DirectShow technology for handling media streams with MPEG format (Motion JPEG streams are not handled using DirectShow). The use of DirectShow by AMC should be transparent to developers working with the AMC API - all the details of the interaction with DirectShow are dealt with by setting the appropriate values in properties such as MediaType.

It is important however, to understand the concept of DirectShow filters and their registration in Windows when providing a custom redistribution of AMC and when your application accesses MPEG streams generated by Axis products.

The DirectShow filters and DMO's provided by AMC perform specific tasks and are self-contained in files with the .ax or .dll extension. AMC makes use of them according to which media stream format it will be processing. These filters need to be installed and registered with their CLSID for them to be found by AMC and work properly, in much the same way as ActiveX components. Refer to the Redistribution section for more information on how the registration needs to be performed when implementing a custom AMC installation. The {SDK}\Bin directory file list lists all the AMC filters available, along with their CLSIDs.

If you are familiar with DirectShow and apply it in your applications, you may use the filters in AMC if they suit your needs. Note however, that Axis does not fully support this usage. If you are specially interested in the source filters, please refer to the Custom Protocol Schemes section for an explanation on how to add them to a filter graph.


Audio support

Audio

The requests specified in this section are supported by Axis devices that have audio capability.

The AXIS Media Control has live audio support for the Axis devices that have audio capability. The AXIS Media Control can be used in your application to play audio received from the Axis device. Audio can also be sent back to the device if it supports two-way audio. Audio is either received unsynchronized, using Motion JPEG over HTTP, or synchronized, using MPEG-4. Audio is always transmitted unsynchronized over HTTP. The next paragraphs describes how to use AMC for unsynchronized audio.

To listen to the sound from the audio device, the only requirement is that you must know the URL of the audio parameters and the URL of the audio stream. This information can be found in the Axis Video API, HTTP interface specification. To start receiving the audio from the Axis video product, set the AudioReceiveURL property to the URL of the audio stream, e.g. 'http://10.13.16.177/axis-cgi/audio/receive.cgi', and the AudioConfigURL property to the URL of the audio parameters, e.g. 'http://10.13.16.177/axis-cgi/audio/getparam.cgi'.

If a loudspeaker is connected to the Axis device, audio can be sent back to the loudspeakers. This enables two-way audio communication between a person at a PC on which the application is running, and a person standing by the Axis audio device. To use the microphone, set the property AudioTransmitURL to the URL for audio transmission, e.g. 'http://10.13.16.177/axis-cgi/audio/transmit.cgi'. Recorded audio can also be sent to the device, use the MediaFile method and the AudioTransmitURL property.

There is a difference in how AMC handles receiving and transmitting audio. When the receive URL is set the audio will always be streamed to the PC regardless if we mute or not. This is to enable the possibility to record audio while muting the speakers. However, audio is transmitted only when the microphone is not muted and the talk button is pushed or when transmitting a file. This is to prevent that audio is transmitted when the client is not active since the Axis device can only receive audio from one client at a time.

As a consequence, when streaming MPEG-4 do NOT set the AudioReceiveURL since this will give you two audio streams, one synchronized audio stream via DirectShow and one unsynchronized audio stream via HTTP.

Currently, only unsynchronized audio recording is supported. That is, there is no support for recording in MPEG-4. To record audio use the StartRecordMedia and StopRecordMedia methods.

See below for the methods, events and properties available for the audio functionality:

methods
properties

The audio stream is sent as a stream of digital audio (Adaptive Differential Pulse Code Modulation, ADPCM G.711, G.726-32, or G.726-24). What codec is used is configured in the Axis device, see the HTTP-API. If you save the stream to a file you will get a 16 bytes linear PCM audio file with Intel byte order (Little-Endian) and a sampling frequency of 8 kHz. In MPEG-4 there is also support for audio from AAC capable devices.


Custom Protocol Schemes

Note: This section is of interest if:

  • you will use MPEG-4.
  • you still wish to use Windows Media Player as the ActiveX for your application accessing Axis products.
  • you wish to access Axis MPEG streams from a DirectShow enabled application.
  • you wish to experiment with the AMC DirectShow filters in the DirectX SDK tool GraphEdit.
  • you wish to use the "transparent" value of the MediaType property.

MPEG media streams generated by Axis products are supported by AMC thanks to a series of DirectShow filters (see the DirectShow & AMC section for more details). Any DirectShow-enabled application can access these media streams using the source filters included with AMC, without needing the ActiveX itself.

The easiest way to make DirectShow aware that a media stream is to be processed by one of the source filters provided by AMC is to use the associated custom protocol scheme.

AMC supports the following custom protocol schemes:

Scheme | Description
axrtpm | MPEG-4 multicast RTP streams (MediaType must be auto-sense)
axrtpu | MPEG-4 unicast RTP streams (MediaType must be auto-sense)
axrtsp | MPEG-4 unicast RTSP streams (MediaType must be auto-sense)
axrtsphttp | MPEG-4 unicast RTSP streams over HTTP (MediaType must be auto-sense)
axmpeghttp | MPEG-2 unicast streams
axsdp | MPEG-2 and MPEG-4 multicast streams. See note 1.

For example, to access a MPEG-4 stream via the RTSP protocol, the URL with the custom protocol scheme could look like this

axrtsp://<server-address>/mpeg4/media.amp (use MediaType auto-sense)

For example, to access a unicast MPEG-2 stream, the URL with the custom protocol scheme could look like this

axmpeghttp://10.13.9.123/axis-cgi/mpeg2/video.cgi

You can test these URLs in Windows Media Player (WMP), selecting "Open URL", and changing the IP address to that of your Axis MPEG product. Since WMP is a DirectShow-aware application, it will recognize the custom protocol scheme and load the Axis RTP source filter or the Axis unicast MPEG-2 source filter.

You can also use the custom protocol scheme in AMC by setting the MediaType property to transparent and prefixing the MediaURL property with the custom protocol scheme. Note however, that this is not the preferred way - your application will perform better if you use auto-sense or the specific value for your protocol for the MediaType property, see MediaType.

Note 1: Use axrtpm for multicast MPEG-4. To use axsdp the server must be configured to always stream the MPEG-4 multicast stream. This option should only be used when accessing Axis products with firmware version earlier that 4.20.

Note 2: in Windows Media Player version 9 and higher, custom protocol schemes must appear in the registry. If you are implementing a custom redistribution of AMC and wish to use WMP, you must create entries for the required schemes. See this MSDN article for more details:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wmplay10/mmp_sdk/customschemeregistrysettings.asp

Note 3: To stream only video add "/trackID=1" to the URL, to stream only audio add "/trackID=2". To get only audio from an audio capable Axis device use an URL like this (here we get audio streamed over RTP unicast):

axrtpu://<server-address>/mpeg4/media.amp/trackID=2 (use MediaType auto-sense)


Control Panel Applet

The AMC dll file includes a control panel applet where certain information can be viewed and a number of user settings can be modified. To activate the applet in the Windows control panel, a registry key must be modified.

The AMC installation procedure launched when accessing Axis products' web pages activates the applet. The redistributable installation packages included in this SDK do NOT activate the applet. If you want to activate the applet, add a value in the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Control Panel\Cpls
Value type: string
Value name: AXIS Media Control
Value: complete path and file name of the AMC dll

Note: this registry key is only applicable to Windows 2000/XP or higher.

If you do not want to activate the applet but want to control all or some of the settings displayed in it, refer to the Registry settings section for a list of all the settings available.


Registry settings

AMC includes the following relevant registry settings:

Control Panel activation

See the Control Panel Applet section for a discussion on the AMC control panel applet and the values to set to activate it.

Custom Protocol Schemes

See the Custom Protocol Schemes section for a discussion on the custom protocol scheme settings if you wish to integrate AMC functionality in Windows Media Player.

User settings

These are the user specific settings that can be modified from the control panel applet. These settings are values under the following key:

HKEY_CURRENT_USER\Software\Axis Communications\AXIS Media Control

Note that some of the settings correspond to properties in AMC. If an instance of AMC uses the corresponding property, the value specified will override the current user's setting. Otherwise, if the user has specified a value (either through the AMC control panel or through your application), then that value will be used. If no value has been specified, the AMC property's default value is used.

Value name | Value type | Description
mpeg4_dec_mode | DWORD | MPEG-4 video decoding mode. Set the value as for the MPEG4VideoDecodingMode property.
mpeg4_advanced_renderer | DWORD | Selection of Video Renderer (that will be used in DirectShow). Set the value as for the MPEG4VideoRenderer property.
net_multicast_if | string | Selects the network interface (IP number) to receive the multicast stream on.
mpeg2_dec_mode | DWORD | MPEG-2 video decoding mode. Set the value as for the MPEG2VideoDecodingMode property.
net_timeout | DWORD | Network timeout. Set the value as for the NetworkTimeout property.
snapshot_dir | string | The directory where snapshot files generated by the snapshot toolbar button will be placed.
snapshot_feedback DWORD The type of feedback given when the snapshot toolbar button is clicked. This is a bitwise combination of the following values:
  • 1 (default) if OK, open the snapshot dir
  • 2 if OK, show a message box
  • 512 if error, show a message box
audio_buffer_level DWORD The level (maximum size) of the audio buffer. There are four levels, each one corresponding to a maximum number of audio samples to store in the buffer. The levels and their corresponding values are:
  • 0 - (default) 100 (Min)
  • 1 - 200 (Low)
  • 2 - 500 (High)
  • 3 - 1000 (Max)
audio_mute_mic DWORD Boolean value telling whether the microphone is muted on start-up or not.
  • 0 unmuted
  • 1 (default) muted
audio_mute_speaker DWORD Boolean value telling whether the speakers are muted on start-up or not.
  • 0 unmuted
  • 1 (default) muted
audio_ptt DWORD Button mode for the talk/listen or talk/silence button in the toolbar. Possible values are:
  • 0 (default) push button ("walkie-talkie mode")
  • 1 toggle button


SDK Files

A list of all the files included in this SDK follows below. {SDK} indicates the directory chosen during the SDK installation.

Important note: All executable files are put and registered in {program files}\Axis Communications\Components. There is a copy of all these files in {SDK}\bin aimed for redistribution. The files common to other Axis SDK's (such as the AXIS Media Parser) in {program files}\Axis Communications\Components may be more resent if they are installed with another Axis component.

{SDK}

File | Description
readme.txt | readme file for this SDK

{SDK}\Bin

File | Description | CLSID
AxisMediaControl.dll | the AMC ActiveX component | {745395C8-D0E1-4227-8586-624CA9A10A8D}
AxisOverlay.ax | DirectShow transform filter that overlays the date and time when viewing Axis-generated MPEG-2 files in external media players | {8A25AD8A-B8BE-4C18-9795-6FCE65B29099}
AxisRTPSrcFilter.ax | DirectShow source filter that enables access to multicast MPEG-2 streams | {4F1D0C59-5ECC-4028-87F3-482191D2230F}
AxisTimeShifter.ax | DirectShow transform filter that performs a necessary time shift in the MPEG-2 sound timestamps | {D8E99687-BB5D-4747-8F5C-7C4655FCEC9A}
AxPicEventsFilter.ax | DirectShow transform filter that notifies each time a new picture is received | {833CAF80-A132-4FEF-8188-2A6004E3F239}
HTTPStreamSourceFilter.ax | DirectShow source filter that enables access to unicast MPEG-2 streams | {BC35E1AD-B98B-408E-8BC8-BF17CC09A981}
MPEGAudioTransformFilter.ax | DirectShow transform filter that converts MPEG-1 audio streams to MPEG-2 audio when viewing Axis-generated MPEG-2 files | {AF7D8180-A8F9-11CF-9A46-00AA00B7DAD1}
Audio.dll COM component handling audio
DMO interface for G7x audio (in MPEG4) 		{53D71A20-15BA-4884-A778-07A75F6049F4}
{D1F283E1-DF6F-41e4-AED1-EB1D6B4B0AE1}

{SDK}\Doc

File | Description
AmcDoc.chm | this help file
license.txt | the license applicable to functionality in AMC in text format
readme.txt | the AMC readme file

{SDK}\Redist

File | Description
amc_redist.EXE | installation package containing all AMC redistributable files (no decoders)
AMC.cab | installation package containing AMC that can be used by web based applications to redistribute AMC

{SDK}\Samples

Contains samples demonstrating how to use AMC in different tools and environments. For more information, see the Sample Code and Descriptions section.


AXIS Media Control License Agreement

License Agreement

For MPEG licenses please see MPEG-2 and MPEG-4 licenses.

YOU SHOULD CAREFULLY READ THE FOLLOWING TERMS. YOUR INSTALLATION OF THE SOFTWARE
COMPONENT INDICATES YOUR ACCEPTANCE OF THESE LICENSE TERMS.

PLEASE READ THIS AGREEMENT CAREFULLY BEFORE INSTALLING THE SOFTWARE COMPONENT.
AXIS COMMUNICATIONS AB WILL ONLY LICENSE THE SOFTWARE COMPONENT TO YOU IF YOU
FIRST ACCEPT THE TERMS OF THIS AGREEMENT BY INSTALLING THE SOFTWARE COMPONENT.
IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, DO NOT INSTALL; EITHER RETURN
OR DESTROY YOUR COPY.

These license terms apply to Your installation and use of the component. This
license is granted to You by Axis Communications AB ("We" or "Us").

1. Disclaimer of Warranty and Limitation of Liability.

THE COMPONENT AND ANY  OTHER PRODUCT WHICH WE PROVIDE TO YOU AS PART OF OUR
SERVICE ARE PROVIDED "AS IS." EXCEPT AS SPECIFICALLY SET FORTH HEREIN, NEITHER
WENOR OUR LICENSORS MAKE ANY   WARRANTIES, REPRESENTATIONS OR CONDITIONS OF
MERCHANTABILITY, QUALITY, AND FITNESS FOR A PARTICULAR PURPOSE RELATING TO OUR
PROGRAM,  SERVICES, AND/OR  RELATED PRODUCTS THAT WE OR OUR LICENSORS PROVIDE
OR THE SERVICE OF ANY OTHER SERVICE PROVIDER. DO NOT USE THE PROGRAM OR RELATED
PRODUCTS IN ANY HIGH RISK ACTIVITIES WHERE DAMAGE OR INJURY TO PERSONS, PROPERTY,
ENVIRONMENT OR BUSINESS MAY RESULT IF AN ERROR OCCURS. YOU EXPRESSLY ASSUME ALL
RISK FOR SUCH USE. WE DISCLAIM ANY WARRANTY OF TITLE OR OTHER WARRANTIES FOR
ANY THIRD PARTY'S OFFERING(S) OR PRODUCT(S). ALL SUCH WARRANTIES AND
REPRESENTATIONS ARE HEREBY EXCLUDED. WITHOUT LIMITATION, NO WARRANTY IS GIVEN
THAT THE  COMPONENT OR PRODUCTS ARE ERROR-FREE.

WE, INCLUDING OUR LICENSORS, DISCLAIM ANY LIABILITY OR RESPONSIBILITY ARISING
FROM ANY CLAIM THAT YOUR USE OF THE COMPONENT, AND/OR RELATED PRODUCTS WE
PROVIDE POSSIBLY INFRINGES ANY THIRD PARTY'S INTELLECTUAL PROPERTY RIGHTS.

IN NO EVENT ARE WE OR OUR LICENSORS LIABLE FOR: A) DIRECT, SPECIAL, INDIRECT,
CONSEQUENTIAL OR INCIDENTAL DAMAGES EVEN IF WE HAVE BEEN ADVISED OF THE
POSSIBILITY THEREOF INCLUDING, BUT NOT LIMITED TO, LOST PROFITS, LOST BUSINESS
REVENUE, OR FAILURE TO REALIZE EXPECTED SAVINGS; OR, B) ANY CLAIMS AGAINST YOU
BY ANY OTHER PARTY.

This Section applies to all claims by You irrespective of the cause of action
underlying Your claim, including, but not limited to: a) breach of contract,
even if in the nature of a breach of condition or a fundamental term or a
fundamental breach, or b) tort including but not limited to negligence or
misrepresentation.

In no event are We or Our Licensors liable for any damages arising from Your
failure to perform Your responsibility in connection with this Component
License Agreement, or arising from any cause beyond Our control. All limitations
and disclaimers stated in this Section also apply to Our Axis Product Licensors
as intended beneficiaries of this Component License Agreement. Any rights or
limits stated herein are the maximum for which we are collectively responsible.

2. Your Additional Rights.

You may have additional rights under certain laws (such as consumer laws) which
do not allow the exclusion of implied warranties, or the exclusion or limitation
of certain damages. If these laws apply, Our exclusions or limitations may not
apply to You.

3. General.

We do not provide any support, maintenance, assistance, or the like with respect
to the Component. You are responsible for payment of any taxes, including Your
personal property taxes, resulting from this Component License Agreement or Your
use of the Component. You agree to comply with all export laws and regulations.
Neither party may bring an action under this Component License Agreement more
than two years after the cause of actions arose. You may terminate Your license
at any time. We may terminate Your license if You fail to comply with the terms
of this Component License Agreement. In either license termination event, You
must destroy all Your copies of the Component.

4. Applicable Law.

This Component License Agreement shall be governed by, and construed in accordance
with Swedish law as such law shall from time to time be in effect, and such law
shall also govern in the settlement, by court proceeding or otherwise of any and
all disputes arising between Axis Communications AB and any Licencee.


AMC API Reference

Properties |
 | AMC properties
Methods |
 | AMC methods
Events |
 | AMC events


AMC API Reference: Properties

Properties

Media

AutoStart
Indicates if the media stream/file defined in MediaURL/MediaFile should be played automatically.
CurrentPosition
Current position in the media stream/file.
DisplayMessages
Controls the display mode of popup messages.
Duration
The total playing time of the current media file.
FramesDrawn
The number of frames drawn since the media stream/file started playing.
MediaFile
Complete path and file name of the media file to display.
MediaPassword
Password for media stream access.
MediaType
Type of the media stream/file.
MediaURL
URL where a media stream can be accessed.
MediaUsername
User name for media stream access.
MPEG2VideoDecodingMode
Mode to use for decoding MPEG2 video streams/files.
MPEG4VideoDecodingMode
Mode to use for decoding MPEG4 video streams/files.
MPEG4VideoRenderer
Selection of Video Renderer that will be used when viewing MPEG-4 in AMC.
Mute
Turns the volume on or off.
Volume
The volume to use when playing media.

Display

FullScreen
Controls the display mode of the media.
ShowStatusBar
Shows or hides the status bar.
ShowToolbar
Shows or hides the toolbar.
StretchToFit
Stretches the image to fit the output frame size, preserving aspect ratio.
ToolbarConfiguration
Specifying what functionality to be included in the toolbar.
UIMode
The user interface mode to use.

Network

NetworkTimeout
The number of milliseconds to wait for network traffic before timing out.

PTZ

PTZControlURL
URL where control of the Pan, Tilt and Zoom behavior of a PTZ unit can be accessed.

Motion Detection

MotionConfigURL
URL where motion detection windows can be configured.
MotionDataURL
URL where motion detection data can be retrieved.

Status

Status
The current status of the control.

Audio

The URLs for audio should be used for unsynchronized audio, i.e., for audio received over HTTP in Motion JPEG and for audio transmitted over HTTP. This means that when streaming MPEG-4 no URL needs to be set to receive audio. If microphone or file transmission is desired in MPEG-4 the AudioConfigURL and the AudioTransmitURL should be set. The receive and transmit URLs have no meaning unless the configuration URL is set as well.That is, at least two of the URLs must always be set to enable unsynchronized audio functionality.

AudioConfigURL
URL where audio configuration can be retrieved.
AudioReceiveURL
URL where audio stream can be retrieved.
AudioTransmitURL
URL where audio stream can be transmitted.
AudioTransmitMute
Turns the transmit volume on or off.
AudioTransmitVolume
The volume to use when transmitting audio.


AMC API Reference: AudioConfigURL

AudioConfigURL Property

URL for audio parameters. This URL is used to retrieve audio configuration from an Axis device with audio capability.

Syntax

AudioConfigURL [= string ]

Value | Description
string | String specifying the URL where Audio configuration is available.

Remarks

This URL must be assigned if Audio should be supported. The audio configuration parameters are necessary for the media control to work correctly when audio is available.

For more information, see the Audio section in the Axis Video HTTP API.

Note that the Axis Video HTTP API audio parameters were changed in firmware 4.20.

Example

Visual Basic 6.0:

AMC.AudioConfigURL= "http://172.21.1.213/axis-cgi/audio/getparam.cgi"

Visual Basic users: The value assigned to this property at design time has no effect. Use this property only at run time.

See Also

Audio AudioReceiveURL AudioTransmitURL AudioReceiveStart AudioTransmitStart Axis Video API, HTTP


AMC API Reference: AudioReceiveURL

AudioReceiveURL Property

The complete URL to an audio stream from an Axis video product.

Syntax

AudioReceiveURL [= string ]

Value | Description
string | String specifying the URL to an audio stream that the client will download from an Axis device.

Remarks

The AudioConfigURL must also be assigned to enable audio support in AMC.

Example

Visual Basic 6.0:

AMC.AudioReceiveURL= "http://172.21.1.213/axis-cgi/audio/receive.cgi"

Visual Basic users: The value assigned to this property at design time has no effect. Use this property only at run time.

See Also

AudioConfigURL AudioTransmitURL AudioReceiveStart AudioReceiveStop Axis Video API, HTTP


AMC API Reference: AudioTransmitURL

AudioTransmitURL Property

URL for transmitting audio to the server. This URL is used for Axis devices capable of two-way audio.

Syntax

AudioTransmitURL [= string ]

Value | Description
string | String specifying the URL for transmitting audio to the server, i.e. a string for the server receiving and playing an audio stream sent by AXIS Media Control.

Remarks

The AudioConfigURL must also be assigned to enable audio support in AMC.

Example

Visual Basic 6.0:

AMC.AudioTransmitURL= "http://172.21.1.213/axis-cgi/audio/transmit.cgi"

Visual Basic users: The value assigned to this property at design time has no effect. Use this property only at run time.

See Also

AudioConfigURL AudioReceiveURL AudioTransmitStart AudioTransmitStop Axis Video API, HTTP


AMC API Reference: AudioTransmitMute

AudioTransmitMute Property

Turns the volume on or off.

Syntax

Mute [= boolean ]

Value | Description
boolean | True if the transmit volume is muted, False (Default) if the transmit volume is not muted.

Remarks

When setting this property to False, the transmit volume level will be set to the value of the AudioTransmitVolume property.

See Also

AudioTransmitVolume


AMC API Reference: AudioTransmitVolume

AudioTransmitVolume Property

The volume to use for audio transmitted to server (e.g., PC microphone.)

Syntax

Volume [= number ]

Value | Description
long | Transmit volume level. Valid range is 0-100.

Remarks

The default transmit volume level is 30. Zero specifies silence and 100 specifies full volume.

See Also

AudioTransmitMute


AMC API Reference: AutoStart

AutoStart Property

Indicates if the media stream/file defined in MediaURL/MediaFile should be played automatically.

Syntax

AutoStart [= boolean ]

Value | Description
boolean | True if the stream/file is automatically played, otherwise False (Default).

Remarks

When this property is set to True, AMC will immediately begin to play when either the MediaURL or MediaFile property is changed.

See Also

Play MediaURL MediaFile


AMC API Reference: CurrentPosition

CurrentPosition Property

Current position in the media stream/file.

Syntax

CurrentPosition [= long ]

Value | Description
long | The current position in the media stream/file, expressed in milliseconds.

Remarks

When playing media files, setting this property makes AMC jump to the specified position in the file. Zero indicates the beginning of the stream/file. The maximum value allowed is the same as the Duration property.

When playing live streams, this property indicates for how long the stream has been played. This is a read only property.

Does not work with audio files.

See Also

Duration Play


AMC API Reference: FullScreen

DisplayMessages Property

Controls the display mode of popup messages.

Syntax

DisplayMessages [= boolean ]

Value | Description
boolean | True (Default) to show popup messages. False to hide all popup messages.

Remarks

Messages shown as popups are also available in the OnError event.

Visual Basic users: The value assigned to this property at design time has no effect. Use this property only at run time.


AMC API Reference: Duration

Duration Property

The total playing time of the current media file. Read-only property.

Syntax

Duration

Value | Description
long | The total playing time of the current media file, expressed in milliseconds.

Remarks

This property is only valid for media files. It has no meaning for live view streams.

Does not work with audio files.

See Also

CurrentPosition Play


AMC API Reference: Enable Context Menu

EnableContextMenu Property

Indicates if the context menu should be available.

Syntax

EnableContextMenu [= boolean ]

Value | Description
boolean | True if the context menu should be available, otherwise False (Default).

Remarks

When this property is set to True, AMC will display the context menu when the user clicks the right mouse button.

The context menu has the follwing functions; Play, Stop, Fullscreen, Snapshot, and Settings. Choosing Settings opens the Control Panel Applet.

See Also

Play Stop Fullscreen Snapshot Control Panel Applet


AMC API Reference: AutoStart

EnableReconnect Property

Indicates if Axis Media Control should reconnect if the stream is lost during playback or is unreachable when connecting.

Syntax

EnableReconnect [= boolean ]

Value | Description
boolean | True if the stream should be reconnected, otherwise False (Default).

Remarks

When this property is set to True and the stream has been lost, AMC will begin a reconnection strategy in order to regain connectivity with the AXIS device. The reconnection strategy can be configured using SetReconnectionStrategy.

See Also

SetReconnectionStrategy Play MediaURL


AMC API Reference: FramesDrawn

FramesDrawn Property

The number of frames drawn since the stream/file started playing. Read-only property.

Syntax

FramesDrawn

Value | Description
long | The number of frames drawn since the stream/file started playing.

Remarks

The value of this property is set to 0 when Pause or Stop is called.

See Also

Play


AMC API Reference: FullScreen

FullScreen Property

Controls the display mode of the media.

Syntax

FullScreen [= boolean ]

Value | Description
boolean | True to show the media in full screen mode. False (Default) to show the media in standard mode.

Remarks

The full screen mode can be ended by pressing the ESC key.

Visual Basic users: The value assigned to this property at design time has no effect. Use this property only at run time.


AMC API Reference: MediaFile

MediaFile Property

Complete path and file name of the media file to play.

Syntax

MediaFile [= string ]

Value | Description
string | String specifying the complete path and file name of the media file to play.

Remarks

No validation of the path and file name occurs until the Play method is called.

If the AutoStart property is set to True, the file will automatically be played when this property is set. Note however, that if a media stream is being recorded, the media stream being displayed will continue.

If both MediaFile and MediaURL are set to something other than an empty string in the same session, the Play method will use the property that was set last.

Any type of file can be played as long as the appropriate filters are installed.

See Also

Play MediaURL AutoStart


AMC API Reference: MediaPassword

MediaPassword Property

Password for media stream access.

Syntax

MediaPassword [= string ]

Value | Description
string | String specifying the user password for media stream access.

Remarks

This password is used when accessing the media stream indicated by MediaURL. It has no meaning when accessing media files.

See Also

MediaUsername MediaURL


AMC API Reference: MediaType

MediaType Property

Type of the media stream.

Syntax

MediaType [= string ]

Value | Description
string | String specifying the type of media stream. Possible values are: auto-sense (Default) AMC tries to identify the media type. mjpeg-unicast the media stream is in Motion JPEG format and the stream is accessed using HTTP mpeg2-unicast the media stream is in MPEG-2 format and the stream is accessed using HTTP mpeg2-multicast the media stream is in MPEG-2 format and the stream is accessed using RTP mpeg4-multicast the media stream is in MPEG-4 format and the stream is accessed using RTP transparent the identification of the media type is left to DirectShow

Remarks

Set the media type property for a more accurate and efficient handling of the media stream type. For example, when accessing live MPEG-2 unicast streams from the AXIS 250S MPEG-2 Video Server, both the auto-sense and mpeg2-unicast values work, but mpeg2-unicast requires less initialization overhead, since the media type is well-known and there is no need for additional type identification.

When viewing MPEG4 video stream using other protocol than axsdp (see MediaURL) the MediaType must be auto-sense. See Custom Protocols for protocols to use with MPEG-4.

If this property is set to auto-sense and the media stream will be accessed using multicast (axsdp), MediaURL must specify a URL that returns "application/sdp" as the HTTP response content type.

Axis provides no support when using the transparent value for this property. Certain AMC features will be limited or not available if this value is used.

See Also

Custom Protocols MediaURL


AMC API Reference: MediaURL

MediaURL Property

URL where a media stream can be accessed.

Syntax

MediaURL [= string ]

Value | Description
string | String specifying the URL where the media stream can be accessed.

Remarks

No validation of the URL occurs until the Play or StartRecord method is called.

If the AutoStart property is set to True, the media stream will automatically be displayed when this property is set. Note however that if a media stream is being recorded, the media stream being displayed will continue.

When viewing MPEG-4 the URL-type shall be one of the types defined in Custom Protocols for MPEG-4. The MediaType shall always be auto-sense when viewing MPEG-4 streams, except when using URL-type axsdp when it must be mpeg4-multicast.

The URL-type rtsp will let AMC test all MPEG-4 protocols the first time AMC connects to the MPEG-4 stream of an Axis server. The first protocol that is usable will be remembered for future connections.

If MediaType is jpeg-unicast and the component is an object in an HTML page, this property may be relative to the URL of the HTML file itself. If the URL property is set, the control will automatically start the download from this URL.

If both MediaFile and MediaURL are set to something other than an empty string in the same session, the Play method will use the property that was set last.

See Also

Custom Protocols MediaType AutoStart MediaFile Play StartRecord Axis Video API, HTTP


AMC API Reference: MediaUsername

MediaUsername Property

User name for media stream access.

Syntax

MediaUsername [= string ]

Value | Description
string | String specifying the user name for media stream access.

Remarks

This user name is used when accessing the media stream indicated by MediaURL. It has no meaning when accessing media files.

See Also

MediaPassword MediaURL


AMC API Reference: MotionConfigURL

MotionConfigURL Property

URL to where motion detection windows configurations will be sent. This URL is used when UIMode is MDConfig.

Syntax

MotionConfigURL [= string ]

Value | Description
string | String specifying the URL where Motion Detection is configured.

Remarks

This URL must be assigned if UIMode is MDConfig.
No camera shall be assiged in this URL. The camera used in MediaURL will be used for this property.

See Also

MotionDataURL MediaURL UIMode MediaType Axis Camera API, HTTP


AMC API Reference: MotionDataURL

MotionDataURL Property

URL where motion detection data can be fetched. The motion data retrieved via this URL is displayed in the Activity panel when when UIMode is assigned to MDConfig.

Syntax

MotionDataURL [= string ]

Value | Description
string | String specifying the URL from where Motion Detection Data is retrieved.

Remarks

When UIMode is assigned to MDConfig this URL shall point to the CGI where motion data can be retrieved. No cgi-parameters shall be added to the URL. The needed parameters is generated in the component depending on user actions.

This property only works if MediaType is jpeg-unicast.

See Also

MotionConfigURL UIMode MediaType Axis Camera API, HTTP


AMC API Reference: MPEG2VideoDecodingMode

MPEG2VideoDecodingMode Property

Mode to use for decoding MPEG2 video streams/files.

Syntax

MPEG2VideoDecodingMode [= long ]

Value | Description
long | The mode to use for decoding video when an MPEG2 stream/file is displayed. The mode is expressed as a combination of flags and can be used to control video quality and rendering performance. The default value is 0 (best possible performance, no de-interlacing).

Remarks

The decoding mode is expressed as a bitwise combination of the following flags:

Value | MPEG2VideoDecodingMode flag | Meaning
0 | - | decode all frames and no de-interlacing.
1 | AMC_MPEG2_VIDEO_DECODE_ONLY_I | decode only I frames.
3 | AMC_MPEG2_VIDEO_DECODE_ONLY_IP | decode only I and P frames.
65536 | AMC_MPEG2_VIDEO_DEINTERLACE | perform de-interlacing.

Use this property to either improve video quality at the cost of overall performance, or to improve performance at the cost of video quality. For instance, if only I frames are to be decoded, less frames per second will be displayed (video quality loss) but the client computer's performance will increase.

For an explanation of I, P and B frames, please refer to the MPEG2 standards.

De-interlacing is an operation that eliminates unwanted image effects when viewing rapidly moving objects. The video will appear smoother in such situations, but with a slight penalty on performance.

Note that changing this property only affects decoding performance on the client computer. Network bandwith used will remain the same, frames will still be sent from the Axis product as specified in its settings.

To check if a property flag is active, use a bitwise AND operator. For example, in Visual Basic:

Const AMC_MPEG2_VIDEO_DEINTERLACE As Long = 65536
If (AMC.MPEG2VideoDecodingMode And AMC_MPEG2_VIDEO_DEINTERLACE) Then
  MsgBox("de-interlace active")
End If

or in C/C++:

#define AMC_MPEG2_VIDEO_DEINTERLACE 65536L
...
if (theMPEG2VideoDecodingMode & AMC_MPEG2_VIDEO_DEINTERLACE)
{
  OutputDebugString("de-interlace active");
}


AMC API Reference: MPEG2VideoDecodingMode

MPEG4VideoDecodingMode Property

Mode to use for decoding MPEG4 video streams/files.

Syntax

MPEG4VideoDecodingMode [= long ]

Value | Description
long | The mode to use for decoding video when an MPEG4 stream/file is displayed. The mode is expressed as a combination of flags and can be used to control video quality and rendering performance. The default value is 0 (best possible performance, no de-interlacing).

Remarks

The decoding mode is expressed as a bitwise combination of the following flags:

Value | MPEG4VideoDecodingMode flag | Meaning
0 | AMC_MPEG4_VIDEO_DECODE_ONLY_I | decode only I frames.
1 | AMC_MPEG4_VIDEO_DECODE_ONLY_IP | decode only I and P frames.
3 | - | decode all frames and no de-interlacing.
65536 | AMC_MPEG4_VIDEO_DEINTERLACE | perform de-interlacing.

Use this property to either improve video quality at the cost of overall performance, or to improve performance at the cost of video quality. For instance, if only I frames are to be decoded, less frames per second will be displayed (video quality loss) but the client computer's performance will increase.

For an explanation of I, P and B frames, please refer to the MPEG4 standards.

De-interlacing is an operation that eliminates unwanted image effects when viewing rapidly moving objects. The video will appear smoother in such situations, but with a slight penalty on performance.

Note that changing this property only affects decoding performance on the client computer. Network bandwith used will remain the same, frames will still be sent from the Axis product as specified in its settings.

To check if a property flag is active, use a bitwise AND operator. For example, in Visual Basic:

Const AMC_MPEG4_VIDEO_DEINTERLACE As Long = 65536
If (AMC.MPEG4VideoDecodingMode And AMC_MPEG4_VIDEO_DEINTERLACE) Then
  MsgBox("de-interlace active")
End If

or in C/C++:

#define AMC_MPEG4_VIDEO_DEINTERLACE 65536L
...
if (theMPEG4VideoDecodingMode & AMC_MPEG4_VIDEO_DEINTERLACE)
{
  OutputDebugString("de-interlace active");
}


AMC API Reference: MPEG4VideoRenderer

MPEG4VideoRenderer Property

Selection of Video Renderer that will be used when viewing MPEG-4 in AMC. The Video Renderer is a component of DirectShow that handles communication with the Display adapter hardware.

Syntax

MPEG4VideoRenderer [= long ]

Value Description
long Selection of Video Renderer:
  • 0 (default) The Video Renderer that is registered as default will be used.
  • 0x1000 The video Mixing Renderer 9 will be used

Remarks

The default Video Renderer is different on different versions of Windows.

The Video Mixing Renderer 9 is a later version of the Video Renderer that installs with DirectX 9. This Video Renderer uses the display adapter hardware more efficient and always uses hardware accelerated graphics. This means that your PC must have a good enough display adapter for the number of streams you want to show simultaneously.

See Microsoft DirectShow documentation.


AMC API Reference: Mute

Mute Property

Turns the volume on or off.

Syntax

Mute [= boolean ]

Value | Description
boolean | True if the volume is muted, False (Default) if the volume is not muted.

Remarks

When setting this property to False, the volume level will be set to the value of the Volume property.

See Also

Volume


AMC API Reference: NetworkTimeout

NetworkTimeout Property

The number of milliseconds to wait for network traffic before timing out.

Syntax

NetworkTimeout [= number ]

Value | Description
number | Number of milliseconds for the network timeout. Recommended values are between 1000 - 25000 (1s - 25s).

Remarks

The default network timeout is 15000 (15s).

To avoid undesired timeouts, the bandwidth and latency of the network should be taken into account when setting this property.


AMC API Reference: PTZControlURL

PTZControlURL Property

URL where control of the Pan, Tilt and Zoom behavior of a PTZ unit can be accessed.

Syntax

PTZControlURL [= string ]

Value | Description
string | String specifying the URL where PTZ control can be accessed.

Remarks

No validation of the URL occurs. Ensure that this URL is valid before issuing any PTZ commands through AMC.

See Also

UIMode Axis Video API, HTTP


AMC API Reference: ShowStatusBar

ShowStatusBar Property

Shows or hides the status bar.

Syntax

ShowStatusBar [= boolean ]

Value | Description
boolean | True if the status bar is shown, False (Default) if the status bar is hidden.

Remarks

When the status bar is active, the height of the area reserved for media display in the Axis Media Control decreases by 22 pixels.

See Also

ShowToolbar


AMC API Reference: ShowToolbar

ShowToolbar Property

Shows or hides the toolbar.

Syntax

ShowToolbar [= boolean ]

Value | Description
boolean | True if the toolbar is shown, False (Default) if the toolbar is hidden.

Remarks

When the toolbar is active, the height of the area reserved for media display in the Axis Media Control decreases by 32 pixels.

See Also

ShowStatusBar ToolbarConfiguration


AMC API Reference: Status

Status Property

The current status of the control. Read-only property.

Syntax

Status

Value | Description
long | The status of the control, expressed as a combination of flags.

Remarks

The status is expressed as a bitwise combination of the following flags:

Value | Status flag | Meaning
1 | AMC_STATUS_IDLE | AMC is idle and ready.
2 | AMC_STATUS_FLAG_PLAYING | A media stream/file is playing.
4 | AMC_STATUS_FLAG_PAUSED | Playing of a media stream/file is paused.
8 | AMC_STATUS_FLAG_RECORDING | A media stream/file is being recorded.
16 | AMC_STATUS_FLAG_OPENING | AMC is opening a media stream/file.
32 | AMC_STATUS_FLAG_RECONNECTING | AMC is performing reconnection attempts.
512 | AMC_STATUS_FLAG_ISSUING_PTZ_COMMAND | Issuing a Pan, Tilt, Zoom command to the device.
1024 | AMC_STATUS_FLAG_EXTENDED_TEXT | An extended text/message is displayed in the status bar.
65536 | AMC_STATUS_FLAG_OPENING_RECEIVE_AUDIO | The stream for receiveing audio is being opened.
131072 | AMC_STATUS_FLAG_OPENING_TRANSMIT_AUDIO | AMC is opening the stream for transmitting audio.
262144 | AMC_STATUS_FLAG_RECEIVE_AUDIO | Receiving audio.
524288 | AMC_STATUS_FLAG_TRANSMIT_AUDIO | Transmitting audio.
1048576 | AMC_STATUS_FLAG_TRANSMIT_AUDIO_FILE | An audio file is being transmitted.
2097152 | AMC_STATUS_FLAG_RECORDING_AUDIO | Recording audio.

The value 1 (AMC_STATUS_IDLE) indicates that the component is not performing any action.

For example, if a media stream is simultaneously being played and recorded, the value of the Status property will be 5 (AMC_STATUS_FLAG_PLAYING + AMC_STATUS_FLAG_RECORDING).

To check if a flag is active, use a bitwise AND operator. For example, in Visual Basic:

Const AMC_STATUS_FLAG_PLAYING As Long = 1
If (AMC.Status And AMC_STATUS_FLAG_PLAYING) Then
  MsgBox("now playing")
End If

or in C/C++:

#define AMC_STATUS_FLAG_PLAYING 1L
...
if (theStatus & AMC_STATUS_FLAG_PLAYING)
{
  OutputDebugString("now playing");
}

See Also

OnStatusChange


AMC API Reference: StretchToFit

StretchToFit Property

Stretches the image to fit the output window size.

Syntax

StretchToFit [= boolean ]

Value | Description
boolean | True if the image will be stretched, False (Default) if the image will not be stretched.

Remarks

When setting this property to False, if the image is smaller than the output window, the image is centered in the window.

When setting this property to True and displaying an MPEG-2 stream, the aspect ratio is kept. This has the effect that if the output window is bigger than the image to be displayed, the stretching will add black stripes either on the sides of the image or on top and bottom.


AMC API Reference: ToolbarConfiguration

ToolbarConfiguration Property

Configures what buttons to show in the toolbar.

Syntax

ToolbarConfiguration [= string ]

Value | Description
string | String specifying what functionality that is included in the toolbar. See below for syntax.

Remarks

The toolbar is configurable through this property. Controls to display can be added and removed as desired.

A control is added to the toolbar by prefix it with a "+" sign. The position in the string determines where on the toolbar the control is placed. A control is removed from the toolbar by prefix it with a "-". This is useful when default is used as a base.

When audio is available "audiocontrol" can be defined to get mute buttons, volume sliders etc available in the toolbar. What controls are displayed depends on the server configuration. E.g. there is a mute button and a volume slider if we only receive audio from the server while a microphone mute button and a microphone volume slider are added if the server is configured for full duplex.

Example: ToolbarConfiguration = "default,-mute,-volume,+rec"

The above example will take the default configuration, remove volume and mute. And then add recording button at the right.

+ | Adds the wanted functionality.
- | Removes a functionality
default | includes play, snapshot, fullscreen, mute, volume.
play | Stream View: play/stop button. File View: play/pause button + stop button.
snapshot | save snapshot to disk.
rec | Record button (only useful for MPEG2 and Motion JPEG audio)
fullscreen | Shows the video in fullscreen mode.
volume | Displays the volume slider.
mute | Displays the mute button.
audiocontrol | Dynamically displays audio controls, depending on server configuration.

See Also

ShowToolbar


AMC API Reference: UIMode

UIMode Property

The user interface mode to use.

Syntax

UIMode [= string ]

Value | Description
string | A string specifying the user interface mode. Possible values are: none - the AMC user interface is in standard mode. ptz-absolute - the AMC user interface accepts Pan, Tilt, Zoom commands in absolute mode ptz-relative - the AMC user interface accepts Pan, Tilt, Zoom commands in relative mode and displays a cross hair in the center of the image. ptz-relative-no-cross - the AMC user interface accepts Pan, Tilt, Zoom commands in relative mode and displays NO cross hair in the center of the image. MDConfig - the AMC user interface includes motion detection configuration

Remarks

If this property is set to one of the PTZ modes, the PTZControlURL property must be set so that PTZ commands can be accepted by the device. Note that not all camera devices support PTZ relative mode.

If this property is set to MDConfig, the MotionConfigURL and MotionDataURL property must be set so that Motion Detection commands can be accepted by the device. Note that not all camera devices support Motion Detection.

Note that UIMode can only have one value at a time, meaning that MDConfig and a PTZ mode can not be activaded at the same time.

See Also

PTZControlURL MotionConfigURL MotionDataURL


AMC API Reference: Volume

Volume Property

The volume to use when playing media.

Syntax

Volume [= number ]

Value | Description
long | Volume level. Valid range is 0-100.

Remarks

The default volume level is 30. Zero specifies silence and 100 specifies full volume.

Setting this property while playing media and when the Mute property is set to True will simply store the value in the component - audio will not be unmuted. To actually change the volume, your application must set Mute to False after Volume has been set. This behaviour is by design.

See Also

Mute


AMC API Reference: Methods

Methods

Media

GetCurrentImage
Gets the data corresponding to the image currently being displayed.
Play
Starts playing the media stream/file specified for AMC.
SaveCurrentImage
Saves the image currently being displayed to the specified file.
StartRecord
Starts recording a media stream to the specified file.
StartRecordMedia
Starts recording one or more media streams.
StartTransmitMedia
Start transmitting a media-file to the camera.
Stop
Stops the media stream/file currently playing.
StopRecord
Stops recording a media stream.
StopRecordMedia
Stops recording a media stream.
StopTransmitMedia
Stops transmitting a media-file to the camera.
TogglePause
Pauses or resumes playing of a media file.
SetReconnectionStrategy
Configures the reconnection strategy.


AMC API Reference: AudioReceiveStart

AudioReceiveStart

Opens an audio stream from the URL given by AudioReceiveURL, and starts playback.

Syntax

  HRESULT AudioReceiveStart();	    [C++]
  AudioReceiveStart()		    [Visual Basic]

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | The operation was not performed because necessary data was not available.
E_FAIL | Unexpected failure.

See Also

AudioReceiveStop


AMC API Reference: AudioReceiveStop

AudioReceiveStop

Stops any incoming audio streams.

Syntax

  HRESULT AudioReceiveStop();	    [C++]
  AudioReceiveStop()		    [Visual Basic]

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | The operation was not performed because necessary data was not available.
E_FAIL | Unexpected failure.

See Also

AudioReceiveStart


AMC API Reference: AudioTransmitStart

AudioTransmitStart

Starts transmit audio from from a local microphone to the URL given by AudioTransmitURL.

Syntax

  HRESULT AudioTransmitStart();	    [C++]
  AudioTransmitStart()		    [Visual Basic]

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | The operation was not performed because necessary data was not available.
E_FAIL | Unexpected failure.

See Also

AudioTransmitStop


AMC API Reference: AudioTransmitStop

AudioTransmitStop

Stops any ongoing audio transmissions.

Syntax

  HRESULT AudioTransmitStop();	    [C++]
  AudioTransmitStop()		    [Visual Basic]

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | The operation was not performed because necessary data was not available.
E_FAIL | Unexpected failure.

See Also

AudioTransmitStart


AMC API Reference: GetCurrentImage

GetCurrentImage

Gets the data corresponding to the image currently being displayed.

Syntax

  HRESULT GetCurrentImage(int theFormat,    [C++]
            VARIANT* theBuffer,
            LONG* theBufferSize
           );
  GetCurrentImage(ByVal theFormat As Integer,    [Visual Basic]
            ByRef theBuffer As Variant,
            ByRef theBufferSize As Long
           )

Parameters

theFormat
Identifier specifiying the format of the image data. Values available are: 0 = JPEG, 1 = BMP
theBuffer
The buffer where the image data is returned.
theBufferSize
Size of the image data buffer returned.

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | The operation was not performed because no current image was available (e.g., stream stopped).
E_FAIL | Unexpected failure.
E_INVALIDARG | Invalid parameter. E.g., unrecognized format.
E_POINTER | An output parameter was not provided.

Remarks

If the format specified is BMP, the image data buffer is returned as a byte array with a BITMAPINFOHEADER structure followed immediately by the bitmap data in RGB24 format. Note that this buffer would not constitute a valid .BMP file if saved to a file. A BITMAPFILEHEADER structure is also required. If your purpose is to save the image to a file use SaveCurrentImage instead. This method will generate a proper .BMP file.

See Also

SaveCurrentImage


AMC API Reference: Play

Play

Starts playing the media stream/file specified for AMC.

Syntax

 HRESULT Play(void); [C++]
 Play()   [Visual Basic]

Parameters

None.

Return Value

Returns an HRESULT value. Possible values include (but are not limited to) the following:

Value | Description
S_OK | Successful execution.
S_FALSE | Invalid status change (e.g., trying to play when already playing). Also returned when the control is invisible and no video can be displayed.
E_FAIL | Unexpected failure.
E_ACCESSDENIED | Access to the media denied due to incorrect user name/password.
E_INVALIDARG | Invalid parameter, both MediaURL and MediaFile are empty.

Remarks

This method uses the value specified by the MediaURL, MediaFile or AudioReceiveURL property to access the media.

The media will continue playing until Stop is called, AMC is closed or an unexpected asynchronous error occurs.

If media playing has been paused, the Play method will have no effect. Use TogglePause to resume playing.

If the AutoStart property is set to True, Play is called when either MediaURL or MediaFile are set.

Any previous call to StartRecord will not be affected by this method call. If both operations are allowed on the stream, AMC will continue recording and playing simultaneously .

This method can return errors due to malformed values for the MediaURL or MediaFile properties. It is sometimes not possible to discern if the error was caused by a network problem or by a malformed address. It is therefore recommended that your application provides a meaningful error message to your users warning them of this problem.

The overhead of the Play method (the time between the method call and the moment media starts being played) may be reduced by specifiying a more specific MediaType value than auto-sense or transparent.

See Also

AutoStart MediaURL MediaFile Stop TogglePause StartRecord


AMC API Reference: SaveCurrentImage

SaveCurrentImage

Saves the image currently being displayed to the specified file.

Syntax

  HRESULT SaveCurrentImage(int theFormat,    [C++]
            BSTR theFile
           );
  SaveCurrentImage(ByVal theFormat As Integer,    [Visual Basic]
            ByVal theFile As String
           )

Parameters

theFormat
Identifier specifiying the format of the resulting file. Values available are: 0 = JPEG, 1 = BMP
theFile
Complete path and file name where the image will be stored.

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | The operation was not performed because no current image was available (e.g., stream stopped).
E_FAIL | Unexpected failure.
E_INVALIDARG | Invalid parameter. Unrecognized format or empty file name.

See Also

GetCurrentImage


AMC API Reference: SetImage

SetImage

Sets an image to be displayed.

Syntax

  HRESULT SetImage(VARIANT* theBuffer,    [C++]
            LONG* theBufferSize
           );
  HRESULT SetImage(ByRef theBuffer As Variant,    [Visual Basic]
            ByRef theBufferSize As Long
           )

Parameters

theBuffer
The image data buffer.
theBufferSize
Size of the image data buffer.

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
E_FAIL | Unexpected failure.
E_NOTIMPL | Not Implemented. (returned if Mediatype is not MJPEG.)

Remarks

SetImage only works when MediaType is MJPEG and the stream must be stopped.

See Also

SaveCurrentImage, MediaType, Stop


AMC API Reference: SetReconnectionStrategy

SetReconnectionStrategy

Configures the reconnection strategy. Defines reconnection phases with the corresponding connection intervals. Up to three phases are supported.

Syntax

  HRESULT SetReconnectionStrategy(LONG theDuration1,    [C++]
            LONG theConnectionInterval1,
            LONG theDuration2,
            LONG theConnectionInterval2,
            LONG theDuration3,
            LONG theConnectionInterval3,
            BOOL infiniteMode
           );
  HRESULT SetReconnectionStrategy(ByVal theDuration1 As LONG,    [Visual Basic]
            ByVal theConnectionInterval1 As LONG,
            ByVal theDuration2 As LONG,
            ByVal theConnectionInterval2 As LONG,
            ByVal theDuration3 As LONG,
            ByVal theConnectionInterval3 As LONG,
            ByVal infiniteMode As Boolean
           );

Parameters

theDuration1
Specifies the duration of the first reconnection phase (milliseconds).
theConnectionInterval1
Specifies the duration between reconnection attempts in the first reconnection phase (milliseconds).
theDuration2
Specifies the duration of the second reconnection phase (milliseconds).
theConnectionInterval2
Specifies the duration between reconnection attempts in the second reconnection phase (milliseconds).
theDuration3
Specifies the duration of the third reconnection phase (milliseconds).
theConnectionInterval3
Specifies the duration between reconnection attempts in the third reconnection phase (milliseconds).
infiniteMode
If set to True, the third phase will be of infinit duration. theDuration3 will be used otherwise.

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
E_FAIL | Unexpected failure.
E_INVALIDARG | Invalid parameter. Negative values are not accepted.

Remarks

The durations and connection intervals cannot have negative values. Setting duration to zero means that the reconnection phase will not be used. The reconnection mechanism will not start a new connection attempt before the previous attempt has finished, why the connection attempts may occur less often than desired. EnableReconnect must be set to True to activate the reconnection functionality.

See Also

EnableReconnect


AMC API Reference: StartRecord

StartRecord

Starts recording a media stream to the specified file.

Syntax

  HRESULT StartRecord(BSTR theFile);    [C++]
  StartRecord(ByVal theFile As String)    [Visual Basic]

Parameters

theFile
Complete path and file name where the media stream will be stored.

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | Invalid status change, e.g., trying to save when already saving.
E_FAIL | Unexpected failure.
E_ACCESSDENIED | Access to the media denied due to incorrect user name/password.
E_INVALIDARG | Invalid parameter.

Remarks

This method uses the value specified by the MediaURL property to access the media stream. Note that if a stream with another MediaURL is already playing, it will be that stream that gets recorded. To play one stream and record another simultaneously, two different instances of AMC are required.

The method can be called at any time, even when the media stream is not being displayed. Recording will continue until StopRecord is called, AMC is closed or an unexpected asynchronous error occurs. Note that calling Stop will not stop a recording.

This method can return errors due to malformed values for the MediaURL or MediaFile properties. It is sometimes not possible to discern if the error was caused by a network problem or a malformed address. It is therefore recommended that your application provides a meaningful error message to your users warning them of this problem.

Important note: recording currently only works for live MPEG-2 unicast (HTTP) streams. This means that you must have a live HTTP unicast stream before starting your recording.

See Also

StopRecord Play MediaURL MediaFile


AMC API Reference: GetCurrentImage

StartRecordMedia

Records one or more media streams to a file.

Syntax

  HRESULT StartRecordMedia(BSTR theFile,    [C++]
            LONG theFlags,
            BSTR theMediaTypes
           );
  StartRecordMedia(ByVal theFile As String,    [Visual Basic]
            ByVal theFlags As Long,
            ByVal theMediaTypes As String
           )

Parameters

theFile
String specifying the file where the recorded media is stored.
theFlags
Flags control the behavior of the recording. Flags 1-4 are used when recording audio received or transmitted in separate streams (using AudioReceiveURL, AudioTransmitURL). Flags 8 and 16 are used to record received video and audio (synchronized) or only video.
Value | Flag | Description
1 | RECORD_FLAG_RECEIVED_AUDIO | Record received audio.
2 | RECORD_FLAG_TRANSMITTED_AUDIO | Record transmitted audio.
4 | RECORD_FLAG_ENCODED_AUDIO | Save audio in the original format (encoded).
8 | RECORD_FLAG_VIDEO | Record video.
16 | RECORD_FLAG_VIDEO_AUDIO | Record video and audio.
theMediaTypes
String containing the format in which the media streams are to be saved. For future use.

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | Operation was not performed because necessary data was not available.
E_FAIL | Unexpected failure.
E_INVALIDARG | Invalid parameter. E.g., unrecognized format.

Remarks

This method records the media stream which is being displayed. Recording will continue as long as the stream is playing or until StopRecordMedia is called.

In the case of recording both received and transmitted audio, incoming audio is stored as the left stereo channel while transmitted audio is stored as the right stereo channel. Currently, video cannot be recorded in MJPEG. Video is recorded in ASF format. When recording only audio PCM format is used.

Windows Media Format 9 Series Runtime, or higher, is required for supporting MPEG-4 recording in AXIS Media Control.

See Also

StopRecordMedia Play Stop


AMC API Reference: GetCurrentImage

StartTransmitMedia

Starts transmitting media to the server.

Syntax

  HRESULT StartTransmitMedia(BSTR theFile,    [C++]
            LONG theFlags
           );
  StartTransmitMedia(ByVal theFile As String,    [Visual Basic]
            ByVal theFlags As Long
           )

Parameters

theFile
String identifying the file to be transmitted.
theFlags
Flags controlling the behaviour of the operation. For future use.

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | The operation was not performed because necessary data was not available.
E_FAIL | Unexpected failure.
E_INVALIDARG | Invalid parameter. E.g., unrecognized format.

Remarks

Currently, only audio files in raw PCM format can be transmitted.

See Also

StopTransmitMedia


AMC API Reference: Stop

Stop

Stops the media stream/file currently playing.

Syntax

  HRESULT Stop(void);    [C++]
  Stop()    [Visual Basic]

Parameters

None.

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | Invalid status change, e.g., trying to stop when not playing.
E_FAIL | Unexpected failure.

Remarks

This method will not stop an ongoing recording, StopRecord or StopRecordMedia must also be called.

See Also

Play TogglePause


AMC API Reference: StopRecord

StopRecord

Stops recording a media stream.

Syntax

  HRESULT StopRecord(void);    [C++]
  StopRecord()    [Visual Basic]

Parameters

None.

Return Value

Returns an HRESULT value. Possible values include the following.

Value | Description
S_OK | Successful execution.
S_FALSE | Invalid status change e.g., trying to stop a recording when not recording.
E_FAIL | Unexpected failure.

Remarks

Stops the recording started by the StartRecord method. If AMC is simultaneously playing the stream, the playing will not be stopped, Stop must also be called.

See Also

StartRecord


AMC API Reference: GetCurrentImage

StopRecordMedia

Ends an ongoing recording and closes the file used for storing the media streams.

Syntax

  HRESULT StopRecordMedia()    	[C++]

  StopRecordMedia()    		[Visual Basic]

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | The operation was not performed because necessary data was not available.
E_FAIL | Unexpected failure.

Remarks

Stops the recording started by the StartRecordMedia method. If AMC is simultaneously playing the stream, the playing will not be stopped, Stop must also be called.

See Also

StartRecordMedia


AMC API Reference: GetCurrentImage

StopTransmitMedia

Interrupts and ends an ongoing transmission.

Syntax

  HRESULT StopTransmitMedia();	    [C++]
  StopTransmitMedia()		    [Visual Basic]

Return Value

Returns an HRESULT value. Possible values include the following:

Value | Description
S_OK | Successful execution.
S_FALSE | The operation was not performed because necessary data was not available.
E_FAIL | Unexpected failure.

See Also

StartTransmitMedia


AMC API Reference: TogglePause

TogglePause

Pauses or resumes playing of a media file.

Syntax

  HRESULT TogglePause(void);    [C++]
  TogglePause()    [Visual Basic]

Parameters

None.

Return Value

Returns an HRESULT value. Possible values include the following.

Value | Description
S_OK | Successful execution.
S_FALSE | Invalid status change e.g., trying to pause when not playing.
E_FAIL | Unexpected failure.
E_NOTIMPL | Pause is not implemented for live streams.

Remarks

Pause has no effect in live streams. Call Stop instead.

See Also

Play Stop


AMC API Reference: Events

Events

Media

    OnNewImage
    Event generated every time a new image/frame is received by the AMC component.

Status

    OnClick
    Event generated when the user clicks the left mouse button while the pointer is over the ActiveX control.
    OnDoubleClick
    Event generated when the user double-clicks a mouse button while the pointer is over the ActiveX control.
    OnError
    Event generated when an asynchronous error occurs.
    OnMouseDown
    Event generated when the user presses down a mouse button while the pointer is over the ActiveX control.
    OnMouseMove
    Event generated when the user moves the mouse while the pointer is over the ActiveX control.
    OnMouseUp
    Event generated when the user releases a mouse button while the pointer is over the ActiveX control.
    OnStatusChange
    Event generated every time a status change occurs in the AMC component.


AMC API Reference: OnClick

OnClick

Event generated when the user clicks a mouse button while the pointer is over the ActiveX control.

Syntax

OnClick(INT X,        [C++]
        INT Y);
OnClick(ByVal X As Long, [Visual Basic]
        ByVal Y As Long)

Parameters

X
Specifies the x-position in pixels at the time the event was fired.
Y
Specifies the y-position in pixels at the time the event was fired.

Remarks

This event must not be used in combination with the OnMouseDown event.

See Also

OnMouseDown


AMC API Reference: OnDoubleClick

OnDoubleClick

Event generated when the user double-clicks a mouse button while the pointer is over the ActiveX control.

Syntax

OnDoubleClick(INT nButton,             [C++]
              INT nShiftState,
              INT fX,
              INT fY
             );
OnDoubleClick(ByVal nButton As Long,      [Visual Basic]
              ByVal nShiftState As Long,
              ByVal fX As Long,
              ByVal fY As Long
             )

Parameters

nButton
Specifies the mouse button that was double-clicked.
nShiftState
Specifies which shift key, if any, was pressed at the time the event was fired.
fX
Specifies the x-position in pixels at the time the event was fired.
fY
Specifies the y-position in pixels at the time the event was fired.

Remarks

The event is only generated when the control is playing a media stream.

See the OnMouseDown event for possible values for nButton and nShiftState.

See Also

OnMouseDown


AMC API Reference: OnError

OnError

Event generated when an asynchronous error occurs.

Syntax

OnError(long theErrorCode,     [C++]
        BSTR theErrorInfo);
OnError(ByVal theErrorCode As Long,  [Visual Basic]
        ByVal theErrorInfo As String)

Parameters

theErrorCode
The error code. A pre-defined number.
theErrorInfo
A string explaining the error in English.

Remarks

This event is triggered when asynchronous errors occur. Asynchronous errors occur while AMC is performing tasks that are not in direct relation to method calls. Synchronous errors occur when methods are called and constitute the return value of those calls.

The following error codes may currently be raised:

Value | Meaning | Hex val | Dec val (LOWORD)
AMC_E_NET_PROBLEMS | A network error occurred. | 0x80040200 | 512
AMC_E_NO_MORE_STREAM | The stream ended while expecting more data. | 0x80040201 | 513
AMC_E_NO_UDP_VIDEO_STREAM_STARTED | The UDP video stream could not be started. Used when checking if Windows XP with SP2 and the firewall is enabled. | 0x80040202 | 514
AMC_E_NO_PTZ_CONTROL_URL | A PTZ control operation was attempted, but no PTZ URL was given. | 0x80040230 | 560
AMC_E_PTZ_FAIL | A PTZ control operation was rejected by the device. | 0x80040231 | 561
AMC_E_AUDIO_NET_PROBLEMS | A network error occurred in audio module. | 0x80040400 | 1024
AMC_E_AUDIO_MAX_CLIENTS | Too many clients trying to receive audio data. | 0x80040401 | 1025
AMC_E_AUDIO_CLOSE_RECEIVE | Error while closing receive channel | 0x80040402 | 1026
AMC_E_AUDIO_CLOSE_TRANSMIT | Error while closing transmit channel. | 0x80040403 | 1027
AMC_E_AUDIO_CLIENT | Not possible to transmit, another client is already sending data to the server. | 0x80040404 | 1028
AMC_E_AUDIO_PROXY | Proxy size problems. | 0x80040405 | 1029
AMC_E_AUDIO_MAX_REC_CLIENTS | Too many receiving clients. Only for full duplex where it is still possible to transmit if no one else is posting. | 0x80040406 | 1030
AMC_E_AUDIO_TRANSMIT | Failed to open http session. | 0x80040407 | 1031
AMC_E_AUDIO_FILE | Failed to open or create file. | 0x80040408 | 1032
AMC_E_AUDIO_NO_MORE_STREAM | The audio stream ended while expecting more audio data (stream was not stopped from client). | 0x80040450 | 1104


AMC API Reference: OnMouseDown

OnMouseDown

Event generated when the user presses down a mouse button while the pointer is over the ActiveX control.

Syntax

OnMouseDown(INT nButton,             [C++]
            INT nShiftState,
            INT fX,
            INT fY
           );
OnMouseDown(ByVal nButton As Long,      [Visual Basic]
            ByVal nShiftState As Long,
            ByVal fX As Long,
            ByVal fY As Long
           )

Parameters

nButton
Specifies the mouse button that was pressed.
nShiftState
Specifies which shift key, if any, was pressed at the time the event was fired.
fX
Specifies the x-position in pixels at the time the event was fired.
fY
Specifies the y-position in pixels at the time the event was fired.

Remarks

The following table lists the possible values for nButton:

Value | Key State Mask | Meaning
1 | MK_LBUTTON | The left button was pressed.
2 | MK_RBUTTON | The right button was pressed.
16 | MK_MBUTTON | The middle button was pressed.

The nShiftState parameter may have the following values:

Value | Key State Mask | Meaning
4 | MK_SHIFT | The Shift key was pressed.
8 | MK_CONTROL | The Ctrl key was pressed.

The values for all pressed keys or buttons are added to the resulting value.

The parameter values are equivalent to Windows key state masks for mouse messages, declared in winuser.h. See WM_LBUTTONDOWN Notification in MSDN for further details.

See Also

OnMouseMove


AMC API Reference: OnMouseMove

OnMouseMove

Event generated when the user moves the mouse while the pointer is over the ActiveX control.

Syntax

OnMouseMove(INT nButton,             [C++]
            INT nShiftState,
            INT fX,
            INT fY
           );
OnMouseMove(ByVal nButton As Long,      [Visual Basic]
            ByVal nShiftState As Long,
            ByVal fX As Long,
            ByVal fY As Long
           )

Parameters

nButton
Specifies the mouse button, if any, that was pressed when the mouse move occurred.
nShiftState
Specifies which shift key, if any, was pressed at the time the event was fired.
fX
Specifies the x-position in pixels at the time the event was fired.
fY
Specifies the y-position in pixels at the time the event was fired.

Remarks

See the OnMouseDown event for possible values for nButton and nShiftState.

See Also

OnMouseDown


AMC API Reference: OnMouseUp

OnMouseUp

Event generated when the user releases a mouse button while the pointer is over the ActiveX control.

Syntax

OnMouseUp(INT nButton,             [C++]
          INT nShiftState,
          INT fX,
          INT fY
         );
OnMouseUp(ByVal nButton As Long,      [Visual Basic]
          ByVal nShiftState As Long,
          ByVal fX As Long,
          ByVal fY As Long
         )

Parameters

nButton
Specifies the mouse button that was released.
nShiftState
Specifies which shift key, if any, was pressed at the time the event was fired.
fX
Specifies the x-position in pixels at the time the event was fired.
fY
Specifies the y-position in pixels at the time the event was fired.

Remarks

See the OnMouseDown event for possible values for nButton and nShiftState.

See Also

OnMouseDown


AMC API Reference: OnNewImage

OnNewImage

Event generated every time a new image/frame is received by the AMC component.

Syntax

OnNewImage(); [C++]
OnNewImage()  [Visual Basic]

Parameters

None.

Remarks

When processing MPEG-2 streams, try to keep the code responding to this event short, so that the frame rate does not decrease.


AMC API Reference: OnStatusChange

OnStatusChange

Event generated every time a status change occurs in the AMC component.

Syntax

OnStatusChange(long theNewStatus,     [C++]
               long theOldStatus);
OnStatusChange(ByVal theNewStatus As Long,  [Visual Basic]
               ByVal theOldStatus As Long)

Parameters

theNewStatus
The new status.
theOldStatus
The status previous to the status change.

Remarks

See the Status property for a description of the possible status values.

See Also

Status


Axis Video API, HTTP

Axis video products using firmware version 4.00 and above support Axis Video API revision 2.00 and later.

For Axis video products with firmware version 2.xx and 3.xx, the earlier revision of Axis Video API must be used.

See the Product Interface Guide for Axis video products on the Axis website for a complete up-to-date list matching revision to product and firmware.

Note
Axis MPEG-2 video products version 3.10 and later also support the new parameter interface specified in Axis Video API revision 2.00.

HTTP API specification, revision 1.14
HTTP API specification, revision 2.09


Axis Video API, HTTP, for products with firmware version 2.xx and 3.xx

Axis Video API, HTTP - Interface Specification

Revision: 1.14
Date: 2003-Dec-04

TABLE OF CONTENTS

  • DOCUMENT HISTORY
  • 1 OVERVIEW
    • 1.1 Product and firmware versions
  • 2 REFERENCES
  • 3 DEFINITIONS
    • 3.1 General notations
      • 3.1.1 General abbreviations
      • 3.1.2 Style convention
      • 3.1.3 General CGI URL syntax and parameters
      • 3.1.4 Parameter value convention
  • 4 INTERFACE SPECIFICATION
    • 4.1 Naming conventions and URL syntax
      • 4.1.1 Obsolete CGI parameters
    • 4.2 Server responses
      • 4.2.1 HTTP status codes
  • 5 API GROUPS
    • 5.1 General
      • 5.1.1 Get camera parameter values
      • 5.1.2 Camera parameter values response
      • 5.1.3 Set camera parameter values
      • 5.1.4 Factory default
      • 5.1.5 Restart server
      • 5.1.6 Server report
      • 5.1.7 System logs
    • 5.2 JPEG/MJPG
      • 5.2.1 JPEG image request
      • 5.2.2 JPEG image (snapshot) CGI request
      • 5.2.3 JPEG image response
      • 5.2.4 JPEG buffer request
      • 5.2.5 MJPG video request
      • 5.2.6 MJPG video CGI request
      • 5.2.7 MJPG video response
    • 5.3 MPEG-2
      • 5.3.1 MPEG-2 video request
      • 5.3.2 MPEG-2 video response
      • 5.3.3 MPEG-2 buffer request
      • 5.3.4 MPEG-2 multicast info request
      • 5.3.5 MPEG-2 multicast info response
    • 5.4 PTZ
      • 5.4.1 PTZ control
    • 5.5 Audio
      • 5.5.1 Multipart audio data request
      • 5.5.2 Multipart audio data response
      • 5.5.3 Multipart audio data transmit
      • 5.5.4 Get audio configuration parameters
    • 5.6 Motion Detection
      • 5.6.1 Set motion detection parameters
      • 5.6.2 Get motion detection parameters
      • 5.6.3 Get motion detection level
    • 5.7 Recording
      • 5.7.1 List recordings
      • 5.7.2 Play recordings
      • 5.7.3 Recorded JPG/MJPG response
      • 5.7.4 Preserve and release recordings
      • 5.7.5 Controlling recordings
    • 5.8 I/O
      • 5.8.1 I/O control
        • 5.8.1.1 Input
        • 5.8.1.2 Output
      • 5.8.2 Virtual I/O control
        • 5.8.2.1 Input
    • 5.9 Serial port
      • 5.9.1 Serial port control
      • 5.9.2 Open serial port
    • 5.10 PPP
      • 5.10.1 Close PPP connection
      • 5.10.2 Reset PPP connection maxtimer
    • 5.11 Event
      • 5.11.1 Event administration
        • 5.11.1.1 Actions
        • 5.11.1.2 Server responses
    • 5.12 Firewall
      • 5.12.1 Firewall administration
        • 5.12.1.1 Actions
        • 5.12.1.2 Parameters
        • 5.12.1.3 Options
        • 5.12.1.4 Server responses

DOCUMENT HISTORY

Version | Date | Comment
1.00 | 2000-nov-01 | Initial version
1.01 | 2000-nov-13 | Added info about dataout and altered description of wait and timeout in "serial port control".
1.02 | 2000-nov-28 | Added entry for controlling image buffers.
1.03 | 2000-nov-30 | Added entries for closing PPP connection and resetting PPP connection maxtimer.
1.04 | 2000-dec-11 | Added examples for setting motion detection parameters.
1.05 | 2001-jan-11 | Corrected multipart boundary examples.
1.06 | 2001-jan-16 | Removed check of output on IO-ports (until it is supported).
1.07 | 2001-sep-07 | Added Audio support.
1.08 | 2001-nov-22 | Changed audio MIME type and audio parameters.
1.09 | 2002-apr-15 | Added frame rate control.
1.10 | 2002-jul-04 | Added MPEG-2, recording, event and firewall support. Grouped the API requests into different sections.
1.11 | 2003-may-07 | Updated and corrected Recording interface.
1.12 | 2003-dec-04 | Added MPEG-2 multicast info request and response. Removed delay parameter and added predelay and postdelay parameters to JPEG buffer request.
1.13 | 2004-jan-22 | Corrected description for JPEG buffer request, do=reset.
1.14 | 2004-apr-22 | Added better description and an example for the info parameter to the ptz.cgi. Corrected some response descriptions.

1 OVERVIEW

This document specifies the external HTTP based application programming interface of the Axis camera and video servers.

The HTTP-based video interface provides the functionality for requesting single and multi-part images, for controlling camera functions (PTZ, output relay etc.) and for getting and setting internal parameter values. The image and CGI-requests are handled by the built-in Web server in the camera and video server.

1.1 Product and firmware versions

The support for this stated HTTP API is very dependent on the product and firmware release. Please refer to the Release Notes for the actual product for compliance information.

2 REFERENCES

HTTP protocol

  • Hypertext Transfer Protocol -- HTTP/1.0

External application programming interfaces (Client side)

  • Axis Video API, HTTP
  • Axis Video Product specific API Notes

3 DEFINITIONS

This section contains information on general usage of this document.

3.1 General notations

3.1.1 General abbreviations

The following abbreviations are used throughout this document
CGI | Common Gateway Interface - a standardized method of communication between a client (e.g., a web browser) and a server (e.g., a web server).
TBD | To be done/designed - notifies the reader that the referenced section/subsection/entity is intended to be specified, but has not reached a level of maturity to be public at this time.
N/A | Not applicable - a feature/parameter/value is of no use in a specific task.

3.1.2 Style convention

In URL syntax and in descriptions of CGI parameters, text in italic within angle brackets denotes content that should be replaced with either a value or a string. When replacing the text string, the angle brackets must also be replaced. An example of this is the description of the name for the server, denoted with <servername> in the URL syntax description below, which is replaced with the string myserver in the URL syntax example, also shown below.

URL syntax is written with the word "Syntax:" shown in bold face, followed by a box with the referred syntax, as shown below. The name of the server is written as <servername>. This is intended to be replaced with the name of the actual server. This can either be a name, e.g., "thecam" or "thecam.adomain.net" or the associated IP number for the server, e.g., 10.10.2.139.

Syntax:
http://<servername>/jpg/image.jpg

A description of returned data is written with "Return:" in bold face, followed by the returned data in a box. All data returned as HTTP formatted, i.e., starting with the string HTTP, is line-separated with a Carriage Return and Line Feed (CRLF) printed as \r\n.

Return:
HTTP/1.0 <HTTP code> <HTTP text>\r\n

URL syntax examples are written with "Example:" in bold face, followed by a short description and a light grey box with the example.

Example: request default image
http://myserver/jpg/image.jpg

Examples of what can be returned by the server from a request is written with "Example:" in bold face, followed by a short description and a light grey box with an example of the returned data.

Example: returned data after a successful request
HTTP/1.0 200 Ok\r\n

3.1.3 General CGI URL syntax and parameters

CGI URLs are written in lower-case. CGI parameters are written in lower-case and as one word, with no underscores or other separators. When the CGI request includes internal camera parameters, the internal parameters must be written exactly as named in the camera or video server. The CGIs are organized in function related directories under the axis-cgi directory. The file extension of the CGI is required.

Syntax:
http://<servername>/axis-cgi/<subdir>[/<subdir>...]/<cgi>.<ext>
[?<parameter>=<value>[&<parameter>=<value>...]]

Example: setting PTZ parameters
http://myserver/axis-cgi/com/ptz.cgi?camera=1&move=home

3.1.4 Parameter value convention

In tables defining CGI parameters and supported parameter values, the default value for optional parameters is system configured.

4 INTERFACE SPECIFICATION

4.1 Naming conventions and URL syntax

4.1.1 Obsolete CGI parameters

Some CGI parameters and values in this specification are obsolete and are provided for backward compatibility. These might not be supported in the future.

Obsolete parameters and values are stated in the request descriptions.

4.2 Server responses

4.2.1 HTTP status codes

The built-in Web server uses the standard HTTP status codes.

Return:
HTTP/1.0 <HTTP code> <HTTP text>\r\n

with the following HTTP code and meanings
HTTP code | HTTP text | Description
200 | OK | The request has succeeded, but an application error can still occur, which will be returned as an application error code.
204 | No Content | The server has fulfilled the request, but there is no new information to send back.
400 | Bad Request | The request had bad syntax or was inherently impossible to be satisfied.
401 | Unauthorized | The request requires user authentication or the authorization has been refused.
404 | Not Found | The server has not found anything matching the request.
409 | Conflict | The request could not be completed due to a conflict with the current state of the resource.
500 | Internal Error | The server encountered an unexpected condition that prevented it from fulfilling the request.
503 | Service Unavailable | The server is unable to handle the request due to temporary overload.

Example: request includes invalid file names.
HTTP/1.0 404 Not Found\r\n

5 API GROUPS

To make it easier for developers to get an idea of which API requests are supported for different products, the requests have been grouped together. Information about which groups are supported can be found in the product-specific release notes document, available for download from the Axis web site.

5.1 General

The requests specified in the General section are supported by all video products.

5.1.1 Get camera parameter values

Get a camera's parameter values.

Note: This request requires administrator access (administrator authorization).

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/admin/getparam.cgi?<parameter>[&<parameter>...]

<parameter>=<value> | Values | Description
<string> 1 | <group>[.<name>] | Returns the value of the camera parameter named <group>.<name> as described in 5.1.2. If <name> is omitted, all the parameters of the <group> are returned The camera parameters must be entered exactly as named in the camera or the video server.

1 The supported parameters are product/release-dependent.

Example: Get the IP address
http://myserver/axis-cgi/admin/getparam.cgi?Network.IPAddress

Example: Get all of the network parameters
http://myserver/axis-cgi/admin/getparam.cgi?Network

5.1.2 Camera parameter values response

When querying parameter values, the current parameter values are returned.

Successful control requests returns parameter pairs, as follows.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
<parameter pair>
where <parameter pair> is
<parameter>=<value>\n
[ <parameter pair> ]

Example: PTZ position query response
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
pan=-50\n
tilt=0\n
zoom=500\n

If the CGI request includes an invalid parameter value, the server returns an error message.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
Error: <error text (or code)>\n
<description>\n

5.1.3 Set camera parameter values

Set a camera's parameter values.

Note: This request requires administrator access (administrator authorization).

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/admin/setparam.cgi?<parameter>=<value>
[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
<string>=<string> | <group.name> = <value> | Assigns <value> to the parameter <group.name> The <value> must be URL-encoded when it contains non-alphanumeric characters. The camera parameters must be entered exactly as named in the camera or the video server.
nosync=<string> 1 | yes | Specifies that there should be no sync (write) of the corresponding configuration file to flash. If parameter is omitted, a sync will occur.

Example: Set default image resolution to 320x240 pixels
http://myserver/axis-cgi/admin/setparam.cgi?Image.Resolution=320x240

Example: Set the bandwidth limitation to 500, without writing the corresponding configuration file to flash
http://myserver/axis-cgi/admin/setparam.cgi?Network.Bandwidth=500&nosync=yes

5.1.4 Factory default

Reload factory default

Note: This request requires administrator access (administrator authorization).

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/factorydefault.cgi

5.1.5 Restart server

Restart server

Note: This request requires administrator access (administrator authorization).

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/restart.cgi

5.1.6 Server report

This CGI request generates and returns a server report. This report is useful as an input when requesting support. The report includes product information, parameter settings and system logs.

Note: This request requires administrator access (administrator authorization).

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/serverreport.cgi

5.1.7 System logs

Get system log information

Note: This request requires administrator access (administrator authorization).

Note: The response is product/release-dependent.

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/systemlog.cgi

Return:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
<system log information>

5.2 JPEG/MJPG

The requests specified in the JPEG/MJPG section are supported by those video products that use JPEG/MJPG encoding.

5.2.1 JPEG image request

Request JPEG image

Method: GET

Syntax:
http://<servername>/jpg[/<camera>]/<name>.jpg

with the following parameters
Parameter | Values | Description
<camera> | 1, ... 1 | Select input source. Applies only to servers with more than one input source. Default: default camera
<name> | image, quad1, halfsize2, fullsize2, hugesize2 | "image" returns an image with the default resolution and compression, as defined in the system configuration. The <camera> option is not allowed in quad request.

1 Product-dependent. Check the product specification.
2 Obsolete.

Example: request JPEG image from default camera with default resolution and compression
http://myserver/jpg/image.jpg

5.2.2 JPEG image (snapshot) CGI request

Request a JPEG image (snapshot) with specified properties.

Method: GET

Syntax:
http://<servername>/axis-cgi/jpg/image.cgi
[?<parameter>=<value>[&<parameter>=<value>...]]

<parameter>=<value> | Values | Description
resolution=<int>x<int> | <width>1,<height>1 | Specify the resolution as <width> times <height> number of pixels of the returned image.
camera=<int> | 1, ... 1 | Applies only to video servers with more than one video input. Selects the source camera.
compression=<int> | 0 - 100 1 | Adjusts the compression level of the image. Higher values correspond to higher compression, i.e. lower quality and smaller image size. Note: This value is internally mapped and is therefore product-dependent.
colorlevel=<int> | 0 - 100 1 | Sets level of color or grayscale. 0 = grayscale, 100 = full color. Note: This value is internally mapped and is therefore product-dependent.
clock=<int> | 0, 1 | Shows/hides the time stamp. 0 = hide, 1 = show
date=<int> | 0, 1 | Shows/hides the date. 0 = hide, 1 = show
quad=<int> | 0, 1 1 | Generate a quad image. 0 = normal, 1 = quad
text=<int> | 0, 1 | Shows/hides the text. 0 = hide, 1 = show
rotation=<int> | 0, 90, 180, 270 1 | Rotates the image clockwise.
showlength=<int> | 0, 1 | Content-Length is added to the HTTP-header and in the boundary section, between the images. 0 = hidden, 1 = shown.
timeout=<int> | > 01 | Set the timeout value (seconds) for the session. If a connection is blocked for this amount of time, the session will be closed by the server.

1 Product-dependent. Check the product specification.

Example: request a JPEG image from camera 1 with a resolution of 320x240 and compression of 25
http://myserver/axis-cgi/jpg/image.cgi?resolution=320x240&camera=1&compression=25

5.2.3 JPEG image response

When a JPEG image is requested, the server either returns the specified JPEG file, or an error.

An optional field "Content-Length" header entry specifying the image size in bytes <image size> may also be included if the camera or video server is configured to include it. The other optional field "Content-Auth" is followed by authorization-specific data <authorization information>, e.g., the encryption method being used.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: image/jpeg\r\n
[ Content-Length: <image size>\r\n ]
[ Content-Auth: <authorization information>\r\n ]
\r\n
<JPEG image data>\r\n

Example: requested JPEG image
HTTP/1.0 200 OK\r\n
Content-Type: image/jpeg\r\n
Content-Length: 15656\r\n
\r\n
<JPEG image data>\r\n

5.2.4 JPEG buffer request

Request for controlling image buffers via HTTP.

Method: GET

Syntax:
http://<servername>/axis-cgi/buffer/command.cgi?<parameter>=<value>
[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
do=<string> | start, stop, get, reset | "start" will create a new image buffer. "stop" will make the image buffer store post alarm images. Buffer will stop after all post alarm images have been taken. "get" is used to fetch an image from the image buffer. "reset" will remove the image buffer, including any buffered images.
buffername=<string> | <any string> | Name used for identifying the buffer.
uri=<string> | <any string> | Corresponding image URI to be used by the image buffer. Note: Must be URI-encoded. The URI should also begin with "ftp://", otherwise an HTTP header is added to the image.
prealarm=<int> | 0, ... | Number of images to be stored in the pre alarm buffer.
postalarm=<int> | 0, ... | Number of images to be saved after an alarm occurs.
predelay=<int> | <milliseconds> | The preferred time between the pre alarm images in milliseconds. Default is one second, 1000 milliseconds.
postdelay=<int> | <milliseconds> | The preferred time between the post alarm images in milliseconds. Default value is equal to the value of predelay. I.e. 1000 milliseconds if not specified, and for example 3000 milliseconds, if predelay is set to that.
index=<int> | <image number> | The index of image in buffer.

Example 1: Create an image buffer, named DOOR1, with 10 pre alarm images and 15 post alarm images.
http://myserver/axis-cgi/buffer/command.cgi?do=start&buffername=DOOR1
&prealarm=10&postalarm=15&&uri=ftp://jpg/1/image.jpg

Example 2: Stop a buffer.
http://myserver/axis-cgi/buffer/command.cgi?do=stop&buffername=DOOR1

Example 3: Get images from a buffer.
http://myserver/axis-cgi/buffer/command.cgi?do=get&buffername=DOOR1&index=1

5.2.5 MJPG video request

Request Multipart JPEG image.

Method: GET

Syntax:
http://<servername>/mjpg[/<camera>]/<name>.mjpg

with the following parameters
Parameter | Values | Description
<camera> | 1, ... 1 | Select input source. Applies only to servers with more than one input source. Default: default camera
<name> | video, quad1, halfsize2, fullsize2, hugesize2 | "video" returns a multipart image stream with the default resolution and compression, as defined in the system configuration. The <camera> option is not allowed in quad request.

1 Product-dependent. Check the product specification.
2 Obsolete.

Example: request JPEG image stream from the 2nd camera with default resolution and compression
http://myserver/mjpg/2/video.mjpg

5.2.6 MJPG video CGI request

Request a Multipart-JPEG image stream (video) with specified properties.

Method: GET

Syntax:
http://<servername>/axis-cgi/mjpg/video.cgi
[?<parameter>=<value>[&<parameter>=<value>...]]

with the following parameters and values
<parameter>=<value> | Values | Description
resolution=<int>x<int> | <width>1,<height>1 | Specify the resolution as <width> times <height> number of pixels of the returned image.
camera=<int> | 1, ... 1 | Applies only to video servers with more than one video input. Selects the source camera. If omitted, the default camera is used.
compression=<int> | 0 - 100 1 | Adjusts the compression level of the image. Higher values correspond to higher compression, i.e. lower quality and smaller image size. Note: This value is internally mapped and is therefore product-dependent.
colorlevel=<int> | 0 - 100 1 | Sets level of color or grayscale. 0 = grayscale, 100 = full color. Note: This value is internally mapped and is therefore product-dependent.
clock=<int> | 0, 1 | Shows/hides the time stamp. 0 = hide, 1 = show
date=<int> | 0, 1 | Shows/hides the date. 0 = hide, 1 = show
quad=<int> | 0, 1 1 | Generate a quad image. 0 = normal, 1 = quad
text=<int> | 0, 1 | Shows/hides the text. 0 = hide, 1 = show
rotation=<int> | 0, 90, 180, 270 1 | Rotates the image clockwise.
showlength=<int> | 0, 1 | Content-Length is added to the HTTP-header and in the boundary section, between the images. 0 = hidden, 1 = shown.
duration=<int> | 0, ... | Specifies for how many seconds the video will be generated and pushed to the client.
nbrofframes=<int> | 1, ... | Specifies how many frames the server will generate and push.
req_fps|des_fps=<int> | 1, ... | Using either req_fps or des_fps (these cannot be used at the same time) it is possible to specify the frame rate from the server. req_fps = required FPS des_fps = desired FPS Required FPS has higher priority than desired FPS if these are used in two different requests simultaneously. Use req_fps for streams with high priority and des_fps for less important streams.
deltatime=<int> | 0, 1 | Timediff, specifying the time between the images in ms, is added to the boundary section between the images. 0 = hidden, 1 = shown.
timeout=<int> | > 01 | Set the timeout value (seconds) of the session. If a connection is blocked for this length of time, the session will be closed by the server.

1 Product-dependent. Check the product specification.

Example: a Multipart JPEG image stream from camera 1 with a resolution of 320x240 and compression of 25
http://myserver/axis-cgi/mjpg/video.cgi?resolution=320x240&camera=1
&compression=25

Example: a Multipart JPEG image stream from camera 1 with a required frame rate of 5
http://myserver/axis-cgi/mjpg/video.cgi?req_fps=5

5.2.7 MJPG video response

When MJPG video is requested, the server returns a continuous flow of JPEG files. The content type is "multipart/x-mixed-replace" and each image ends with a boundary string <boundary>. The returned image and HTTP data is equal to the request for a single JPEG image.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=<boundary>\r\n
\r\n
--<boundary>\r\n
<image>
where the proposed <boundary> is
myboundary
and the returned <image> field is
Content-Type: image/jpeg\r\n
[ Content-Length: <image size>\r\n ]
[ Content-Auth: <authorization information>\r\n ]
\r\n
<JPEG image data>\r\n
--<boundary>\r\n
<image>

Example: requested Multipart JPEG image
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=myboundary\r\n
\r\n
--myboundary\r\n
Content-Type: image/jpeg\r\n
Content-Length: 15656\r\n
\r\n
<JPEG image data>\r\n
--myboundary\r\n
Content-Type: image/jpeg\r\n
Content-Length: 14978\r\n
\r\n
<JPEG image data>\r\n
--myboundary\r\n
Content-Type: image/jpeg\r\n
Content-Length: 15136\r\n
\r\n
<JPEG image data>\r\n
--myboundary\r\n
 .
 .
 .

5.3 MPEG-2

The requests specified in the MPEG-2 section are supported by those products that use MPEG-2 encoding.

5.3.1 MPEG-2 video request

Requests an MPEG-2 video stream with specified properties.

Method: GET

Syntax:
http://<servername>/axis-cgi/mpeg2/video.cgi[?<parameter>=<value>
[&<parameter>=<value> ...]]

with the following parameters and values
<parameter>=<value> | Values | Description
duration=<int> | 0, ... | Specifies for how many seconds the video shall be generated and pushed to the client. If the duration parameter is omitted, an infinite video stream will be provided to the client.
camera=<int> | 1, ... 1 | Searched recording should match this camera id.
maxlag=<int> | 500,... 1 | A number specifying at which lag (in ms) the server should eliminate the lag by cutting the stream. A lag could occur at the client due to clock differences between the client computer and the server. Note: This will be the maximum lag. The real lag may be lower than the specified value. Values less than 500 will be interpreted as 500. If the maxlag parameter is left out, the maximum lag will be determined by the available space in the server.

1 Product-dependent. Check the product specification.

5.3.2 MPEG-2 video response

When MPEG-2 video is requested, the server either returns the specified video stream, or an error message.

A field "X-Prebuffer-Length" is included in the HTTP header when responding to an MPEG-2 buffer request. This entry specifies the length (in seconds) of the pre-buffer video that is included in the video stream response. This length depends on what is specified in the request, and on a maximum value set by the server. If the requested length is greater than or equal to the maximum value set by the server, the returned pre-buffer length will be equal to the maximum value. If the requested length is shorter than the maximum value, the returned length will be equal to the requested length.

HTTP/1.0 200 OK \r\n
Content-type: video/mpeg\r\n
[X-Prebuffer-Length: <floating number in seconds> \r\n]
\r\n
<MPEG stream>\r\n

Example:
HTTP/1.0 200 OK\r\n

Content-Type: video/mpeg\r\n

\r\n

<MPEG stream>\r\n

5.3.3 MPEG-2 buffer request

Request for pre-buffered MPEG-2 video.

Method: GET

Syntax:
http://<servername>/axis-cgi/mpeg2/buffer.cgi?
[?<parameter>=<value>[&<parameter>=<value>...]]

with the following parameters and values
<parameter>=<value> | Values | Description
prebuffer=<int> | 0, ... | Number of seconds of video, buffered before the request, to be provided to the client.
duration=<int> | 0, ... | Specifies for how many seconds the video will be generated and pushed to the client. If the duration parameter is omitted, an infinite video stream will be provided to the client.

5.3.4 MPEG-2 multicast info request

The requests specified in this section can be used with MPEG-2 products that support multicasting and which have this support enabled.

Method: GET

Syntax:
http://<servername>/view/sdp/guide.sdp
http://<servername>/view/sdp/guide.axsdp
http://<servername>/view/sdp/guide.sdpx

5.3.5 MPEG-2 multicast info response

The response to an MPEG-2 multicast info request is a text file describing the characteristics of the stream elements and where they can be retrieved.

The description text is in SDP format and follows RFC 2327.

All requests return the same description file. The responses from guide.sdp and guide.axsdp have "application/sdp" as content type, but using guide.sdp is preferred practice. The response from guide.sdpx has "text/plain" as content type.

Return: A successful guide.sdp or guide.axsdp request
HTTP/1.0 200 OK\r\n
Date: <date>
Server: <web server>
Content-Length: <length>
Last-Modified: <date>
Content-Type: application/sdp\r\n
\r\n
\r\n
<text according to RFC 2327>

Return: A successful guide.sdpx request
HTTP/1.0 200 OK\r\n
Date: <date>
Server: <web server>
Content-Length: <length>
Last-Modified: <date>
Content-Type: text/plain\r\n
\r\n
\r\n
<text according to RFC 2327>

Example: Requested MPEG-2 media stream session info with guide.sdp from an MPEG-2 video product
HTTP/1.0 200 OK
Date: Thu, 28 Nov 2002 13:16:13 GMT
Server: Boa/0.92o
Content-Length: 777
Last-Modified: Thu, 28 Nov 2002 13:12:24 GMT
Content-Type: application/sdp

v=0
o=root 1038489142 1038489142 IN IP4 10.13.9.123
s=AXIS 250S MPEG-2 Video Server RTP Stream from 10.13.9.123
b=AS:4000
t=0 0
a=type:broadcast
a=tool:AXIS 250S MPEG-2 Video Server 3.10
m=video 5000 RTP/AVP 32
c=IN IP4 239.192.182.161/5
a=x-dimensions:720,576
a=framerate:25
a=x-iptv-svr:video 10.13.9.123 file 1 loop
m=audio 5000 RTP/AVP 14
c=IN IP4 239.192.182.94/5
a=x-bitrate:128
a=x-samplerate:44100
a=x-iptv-svr:audio 10.13.9.123 file 1 loop
v=0
o=root 1038489143 1038489143 IN IP4 10.13.9.123
s=AXIS 250S MPEG-2 Video Server RTP Stream No Audio from 10.13.9.123
b=AS:4000
t=0 0
a=type:broadcast
a=tool:AXIS 250S MPEG-2 Video Server 3.10
m=video 5000 RTP/AVP 32
c=IN IP4 239.192.182.161/5
a=x-dimensions:720,576
a=framerate:25
a=x-iptv-svr:video 10.13.9.123 file 1 loop

5.4 PTZ

The requests specified in the PTZ section are supported by those video products that have support for Pan/Tilt/Zoom devices.

5.4.1 PTZ control

To control the Pan, Tilt, and Zoom behavior of a PTZ unit, the following PTZ control URL is used.

Important: The PTZ control is device-dependent. Please check the specification of the Axis PTZ driver you intend using, for information about supported parameters and actual parameter values. The following table is only an overview.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/com/ptz.cgi?<parameter>=<value>[&
<parameter>=<value>... ]

with the following parameters and values
<parameter>=<value> | Values | Description
camera=<int> | 1, ... 1 | Applies only to video servers with more than one video input. Selects the source camera. If omitted, the default camera is used.
whoami=<string> | <any value> | Returns the name of the system-configured device driver.
center=<int>,<int> extrem3=<int>,<int> | <x>,<y> | Absolute: Used to send the coordinates for the point in the image where the user clicked. This information is then used by the server to calculate the pan/tilt move required to (approximately) center the clicked point. Relative: Used to send the coordinates for the point in the image where the user clicked. This information is then used by the server to calculate the direction and number of degrees to move. The number of degrees increases with the distance from the center of the image to the point clicked.
imagewidth=<int> | 1, ...1 | Required in conjunction with center if the image width is displayed different from the default size of the image, which is product-specific.
imageheight=<int> | 1, ...1 | Needed in conjunction with center if the image height is different from the default size, which is product-specific.
move=<string> | home, up, down, left, right, upleft, upright, downleft, downright | Absolute: Moves the device 5 degrees in the specified direction. Relative: Moves the device approx. 50-90 degrees2 in the specified direction.
pan=<float> | -180.0 - 180.0 | Absolute: Pans the device relative to the (0,0) position. Relative: N/A
tilt=<float> | -180.0 - 180.0 | Absolute: Tilts the device relative to the (0,0) position. Relative: n/a
zoom=<int> | 1 - 9999 | Absolute: Zooms the device n steps. Relative: n/a
focus=<int> | 1 - 9999 | Absolute: Move Focus n steps. Relative: n/a
iris=<int> | 1 - 9999 | Absolute: Move iris to n steps. Relative: n/a
rpan=<float> | -360.0 - 360.0 | Absolute: Pans the device n degrees relative to the current position. Relative: Pans the device approx. n degrees relative to the current position.
rtilt=<float> | -360.0 - 360.0 | Absolute: Tilts the device n degrees relative to the current position. Relative: Tilts the device approx. n degrees relative to the current position.
rzoom=<int> | -9999 - 9999 | Absolute: Zooms the device n steps relative to the current position. Positive values mean zoom in, negative values mean zoom out. Relative: Zooms the device approx. n steps relative to the current position. Positive values mean zoom in, negative values mean zoom out.
rfocus=<int> | -9999 - 9999 | Absolute: Move Focus n steps relative to the current position. Positive values mean focus near, negative values mean focus far. Relative: Move Focus approx. n steps relative to the current position. Positive values mean focus near, negative values mean focus far.
riris=<int> | -9999 - 9999 | Absolute: Move iris n steps relative to the current position. Positive values mean open iris, negative values mean close iris. Relative: Move iris approx. n steps relative to the current position. Positive values mean open iris, negative values mean close iris.
zoomrel3=<string> | tele, wide, telemax, telemin | Adjusts the zoom gradually.
focusrel3=<string> | far, farmore, near, nearmore | Adjusts the focus gradually.
irisrel3=<string> | open, close, openmore, closemore | Adjusts the iris gradually.
autofocus=<string> | on, off | Autofocus On/Off.
autoiris=<string> | on, off | Autoiris On/Off.
continuouspantiltmove= <int>,<int> | -100 - 100, -100 - 100 | Continuous pan/tilt motion. Positive values mean right (pan) and up (tilt), negative values mean left (pan) and down (tilt). "0,0" means stop. Values as <pan speed>,<tilt speed>
continuouszoommove= <int> | -100 - 100 | Continuous zoom motion. Positive values mean zoom in and negative values mean zoom out. "0" means stop.
continuousfocusmove= <int> | -100 - 100 | Continuous focus motion. Positive values mean focus near and negative values mean focus far. "0" means stop.
continuousirismove= <int> | -100 - 100 | Continuous iris motion. Positive values mean iris open and negative values mean iris close. "0" means stop.
auxiliary=<string> | <function name> | Activates/deactivates auxiliary functions of the device where <function name> is the name of the device-specific function.
setserverpresetname= <string> | <preset name>4 | Associates the current position to <preset name> as a preset position in the server.
setserverpresetno= <int> | 1, ... | Saves the current position as a preset position number in the server.
removeserverpresetname= <string> | <preset name>4 | Removes the specified preset position associated with <preset name>.
removeserverpresetno= <int> | 1, ... | Removes the specified preset position.
gotoserverpresetname= <string> | <preset name>4 | Move to the position associated with the <preset name>.
gotoserverpresetno= <int> | 1, ... | Move to the position associated with the specified preset position number.
setdevicepreset= <int> | <preset pos> | Bypasses the presetpos interface and tells the device to save its current position as preset position <preset pos> directly in the device, where <preset pos> is a device-specific preset position number.
gotodevicepreset= <int> | <preset pos> | Bypasses the presetpos interface and tells the device to go directly to the preset position number <preset pos> stored in the device, where the <preset pos> is a device-specific preset position number.
barcoord=<int>,<int> | <x>,<y> | Used in conjunction with panbar, tiltbar, zoombar, focusbar or irisbar, to send coordinates to the server.
panbar=<int>,<string> | <length>, <alignment> | <length> is the length of the bar in pixels, which is needed in order to calculate the center of the bar. <alignment> is one of the strings "horisontal" or "vertical". The alignment string determines if the x (horizontal) or the y (vertical) coordinate from barcoord is used, i.e. if the bar is horizontal; use "horizontal" and if the bar is vertical; use "vertical" as alignment.
tiltbar=<int>,<string> | <length>, <alignment> | <length> is the length of the bar in pixels, which is needed in order to calculate the center of the bar. <alignment> is one of the strings "horisontal" or "vertical". The alignment string determines if the x (horizontal) or the y (vertical) coordinate from barcoord is used, i.e. if the bar is horizontal; use "horizontal" and if the bar is vertical; use "vertical" as alignment.
zoombar=<int>,<string> | <length>, <alignment> | <length> is the length of the bar in pixels, which is needed in order to calculate the center of the bar. <alignment> is one of the strings "horisontal" or "vertical". The alignment string determines if the x (horizontal) or the y (vertical) coordinate from barcoord is used, i.e. if the bar is horizontal; use "horizontal" and if the bar is vertical; use "vertical" as alignment.
focusbar=<int>,<string> | <length>, <alignment> | <length> is the length of the bar in pixels, which is needed in order to calculate the center of the bar. <alignment> is one of the strings "horisontal" or "vertical". The alignment string determines if the x (horizontal) or the y (vertical) coordinate from barcoord is used, i.e. if the bar is horizontal; use "horizontal" and if the bar is vertical; use "vertical" as alignment.
irisbar=<int>,<string> | <length>, <alignment> | <length> is the length of the bar in pixels, which is needed in order to calculate the center of the bar. <alignment> is one of the strings "horisontal" or "vertical". The alignment string determines if the x (horizontal) or the y (vertical) coordinate from barcoord is used, i.e. if the bar is horizontal; use "horizontal" and if the bar is vertical; use "vertical" as alignment.
speed=<int> | 1 - 100 | Sets the head speed of the device connected to the specified camera.
query=<string> | speed, position, presetposcam, presetposall | Returns the current parameter values. See 5.1.2 for more information about server responses.
info=<int> | 1 | Returns a description of available PTZ commands. No PTZ control is performed.

1 Product-dependent. Check the product specification.
2 Actual values are device driver-specific.
3 Obsolete.
4 <preset name> is a string with a maximum of 31 characters, ~ is not allowed.

Example: Request information about which PTZ commands are available for camera 3.
http://myserver/axis-cgi/com/ptz.cgi?info=1&camera=3

5.5 Audio

The requests specified in the Audio section are supported by those video products that have audio capability.

5.5.1 Multipart audio data request

Request a Multipart Audio stream.

Method: GET

Syntax:
http://<servername>/axis-cgi/audio/receive.cgi

There are no valid parameters and values

Example: a Multipart Audio stream
http://myserver/axis-cgi/audio/receive.cgi

5.5.2 Multipart audio data response

When an audio stream is requested/transmitted, the server returns/receives a continuous flow of audio packets. The content type is "multipart/x-mixed-replace" and each audio packet ends with a boundary string <boundary>. The MIME type used for the audio transmitted is audio/32KADPCM. The message body contains a block of binary data.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=<boundary>\r\n
\r\n
--<boundary>\r\n
<audio>
where the proposed <boundary> is
myboundary
and the <audio> field is
Content-Type: audio/32KADPCM\r\n
\r\n
<Audio data>\r\n
--<boundary>\r\n
<audio>

Example: Multipart Audio data
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=myboundary\r\n
\r\n
--myboundary\r\n
Content-Type: audio/32KADPCM\r\n
\r\n
<Audio data>\r\n
--myboundary\r\n
Content-Type: audio/32KADPCM\r\n
\r\n
<Audio data>\r\n
--myboundary\r\n
Content-Type: audio/32KADPCM\r\n
\r\n
<Audio data>\r\n
--myboundary\r\n
 .
 .
 .

5.5.3 Multipart audio data transmit

Transmits a Multipart Audio data stream.

Method: POST

Syntax:
http://<servername>/axis-cgi/audio/transmit.cgi

There are no valid parameters and values.

Example: transmit a Multipart Audio stream
http://myserver/axis-cgi/audio/transmit.cgi

5.5.4 Get audio configuration parameters

Get information about audio configuration parameters.

Method: GET

Syntax:
http://<servername>/axis-cgi/audio/getparam.cgi

Return:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
<audio parameters>
and <audio parameters> is
root.Audiod.duplexMode=<duplexMode>\n
root.Audiod.maxNumberOfClients=<maxNumberOfClients>\n
root.Audiod.forwardOnPost=<forwardOnPost>\n
root.Audiod.buttonMode=<buttonMode>\n
root.Audiod.acousticEcho=<acousticEcho>\n
root.Audiod.lineEcho=<lineEcho>\n
root.Audiod.slopeFilter=<slopeFilter>\n
root.Audiod.noisecancelIOgain=<noicecancelIOgain>\n
root.Audiod.noisecancelAttenuation=<noisecancelAttenuation>\n
root.Audiod.audioEncoding=<audioEncoding>\n
root.Audiod.httpMessageType=<httpMessageType>\n
root.Audiod.microphoneMode=<microphoneMode>\n
root.Audiod.speakerMode=<speakerMode>\n
root.Audiod.forceMicrophoneMode=<forceMicrophoneMode>\n
root.Audiod.forceSpeakerMode=<forceSpeakerMode>\n
root.Audiod.bufferLevel=<bufferLevel>\n
root.Audiod.forceBufferLevel=<forceBufferLevel>\n
\n

Example:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
root.Audiod.duplexMode=<duplexMode>\n
root.Audiod.maxNumberOfClients=<maxNumberOfClients>\n
root.Audiod.forwardOnPost=<forwardOnPost>\n
root.Audiod.buttonMode=<buttonMode>\n
root.Audiod.acousticEcho=<acousticEcho>\n
root.Audiod.lineEcho=<lineEcho>\n
root.Audiod.slopeFilter=<slopeFilter>\n
root.Audiod.noisecancelIOgain=<noicecancelIOgain>\n
root.Audiod.noisecancelAttenuation=<noisecancelAttenuation>\n
root.Audiod.audioEncoding=<audioEncoding>\n
root.Audiod.httpMessageType=<httpMessageType>\n
root.Audiod.microphoneMode=<microphoneMode>\n
root.Audiod.speakerMode=<speakerMode>\n
root.Audiod.forceMicrophoneMode=<forceMicrophoneMode>\n
root.Audiod.forceSpeakerMode=<forceSpeakerMode>\n
root.Audiod.bufferLevel=<bufferLevel>\n
root.Audiod.forceBufferLevel=<forceBufferLevel>\n
\n

5.6 Motion Detection

The requests specified in the Motion Detection section are supported by those video products that have built-in motion detection.

5.6.1 Set motion detection parameters

Adding new motion detection window, removing or updating any existing window.

The "key" entry is a unique window identity communicated in all actions concerning the window, i.e., when adding, updating or removing it, or when reading information about it. The "name" entry is a window identification useful when e.g. communicating with a user in an application or an alarm. The three parameters "size", "sensitivity" and "history" are as generic as possible, i.e. they do not depend on the actual motion detection algorithm.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/admin/mdsetparam.cgi?<parameter>=<value>[&
<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
action=<string> | add, remove, update | "add" creates a new motion detection window and requires both the "key" and "name" entries to be defined. "update" make changes to an existing window and only requires the "key" entry to be defined. "remove" deletes an existing window and only requires the "key" entry to be defined. Any other additional entry is ignored. Default: no default value provided.
key=<int> | 0, ...1 | A unique identity to the motion detection window. Default: no default value provided.
name=<string> | <any string> | A user's window identification, e.g., "Door" or "Window". Default: no default value provided.
method=<char> | w | Motion detection method to use for this window. Default: w
left=<int> | 0 ... 9999 | The coordinate for the left boundary of the rectangular motion detection window. The full value range is related to the full image width and 0 is counted from the left hand side of the image. Default: 0
right=<int> | 0 ... 9999 | The coordinate for the right boundary of the rectangular motion detection window. The full value range is related to the full image width and 0 is counted from the left hand side of the image. Default: 9999
top=<int> | 0 ... 9999 | The coordinate for the upper boundary of the rectangular motion detection window. The full value range is related to the full image height and 0 is counted from the upper side of the image. Default: 0
bottom=<int> | 0 ... 9999 | The coordinate for the bottom boundary of the rectangular motion detection window. The full value range is related to the full image height and 0 is counted from the upper side of the image. Default: 9999
sensitivity=<int> | 0 ... 100 | This tunes the "object difference from the background"-sensitivity, i.e. difference in terms of color and/or structure. A low value detects even very small changes and can e.g. trigger on image noise if set too low. A very high value on the other hand, requires a very dramatic change, with e.g. a dark object appearing in an almost white scene (or vice versa). Default: method specific
history=<int> | 0 ... 100 | This adjusts the motion detection to be more or less sensitive for very fast motion. At very low values motion is detected only when a scene has changed, but rapidly adopts to this changed scene as the new normal scene. Higher values are more conservative and will detect motion in a greater number of pictures before considering this as being a normal object in the scene. Default: method specific
size=<int> | 0 ... 100 | Defines as a percentage the size of the object that will result in motion detection. At a low value, even very small changes will trigger detection, whilst a very large value requires a very large object to trigger detection. Default: method specific

Return: all parameters are set correct
HTTP/1.0 204 No Content\r\n

Return: one or more critical errors occurred
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Error: <error description>\r\n

Example: Add a new motion detection window
http://myserver/axis-cgi/admin/mdsetparam.cgi?action=add&key=2
&name=Entrance&top=500&bottom=7000&left=5000&right=8500

Example: Update parameters for an existing motion detection window
http://myserver/axis-cgi/admin/mdsetparam.cgi?action=update&key=2
&top=1500&bottom=8000

Example: Remove a motion detection window
http://myserver/axis-cgi/admin/mdsetparam.cgi?action=remove&key=2

5.6.2 Get motion detection parameters

Read information about current defined motion detection windows.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/motion/mdgetparam.cgi

Return:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
<window data>
and <window data> is
key=<key>\r\n
name=<name>\r\n
method=<method>\r\n
left=<left>\r\n
top=<top>\r\n
right=<right>\r\n
bottom=<bottom>\r\n
sensitivity=<sensitivity>\r\n
history=<history>\r\n
size=<size>\r\n
\r\n
[ <window data> ]

Example: two motion detection windows "Backdoor" and "Window"
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
key=0\r\n
name=Backdoor\r\n
method=W\r\n
left=200\r\n
top=800\r\n
right=3600\r\n
bottom=9400\r\n
sensitivity=90\r\n
history=85\r\n
size=10\r\n
\r\n
key=1\r\n
name=Window\r\n
method=W\r\n
left=7000\r\n
top=1000\r\n
right=9500\r\n
bottom=4000\r\n
sensitivity=95\r\n
history=85\r\n
size=25\r\n
\r\n

5.6.3 Get motion detection level

To read the current motion detection levels of all windows, the URL stated below is used.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/motion/motiondetect.cgi

Return:
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=<boundary>\r\n
\r\n
--<boundary>\r\n
<motion levels>
where the proposed boundary <boundary> is
axismdb
and the <motion levels> part is
Content-Type: text/plain\r\n
\r\n
<motion level for window n>
--<boundary>\r\n
and <motion level for window n>" is
key=<key n>;level=<motion level for n>;
threshold=<threshold level for n>;\r\n
[ <motion level for window n+1> ]

Example: two motion detection windows with key "0" and key "1"
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=axismdb\r\n
\r\n
--axismdb\r\n
Content-Type: text/plain\r\n
\r\n
key=0;level=28;threshold=45;\r\n
key=1;level=43;threshold=25;\r\n
--axismdb\r\n
Content-Type: text/plain\r\n
\r\n
key=0;level=54;threshold=45;\r\n
key=1;level=38;threshold=25;\r\n
--axismdb\r\n
Content-Type: text/plain\r\n
\r\n
key=0;level=49;threshold=45;\r\n
key=1;level=19;threshold=25;\r\n
--axismdb\r\n
 .
 .
 .

5.7 Recording

The requests specified in the Recording section are supported by those products that provide storage of recordings.

5.7.1 List recordings

Choose to list all recordings, one specific recording, or all recordings matching a criteria.

Method: GET

Syntax:
http://<servername>/axis-cgi/view/reclist.cgi[?<parameter>=<value>
[&<parameter>=<value> ...]]

with the following parameters and values
<parameter>=<value> | Values | Description
recordingid=<int> | > 0 | Recording id, unique number for each recording. Only this recording will be listed.
camera=<int> | 1, ... 1 | List only recordings that match this camera id.
event=<int> | > 0 | List only recordings that match this event id. Id of an event can be found in the event parameters.
time=<int> | Seconds since 1970: 1/100 seconds | List only recordings made during this time.
timespan=<int> | > 0 | List only recordings made during the time span from "time" until "time" + "timespan". Requires: parameter "time"
info=<string> | count | Begin the server response with a count of the number of listed recordings.

1 Product-dependent. Check the product specification.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
<info data>1
<recording data>
and <info data> is
numberofrecordings=<count>\r\n
\r\n

and <recording data> is
recordingid=<recordingid>\r\n
cameraid=<cameraid>\r\n
cameraname=<name>\r\n
eventid=<eventid>\r\n
eventpath=<eventpath>\r\n
eventname=<name>\r\n
prebufferstartframe=<prebufferstartframe>\r\n
prebufferstarttime=<prebufferstarttime>\r\n
eventstartframe=<eventstartframe>\r\n
eventstarttime=<eventstarttime>\r\n
eventstopframe=<eventstopframe>\r\n
eventstoptime=<eventstoptime>\r\n
postbufferstopframe=<postbufferstopframe>\r\n
postbufferstoptime=<postbufferstoptime>\r\n
priority=<priority>\r\n
ongoing=<ongoing>\r\n
secured=<secured>\r\n
startquality=<startquality>\r\n
stopquality=<stopquality>\r\n
\r\n
[ <recording data> ]

1 Only if parameter "info=count" is used.

with the following parameters and values
<parameter>=<value> | Values | Description
recordingid=<int> | > 1 | Recording id, unique number for every recording.
camera=<int> | 1, ... 1 | ID of camera recorded from.
cameraname=<string> | user specified | Name of the camera recorded from.
eventid=<int> | user specified | Event ID
eventpath=<string> | parameter path | Parameter path to event parameters. Example: root.Event.E7
eventname=<string> | user specified | Name of recorded event.
prebufferstartframe=<int>:<int> | frame id | Startframe is the first image/frame of the recording. If the beginning is deleted by reduction the startframe is moved to the new start. Example: 785421:57
prebufferstarttime=<int>:<int> | Seconds since 1970: 1/100 seconds | Time of the startframe. Example: 983453412:10
eventstartframe=<int>:<int> | frame id | The image/frame when the event was trigged. Example: 785421:57
eventstarttime=<int>:<int> | Seconds since 1970: 1/100 seconds | Time of the eventstartframe. Example: 983453412:10
eventstopframe=<int>:<int> | frame id | The image/frame when the event ended. Example: 785421:57
eventstoptime=<int>:<int> | Seconds since 1970: 1/100 seconds | Time of the eventstopframe. Example: 983453412:10
postbufferstopframe=<int>:<int> | frame id | The last image/frame of recording. Example: 785421:57
postbufferstoptime=<int>:<int> | Seconds since 1970: 1/100 seconds | Time of the postbufferstopframe. Example: 983453412:10
priority=<int> | 0 - 100 1 | Priority of the event. 100 = highest priority. Note: This value is internally mapped and is therefore product-dependent.
ongoing=<string> | yes, no | Recording in progress or not.
secured=<string> | yes, no | A secured (preserved) recording will not be reduced or deleted. See Preserve and release recordings
startquality=<int> | 0 - 100 1 | Quality of the beginning of the recording, due to reduction. 100 = highest quality. Note: This value is internally mapped and is therefore product-dependent.
stopquality=<int> | 0 - 100 1 | Quality of the beginning of the recording, due to reduction. 100 = highest quality. Note: This value is internally mapped and is therefore product-dependent.

1 Product-dependent. Check the product specification.

Example 1: List recording id 12:

Request:
http://myserver/axis-cgi/view/reclist.cgi?recordingid=12

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
recordingid=12\r\n
cameraid=1\r\n
cameraname=backdoor\r\n
eventid=2\r\n
eventpath=root.Event.E2\r\n
eventname=alarm\r\n
prebufferstartframe=456213:00\r\n
prebufferstarttime=98992000:00\r\n
eventstartframe=456345:00\r\n
eventstarttime=98992501:00\r\n
eventstopframe=456287:34\r\n
eventstoptime=98992500:34\r\n
postbufferstopframe=456288:34\r\n
postbufferstoptime=98992501:34\r\n
priority=2\r\n
ongoing=no\r\n
secured=no\r\n
startquality=3\r\n
stopquality=4\r\n
\r\n

Example 2: List recordings made during timespan Jul 4 2002 12:00:00 - 13:00:00 CET with count info:

Request:
http://myserver/axis-cgi/view/reclist.cgi?time
=1025776800&timespan=3600&info=count

Response: (edited)
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
numberofrecordings=3\r\n
\r\n
recordingid=245\r\n
...
eventstarttime=1025754065:43\r\n
...
eventstoptime=1025779423:32\r\n
...
\r\n
recordingid=356\r\n
...
eventstarttime=1025776780:32\r\n
...
eventstoptime=1025776850:02\r\n
...
\r\n
recordingid=357\r\n
...
eventstarttime=1025778305:00\r\n
...
eventstoptime=1025778401:34\r\n
...
\r\n

Example 3: Search and list recordings of event 6 from camera 1:
http://myserver/axis-cgi/view/reclist.cgi?camera=1&event=6

Example 4: List all available recordings with count info:
http://myserver/axis-cgi/view/reclist.cgi?info=count

5.7.2 Play recordings

With this interface, recorded images can be replayed from the server, either single JPG images or MJPG video streams.

Method: GET

Syntax:
http://<servername>/axis-cgi/view/player.cgi[?<parameter>=<value>
[&<parameter>=<value> ...]]

Parameters and values listed below.

For greater efficiency when playing back and forward, stepping etc., the player uses recording id and session id. Recording id is received by list recording.
Use the recording id in the first player call, and then the session id returned in every player response.

Example:
AXIS Server -> | <- Client
List all recordings
http://myserver/axis-cgi/view/reclist.cgi |
 | Server response containing info about all recordings
Play recording 24
http://myserver/axis-cgi/view/player.cgi?recordingid=24 |
 | Server response containing sessionid=3 and images.
Play backward
http://myserver/axis-cgi/view/player.cgi?sessionid=3&direction=backward |
 | Server response containing sessionid=3 and images.

with the following parameters and values
Parameter/Syntax | Values | Description
recordingid=<int> | > 0 1 | The id of the recording to play.
sessionid=<int> 0 if no session, else > 0 1 Id of this session. Returned in previous server response.
Used for faster database search.
camera | 1, ... 2 | Play from this camera.
info=<int> | 1 | Returns a description of this CGI-request. No image generated.
starttime=<int>:<int> Seconds since 1970: 1/100 seconds 3 Play only a part of the recording. Start at this time.

Example: 983453412:10

stoptime=<int>:<int> Seconds since 1970: 1/100 seconds 3 Play only a part of the recording. Stop at this time.

Example: 983453412:10

startframe=<int>:<int> frame id 3 Play only a part of the recording. Start at this frame.

Example: 785421:57

stopframe=<int>:<int> frame id3 Play only a part of the recording. Stop at this frame.

Example: 785421:57

time=<int>:<int> Seconds since 1970: 1/100 seconds 4 Get a single image closest to this time.

Example: 983453412:10

frame=<int>:<int> frame id 4 Get a single image closest to this frame id.

Example: 785421:57

direction=<string> forward, backward Play recording forwards or backwards.

Default: forward

step=<int>
MJPG video stream

> 0
MJPG video stream

Play only every n:th frame. Can be used to "fast forward" a recording.

Default: 1 (play every frame)

JPG single image

>= 0
JPG single image

Get the n:th frame in the given direction from the specified frame.

Default: 0 (get the specified frame)

session=<string> close Closes the session and frees server resources for a new session.
If a session is not closed it will eventually timeout and be automatically closed.

Requires: sessionid

timeout=<int> > 0 Set the timeout value (in seconds) of the player session.

The session will be automatically closed if

  • an open stream is blocked for this amount of time
  • the client has not made a new request in this amount of time after the last stream was closed.

    • Default: 150

keepalive=<string> yes, no Push search progress information in the stream prior to the first frame.

This is useful as user feedback and also prevents client software or connection from timing out if the recording lookup (when using start/stop time/frame) takes a long time.

Default: no

1 Request must contain one of these. See example below.
2 Product-dependent. Check the product specification.
3 Use either starttime/stoptime or startframe/stopframe. Do not combine time and frame formats in same request.
4 Use either time or frame to get a JPG single image.

If time is specified, the first subsection found that matches the time (within the specified recording, if such is specified) will be played. Since there can be several subsections that matches the same time (due to changes in server time) there is no way of knowing which was requested, hence the first match is always played.
Frame ID is used to directly identify a unique video frame from a specific camera. This is independent of different recordings and changes in server time. The scale of the Frame ID is linear to real time.

Example 1: Play recording 5
http://myserver/axis-cgi/view/player.cgi?recordingid=5

Example 2: Play part of recording backward - (sessionid=3 was returned in previous server response)
http://myserver/axis-cgi/view/player.cgi?sessionid=3&startframe=45347:00
&stopframe=47023:00&direction=backward&keepalive=yes

Example 3: Fast forward part of recording - (sessionid=3 was returned in previous server response)
http://myserver/axis-cgi/view/player.cgi?sessionid=3&startframe=45347:00
&stopframe=47023:00&step=4&keepalive=yes

Example 4: Get single JPG image of specific time - (sessionid=3 was returned in previous server response)
http://myserver/axis-cgi/view/player.cgi?sessionid=3&time=983433518:00&keepalive=yes

Example 5: Get next single JPG image from specified frame - (sessionid=3 was returned in previous server response)
http://myserver/axis-cgi/view/player.cgi?sessionid=3&frame=45692:14
&direction=forward&step=1&keepalive=yes

Example 6: Close session - (sessionid=3 was returned in previous server response)
http://myserver/axis-cgi/view/player.cgi?sessionid=3&session=close

Example 7: Play time interval - (The first found matching interval for the camera is played)
http://myserver/axis-cgi/view/player.cgi?camera=4&starttime=982813227:00
&stoptime=982813720:00&keepalive=yes

5.7.3 Recorded JPG/MJPG response

When recorded MJPG video is requested, the server returns a continuous flow of JPEG files. The content type is "multipart/x-mixed-replace" and each image is preceded of data about the image and ends with a boundary string <boundary>.

MJPG video stream response:
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=<boundary>\r\n
\r\n
--<boundary>\r\n
<progress>1
<image>
where the proposed <boundary> is
myboundary
and the <progress> field is
x-axis-dvr-search-progress-percent: <percent>\r\n
Content-Type: text/plain\r\n
\r\n
searchsourceframe=<frame id>\r\n
searchcurrentframe=<frame id>\r\n
searchdestinationframe=<frame id>\r\n
--<boundary>\r\n
<progress>
and the returned <image> field is
x-axis-dvr-session-id: <sessionid>\r\n
x-axis-dvr-frame-time: <time>\r\n
x-axis-dvr-frame-id: <frameid>\r\n
x-axis-dvr-frame-state: <state>\r\n
Content-Type: image/jpeg\r\n
Content-Length: <image size>\r\n
\r\n
<JPEG image data>\r\n
--<boundary>\r\n
<image>

1 Only if parameter "keepalive=yes" is used and the search for the start frame takes more than a few seconds. Progress fields are pushed with a few seconds interval.

JPG singe image response:
HTTP/1.0 200 OK\r\n
\r\n
x-axis-dvr-session-id: <sessionid>\r\n
x-axis-dvr-frame-time: <time>\r\n
x-axis-dvr-frame-id: <frameid>\r\n
x-axis-dvr-frame-state: <state>\r\n
Content-Type: image/jpeg\r\n
Content-Length: <image size>\r\n
\r\n
<JPEG image data>\r\n

Meta tag | Description
x-axis-dvr-search-progress-percent: <int> | Percent (0-100) of search completed.
x-axis-dvr-session-id: <int> | ID of the session.
x-axis-dvr-frame-time: <int>:<int> | Timestamp in string format epoch:hh.
x-axis-dvr-frame-id: <int>:<int> | Frame ID.
x-axis-dvr-frame-state: <int> | Active alarm inputs when this picture was taken, numeric representation of 4-bit field. Alarm inputs 1 - 4 are represented by values 1 (0001), 2 (0010), 4 (0100), 8 (1000). Example: State 5 represents inputs 1 and 3 active (1+4). State 15 represents all inputs active (1+2+4+8).

<parameter>=<value> | Values | Description
searchsourceframe=<int>:<int> | frame id | Frame that search started at. Example: 785421:57
searchcurrentframe=<int>:<int> | frame id | Frame that search is currently at. Example: 785421:57
searchdestinationframe=<int>:<int> | frame id | Frame that is search for. Example: 785421:57

Example: Response to request for part of recording starting at frame 563234:23 with keepalive set.
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=myboundary\r\n
\r\n
--myboundary\r\n
x-axis-dvr-search-progress-percent: 67\r\n
Content-Type: text/plain\r\n
\r\n
searchsourceframe=436799:00\r\n
searchcurrentframe=521510:66\r\n
searchdestinationframe=563234:23\r\n
--myboundary\r\n
x-axis-dvr-search-progress-percent: 100\r\n
Content-Type: text/plain\r\n
\r\n
searchsourceframe=436799:00\r\n
searchcurrentframe=563234:23\r\n
searchdestinationframe=563234:23\r\n
--myboundary\r\n
x-axis-dvr-session-id: 132\r\n
x-axis-dvr-frame-time: 1003445674:23\r\n
x-axis-dvr-frame-id: 563234:23\r\n
x-axis-dvr-frame-state: 3\r\n
Content-Type: image/jpeg\r\n
Content-Length: 15656\r\n
\r\n
<JPEG image data>\r\n
--myboundary\r\n
x-axis-dvr-session-id: 132\r\n
x-axis-dvr-frame-time: 1003445674:54\r\n
x-axis-dvr-frame-id: 563234:54\r\n
x-axis-dvr-frame-state: 3\r\n
Content-Type: image/jpeg\r\n
Content-Length: 14978\r\n
\r\n
<JPEG image data>\r\n
--myboundary\r\n
x-axis-dvr-session-id: 132\r\n
x-axis-dvr-frame-time: 1003445675:21\r\n
x-axis-dvr-frame-id: 563235:21\r\n
x-axis-dvr-frame-state: 3\r\n
Content-Type: image/jpeg\r\n
Content-Length: 15136\r\n
\r\n
<JPEG image data>\r\n
--myboundary\r\n
 .
 .
 .

5.7.4 Preserve and release recordings

Note: This request requires Administrator or Operator access.

This request changes the status on a recording from released to preserved or vice versa.
A preserved recording is not affected by quality reduction, but maintains the quality it had when preserved, until released.

Syntax:
http://<servername>/axis-cgi/operator/recadmin.cgi?
camera=<camera id>&[preserve|release]=<recid>

Example 1: Preserve recording 4234 from camera 2:
http://myserver/axis-cgi/operator/recadmin.cgi?camera=2&preserve=4234

Example 2: Release recording 243592 from camera 1:
http://myserver/axis-cgi/operator/recadmin.cgi?camera=1&release=243592

5.7.5 Controlling recordings

This interface is used to start and stop recordings from a camera.

Method: GET

Syntax:
http://<servername>/axis-cgi/view/record.cgi[?<parameter>=<value>
[&<parameter>=<value> ...]]

with the following parameters and values:
<parameter>=<value> | Values | Description
do=<string>1 | start, stop | Start or stop recording.
camera=<int>1 | 1, ... 2 | Selects a camera.

1 Request must contain these. See example below.
2 Product-dependent. Check the product specification.

Example 1: Start recording from camera 1
http://myserver/axis-cgi/view/record.cgi?do=start&camera=1

Example 2: Stop recording from camera 2
http://myserver/axis-cgi/view/record.cgi?do=stop&camera=2

5.8 I/O

The requests specified in the I/O section are supported by those products that have Input/Output connectors.

5.8.1 I/O control

5.8.1.1 Input

Input

Method: GET

Syntax:
http://<servername>/axis-cgi/io/input.cgi?<parameter>=<value>
[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
check=<int>[,<int>, ...] | <id1>[,<id2>, ...] 1 | Returns the status of one or more inputs numbered id1 ,id2, .... See 5.2.1 for more information about server responses.
monitor=<int>[, <int>, ...] 2 | <id1>[,<id2>, ...] 1 | Returns a multipart stream of "check" inputs (see return description below).

1 Number of inputs may differ for different camera and video servers. See product specification.
2 Support for this parameter is product/release-dependent.

Return: "monitor", i.e., multipart "check" parameter
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=<boundary>\r\n
\r\n
--<boundary>\r\n
<monitor data>
where the proposed boundary <boundary> is
ioboundary
and the <monitor data> part is
Content-Type: text/plain\r\n
\r\n
<check data>
--<boundary>\r\n
and <check data> is
IO<n>:<action char>\r\n
and <n> is the I/O port number and <action char> is the action character described in the table above.
Note: The output can contain extra blank lines, i.e., extra \r\n within the sections.

Example: Monitor data on input ports 1, 2, 3, and 4
http://myserver/axis-cgi/io/input.cgi?monitor=1,2,3,4

Example: Monitor data on input port 1
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace; boundary=ioboundary\r\n
\r\n
\r\n
\r\n
\r\n
--ioboundary\r\n
Content-Type: text/plain\r\n
\r\n
IO0:/\n
\r\n
\r\n
--ioboundary\r\n
Content-Type: text/plain\r\n
\r\n
IO0:H\n
\r\n
--ioboundary\r\n
Content-Type: text/plain\r\n
\r\n
\r\n
IO0:\\n
\r\n
\r\n
--ioboundary\r\n
Content-Type: text/plain\r\n
\r\n
\r\n
\r\n
\r\n
--ioboundary\r\n
Content-Type: text/plain\r\n
\r\n
\r\n
 .
 .
 .

5.8.1.2 Output

Output

Method: GET

Syntax:
http://<servername>/axis-cgi/io/output.cgi?<parameter>=<value>
[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
check=<int>[,<int>, ...] | <id1>[,<id2>, ...] 1 | Returns the status of one or more outputs numbered id1 ,id2, .... See 5.2.1 for more information about server responses.
monitor=<int>[, <int>, ...] 2 | <id1>[,<id2>, ...] 1 | Returns a multipart stream of "check" outputs (see return description below).
action=<string> | [<id>1]:<a>[<wait> <a> ...] | Sets the output relay <id> on or off and waits <wait> milliseconds. <id> = Output number. If omitted, output 1 is selected. <a> = Action character: / or \ / = on, \ = off. <wait> = Delay in milliseconds.

1 Number of outputs may differ for different camera and video servers. See product specification.
2 Support for this parameter is product/release-dependent.

Example: Set output 1 on
http://myserver/axis-cgi/io/output.cgi?action=1:/

Example: Set two 300 ms pulses with 500 ms delay between the pulses on output 1
http://myserver/axis-cgi/io/output.cgi?action=1:/300\500/300\

Example: Wait 1 second before setting output 1 on
http://myserver/axis-cgi/io/output.cgi?action=1:1000/

5.8.2 Virtual I/O control

5.8.2.1 Input

Input

Method: GET

Syntax:
http://<servername>/axis-cgi/io/virtualinput.cgi?<parameter>=<value>

with the following parameters and values
<parameter>=<value> | Values | Description
action=<string> | [<id>]:<a> | Sets the virtual input <id> on or off. <id> = Input number. If omitted, input 1 is selected. <a> = Action character: / or \ / = on, \ = off.

Example: Set virtual input 1 on
http://myserver/axis-cgi/io/virtualinput.cgi?action=1:/

5.9 Serial Port

The requests specified in the Serial Port section are supported by those video products that have implemented a Generic driver.

5.9.1 Serial port control

Control serial port

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/com/serial.cgi?<parameter>=<value>
[&<parameter>=<value>... ]

with the following parameters and values
<parameter>=<value> | Values | Description
port=<int> | 1, ... 1 | The COM port is selected with this parameter.
write=<string> dataout2=<string> | <bytestring> | <bytestring>: hex coded bytes with values of {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, a, b, c, d, e, f} Writes the specified data string to the selected serial port. Max string length: 128 bytes 1 .
writestring=<string> | <url encoded string> | Writes the URL-encoded string to the selected serial port. Max string length: 128 bytes 1.
read=<int> | 1, ... | Reads n bytes from the selected serial port. The returned data will be hexadecimal coded and placed between #s (e.g. #3A#)
wait=<int> | 1 - 9 | Specified in seconds. Used together with the "read" parameter. A read is terminated when the specified number of bytes is read or when the wait period has ended.
timeout=<int> | 1 - 9000 | Specified in milliseconds. Used together with the "read" parameter. A read is terminated when the specified number of bytes is read or the timeout has expired.

1 Product-dependent. Check the product specification.
2 Obsolete.

5.9.2 Open serial port

This CGI makes it possible to open the serial port using the HTTP protocol. Authentication is handled by the Web server.

  • After an initial connect command from the client, the connection is kept alive until the client closes it.
  • Several clients may be connected concurrently to the same serial port.
  • After the connection has been set up, data sent from the client to the Web server is forwarded to the serial port, and incoming serial data is returned to all currently connected clients.

Syntax:
http://<servername>/axis-cgi/com/serial.cgi?<parameter>=<value>
[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
port=<int> | 1, ... 1 | Select COM port.
camera=<int> unit=<int> | 1, ... 1 | Selects the source camera or external unit. If omitted, and "port=" command is also omitted, the default camera/unit is used to determine the serial port to use.
connect=<string> | yes | Makes the server keep the connection open, and start acting as a link between the client and the serial port.

1 Product-dependent. Check the product specification.

5.10 PPP

The requests specified in the PPP section are supported by those products that have support for the PPP protocol.

5.10.1 Close PPP connection

Note: This request requires administrator access (administrator authorization).

Accessing this URL will force the Axis device to immediately close and disconnect any current PPP connection. When closing a PPP connection, all connections will be closed (dial-in, dial-out, callback).

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/closeppp.cgi[?<wait>]

with the following parameter and value
<parameter> | Value | Description
<wait> | <int> | Number of seconds from request is received until the PPP connection is closed. Default: 0

Return: close PPP connection
HTTP/1.0 204 No Content\r\n

5.10.2 Reset PPP connection maxtimer

Note: This request requires administrator access (administrator authorization).

Accessing this URL will reset the timer counting down the maximum time a device is allowed to be connected over a PPP connection.

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/resetppptimer.cgi

Return: reset PPP connection maxtimer
HTTP/1.0 204 No Content\r\n

5.11 Event

The requests specified in the Event section are supported by those products that have support for event handling.

5.11.1 Event administration

Note: This request requires Administrator or Operator access.

Used to administer the list of event entries.

Method: GET

Syntax:
http://<servername>/axis-cgi/operator/ev_admin.cgi?add
http://<servername>/axis-cgi/operator/ev_admin.cgi?delete=<entry>

5.11.1.1 Actions

These are the actions used to administer the events. Each event is given an entry identifier (E0, E1 E2, etc) which is later used to delete the entry. The identifier of a deleted entry may be reused by a new entry.

Action/Syntax | Argument | Description
add |  | Add a new empty entry to list of events.
delete=<entry> | E0, E1, E2, ... | Delete an entry from list of events.

5.11.1.2 Server responses

The actions produce one of the following server responses:

Return: A successful delete:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
OK\r\n

Return: A successful add:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
<entry> OK\r\n

Return: A failed request. Input values are probably incorrect:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Request failed: <error message>\r\n

Example: Adding new event entry
http://myserver/axis-cgi/operator/ev_admin.cgi?add

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
E7 OK\r\n

Example: Deleting event entry
http://myserver/axis-cgi/operator/ev_admin.cgi?delete=E7

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
OK\r\n

5.12 Firewall

The requests specified in the Firewall section are supported by those products that have built-in firewall functionality.

5.12.1 Firewall administration

Note: This request requires Administrator access.

Used to administer the built-in firewall, which restricts network access to the server. When enabled, only the hosts added through this interface will be able to access the server.

For each added entry, the services that are to be accessible must be specified. This is done by parameters, from where a specific service or a range of port numbers for custom services can be specified.

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/fwall_admin.cgi?list
http://<servername>/axis-cgi/admin/fwall_admin.cgi?enable[&<option> ...]

http://<servername>/axis-cgi/admin/fwall_admin.cgi?disable[&<option> ...]

http://<servername>/axis-cgi/admin/fwall_admin.cgi?add[&<parameter>[=<value>] ...]]
[&<option> ...]

http://<servername>/axis-cgi/admin/fwall_admin.cgi?update=<entry>[&<parameter>
[=<value>] ...]][&<option> ...]

http://<servername>/axis-cgi/admin/fwall_admin.cgi?delete=<entry>[&<option> ...]

5.12.1.1 Actions

These are the actions used to administer the firewall. Each added host is given an entry identifier (F0, F1 F2, etc) which is later used to modify or delete the entry. The identifier of a deleted entry may be reused by a new entry.

Action/Syntax | Argument | Description
list |  | Produce a list of all settings and entries.
add |  | Add a new entry to list of accepted hosts.
delete=<entry> | F0, F1, F2, ... | Delete an entry from list of accepted hosts.
update=<entry> | F0, F1, F2, ... | Update an entry in list of accepted hosts.
enable |  | Enable the firewall. Blocks access from all except the added entries.
disable |  | Disables the firewall. Enables access by everyone.

5.12.1.2 Parameters
Parameter/Syntax | Values | Description
host=<address>1 | host name2 or numerical Internet address | Host to add or modify.
http |  | Opens ports for HTTP access.
https |  | Opens ports for HTTPS access.
ftp |  | Opens ports for FTP access.
telnet |  | Opens ports for TELNET access.
tcp=<int>-<int> | 1024 - 65535 | Opens specified TCP port range.
udp=<int>-<int> | 1024 - 65535 | Opens specified UDP port range.

1 Required by action add.
2Address specified by host name requires that the server has access to a Domain Name Server.

5.12.1.3 Options

Before modifying the settings of an enabled firewall, the script will verify that the host that requested the action will still have access to the server once the action is performed. If the client uses a proxy, proxy access will be verified instead.

If verification fails, i.e. the host would have been blocked from the server, the action is not carried out and an error is returned. This prevents accidental lock out by the administrator, etc.

By setting the force option this verification is skipped and all actions are carried out, regardless of their consequences.

Option/Syntax | Description
force | Do not verify host accessibility.

5.12.1.4 Server responses

The actions produce one of the following server responses:

Return: A successful enable, disable, delete or update:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
OK\r\n

Return: A successful add:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
<entry> OK\r\n

Return: A failed request. Input values are probably incorrect:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Request failed: <error message>\r\n

Return: A failed verification by an enable, add, delete or update request. No settings have been changed. Use the force option to override the verification.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Verification failed for IP <Numerical Internet address>\r\n

Return: A list request.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
[Firewall]\r\n
enabled=<value>\r\n
\r\n
<entry data>
<entry data>
...
where each <entry data> is:

[<entry>]\r\n
host=<value>\r\n
http=<value>\r\n
https=<value>\r\n
ftp=<value>\r\n
telnet=<value>\r\n
tcp=<value>\r\n
udp=<value>\r\n
\r\n

The parameter values has the following syntax:
Parameter | Values | Description
enabled | yes, no | States if the firewall is enabled or disabled.
host | host name1 or numeric Internet address | The host for this entry.
http | yes, no | States if host has HTTP access.
https | yes, no | States if host has HTTPS access.
ftp | yes, no | States if host has FTP access.
telnet | yes, no | States if host has TELNET access.
tcp | [1024-65535]-[1024-65535] | Specific TCP port range accessible by host.
udp | [1024-65535]-[1024-65535] | Specific UDP port range accessible by host.

1Address specified by host name requires that the server has access to a Domain Name Server.

Example: Adding new host with HTTP and FTP access, with verification
http://myserver/axis-cgi/admin/fwall_admin.cgi?add&host=10.13.18.20&http&ftp

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
F1 OK\r\n

Example: Listing entries
http://myserver/axis-cgi/admin/fwall_admin.cgi?list

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
[Firewall]\r\n
enabled="yes"\r\n
\r\n
[F0]\r\n
\r\n
host=10.13.18.1\r\n
http=yes\r\n
https=no\r\n
ftp=no\r\n
telnet=no\r\n
tcp=4000-4001\r\n
udp=\r\n
\r\n
[F1]\r\n
host=10.13.18.20\r\n
http=yes\r\n
https=no\r\n
ftp=yes\r\n
telnet=no\r\n
tcp=\r\n
udp=\r\n
\r\n

Example: Deleting entry, with failed verification
http://myserver/axis-cgi/admin/fwall_admin.cgi?delete=F1

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Verification failed for IP 10.13.18.20\r\n

Example: Deleting entry, overriding verification
http://myserver/axis-cgi/admin/fwall_admin.cgi?delete=F1&force

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
OK\r\n


Axis Video API, HTTP, for products with firmware version 4.00 and above

Axis Video API, HTTP - Interface Specification - For products with firmware version 4.xx and above

Revision: 2.09
Date: 2004-Nov-04

TABLE OF CONTENTS

  • DOCUMENT HISTORY
  • 1 OVERVIEW
    • 1.1 Product and firmware versions
  • 2 REFERENCES
  • 3 DEFINITIONS
    • 3.1 General notations
      • 3.1.1 General abbreviations
      • 3.1.2 Style convention
      • 3.1.3 General CGI URL syntax and parameters
      • 3.1.4 Parameter value convention
  • 4 INTERFACE SPECIFICATION
    • 4.1 Naming conventions and URL syntax
      • 4.1.1 Obsolete CGI parameters
    • 4.2 Server responses
      • 4.2.1 HTTP status codes
  • 5 API GROUPS
    • 5.1 General
      • 5.1.1 Add, update, remove and list parameters and their values
        • 5.1.1.1 List parameters
        • 5.1.1.2 List output format
        • 5.1.1.3 Update parameters
        • 5.1.1.4 Add parameters
        • 5.1.1.5 Remove parameters
        • 5.1.1.6 Add/Remove server responses
      • 5.1.2 Add, modify and delete users
      • 5.1.3 Factory default
      • 5.1.4 Hard factory default
      • 5.1.5 Backup
      • 5.1.6 Restore
      • 5.1.7 Firmware upgrade
      • 5.1.8 Restart server
      • 5.1.9 Server report
      • 5.1.10 System logs
      • 5.1.11 System date and time
        • 5.1.11.1 Get system date and time
        • 5.1.11.2 Set system date and time
    • 5.2 Image and Video
      • 5.2.1 Image size
      • 5.2.2 Video status
      • 5.2.3 Bitmap
        • 5.2.3.1 Bitmap image request
        • 5.2.3.2 Bitmap image (snapshot) CGI request
        • 5.2.3.3 Bitmap image response
      • 5.2.4 JPEG/MJPG
        • 5.2.4.1 JPEG image request
        • 5.2.4.2 JPEG image (snapshot) CGI request
        • 5.2.4.3 JPEG image response
        • 5.2.4.4 JPEG buffer request
        • 5.2.4.5 MJPG video request
        • 5.2.4.6 MJPG video CGI request
        • 5.2.4.7 MJPG video response
      • 5.2.5 Image overlay
        • 5.2.5.1 Upload image
        • 5.2.5.2 Create image
        • 5.2.5.3 Delete image
        • 5.2.5.4 Set image
      • 5.2.6 MPEG-4
        • 5.2.6.1 MPEG-4 SDP description request
        • 5.2.6.2 Restart the MPEG-4 stream
        • 5.2.6.3 MPEG-4 statistics
    • 5.3 PTZ
      • 5.3.1 PTZ driver update
      • 5.3.2 PTZ administration
      • 5.3.3 PTZ control
      • 5.3.4 PTZ configuration
      • 5.3.5 Set PTZ parameters
      • 5.3.6 PTZ control queue
      • 5.3.7 PTZ control queue response
    • 5.4 Motion Detection
      • 5.4.1 Add a Motion Detection window
      • 5.4.2 Remove a Motion Detection window
      • 5.4.3 Update the Motion Detection parameters
      • 5.4.4 List the Motion detection parameters
      • 5.4.5 Get the Motion Detection level
    • 5.5 I/O
      • 5.5.1 I/O control
        • 5.5.1.1 Input
        • 5.5.1.2 Output
      • 5.5.2 Virtual I/O control
        • 5.5.2.1 Input
    • 5.6 Serial port
      • 5.6.1 Serial port control
      • 5.6.2 Open serial port
    • 5.7 IP filter
      • 5.7.1 IP filter administration
      • 5.7.2 Server responses
    • 5.8 Audio
      • 5.8.1 Audio MIME types
      • 5.8.2 Audio data request
      • 5.8.3 Singlepart audio data response
      • 5.8.4 Multipart audio data response
      • 5.8.5 Audio data transmit
    • 5.9 AXIS 292 Network Video Decoder
      • 5.9.1 Alarm
      • 5.9.2 Video control
        • 5.9.2.1 Connect
        • 5.9.2.2 Disconnect
        • 5.9.2.3 Invalidate Cache
        • 5.9.2.4 Select Source

DOCUMENT HISTORY

Version | Date | Comment
2.00 | 2003-Sep-16 | Initial version
2.01 | 2004-Feb-03 | Added requests for Video status, Bitmap, JPEG buffer, PTZ, Motion Detection, I/O and Serial port. Added new parameters to JPEG image CGI request and MJPG video CGI request.
2.02 | 2004-Feb-16 | Added requests for Image overlay.
2.03 | 2004-May-27 | Added more valid values for the parameter resolution, to the Bitmap image, JPEG image and MJPG video CGI requests. Added requests for Backup, Restore, Firmware upgrade and IP address filtering.
2.04 | 2004-July-09 | Added more valid values for the parameter resolution, to the JPEG image and MJPG video CGI requests.
2.05 | 2004-July-23 | Added requests for MPEG-4.
2.06 | 2004-Nov-03 | Added requests for Audio. Added responseformat parameter to param.cgi?action=list.
2.07 | 2005-Feb-25 | Removed the nosync parameter from param.cgi. Added reference to the RTSP API for controlling MPEG-4 streams. The MPEG-4 SDP description request have been changed to media.sdp. The previous video.sdp will still be supported.
2.08 | 2005-May-26 | Added a policy parameter for the ipfilter.cgi and examples. Added new HTTP APIs for the AXIS 292 Network Video Decoder.
2.09 | 2005-Oct-26 | Added example to list parameters using wildcards. Added the parameter "range" to the JPEG buffer request. Added example to pulse the virtual input. Moved PTZ preset position configuration from ptz.cgi to ptzconfig.cgi. More information under point 2 here. Added ptzconfig.zgi for OSD menu control. Updated information about the PTZ control queue response.

1 OVERVIEW

This document specifies the external HTTP-based application programming interface of the Axis camera and video servers with firmware version 4.00 and above.

The HTTP-based video interface provides the functionality for requesting single and multi-part images and for getting and setting internal parameter values. The image and CGI-requests are handled by the built-in Web server in the camera and video servers.

1.1 Product and firmware versions

The support for the HTTP API is product and firmware dependent. Please refer to the Release Notes for the actual product for compliance information.

2 REFERENCES

HTTP protocol

  • Hypertext Transfer Protocol -- HTTP/1.0

External application programming interfaces (Client side)

  • Axis Video API, HTTP
  • Axis Video API, RTSP
  • Axis Video Product specific API Notes
  • Axis Video Parameter specification

3 DEFINITIONS

This section contains information on general usage of this document.

3.1 General notation

3.1.1 General abbreviations

The following abbreviations are used throughout this document
CGI | Common Gateway Interface - a standardized method of communication between a client (e.g. a web browser) and a server (e.g. a web server).
TBD | To be done/designed - signifies that the referenced section/subsection/entity is intended to be specified, but has not reached a level of maturity to be public at this time.
N/A | Not applicable - a feature/parameter/value is of no use in a specific task
URL | RFC 1738 describes the syntax and semantics for a compact string representation for a resource available via the Internet. These strings are called "Uniform Resource Locators" (URLs).
URI | A Uniform Resource Identifier (URI) is a compact string of characters for identifying an abstract or physical resource. RFC 2396 describes the generic syntax of URI.

3.1.2 Style convention

In URL syntax and in descriptions of CGI parameters, text in italics within angle brackets denotes content that should be replaced with either a value or a string. When replacing the text string, the angle brackets must also be replaced. An example of this is the description of the name for the server, denoted with <servername> in the URL syntax description below, which is replaced with the string myserver in the URL syntax example, also shown below.

URL syntax is written with the word "Syntax:" shown in bold face, followed by a box with the referred syntax, as shown below. The name of the server is written as <servername>. This is intended to be replaced with the name of the actual server. This can either be a name, e.g. "thecam" or "thecam.adomain.net" or the associated IP number for the server, e.g. 10.10.2.139.

Syntax:
http://<servername>/jpg/image.jpg

A description of returned data is written with "Return:" in bold face, followed by the returned data in a box. All data returned as HTTP-formatted, i.e. starting with the string HTTP, is line-separated with a Carriage Return and Line Feed (CRLF) printed as \r\n.

Return:
HTTP/1.0 <HTTP code> <HTTP text>\r\n

URL syntax examples are written with "Example:" in bold face, followed by a short description and a light grey box with the example.

Example: Request default image.
http://myserver/jpg/image.jpg

Examples of what can be returned by the server from a request are written with "Example:" in bold face, followed by a short description and a light grey box with an example of the returned data.

Example: Returned data after a successful request.
HTTP/1.0 200 Ok\r\n

3.1.3 General CGI URL syntax and parameters

CGI URLs are written in lower-case. CGI parameters are written in lower-case and as one word. When the CGI request includes internal camera parameters, the internal parameters must be written exactly as named in the camera or video server. The CGIs are organized in function related directories under the axis-cgi directory. The file extension of the CGI is required.

Syntax:
http://<servername>/axis-cgi/<subdir>[/<subdir>...]/<cgi>.<ext>
[?<parameter>=<value>[&<parameter>=<value>...]]

Example: List the Network parameters.
http://<servername>/axis-cgi/operator/param.cgi?action=list&group=Network

3.1.4 Parameter value convention

In tables defining CGI parameters and supported parameter values, the default value for optional parameters is system configured.

4 INTERFACE SPECIFICATION

4.1 Naming conventions and URL syntax

4.1.1 Obsolete CGI parameters

Some CGI parameters and values in this specification may be obsolete and are provided for backward compatibility. These might not be supported in the future.

Obsolete parameters and values are stated in the request descriptions.

Some CGI requests described in the Axis Video HTTP API version 1.xx are still supported by Axis products with firmware version 4.00 and above, and are provided for backward compatibility. They are, however, obsolete and should not be used. For more information, please read the document describing the differences between Axis Video HTTP API version 1.xx and version 2.xx: cam_http_api_diffdoc.htm

4.2 Server responses

4.2.1 HTTP status codes

The built-in Web server uses the standard HTTP status codes.

Return:
HTTP/1.0 <HTTP code> <HTTP text>\r\n

with the following HTTP code and meanings
HTTP code | HTTP text | Description
200 | OK | The request has succeeded, but an application error can still occur, which will be returned as an application error code.
204 | No Content | The server has fulfilled the request, but there is no new information to send back.
302 | Moved Temporarily | The server redirects the request to the URI given in the Location header.
400 | Bad Request | The request had bad syntax or was impossible to fulfill.
401 | Unauthorized | The request requires user authentication or the authorization has been refused.
404 | Not Found | The server has not found anything matching the request.
409 | Conflict | The request could not be completed due to a conflict with the current state of the resource.
500 | Internal Error | The server encountered an unexpected condition that prevented it from fulfilling the request.
503 | Service Unavailable | The server is unable to handle the request due to temporary overload.

Example: Request includes invalid file names.
HTTP/1.0 404 Not Found\r\n

5 API GROUPS

To make it easier for developers to get an idea of which API requests are supported for different products, the requests have been grouped together. Information about which groups are supported can be found in the product-specific release notes document, available for download from the Axis web site.

5.1 General

The requests specified in the General section are supported by all video products with firmware version 4.00 and above.

5.1.1 Add, update, remove and list parameters and their values

Note:

  • These requests have different security levels. The security level for each parameter is specified in the parameter document.
  • The URL must follow the standard way of writing a URL, (RFC 2396: Uniform Resource Identifiers (URI) Generic Syntax); that is, spaces and other reserved characters (";", "/", "?", ":", "@", "&", "=", "+", "," and "$") within a <parameter> or a <value> must be replaced with %<ASCII hex>. For example, in the string My camera, the space will have to be replaced with %20, My%20camera.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/view/param.cgi?
<parameter>=<value>[&<parameter>=<value>...]
http://<servername>/axis-cgi/operator/param.cgi?
<parameter>=<value>[&<parameter>=<value>...]
http://<servername>/axis-cgi/admin/param.cgi?
<parameter>=<value>[&<parameter>=<value>...]

with the following parameter and values
<parameter>=<value> | Values | Description
action=<string> | add, remove, update or list | Specifies the action to take. Depending on this parameter, various parameters may be set, as described in the following sections.

5.1.1.1 List parameters

Syntax:
http://<servername>/axis-cgi/view/param.cgi?action=list
[&<parameter>=<value>...]
http://<servername>/axis-cgi/operator/param.cgi?action=list
[&<parameter>=<value>...]
http://<servername>/axis-cgi/admin/param.cgi?action=list
[&<parameter>=<value>...]

with the following parameter and values
<parameter>=<value> | Values | Description
group=<string>[,<string>...] | <group[.name]>[,<group[.name]>...] | Returns the value of the camera parameter named <group>.<name>. If <name> is omitted, all the parameters of the <group> are returned. The camera parameters must be entered exactly as they are named in the camera or video server. Wildcard (*) can be used when listing parameters. See example below. If this parameter is omitted, all parameters in the device are returned.
responseformat | rfc | Get the HTTP response format according to standard. Response format: HTTP/1.0 200 OK\r\n Content-Type: text/plain\r\n \r\n <parameter pair>

Example: List the Network parameters.
http://myserver/axis-cgi/admin/param.cgi?action=list&group=Network

Example: List the names of all Event parameters.
http://myserver/axis-cgi/admin/param.cgi?action=list&group=Event.*.Name

5.1.1.2 List output format
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
<parameter pair>

where <parameter pair> is

<parameter>=<value>\n
[ <parameter pair> ]

Example: Network query response.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
root.Network.IPAddress=10.13.12.36\n
root.Network.SubnetMask=255.255.255.0\n

If the CGI request includes an invalid parameter value, the server returns an error message.
Return:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
# Error: <description>\n

5.1.1.3 Update parameters

Syntax:
http://<servername>/axis-cgi/operator/param.cgi?action=update
[&<parameter>=<value>...]
http://<servername>/axis-cgi/admin/param.cgi?action=update
[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
<string>=<string> | <group.name>=<value> | Assigns <value> to the parameter <group.name>. The <value> must be URL-encoded when it contains non-alphanumeric characters. The camera parameters must be entered exactly as named in the camera or the video server.

Example: Set the default image resolution to 320x240 pixels.
http://myserver/axis-cgi/operator/param.cgi?
action=update&Image.I0.Resolution=320x240

Example: Set the maximum number of viewers to 5.
http://myserver/axis-cgi/operator/param.cgi?
action=update&Image.MaxViewers=5

5.1.1.4 Add parameters

Note: Only applicable for dynamic parameter groups such as the event parameters.

Syntax:
http://<servername>/axis-cgi/operator/param.cgi?action=add[&<parameter>=<value>...]
http://<servername>/axis-cgi/admin/param.cgi?action=add[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
template=<string> | <template> | Use the specified <template> when creating the new group. The template is a file, which describes all parameters for this group. Depending on the product, different templates are available, please check the Release notes of the firmware version. See examples below.
group=<string> | <group> | Specifies the parent group. The parent group defines where in the parameter structure the new group will be created. For example, if adding an event (template=event) and specify group=Event the new group will be available as Event.E<number>. Where <number> is the unique number for the group (see return values below). The character before <number> is generated from the last section of the group name. E.g. Event will generate the character E and Event.Notification will generate the character N.
<string>=<string> | <group.name>=<value> | Set a parameter in the newly created group. As the group number is not known before the group is created, the id-number is simply left out, see the examples below. The new group number is created dynamically and can be any number. This is why all parameters are specified to set without any group number. The base path to the parameter is specified as <group>.<uppercase first letter of group>.<parameter name>.

Example: Create a new event under the group Event and set the name to MyEvent and the Enabled parameter to yes.
http://myserver/axis-cgi/operator/param.cgi?action=add&group=Event
&template=event&Event.E.Name=MyEvent&Event.E.Enabled=yes

Example: A listing of the new group will output the following.
root.Event.E0.Name=MyEvent
root.Event.E0.Type=T
root.Event.E0.Enabled=yes
root.Event.E0.Active=no
root.Event.E0.Priority=1
root.Event.E0.Image=1
root.Event.E0.HWInputs=xxxx
root.Event.E0.SWInput=
root.Event.E0.Weekdays=1111111
root.Event.E0.Starttime=00:00
root.Event.E0.Duration=0
root.Event.E0.ImageURLSettingsEnabled=no
root.Event.E0.ImageURLSettings=
root.Event.E0.IncludePreTrigger=no
root.Event.E0.PreTriggerSize=0
root.Event.E0.PreTriggerInterval=1000
root.Event.E0.PreTriggerIntervalUnit=s
root.Event.E0.PreTriggerUnit=s
root.Event.E0.IncludePostTrigger=no
root.Event.E0.PostTriggerSize=0
root.Event.E0.PostTriggerInterval=1000
root.Event.E0.PostTriggerIntervalUnit=s
root.Event.E0.PostTriggerUnit=s
root.Event.E0.IncludeBestEffort=no
root.Event.E0.BestEffortInterval=1000
root.Event.E0.BestEffortDuration=0
root.Event.E0.BestEffortIntervalUnit=s
root.Event.E0.BestEffortDurationUnit=s
root.Event.E0.FileName=image.jpg
root.Event.E0.Suffix=%y-%m-%d_%H-%M-%S-%f
root.Event.E0.MaxSequenceNumber=-100

Note that in this example the id is E0. This can be any number, depending on if other events were added before. Parameters that are not specified in the request will have their default values, as specified in the configuration file.

5.1.1.5 Remove parameters

Note: Only applicable for dynamic parameter groups such as the event parameters.

Syntax:
http://<servername>/axis-cgi/operator/param.cgi?
action=remove[&<parameter>=<value>...]
http://<servername>/axis-cgi/admin/param.cgi?
action=remove[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
group=<string>[,<string>...] | <group>[,<group>] | Deletes the specified <group>

Example: Delete event group E2 and E4.
http://myserver/axis-cgi/operator/param.cgi?action=remove&group=Event.E2,Event.E4

5.1.1.6 Add/Remove server responses

These actions produce one of the following server responses:

Return: A successful add.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
<entry> OK\r\n

Return: A successful remove.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
OK\r\n

Return: Add new group failed. The group was not created, due to errors in the parameters to add command.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
<additional error information>
# Request failed: <error message>\n

Return: Add new group failed. The group was created, but the specified parameters could not be set.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
<additional error information>
# Error: <error message>\r\n

Return: Remove failed.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
<additional error information>
# Request failed: <error message>\r\n

Example: Add new event entry and set the specified name.
http://myserver/axis-cgi/operator/param.cgi?action=add&group=Event&template=event
&Event.E.Name=MyEvent

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
E7 OK\r\n

Example: Delete an event entry.
http://myserver/axis-cgi/operator/param.cgi?action=remove&group=Event.E7

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\n
\n
OK\r\n

5.1.2 Add, modify and delete users

Add a new user with password and group membership, modify the information and remove a user.

Note: This request requires root access (root authorization).

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/pwdgrp.cgi?
<parameter>=<value>[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
action=<string> | add, update, remove or get | add = create a new user account. update = change account information of specified parameters if the account exists. remove = remove an existing account if it exists. get = get a list of the users which belong to each group defined.
user=<string> | <string> | The user account name, a non-existing user name. Valid characters are a thru z, A thru Z and 0 thru 9.
pwd=<string> | <string> | The unencrypted password of the account. Valid characters are a thru z, A thru Z and 0 thru 9.
grp=<string> | <string> | An existing primary group name of the account.
sgrp=<string>:[<string>...] | <string>[,<string>...] | Colon separated existing secondary group names of the account.
comment=<string> | <string> | The comment field of the account.

Example: Create a new administrator account.
http://myserver/axis-cgi/admin/pwdgrp.cgi?action=add&user=joe&pwd=foo&grp=axuser
&sgrp=axadmin:axoper:axview&comment=Joe

Example: Change the password of an existing account.
http://myserver/axis-cgi/admin/pwdgrp.cgi?action=update&user=joe&pwd=bar

Example: Remove an account.
http://myserver/axis-cgi/admin/pwdgrp.cgi?action=remove&user=joe

Example: List groups and users.
http://myserver/axis-cgi/admin/pwdgrp.cgi?action=get

5.1.3 Factory default

Reload factory default. All parameters except Network.BootProto, Network.IPAddress, Network.SubnetMask, Network.Broadcast and Network.DefaultRouter are set to their factory default values.

Note: This requires administrator access (administrator authorization).

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/factorydefault.cgi

5.1.4 Hard factory default

Reload factory default. All parameters are set to their factory default value.

Note: This request requires administrator access (administrator authorization).

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/hardfactorydefault.cgi

5.1.5 Backup

Download a unit specific backup of all files in the folder /etc in tar format.

Note: This requires administrator access (administrator authorization).

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/backup.cgi

Return:
HTTP/1.0 200 OK\r\n
Content-Type: application/x-tar\r\n
Content-Disposition: attachment; filename=backup_<MAC address>.tar\r\n
\r\n
<file content of backup_<MAC address>.tar>

5.1.6 Restore

Upload a unit specific backup previously created by the backup.cgi.

Note: This requires administrator access (administrator authorization).

Method: POST

Syntax:
http://<servername>/axis-cgi/admin/restore.cgi

The file content is provided in the HTTP body according to the format given in RFC 1867. The body is created automatically by the browser if using HTML form with input type "file".

Example: Upload of backup, where "\r\n" has been omitted in the HTTP body.
POST /axis-cgi/admin/restore.cgi? HTTP/1.0\r\n
Content-Type: multipart/form-data; boundary=AaBo3x\r\n
Content-Length: <content length>\r\n
\r\n
--AaBo3x\r\n
Content-Disposition: form-data; name="backup.tar";
filename="backup_<MAC address>.tar"\r\n
Content-Type: application/x-tar\r\n
\r\n
<file content of backup_<MAC address>.tar>
\r\n
--AaBo3x--\r\n

5.1.7 Firmware upgrade

Upgrade the firmware version.

Note: This requires administrator access (administrator authorization).

Method: POST

Syntax:
http://<servername>/axis-cgi/admin/firmwareupgrade.cgi[?<parameter>=<value>]

with the following parameters and values
<parameter>=<value> | Values | Description
type=<string> | normal, factorydefault | Specifies the type of firmware upgrade. normal = Upgrade and restore old settings. factorydefault = Upgrade and discard all settings. type is by default set to normal.

The file content is provided in the HTTP body according to the format given in RFC 1867. The body is created automatically by the browser if using HTML form with input type "file".

Example:
POST /axis-cgi/admin/firmwareupgrade.cgi?type=normal HTTP/1.0\r\n
Content-Type: multipart/form-data; boundary=AsCg5y\r\n
Content-Length: <content length>\r\n
\r\n
--AsCg5y\r\n
Content-Disposition: form-data; name="firmware.bin"; filename="firmware.bin"\r\n
Content-Type: application/octet-stream\r\n
\r\n
<firmware file content>
\r\n
--AsCg5y--\r\n

5.1.8 Restart server

Restart server.

Note: This requires administrator access (administrator authorization).

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/restart.cgi

5.1.9 Server report

This CGI request generates and returns a server report. This report is useful as an input when requesting support. The report includes product information, parameter settings and system logs.

Note: This requires administrator access (administrator authorization).

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/serverreport.cgi

5.1.10 System logs

Get system log information.

Note: This requires administrator access (administrator authorization).

Note: The response is product/release-dependent.

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/systemlog.cgi

Return:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
<system log information>

5.1.11 System date and time

Get or set the system date and time.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/admin/date.cgi?<parameter>=<value>

with the following parameter and values
<parameter>=<value> | Values | Description
action=<string> | get or set | Specifies what to do. get = get the current date and time. set = set the current date and/or time.

5.1.11.1 Get system date and time

Syntax:
http://<servername>/axis-cgi/admin/date.cgi?action=get

Return:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
<month> <day>, <year> <hour>:<minute>:<second>\r\n

Example:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Apr 03, 2003 15:16:04\r\n

5.1.11.2 Set system date and time

Syntax:
http://<servername>/axis-cgi/admin/date.cgi?action=set[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
year=<int> | 1970 - 2031 | Current year.
month=<int> | 1 - 12 | Current month.
day=<int> | 1 - 31 | Current day.
hour=<int> | 0 - 23 | Current hour.
minute=<int> | 0 - 59 | Current minute.
second=<int> | 0 - 59 | Current second.

The set action produces one of the following server responses:

Return: A successful set.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
OK\r\n

Return: A failed set. Settings or syntax are probably incorrect.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Request failed: <error message>\r\n

Example: Set the date.
http://myserver/axis-cgi/admin/date.cgi?action=set&year=2005&month=4&day=3

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
OK\r\n

5.2 Image and video

5.2.1 Image size

Get the actual image size of default image settings, or with given parameters.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/view/imagesize.cgi?
<parameter>=<value>[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
camera=<string> | 1, 2, 3, 4 or quad1 | Returns image size of the camera. Note: This parameter is required.
Any parameter from jpeg-interface affecting image size. |  | See 5.2.4.2 for more information about image parameters.

1 The number of video inputs may differ between different cameras and video servers. See the product's specification.

Example: Request image size of default settings from camera 1.
http://myserver/axis-cgi/view/imagesize.cgi?camera=1

Example: Returned data after a successful request.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
image width = 640\n
image height = 480\n

Example: Request image size with supplied parameters for camera 1.
http://myserver/axis-cgi/view/imagesize.cgi?camera=1&resolution=QCIF&compression=60

Example: Returned data after a successful request.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
image width = 160\n
image height = 120\n

5.2.2 Video status

Check the status of one or more video sources.

Method: GET

Syntax:
http://<servername>/axis-cgi/view/videostatus.cgi?<parameter>=<value>

with the following parameter and values
<parameter>=<value> | Values | Description
status=<int>[[,<int>],...] | 1 ... 41 | Returns the status of one or more inputs.

1 The number of video inputs may differ between different cameras and video servers. See the product's specification.

Example: Request video status from input 1, 2, 3 and 4.
http://myserver/axis-cgi/view/videostatus.cgi?status=1,2,3,4

Example: Returned data after a successful request.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Video 1 = video
Video 2 = no video
Video 3 = no video
Video 4 = video

5.2.3 Bitmap

The requests specified in the bitmap section are supported by those video products that have bitmap support. Supported image formats can be checked by reading the parameter Properties.Image.Format. The parameter can be listed using param.cgi.

5.2.3.1 Bitmap image request

Returns an image with the default resolution as defined in the system configuration.

Method: GET

Syntax: Request a bitmap image
http://<servername>/bitmap[/<camera>]/image.bmp

with the following parameter and values
<parameter>=<value> | Values | Description
<camera> | 1 ... 41 quad1 | Select the input source. Applies only to servers with more than one input source.

1 Product-dependent. See the product's specification.

Example: Request a bitmap image from the default camera with the default resolution.
http://myserver/bitmap/image.bmp

Example: Request a bitmap image from camera 2 with the default resolution.
http://myserver/bitmap/2/image.bmp

Example: Request a bitmap image containing four video sources.
http://myserver/bitmap/quad/image.bmp

5.2.3.2 Bitmap image (snapshot) CGI request

Request a bitmap image with the specified properties.

Method: GET

Syntax:
http://<servername>/axis-cgi/bitmap/image.bmp
[?<parameter>=<value>[&<parameter>=<value>...]]

with the following parameters and values
<parameter>=<value> | Values | Description
resolution=<string> | 768x576, 4CIF, 704x576, 704x480, VGA, 640x480, 2CIFEXP, 2CIF, 704x288, 704x240, 480x360, CIF, 384x288, 352x288, 352x240, 320x240, 240x180, QCIF, 192x144, 176x144, 176x120, 160x120 1 | Specifies the resolution as <width> times <height> number of pixels of the returned image.
camera=<string> | 1 ... 41 quad1 | The camera source. Applies only to video servers with more than one video input.
squarepixel=<int> | 0, 1 | Enable/disable square pixel correction. Applies only to video servers.

1 Product-dependent. See the product's specification.

Example: Request a bitmap image from camera 1 with a resolution of 320x240.
http://myserver/axis-cgi/bitmap/image.bmp?resolution=320x240&camera=1

5.2.3.3 Bitmap image response

When a bitmap image is requested, the server either returns the specified bitmap image file or an error.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: image/bitmap\r\n
Content-Length: <image size>\r\n
\r\n
<bitmap image data>\r\n

Example: Requested bitmap image.
HTTP/1.0 200 OK\r\n
Content-Type: image/bitmap\r\n
Content-Length: 1216566\r\n
\r\n
<bitmap image data>\r\n

5.2.4 JPEG/MJPG

The requests specified in the JPEG/MJPG section are supported by those video products that use JPEG and MJPG encoding.

5.2.4.1 JPEG image request

Returns an image with the default resolution and compression as defined in the system configuration.

Method: GET

Syntax:
http://<servername>/jpg[/<camera>]/image.jpg

with the following parameter
Parameter | Values | Description
<camera> | 1, 2, 3, 4 or quad1 | Select input source. Applies only to servers with more than one input source. Default: default camera.

1 Product-dependent. Check the product's specification.

Example: Request JPEG image from default camera with default resolution and compression.
http://myserver/jpg/image.jpg

Example: Request JPEG image from camera number 2 with default resolution and compression.
http://myserver/jpg/2/image.jpg

Example: Request JPEG image containing four video sources.
http://myserver/jpg/quad/image.jpg

5.2.4.2 JPEG image (snapshot) CGI request

Request a JPEG image (snapshot) with specified properties.

Method: GET

Syntax:
http://<servername>/axis-cgi/jpg/image.cgi
[?<parameter>=<value>[&<parameter>=<value>...]]

with the following parameters and values
<parameter>=<value> | Values | Description
resolution=<string> | 1280x1024, 1280x960, 1280x720, 768x576, 4CIF, 704x576, 704x480, VGA, 640x480, 640x360, 2CIFEXP, 2CIF, 704x288, 704x240, 480x360, CIF, 384x288, 352x288, 352x240, 320x240, 240x180, QCIF, 192x144, 176x144, 176x120, 160x120 1 | Specify the resolution of the returned image.
camera=<string> | 1, 2, 3, 4 or quad 1 | Applies only to video servers with more than one video input. Selects the source camera.
compression=<int> | 0 - 100 1 | Adjusts the compression level of the image. Higher values correspond to higher compression, i.e. lower quality and smaller image size. Note: This value is internally mapped and is therefore product-dependent.
colorlevel=<int>2 | 0 - 100 1 | Sets level of color or grey-scale. 0 = grey-scale, 100 = full color. Note: This value is internally mapped and is therefore product-dependent.
color=<int> | 0, 1 | Enables/disables color. 0 = black and white, 1 = color.
clock=<int> | 0, 1 | Shows/hides the time stamp. 0 = hide, 1 = show.
date=<int> | 0, 1 | Shows/hides the date. 0 = hide, 1 = show.
text=<int> | 0, 1 | Shows/hides the text. 0 = hide, 1 = show.
textstring=<string>2 | A string | The text shown in the image, the string must be URL encoded.
textcolor=<string>2 | black, white | The color of the text shown in the image.
textbackgroundcolor=<string>2 | black, white, transparent, semitransparent | The color of the text background shown in the image.
rotation=<int> | 0, 90, 180, 270 1 | Rotates the image clockwise.
textpos=<string> | top, bottom | The position of the string shown in the image.
overlayimage=<int>2 | 0, 1 | Enable/disable overlay image.
overlaypos=<int>x<int>2 | <xoffset>1x<yoffset>1 | Set the position of the overlay image.
squarepixel=<int>2 | 0, 1 | Enable/disable square pixel correction. Applies only to video servers.

1 Product-dependent. Check the product's specification.
2 Support for this parameter is product/release-dependent.

Example: Request a JPEG image from camera 1 with a resolution of 320x240 and compression of 25.
http://myserver/axis-cgi/jpg/image.cgi?resolution=320x240&camera=1&compression=25

Example: Request a JPEG image from camera 2 with the text My Camera displayed.
http://myserver/axis-cgi/jpg/image.cgi?camera=2&text=1&textstring=My%20Camera

5.2.4.3 JPEG image response

When a JPEG image is requested, the server returns either the specified JPEG image file or an error.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: image/jpeg\r\n
Content-Length: <image size>\r\n
\r\n
<JPEG image data>\r\n

Example: Requested JPEG image.
HTTP/1.0 200 OK\r\n
Content-Type: image/jpeg\r\n
Content-Length: 15656\r\n
\r\n
<JPEG image data>\r\n

5.2.4.4 JPEG buffer request

Requests for controlling image buffers via HTTP.

Method: GET

Syntax:
http://<servername>/axis-cgi/buffer/command.cgi?
<parameter>=<value>[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
do=<string> | start stop get reset remove | start = create a new image buffer. stop = this corresponds to an alarm occurring and it makes the image buffer store post-alarm images. The buffer will stop after all post-alarm images have been taken. get = used to fetch an image from the image buffer. reset = restarts the image buffer, removing any buffered images. remove = removes the image buffer, including any buffered images.
buffername=<string> | <string> | Name used for identifying the buffer.
uri=<string> | <string> | Corresponding image URI to be used by the image buffer. Note: Must be URI encoded. The URI should also begin with "ftp://".
prealarm=<int> | 0, ... | Number of images to be saved in the pre-alarm buffer.
postalarm=<int> | 0, ... | Number of images to be saved after an alarm occurs.
predelay=<int> | <milliseconds> | The preferred time between the pre-alarm images in milliseconds.
postdelay=<int> | <milliseconds> | The preferred time between the post-alarm images in milliseconds.
index=<int> | <image number> | The index of an image in the buffer.
range=<string> | all, allpre, allpost, <index>-<index> | Retrieve a range of images from the image buffer. all = get all the images in the buffer. allpre = get all the pre alarm images. allpost = get all the post alarm images. <index>-<index> = get images in the specified range.

Example 1: Create an image buffer, named DOOR1, with 10 pre-alarm images and 15 post-alarm images.
http://myserver/axis-cgi/buffer/command.cgi?do=start&buffername=DOOR1&prealarm=10
&postalarm=15&uri=ftp://jpg/1/image.jpg

Example 2: Stop a buffer.
http://myserver/axis-cgi/buffer/command.cgi?do=stop&buffername=DOOR1

Example 3: Get images from the buffer.
http://myserver/axis-cgi/buffer/command.cgi?do=get&buffername=DOOR1&index=1

Example 4: Create an image buffer, named DOOR2. The images should be taken from camera 1 and have a resolution of 320x240 pixels. Five post-alarm images should be stored.
http://myserver/axis-cgi/buffer/command.cgi?do=start&buffername=DOOR2
&postalarm=5&uri=ftp://jpg/image.jpg?resolution=320x240&camera=1

5.2.4.5 MJPG video request

Returns a multipart image stream with the default resolution and compression as defined in the system configuration.

Method: GET

Syntax: Request Multipart JPEG image.
http://<servername>/mjpg[/<camera>]/video.mjpg

with the following parameter
Parameter | Values | Description
<camera> | 1, 2, 3, 4 or quad1 | Select input source. Applies only to servers with more than one input source. Default: default camera.

1 Product-dependent. Check the product's specification.

Example: Request JPEG image stream from the 2nd camera with default resolution and compression.
http://myserver/mjpg/2/video.mjpg

Example: Request quad composed JPEG image stream with default resolution and compression.
http://myserver/mjpg/quad/video.mjpg

5.2.4.6 MJPG video CGI request

Request a Multipart-JPEG image stream (video) with specified properties.

Method: GET

Syntax:
http://<servername>/axis-cgi/mjpg/video.cgi
[?<parameter>=<value>[&<parameter>=<value>...]]

with the following parameters and values
<parameter>=<value> | Values | Description
resolution=<string> | 1280x1024, 1280x960, 1280x720, 768x576, 4CIF, 704x576, 704x480, VGA, 640x480, 640x360, 2CIFEXP, 2CIF, 704x288, 704x240, 480x360, CIF, 384x288, 352x288, 352x240, 320x240, 240x180, QCIF, 192x144, 176x144, 176x120, 160x120 1 | Specify the resolution of the returned image.
camera=<string> | 1, 2, 3, 4 or quad 1 | Applies only to video servers with more than one video input. Selects the source camera.
compression=<int> | 0 - 100 1 | Adjusts the compression level of the image. Higher values correspond to higher compression, i.e. lower quality and smaller image size. Note: This value is internally mapped and is therefore product-dependent.
colorlevel=<int>2 | 0 - 100 1 | Sets level of color or grey-scale. 0 = grey-scale, 100 = full color. Note: This value is internally mapped and is therefore product-dependent.
color=<int> | 0, 1 | Enables/disables color. 0 = black and white, 1 = color.
clock=<int> | 0, 1 | Shows/hides the time stamp. 0 = hide, 1 = show.
date=<int> | 0, 1 | Shows/hides the date. 0 = hide, 1 = show.
text=<int> | 0, 1 | Shows/hides the text. 0 = hide, 1 = show.
textstring=<string>2 | A string | The text shown in the image, the string must be URL encoded.
textcolor=<string>2 | black, white | The color of the text shown in the image.
textbackgroundcolor=<string>2 | black, white, transparent, semitransparent | The color of the text background shown in the image.
textposition=<string>2 | top, bottom | The position of the string shown in the image.
rotation=<int> | 0, 90, 180, 270 1 | Rotates the image clockwise.
textpos=<int>2 | 0, 1 | Specify text position. 0 = top, 1 = bottom.
overlayimage=<int>2 | 0, 1 | Enable/disable overlay image.
overlaypos=<int>x<int>2 | <xoffset>1x<yoffset>1 | Set the position of the overlay image.
squarepixel=<int>2 | 0, 1 | Enable/disable square pixel correction. Applies only to video servers.
duration=<int> | 0, ... | Specifies for how many seconds the video will be generated and pushed to the client. 0 = unlimited.
nbrofframes=<int> | 0, ... | Specifies how many frames the server will generate and push. 0 = unlimited.
fps=<int> | 0, ... | Using fps it is possible to specify the frame rate from the server. 0 = unlimited.

1 Product-dependent. Check the product's specification.
2 Support for this parameter is product/release-dependent.

Example: Request a Multipart JPEG image stream from camera 1 with a resolution of 320x240 and compression of 25.
http://myserver/axis-cgi/mjpg/video.cgi?resolution=320x240&camera=1&compression=25

Example: Request a Multipart JPEG image stream from camera 1 with a frame rate of 5.
http://myserver/axis-cgi/mjpg/video.cgi?fps=5

5.2.4.7 MJPG video response

When MJPG video is requested, the server returns a continuous flow of JPEG files. The content type is "multipart/x-mixed-replace" and each image ends with a boundary string <boundary>. The returned image and HTTP data is equal to the request for a single JPEG image.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=<boundary>\r\n
\r\n
--<boundary>\r\n
<image>
where the proposed <boundary> is
myboundary
and the returned <image> field is
Content-Type: image/jpeg\r\n
Content-Length: <image size>\r\n
\r\n
<JPEG image data>\r\n
--<boundary>\r\n
<image>

Example: Requested Multipart JPEG image.
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=myboundary\r\n
\r\n
--myboundary\r\n
Content-Type: image/jpeg\r\n
Content-Length: 15656\r\n
\r\n
<JPEG image data>\r\n
--myboundary\r\n
Content-Type: image/jpeg\r\n
Content-Length: 14978\r\n
\r\n
<JPEG image data>\r\n
--myboundary\r\n
Content-Type: image/jpeg\r\n
Content-Length: 15136\r\n
\r\n
<JPEG image data>\r\n
--myboundary\r\n
 .
 .
 .

5.2.5 Image overlay

These CGI requests handle upload, creation, deletion and selection of overlay images.

5.2.5.1 Upload image

Uploads the source image that is converted to an overlay image by Create image.

Method: POST

Syntax:
http://<servername>/axis-cgi/operator/call_overlay_upload.cgi

The file content is provided in the HTTP body according to the format given in RFC 1867. The body is created automatically by the browser if using HTML form with input type "file". A few rules apply to the uploaded image:

  1. Supported file format is BMP, more precisely Windows 4- and 24-bit and OS/2 4 bit.
  2. Both the width and height of the image must be evenly divisible by 4.

Example: Upload of image logo.bmp, where "\r\n" has been omitted in the HTTP body.
POST /axis-cgi/operator/call_overlay_upload.cgi? HTTP/1.0\r\n
Content-Type: multipart/form-data; boundary=AaBo3x\r\n
Content-Length: <content length>\r\n
\r\n
--AaBo3x\r\n
Content-Disposition: form-data; name="fileInput"; filename="logo.bmp"\r\n
Content-Type: image/bmp\r\n
\r\n
<file content of logo.bmp>
\r\n
--AaBo3x--\r\n

5.2.5.2 Create image

Converts the image uploaded by Upload image to an overlay image. The original image is deleted and the new is created as /etc/overlays/<file prefix>(<width>x<height>).ovl. E.g. the uploaded file logo.bmp has dimensions 200x100. The created overlay image will be /etc/overlays/logo(200x100).ovl. Note that this enables upload of multiple bitmap images with identical names as long as they have different dimensions.

Method: POST

Syntax:
http://<servername>/axis-cgi/operator/create_overlay.cgi?
[<parameter>=<value>[&<parameter>=<value>...]]

with the following parameters and values
<parameter>=<value> | Values | Description
type=<string> | fullcolor, fourbits | For 24 and 4 bit images respectively.
ov_path=<string> | <string> | The path for the uploaded file name, normally /tmp/<file name>, e.g. /tmp/logo.bmp.

Below parameters are only relevant for full color (24 bit) images
usetransparent=<string> | true, false | true if any color in the image shall be made transparent.
colorcode=<string> | 6 digit RGB hexadecimal value in the format RRGGBB | The RGB color code for the color that shall be made transparent, e.g. 1F0A0F.

Below parameters are only relevant for 4 bit images. Each of the 16 colors can have its own individual setting. # denotes the color number between 1-16
o_t#=<string> solid,
halftransparent,
transparent 		Transparency setting.

solid = the color is displayed normally.

halftransparent = the color is mixed with the background video image, which is partially visible.

transparent = the color is completely transparent and the background video image is fully visible.

Since this request only supports the POST method and not the simpler GET method, we merely give the parameter values (URL encoding omitted) here for perspicuousness.

Example: Convert the 24 bit bitmap image with dimensions 120 x 60, uploaded as /tmp/logo.bmp, into the full color overlay image /etc/overlays/logo(120x60).ovl.
type=fullcolor&ov_path=/tmp/logo.bmp

Example: Convert the 4 bit bitmap image with dimensions 80 x 160, uploaded as /tmp/logo.bmp, into a 16 color overlay image /etc/overlays/logo(80x160).ovl where color number 3 has been made transparent.
type=fullcolor&ov_path=/tmp/logo.bmp&o_t3=transparent

5.2.5.3 Delete image

Removes the overlay image from the file system.

Method: POST

Syntax:
http://<servername>/axis-cgi/operator/call_overlay_del.cgi?<file path>

<file path> is the complete path to the overlay image as described in the previous CGI request (Create image), e.g. /etc/overlays/logo(200x100).ovl.

Example: Deletes the overlay image /etc/overlays/logo(80x20).ovl.
http://myserver/axis-cgi/operator/call_overlay_del.cgi?
%2Fetc%2Foverlays%2Flogo(80x20).ovl

5.2.5.4 Set image

Selects which overlay image to be used. Note that for the image to be visible for a particular video number, it must be enabled for that video as described in the parameter document, which also explains how to set the position of the overlay image.

Method: POST

Syntax:
http://<servername>/axis-cgi/operator/call_overlay_set.cgi?<value>

with the following parameter values
<value> | Values | Description
<string> | <string> | no overlay - no overlay image selected. <file path> - the file path of the overlay image to use, as described in the CGI request for creation of overlay image, e.g. /etc/overlays/logo(200x100).ovl.

Example: Select the overlay image /etc/overlays/logo(120x40).ovl to be used for all video channels.
http://myserver/axis-cgi/operator/call_overlay_set.cgi?
%2Fetc%2Foverlays%2Flogo(120x40).ovl

5.2.6 MPEG-4

Due to the streaming properties of the MPEG-4 media format, the control of the MPEG-4 streams is handled via RTSP, which is an HTTP-like protocol designed for controlling real-time multi-media streams. Please check the RTSP API.

5.2.6.1 MPEG-4 SDP description request

Returns the SDP description for an MPEG-4 stream.

Method: GET

Syntax:
http://<servername>/mpeg4[/<camera>]/video.sdp 1
http://<servername>/mpeg4[/<camera>]/media.sdp 1

1Firmware dependent. media.sdp should be used for firmware 4.20 and above.

with the following parameter
<value> | Values | Description
<camera> | 1, 2, 3, 4 or quad 1 | Select input source. Applies only to servers with more than one input source. Default: default camera.

1 Product dependent. Check the product specification.

Example: Request the MPEG-4 SDP description for the first camera.
http://myserver/mpeg4/1/media.sdp

5.2.6.2 Restart the MPEG-4 stream

Restarts the MPEG-4 stream. This will force the server to break the current GOV and insert configuration headers followed by a new GOV. This can be used by a new client to make sure that it can start to show the stream as fast as possible.

Method: GET, POST

Syntax:
http://<servername>/axis-cgi/mpeg4/restart_stream.cgi[?<parameter>=<value>&...]

with the following parameters and values
<value> | Values | Description
camera=<string> | 1, 2, 3, 4 or quad 1 | Select input source. Applies only to servers with more than one input source. Default: default camera.

1 Product dependent. Check the product specification.

Example: Restart the MPEG-4 stream from the first camera.
http://myserver/axis-cgi/mpeg4/restart_stream.cgi?camera=1

5.2.6.3 MPEG-4 statistics

It is possible to retrieve some statistics about the generated MPEG-4 streams. These statistics reflects the servers point-of-view of the stream, i.e., a slow network or client may result in a difference in appearance compared to these values.

Method: GET, POST

Syntax:
http://<servername>/axis-cgi/operator/mpeg4_statistics.cgi[?<parameter>=<value>&...]

with the following parameters and values
<value> | Values | Description
camera=<string> | 1, 2, 3, 4 or quad 1 | Select input source. Applies only to servers with more than one input source. Default: default camera.
stats=<string>[,<string>...] | bitrate, minbitrate, maxbitrate, framerate, minframerate, maxframerate, compression | Which statistics to include. Default: all
reset=<int> | 1 | Reset the min and max values to the current values.

1 Product dependent. Check the product specification.

Example: Retrieve all statistics for the first camera.
http://myserver/axis-cgi/operator/mpeg4_statistics.cgi?camera=1

Example: Retrieve the current bit rate and frame rate for the default camera.
http://myserver/axis-cgi/operator/mpeg4_statistics.cgi?stats=bitrate,framerate

Example: Reset the min and max values for the first camera.
http://myserver/axis-cgi/operator/mpeg4_statistics.cgi?camera=1&reset=1

5.3 PTZ

The requests specified in the PTZ section are supported by those video products that have support for Pan/Tilt/Zoom devices.

Note! Installing a PTZ driver is done in three main steps:

  1. Upload the driver
  2. Associate the driver with a serial port
  3. Connect cameras to the serial port

PTZ driver update can accomplish step 1 and 2 in one request.
PTZ administration can accomplish step 2 if the driver is already present in the product.
Open serial port accomplishes step 3.

5.3.1 PTZ driver update

Handles installation and removal of PTZ drivers.

Method: POST

Syntax:
http://<servername>/axis-cgi/ptz/ptzupdate.cgi?
[<parameter>=<value>[&<parameter>=<value>...]]

with the following parameters and values
<parameter>=<value> | Values | Description
replacedriver=<string> | Names from the parameter values in group root.PTZ.PTZDrivers.Driver# where '#' denotes the index for the installed driver. | Uninstall currently installed driver <string>. See below for rules concerning driver replacement.
port=<int> | 1, ... 1 | Associate the driver with this serial port. See below for rules concerning driver replacement.
force=<string> | yes | Force driver installation even if the driver is potentially incompatible with firmware (if for instance a relevant library has been considerably updated) but may still work well. This parameter has no effect on serious incompatibilities such as wrong CPU architecture.

1 Product-dependent. Check the product's specification.

The file content, if any, is provided in the HTTP body according to the format given in RFC1867. The body is created automatically by the browser if using HTML form with input type "file". Empty file content will result in the removal of the driver only.

The following rules apply for driver replacement, in descending order of priority:

  1. If parameter replacedriver is provided, the given driver will be uninstalled.
  2. If parameter port is provided, the driver currently associated with that serial port, if any, is uninstalled.
  3. If the maximum number of installed drivers (equals the number of serial ports) is not reached, no driver is uninstalled.
  4. Any driver not currently associated with any serial port will be uninstalled.

Example: The driver "Videmech" is currently associated with serial port 1. A client sends this request, where "\r\n" has been omitted in the HTTP body.
POST /axis-cgi/ptz/ptzupdate.cgi HTTP/1.0\r\n
Content-Type: multipart/form-data; boundary=AaBo3x\r\n
Content-Length: <content length>\r\n\r\n
--AaBo3x
Content-Disposition: form-data; name="port"

1
--AaBo3x
Content-Disposition: form-data; name="Upload Driver"; filename="Philips-1.0.ptz"
Content-Type: text/plain

<file content of Philips-1.0.ptz>

--AaBo3x--

I.e. providing the parameter port=1 together with the file content of the installation file Philips-1.0.ptz for the new driver in the HTTP body.

This will uninstall the driver "Videmech" and install the "Philips" driver provided in the HTTP body. The new driver is then associated with serial port 1.

5.3.2 PTZ administration

Handles relations between a driver and a serial port. When associating a driver with a serial port, any currently associated driver is first disassociated. The new driver is then activated to control units on that serial port. Any disassociated driver is automatically stopped.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/com/ptzadmin.cgi?
<parameter>[=<value>][&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
port=<int> | 1, ... 1 | Selects the serial port.
ptzdrivername=<string> | Name of a driver from values in parameter group root.PTZ.PTZDrivers | Associates a driver name with a serial port. If "none" the current driver (if any) is disassociated from the serial port.

1 Product-dependent. Check the product's specification.

Example: Associate driver "Videmech" with serial port 2.
http://myserver/axis-cgi/com/ptzadmin.cgi?port=2&ptzdrivername=Videmech

5.3.3 PTZ control

To control the Pan, Tilt and Zoom behavior of a PTZ unit, the following PTZ control URL is used. This URL has view access rights.

Important:
Some PTZ units automatically reduce pan and tilt movements as the zoom factor increases. Therefore, the actual movement may be less than what is requested of these units.
The PTZ control is device-dependent. For information about supported parameters and actual parameter values, please check the specification of the Axis PTZ driver you intend to use. The following table is only an overview.

Note:
The URL must follow the standard way of writing a URL, (RFC 2396: Uniform Resource Identifiers (URI) Generic Syntax); that is, spaces and other reserved characters (";", "/", "?", ":", "@", "&", "=", "+", "," and "$") within a <parameter> or a <value> must be replaced with %<ASCII hex>. For example, in the string My camera, the space will have to be replaced with %20, My%20camera.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/com/ptz.cgi?<parameter>=<value>[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
camera=<int> | 1, ... 1 | Applies only to video servers with more than one video input. Selects the source camera. If omitted, the default camera is used.
whoami=<string> | <any value> | Returns the name of the system-configured device driver.
center=<int>,<int> extrem3=<int>,<int> | <x>,<y> | Absolute: Used to send the coordinates for the point in the image where the user clicked. This information is then used by the server to calculate the pan/tilt move required to (approximately) center the clicked point. Relative: Used to send the coordinates for the point in the image where the user clicked. This information is then used by the server to calculate the direction and number of degrees to move. The number of degrees increases with the distance from the center of the image to the point clicked.
imagewidth=<int> | 1, ... 1 | Required in conjunction with center if the image width displayed is different from the default size of the image, which is product-specific.
imageheight=<int> | 1, ... 1 | Needed in conjunction with center if the image height is different from the default size, which is product-specific.
move=<string> | home, up, down, left, right, upleft, upright, downleft, downright | Absolute: Moves the device 5 degrees in the specified direction. Relative: Moves the device approx. 50-90 degrees2 in the specified direction. Note: home is only valid if any home position has been previously set with "home=yes".
pan=<float> | -180.0 - 180.0 | Absolute: Pans the device relative to the (0,0) position. Relative: n/a
tilt | -180.0 - 180.0 | Absolute: Tilts the device relative to the (0,0) position. Relative: n/a
zoom=<int> | 1 - 9999 | Absolute: Zooms the device n steps. Relative: n/a
focus=<int> | 1 - 9999 | Absolute: Move Focus n steps. Relative: n/a
iris=<int> | 1 - 9999 | Absolute: Move iris n steps. Relative: n/a
rpan=<float> | -360.0 - 360.0 | Absolute: Pans the device n degrees relative to the current position. Relative: Pans the device approx. n degrees relative to the current position
rtilt=<float> | -360.0 - 360.0 | Absolute: Tilts the device n degrees relative to the current position. Relative: Tilts the device approx. n degrees relative to the current position.
rzoom=<int> | -9999 - 9999 | Absolute: Zooms the device n steps relative to the current position. Positive values mean zoom in, negative values mean zoom out. Relative: Zooms the device approx. n steps relative to the current position. Positive values mean zoom in, negative values mean zoom out.
rfocus=<int> | -9999 - 9999 | Absolute: Move Focus n steps relative to the current position. Positive values mean focus far, negative values mean focus near. Relative: Move Focus approx. n steps relative to the current position. Positive values mean focus far, negative values mean focus near.
riris=<int> | -9999 - 9999 | Absolute: Move iris n steps relative to the current position. Positive values mean open iris, negative values mean close iris. Relative: Move iris approx. n steps relative to the current position. Positive values mean open iris, negative values mean close iris.
autofocus=<string> | on, off | Autofocus On/Off.
autoiris=<string> | on, off | Autoiris On/Off.
continuouspantiltmove= <int>,<int> | -100 - 100,-100 - 100 | Continuous pan/tilt motion. Positive values mean right (pan) and up (tilt), negative values mean left (pan) and down (tilt). "0,0" means stop. Values as <pan speed>,<tilt speed>
continuouszoommove=<int> | -100 - 100 | Continuous zoom motion. Positive values mean zoom in and negative values mean zoom out. "0" means stop.
continuousfocusmove=<int> | -100 - 100 | Continuous focus motion. Positive values mean focus near and negative values mean focus far. "0" means stop.
continuousirismove=<int> | -100 - 100 | Continuous iris motion. Positive values mean iris open and negative values mean iris close. "0" means stop.
auxiliary=<string> | <function name> | Activates/deactivates auxiliary functions of the device where <function name> is the name of the device-specific function.
setserverpresetname=<string> | <preset name>4 | Associates the current position to <preset name> as a preset position in the server. Note: This request is moved to ptzconfig.zgi
setserverpresetno=<int> | 1, ... | Saves the current position as a preset position number in the server. Note: This request is moved to ptzconfig.zgi
home=<string> | yes | Makes the current position the home position for the camera. Used with setserverpresetname or setserverpresetno. Note: This request is moved to ptzconfig.zgi
removeserverpresetname=<string> | <preset name>4 | Removes the specified preset position associated with <preset name>. Note: This request is moved to ptzconfig.zgi
removeserverpresetno=<int> | 1, ... | Removes the specified preset position. Note: This request is moved to ptzconfig.zgi
gotoserverpresetname=<string> | <preset name>4 | Move to the position associated with the <preset name>.
gotoserverpresetno=<int> | 1, ... | Move to the position associated with the specified preset position number.
setdevicepreset=<int> | <preset pos> | Bypasses the presetpos interface and tells the device to save its current position as preset position <preset pos> directly in the device, where <preset pos> is a device-specific preset position number. Note: This request is moved to ptzconfig.zgi
gotodevicepreset=<int> | <preset pos> | Bypasses the presetpos interface and tells the device to go directly to the preset position number <preset pos> stored in the device, where the <preset pos> is a device-specific preset position number.
bartype=<string> | absolute, relative | Used together with barcoord and determines how the bar shall be interpreted. If "absolute", the endpoints of the bar correspond to the current limits. If "relative", the behavior is device-dependent. The default interpretation is "absolute" for panbar, tiltbar and zoombar and "relative" for focusbar and irisbar.
barcoord=<int>,<int> | <x>,<y> | Used in conjunction with panbar, tiltbar, zoombar, focusbar or irisbar, to send coordinates to the server.
panbar=<int>,<string> | <length>,<alignment> | <length> is the length of the bar in pixels, which is needed in order to calculate the center of the bar. <alignment> is one of the strings "horisontal" or "vertical". The alignment string determines if the x (horisontal) or the y (vertical) coordinate from barcoord is used, i.e. if the bar is horisontal; use "horisontal" and if the bar is vertical; use "vertical" as alignment.
tiltbar=<int>,<string> | <length>,<alignment> | <length> is the length of the bar in pixels, which is needed in order to calculate the center of the bar. <alignment> is one of the strings "horisontal" or "vertical". The alignment string determines if the x (horisontal) or the y (vertical) coordinate from barcoord is used, i.e. if the bar is horisontal; use "horisontal" and if the bar is vertical; use "vertical" as alignment.
zoombar=<int>,<string> | <length>,<alignment> | <length> is the length of the bar in pixels, which is needed in order to calculate the center of the bar. <alignment> is one of the strings "horisontal" or "vertical". The alignment string determines if the x (horisontal) or the y (vertical) coordinate from barcoord is used, i.e. if the bar is horisontal; use "horisontal" and if the bar is vertical; use "vertical" as alignment.
focusbar=<int>,<string> | <length>,<alignment> | <length> is the length of the bar in pixels, which is needed in order to calculate the center of the bar. <alignment> is one of the strings "horisontal" or "vertical". The alignment string determines if the x (horisontal) or the y (vertical) coordinate from barcoord is used, i.e. if the bar is horisontal; use "horisontal" and if the bar is vertical; use "vertical" as alignment.
irisbar=<int>,<string> | <length>,<alignment> | <length> is the length of the bar in pixels, which is needed in order to calculate the center of the bar. <alignment> is one of the strings "horisontal" or "vertical". The alignment string determines if the x (horisontal) or the y (vertical) coordinate from barcoord is used, i.e. if the bar is horisontal; use "horisontal" and if the bar is vertical; use "vertical" as alignment.
speed=<int> | 1 - 100 | Sets the head speed of the device that is connected to the specified camera.
imagerotation=<int> | 0, 90, 180, 270 | If PTZ command refers to an image stream that is rotated differently than the current image setup, then the image stream rotation must be added to each command with this parameter to allow the server to compensate.
query=<string> | speed, position, presetposcam, presetposall | Returns the current parameter values.
info=<int> | 1 | Returns a description of available PTZ commands. No PTZ control is performed.

1 Product-dependent. Check the product's specification.
2 Actual values are device driver-specific.
3 Obsolete.
4 <preset name> is a string with a maximum of 31 characters, ~ is not allowed.

Example: Request information about which PTZ commands are available for camera 3.
http://myserver/axis-cgi/com/ptz.cgi?info=1&camera=3

5.3.4 PTZ configuration

Configure PTZ preset positions. On Screen Display (OSD) control.

Note: This request requires administrator access (administrator authorization).

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/com/ptzconfig.cgi?
<parameter>=<value>[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
camera=<int> | 1, ... 1 | Applies only to video servers with more than one video input. Selects the source camera. If omitted, the default camera is used.
osdmenu=<string> | open, close, up, down, left, right, select, back | Commands to control the OSD menu in the camera. Note that the support of the different commands, and the behavior of the commands, is driver dependant.
setserverpresetname=<string> | <preset name>1 | Associates the current position to <preset name> as a preset position in the server.
setserverpresetno=<int> | 1, ... | Saves the current position as a preset position number in the server.
home=<string> | yes | Makes the current position the home position for the camera. Used with setserverpresetname or setserverpresetno.
removeserverpresetname=<string> | <preset name>1 | Removes the specified preset position associated with <preset name>.
removeserverpresetno=<int> | 1, ... | Removes the specified preset position.
setdevicepreset=<int> | <preset pos> | Bypasses the presetpos interface and tells the device to save its current position as preset position <preset pos> directly in the device, where <preset pos> is a device-specific preset position number.

1 <preset name> is a string with a maximum of 31 characters, ~ is not allowed.

5.3.5 Set PTZ parameters

Set PTZ parameters. Listing the PTZ parameters is done with param.cgi, List parameters.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/com/ptzparam.cgi?
<parameter>=<value>[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
port=<int> | 1, ... 1 | Selects the serial port. Used together with grpdefault below, for group "Serial".
camera=<int> | 1, ... 1 | Selects the camera. If omitted, the default camera is used. Used together with grpdefault below, for all groups but "Serial".
<PTZ parameter>2=<value> | Any parameter in the groups PTZ.Limit.L#, where # denotes the camera number, e.g. PTZ_Limit_L2_MaxPan | Sets a PTZ limit parameter. Max values are adjusted so that they are greater than or equal to min values, e.g. PTZ.Limit.L2.MaxPan >= PTZ.Limit.L2.MinPan.
pardefault=<string>2 | Any parameter in the group: Serial.Ser# where # denotes the serial port number, and the groups: PTZ.Support.S# PTZ.Limit.L# PTZ.Various.V# PTZ.UserBasic.U# PTZ.UserAdv.U# where # denotes the camera number. | Sets the default value for a parameter. Note: No max value validation is performed as with previous CGI parameter.
grpdefault=<string> | Serial, Support, Limit, Various, UserBasic, UserAdv | Sets the default value for a parameter group. The default values are taken from the driver currently associated with the port or camera.

1 Product-dependent. Check the product's specification.
2 The path shall have the format root_PTZ..., e.g. root_PTZ_Limit_L1_MaxPan for parameter PTZ.Limit.L1.MaxPan. The reason for this format is related to internal ssi implementation.

In the examples below, assume the driver installed on index 1 is associated with serial port 2 (ttyS1) and camera 3 is mapped to serial port 2.

Example: Set PTZ.Limit.L3.MaxPan to 110 and adjust it so that it is >= PTZ.Limit.L3.MinPan.
http://myserver/axis-cgi/com/ptzparam.cgi?root_PTZ_Limit_L3_MaxPan=110

Example: Set PTZ.Limit.L3.MaxPan to the value of PTZ.Driver1.Limit.L0.MaxPan.
http://myserver/axis-cgi/com/ptzparam.cgi?pardefault=root_PTZ_Limit_L3_MaxPan

Example: Copy the parameter values from group PTZ.Driver1.Limit.L0 to group PTZ.Limit.L3.
http://myserver/axis-cgi/com/ptzparam.cgi?camera=3&grpdefault=Limit

Example: Copy the parameter values from group PTZ.Driver1.Serial.S0 to group Serial.Ser1.
http://myserver/axis-cgi/com/ptzparam.cgi?port=2&grpdefault=Serial

5.3.6 PTZ control queue

If the PTZ control queuing mechanism is enabled for the camera concerned, control of PTZ units is limited to the client currently possessing the control, if any. This CGI request handles requests concerning the control queue.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/com/ptzqueue.cgi?
<parameter>=<value>[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
control=<string> | request, drop, query | "request" requests PTZ control. "drop" drops the PTZ control or leaves the queue. "query" reports the current status for the client. For possessing clients with no peers existing in the queue, "request" will reset the control timer. For all other clients, "request" will have the same effect as "query".
camera=<int> | 1, ... 1 | The camera number. If omitted, the default camera is used.

1 Product-dependent. Check the product's specification.

Example: Request PTZ control for camera 2.
http://myserver/axis-cgi/com/ptzqueue.cgi?control=request&camera=2

5.3.7 PTZ control queue response

The 200 OK response on success for "request" and "query" has a format that enables simple java-script implementations using the DOM API and should be easy to parse for components such as ActiveX as well.

Return: A successful request:
HTTP/1.0 200 OK\r\n
Content-Length: <length>\r\n
\r\n
<body><a name="<pos>"></a><a name="<seconds>"></a><a name="<period>"></a></body>
where
<pos> can have a value from 0 to the maximum value of how many clients are allowed in the queue. This value is the given position in the queue. 0 means that the client is not in the queue, 1 means control is possessed. For 0 the other parameters are undefined.
<seconds> is the estimated number of seconds remaining, i.e. for position 1 the remaining control time and for other positions, the time until position 1 is reached. -1 denotes that the time remaining to get control cannot be estimated. This means that a client in the queue has the "TimeoutType" set to infinity.
<period> is the recommended time in seconds when the client should send a new "control=query" requests. To stay active in the queue the client must regularly send PTZ requests to the camera. An inactive client will automatically be removed from the queue.

On failure no anchor elements are provided but simply the error message in plain text.

Return: A failed request:
HTTP/1.0 200 OK\r\n
Content-Length: <length>\r\n
\r\n
Error:\r\n
<error information>

Example: Control requested.
HTTP/1.0 200 OK\r\n
Content-Length: 63\r\n
\r\n
<body><a name="3"></a><a name="410"></a><a name="5"></a></body>

This means the client was assigned queue position 3. The expected number of seconds until control is possessed is 410 and the recommended time until the next request is 5 seconds.

5.4 Motion Detection

To be able to define Motion Detection parameters, the video product must have built-in Motion Detection.
A motion detection window is defined by several parameters. The motion detection parameters reside within a dynamic parameter group. Accordingly it is possible to add, remove, list and update the motion detection parameters with param.cgi, The dynamic motion detection parameter groups are divided into sub groups of the main motion parameter group, i.e. Motion.M<group number>.<parameter name>. group number is a unique number which is stated when a new dynamic parameter group is created, i.e. Motion.M3.

5.4.1 Add a Motion Detection window

When adding a Motion Detection window, the template file motion is used. The group number should be excluded when adding a new Motion Detection window with specified values since the group number will be defined when the new dynamic group is created.

Example: Add a new Motion Detection window with default values.
http://myserver/axis-cgi/operator/param.cgi?action=add&group=Motion&template=motion

Example: Add a new Motion Detection window with specified values.
http://myserver/axis-cgi/operator/param.cgi?action=add&group=Motion&template=motion
&Motion.M.Name=Entrance&Motion.M.Top=500&Motion.M.Bottom=7000&Motion.M.Left=5000
&Motion.M.Right=8500

Return:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
M<group number> OK\r\n

5.4.2 Remove a Motion Detection window

Example: Remove Motion Detection window defined within Motion.M3 and Motion.M5.
http://myserver/axis-cgi/operator/param.cgi?
action=remove&group=Motion.M3,group=Motion.M5

5.4.3 Update the Motion Detection parameters

Example: Update the parameters for an existing Motion Detection window.
http://myserver/axis-cgi/operator/param.cgi?action=update&Motion.M1.Top=1500
&Motion.M1.Bottom=8000

5.4.4 List the Motion Detection parameters

Example: List the Motion.M1 and Motion.M2 parameters.
http://myserver/axis-cgi/operator/param.cgi?
action=list&group=Motion.M1,group=Motion.M2

Example: List all Motion Detection windows.
http://myserver/axis-cgi/operator/param.cgi?action=list&group=Motion

5.4.5 Get the Motion Detection level

It is possible to get the current Motion Detection levels from certain Motion Detection windows or from all MD windows, except from those windows that are defined to be Motion Detection exclude windows. It is also possible to define a Motion Detection window configuration and get the related motion levels in return. The URL stated below is used.

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/motion/motiondata.cgi[?<parameter>=<value>...]

with the following parameter and value
<parameter>=<value> | Values | Description
group=<int>[,<int>, ...] | <group number>[,<group number>, ...] | Specify the Motion Detection windows that are of interest. Excluding the group parameter will return all Motion Detection level information from all Motion Detection windows. Exclude windows are ignored.
<string>=<string> | <parameter name>=<value> | Get the Motion Detection levels related to a specific window configuration. The last part of the parameters in the parameter group Motion.M#.<name> (where # is a number) can be used, e.g. Sensitivity and History.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=<boundary>\r\n
\r\n
--<boundary>\r\n
<motion levels>
where the proposed boundary <boundary> is
axismdb
and the <motion levels> part is
Content-Type: text/plain\r\n
\r\n
<motion level for window with lowest group number>
--<boundary>\r\n
and <motion level for window with group number n>" is
group=<group number n>;level=<motion level for n>;threshold=
<threshold level for n>;\r\n[ <motion level for window n+1> ]

Example: Get Motion Detection levels related to Motion Detection windows defined within Motion.M0 and Motion.M1.
http://myserver/axis-cgi/motion/motiondata.cgi?group=0,1

Return: The example above returns the following.
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=axismdb\r\n\r\n
--axismdb\r\n
Content-Type:text/plain\r\n\r\n
group=0;level=28;threshold=45;\r\n
group=1;level=43;threshold=25;\r\n
--axismdb\r\n
Content-Type:text/plain\r\n\r\n
group=0;level=54;threshold=45;\r\n
group=1;level=38;threshold=25;\r\n
--axismdb\r\n
Content-Type:text/plain\r\n\r\n
group=0;level=49;threshold=45;\r\n
group=1;level=19;threshold=25;\r\n
--axismdb\r\n
 .
 .
 .

Example: Get Motion Detection levels related to a specific window configuration. The group number related to this Motion Detection window configuration will always be X.
http://myserver/axis-cgi/motion/motiondata.cgi?
Name=Temp&ImageSource=2&WindowType=include
&Left=300&Right=500&Top=300&Bottom=500&Sensitivity=65&History=50&Size=35

Return: The example above returns the following:
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=axismdb\r\n\r\n
--axismdb\r\n
Content-Type:text/plain\r\n\r\n
group=X;level=16;threshold=35;\r\n
--axismdb\r\n
Content-Type:text/plain\r\n\r\n
group=X;level=55;threshold=35;\r\n
--axismdb\r\n
Content-Type:text/plain\r\n\r\n
group=X;level=39;threshold=35;\r\n
--axismdb\r\n
 .
 .
 .

  • If no Motion Detection windows are defined or only exclude windows are defined, HTTP/1.0 204 No Content is returned.
  • If any errors are found in the CGI request, HTTP/1.0 400 Bad Request is returned.
  • If too many clients try to get motion data, HTTP/1.0 503 Service Unavailable is returned.

5.5 I/O

The requests specified in the I/O section are supported by those products that have Input/Output connectors.

5.5.1 I/O control

5.5.1.1 Input

Input

Method: GET

Syntax:
http://<servername>/axis-cgi/io/input.cgi?<parameter>=<value>[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
check=<int>[,<int>, ...] | <id1>[,<id2>, ...] 1 | Returns the status (1 or 0) of one or more inputs numbered id1 ,id2, ....
checkactive=<int>[,<int>, ...] | <id1>[,<id2>, ...] 1 | Returns the status (active or inactive) of one or more inputs numbered id1,id2, ....
monitor=<int>[,<int>, ...]2 | <id1>[,<id2>, ...] 1 | Returns a multipart stream of "check" inputs (see return description below).

1 Number of inputs may differ for different cameras and video servers. See the product's specification.
2 Support for this parameter is product/release-dependent.

Return: "monitor", i.e., multipart "check" parameter
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=<boundary>\r\n
\r\n
--<boundary>\r\n
<monitor data>
where the proposed boundary <boundary> is
ioboundary
and the <monitor data> part is
Content-Type: text/plain\r\n
\r\n
<check data>
--<boundary>\r\n
and <check data> is
IO<n>:<action char>\r\n
and <n> is the I/O port number and <action char> is the action character described in the table above.
Note: The output can contain extra blank lines, i.e., extra \r\n within the sections.

Example: Monitor data on input ports 1, 2, 3, and 4.
http://myserver/axis-cgi/io/input.cgi?monitor=1,2,3,4

Example: Monitor data on input port 1.
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace; boundary=ioboundary\r\n
\r\n
\r\n
\r\n
\r\n
--ioboundary\r\n
Content-Type: text/plain\r\n
\r\n
IO0:/\n
\r\n
\r\n
--ioboundary\r\n
Content-Type: text/plain\r\n
\r\n
IO0:H\n
\r\n
--ioboundary\r\n
Content-Type: text/plain\r\n
\r\n
\r\n
IO0:\\n
\r\n
\r\n
--ioboundary\r\n
Content-Type: text/plain\r\n
\r\n
\r\n
\r\n
\r\n
--ioboundary\r\n
Content-Type: text/plain\r\n
\r\n
\r\n
 .
 .
 .

5.5.1.2 Output

Output

Method: GET

Syntax:
http://<servername>/axis-cgi/io/output.cgi?
<parameter>=<value>[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
check=<int>[,<int>, ...] | <id1>[,<id2>, ...] 1 | Returns the status (1 or 0) of one or more outputs numbered id1 ,id2, ....
checkactive=<int>[,<int>, ...] | <id1>[,<id2>, ...] 1 | Returns the status (active or inactive) of one or more outputs numbered id1 ,id2, ....
monitor=<int>[,<int>, ...] 2 | <id1>[,<id2>, ...] 1 | Returns a multipart stream of "check" outputs (see return description below).
action=<string> | [<id>1]:<a>[<wait> <a> ...] | Sets the output relay <id> active or inactive and waits <wait> milliseconds. Note that only one output relay can be activated/deactivated per request. <id> = Output number. If omitted, output 1 is selected. <a> = Action character: / or \ / = active, \ = inactive. <wait> = Delay in milliseconds.

1 Number of outputs may differ for different cameras and video servers. See the product's specification.
2 Support for this parameter is product/release-dependent.

Example: Set output 1 active.
http://myserver/axis-cgi/io/output.cgi?action=1:/

Example: Set two 300 ms pulses with 500 ms delay between the pulses on output 1.
http://myserver/axis-cgi/io/output.cgi?action=1:/300\500/300\

Example: Wait 1 second before setting output 1 active.
http://myserver/axis-cgi/io/output.cgi?action=1:1000/

5.5.2 Virtual I/O control

5.5.2.1 Input

Input

Method: GET

Syntax:
http://<servername>/axis-cgi/io/virtualinput.cgi?<parameter>=<value>

with the following parameter and values
<parameter>=<value> | Values | Description
action=<string> | [<id>]:<a> | Simulates an activation or inactivation of an Input connector or sets a virtual input <id> active or inactive. <id> = Input number. If omitted, input 1 is selected. <a> = Action character: / or \ / = active, \ = inactive.

Example: Set Input 1 active.
http://myserver/axis-cgi/io/virtualinput.cgi?action=1:/

Example: Pulse the Input. First set it active, wait 2 seconds, then set it inactive again.
http://myserver/axis-cgi/io/virtualinput.cgi?action=1:/2000\

5.6 Serial Port

The requests specified in the Serial Port section are supported by products with PTZ support.

5.6.1 Serial port control

Control serial port

Method: GET/POST

Syntax:
http://<servername>/axis-cgi/com/serial.cgi?
<parameter>=<value>[&<parameter>=<value>... ]

with the following parameters and values
<parameter>=<value> | Values | Description
port=<int> | 1, ... 1 | Select COM port. -1 means disconnect the camera from the serial port.
write=<string> dataout2=<string> | <bytestring> | <bytestring>: hex coded bytes with values of {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, a, b, c, d, e, f} Writes the specified data string to the selected serial port. Max string length: 128 bytes 1 .
writestring=<string> | <url encoded string> | Writes the URL-encoded string to the selected serial port. Max string length: 128 bytes 1.
read=<int> | 1, ... | Reads n bytes from the selected serial port. The returned data will be hexadecimal coded and placed between #s (e.g. #3A#)
wait=<int> | 1 - 9 | Specified in seconds. Used together with the "read" parameter. A read is terminated when the specified number of bytes is read or when the wait period has ended.
timeout=<int> | 1 - 9000 | Specified in milliseconds. Used together with the "read" parameter. A read is terminated when the specified number of bytes is read or the timeout has expired.

1 Product-dependent. Check the product's specification.
2 Obsolete.

5.6.2 Open serial port

This CGI makes it possible to open the serial port using the HTTP protocol. Authentication is handled by the Web server.

  • After an initial connect command from the client, the connection is kept alive until the client closes it.
  • Several clients may be connected concurrently to the same serial port.
  • After the connection has been set up, data sent from the client to the Web server is forwarded to the serial port, and incoming serial data is returned to all currently connected clients.

Syntax:
http://<servername>/axis-cgi/com/serial.cgi?
<parameter>=<value>[&<parameter>=<value>...]

with the following parameters and values
<parameter>=<value> | Values | Description
port=<int> | 1, ... 1 | Select COM port. -1 = disconnect the camera from any serial port.
camera=<int> unit=<int> | 1, ... 1 | Selects the source camera or external unit. If omitted, and "port=" command is also omitted, the default camera/unit is used to determine the serial port to use.
connect=<string> | yes | Instructs the server to keep the connection open and serve as a link between the client and the serial port.

1 Product-dependent. Check the product's specification.

Example: Open serial port 1 if not already opened and connect camera 2 to it.
http://myserver/axis-cgi/com/serial.cgi?port=1&camera=2

Example: Disconnect camera 2 from any serial port (but keep that port open).
http://myserver/axis-cgi/com/serial.cgi?port=-1&camera=2

5.7 IP filter

The requests specified in the IP filter section are supported by products that support IP address filtering.

5.7.1 IP address filter administration

Allow or deny the listed IP addresses to access the Axis device.

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/ipfilter.cgi?
<parameter>=<value>[&<parameter>=<value>... ]

with the following parameters and values
<parameter>=<value> Values Description
action=<string> add, remove, removeall, update or list Specifies the action to take.

add = Add new IP address (or addresses).
remove = remove an entry in the IP address list.
removeall = Remove all IP addresses. The IP address filtering function will automatically be disabled.
update = Update settings for the IP address filtering function.
list = List the settings for the IP address filtering function.
ipaddress=<string>[%20<string>...] <IP addresses> The addresses allowed passing through the filter. A space separated list of IP addresses and network addresses in the CIDR notation (IP address/netmask bits).

Note: If accessing the Axis device via a proxy server, the proxy server's IP address must be added to the list of allowed addresses.
enable=<string> yes,
no 		Enable/disable the IP address filtering function.
policy=<string> allow,
deny 		Allow or deny access for the addresses in the list. If omitting this parameter the policy will be allow by default.

Note: The policy used will apply for all the addresses in the list!

verify=<string> yes,
no 		Verify that you are able to access the Axis device with the new settings. A failed verification will make the settings to remain as before.

verify is automatically set to yes when using requests that risk to make the device inaccessible, i.e. setting enable to yes, or adding, updating and removing IP addresses when the filter function is enabled. In the same way verify is by default set to no when using requests that do not risk to make the device inaccessible, i.e. listing filter settings or adding, updating and removing IP addresses when the filter function is disabled. This behaviour can be changed by setting this parameter in the request.

yes = Use verification.
no = Do not use verification. Note: setting verify to no, may cause the Axis device to be inaccessible.

Example: Add a list of IP addresses and enable the IP address filtering function. Verification that the device is still accessible will automatically be done.
http://myserver/axis-cgi/admin/ipfilter.cgi?action=add
&ipaddress=10.13.10.12%2010.13.17.0/24&enable=yes

Example: List settings for the IP address filtering function.
http://myserver/axis-cgi/admin/ipfilter.cgi?action=list

Example: Remove an entry in the list of addresses. Verification will automatically be done if the IP filter function is enabled.
http://myserver/axis-cgi/admin/ipfilter.cgi?action=remove&ipaddress=10.13.10.12

Example: Add 10.13.10.12 to the list of addresses which will be allowed access to the device.
http://myserver/axis-cgi/admin/ipfilter.cgi?action=add&ipaddress=10.13.10.12
&policy=allow&enable=yes

Example: Add 10.13.10.12 to the list of addresses which will be denied access to the device.

http://myserver/axis-cgi/admin/ipfilter.cgi?action=add&ipaddress=10.13.10.12
&policy=deny&enable=yes

Example: Remove all IP addresses and automatically disable the IP address filtering function

http://myserver/axis-cgi/admin/ipfilter.cgi?action=removeall

5.7.2 Server responses

Return: A successful add, remove, removeall or update.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
OK\r\n

Return: A list.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Accept addresses: <IP addresses>\r\n
Enabled: <yes/no>\r\n

Return: Verification failed. The settings did not take place.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Verification failed: IP address "<IP address>" is not an accepted address\r\n

Example: List settings for the IP address filtering function, set verify to yes to check that my computers IP address is accepted.
http://myserver/axis-cgi/admin/ipfilter.cgi?action=list&verify=yes

Response: Only the IP address 10.13.10.12 is an accepted address. The computer 10.13.17.245 will not be able to access the device if enabling the IP address filtering function.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
\r\n
Accept addresses: 10.13.10.12\r\n
Enabled: no\r\n
Verification failed: IP address "10.13.17.245" is not an accepted address

5.8 Audio

The requests specified in the Audio section are supported by products that have audio capability.

5.8.1 Audio MIME types

Supported MIME types for audio
audio/basic
audio/32KADPCM
audio/G723
 which is G.711 µ-law 64kbit/s
which is G.726 32kbit/s
which is G.726 24kbit/s

5.8.2 Audio data request

Request an audio stream.

Method: GET

Syntax:
http://<servername>/axis-cgi/audio/receive.cgi[?<parameter>=<value>]

with the following parameters and values
<parameter>=<value> | Values | Description
httptype=<string> | singlepart, multipart | Choose streaming method. Default value is defined by the parameter Audiod.HttpMessageType

Example: Request a singlepart audio stream
http://myserver/axis-cgi/audio/receive.cgi?httptype=singlepart

5.8.3 Singlepart audio data response

When an audio stream is requested/transmitted, the server returns/receives a continuous flow of audio packets. The content type is only set at the beginning of the connection. When the connection is up and running the audio packets will come right after another without any extra information between the packets. The message body contains a block of binary data. Each block of coded audio data is 240 byte.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: <audio MIME>\r\n
\r\n
<Audio data>

Example: Singlepart Audio data encoded with G.711 µ-law.
HTTP/1.0 200 OK\r\n
Content-Type: audio/basic\r\n
\r\n
<Audio data>
<Audio data>
<Audio data>
.
.
.

5.8.4 Multipart audio data response

When an audio stream is requested/transmitted, the server returns/receives a continuous flow of audio packets. The content type is "mutipart/x-mixed-replace" and each audio packet ends with a boundary string. The message body contains a block of binary data. Each block of coded audio data is 240 byte.

Return:
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=--<boundary>\r\n
\r\n
--<boundary>\r\n
<audio>
where the proposed <boundary> is:
myboundary
and the <audio> field is
Content-Type: <audio MIME>\r\n
\r\n
<Audio data>\r\n
--<boundary>\r\n
<audio>

Example: Multipart Audio data encoded with G.726 32kbit/s (G.721).
HTTP/1.0 200 OK\r\n
Content-Type: multipart/x-mixed-replace;boundary=myboundary\r\n
\r\n
--myboundary\r\n
Content-Type: audio/32KADPCM\r\n
\r\n
<Audio data>\r\n
--myboundary\r\n
Content-Type: audio/32KADPCM\r\n
\r\n
<Audio data>\r\n
--myboundary\r\n
Content-Type: audio/32KADPCM\r\n
<Audio data>\r\n
--myboundary\r\n
Content-Type: audio/32KADPCM\r\n
\r\n
<Audio data>\r\n
--myboundary\r\n
.
.
.

5.8.5 Audio data transmit

Transmit a Singlepart/Multipart Audio data stream.

Method: POST

Syntax:
http://<servername>/axis-cgi/audio/transmit.cgi

There are no valid parameters and values.

Example: Singlepart/Multipart Audio data
http://myserver/axis-cgi/audio/transmit.cgi

5.9 AXIS 292 Network Video Decoder

5.9.1 Alarm

When the decoder operates in manual mode it can receive alarms from an encoder. This can be a motion detected or input triggered event on the encoder. The decoder will automatically switch to the encoder <sourcename> when receiving an alarm, where <sourcename> is the name of the given encoder in the video source list. The On Screen Display (OSD) will display "ALARM: <sourcename>" and an optional line with a text message of maximum 40 characters.

Note: The alarm function can only be used in manual mode and requires administrator access.

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/alarm.cgi?sourcename=<camera>&textmessage=<text>

with the following parameters and values
<parameter>=<value> | Values | Description
sourcename=<camera> | A string | Reflects the same name found in Encoder.E#.Name.
textmessage=<string> | A string | The text message to be displayed on the screen. Maximum 40 characters will be displayed. Note that this message must be URI encoded.

Example: Send an alarm from camera1
http://myserver/axis-cgi/admin/alarm.cgi?sourcename=camera1

Example: Send an alarm from camera3 with the message "Door is open"
http://myserver/axis-cgi/admin/alarm.cgi?sourcename=camera3
&textmessage=Door%20is%20open

Response: Response from a successful alarm
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
Expires: 0\r\n
Pragma: no-cache\r\n
\r\n
OK\r\n

Response: Response from an unsuccessful alarm with unknown sourcename
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
Expires: 0\r\n
Pragma: no-cache\r\n
\r\n
# Error: Unknown sourcename\r\n

Response: Response from an unsuccessful alarm with sourcename missing
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
Expires: 0\r\n
Pragma: no-cache\r\n
\r\n
# Error: sourcename must be specified\r\n

5.9.2 Video control

Handles various video states such as Connect, Disconnect, Invalidatecache and Goto.

Note: This requires administrator access.

Method: GET

Syntax:
http://<servername>/axis-cgi/admin/videocontrol.cgi?action=<string>

Response: Response from a videocontrol request with no action specified
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
Expires: 0\r\n
Pragma: no-cache\r\n
\r\n
# Error: Action value is missing. Supported actions are invalidatecache, goto, connect,
disconnect\r\n

5.9.2.1 Connect

The video decoder will connect to the first source in the video source list.

Syntax:
http://<servername>/axis-cgi/admin/videocontrol.cgi?action=connect

Example: Connect the Network Video Decoder
http://myserver/axis-cgi/admin/videocontrol.cgi?action=connect

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
Expires: 0\r\n
Pragma: no-cache\r\n
\r\n
OK\r\n

5.9.2.2 Disconnect

Disconnect the Network Video Decoder.

Syntax:
http://<servername>/axis-cgi/admin/videocontrol.cgi?action=disconnect

Example: Disconnect the Network Video Decoder
http://myserver/axis-cgi/admin/videocontrol.cgi?action=disconnect

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
Expires: 0\r\n
Pragma: no-cache\r\n
\r\n
OK\r\n

5.9.2.3 Invalidate Cache

Removes all cached information. This cache contains information about the video sources. Values that are cached can be found in the Axis Video Parameter document under Encoder.E#.Info. When connecting to a source the second time, the decoder will use the information found in this cache for how to connect, instead of doing an autodetect.

Syntax:
http://<servername>/axis-cgi/admin/videocontrol.cgi?action=invalidatecache

Example: Connect the Network Video Decoder
http://myserver/axis-cgi/admin/videocontrol.cgi?action=invalidatecache

Response:
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
Expires: 0\r\n
Pragma: no-cache\r\n
\r\n
OK\r\n

5.9.2.4 Select source

The decoder will connect to a specified video source.

Syntax:
http://<servername>/axis-cgi/admin/videocontrol.cgi?action=goto&sourcename=<name>

Example: Go to the video source named "camera1"
http://myserver/axis-cgi/admin/videocontrol.cgi?action=goto&sourcename=camera1

Response: A successful goto.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
Expires: 0\r\n
Pragma: no-cache\r\n
\r\n
OK\r\n

Response: Goto failed, the video source name was wrong.
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
Expires: 0\r\n
Pragma: no-cache\r\n
\r\n
# Error: Unknown sourcename\r\n

Response: Goto failed, the video source name was missing
HTTP/1.0 200 OK\r\n
Content-Type: text/plain\r\n
Expires: 0\r\n
Pragma: no-cache\r\n
\r\n
# Error: sourcename must be specified\r\n


Sample Code and Descriptions

These descriptions and examples show how AXIS Media Control (AMC) and the HTTP Camera API can be used in Microsoft Developer Tools or in Microsoft Internet Explorer.

Microsoft Developer Tools | Some sample descriptions on how to use AMC in Microsoft Visual C++ 6.0, Microsoft Visual Basic 6.0 and C#.
Microsoft Internet Explorer | Some sample descriptions on how to use AMC in Microsoft Internet Explorer.


Microsoft Development Tool Samples

These descriptions and examples show how AXIS Media Control and the HTTP based video API can be used in Microsoft Development Tools.

The related sample projects can be found under ({SDK} denotes the installation directory chosen for this SDK):

{SDK}\Samples\Visual Basic 6.0\ and
{SDK}\Samples\Visual C#\ and
{SDK}\Samples\Visual C++ 6.0\

Here are some sample descriptions on how to use AXIS Media Control. The samples are available for Microsoft Visual C++ 6.0, Visual Basic 6.0, Visual C++ .NET and Visual Basic .NET.

AXIS Media Control samples

  • View Live MJPEG Unicast Stream
  • View Live MPEG-2 Unicast Stream
  • View Live MPEG-4 Unicast Stream
  • Record MPEG-2 Unicast Stream
  • MPEG-4 Video and Audio Recording
  • View MPEG-2 File
  • Move the Camera by Clicking
  • Snapshots from a Stream
  • Password Protected Server
Other samples
  • Add Parameters using the HTTP API

See Also

AXIS Media Control Usage | Microsoft Internet Explorer Samples


Sample: View Live MPEG-2 Unicast Stream

View Live MJPEG Unicast Stream

The most basic AMC functionality is the viewing of live streams from Axis video products supporting MJPEG. To do this, simply assign the MediaURL property a valid URL. A call to the Play method will then use the assigned media URL to retrieve the MJPEG stream from the Axis video product.

The MediaType property is used to determine the type of media stream. For example, when it is known that the MJPEG stream is retrieved over HTTP the MediaType property should be set to "mjpeg-unicast". The default value ("auto-sense") also works.

In the sample application, two buttons are used to start and stop playing the media stream from the Axis video product. When the button "Play Live" is pressed, the MediaURL is set to the MJPEG URL for the Axis video product. The Play method is called to start the download. When the button "Stop" is pressed, the Stop method is called to stop the live view.

If the Axis video product is configured for password protection, a valid user name and password must be used when accessing it. See Password Protected Server example for more details about this.

Note: to run the sample, change the IP address in the MediaURL to a valid IP address for an Axis video product on your network.

In C#:

private void btnPlayLive_Click(object sender, System.EventArgs e)
{
  // Set the media URL and the media type
  AMC.MediaURL = "http://" + ipText.Text + "/axis-cgi/mjpg/video.cgi";
  AMC.MediaType = "mjpeg-unicast";

  try
  {
    // Starts the download of the mjpeg stream from the Axis camera/video server
    AMC.Play();
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

private void btnStop_Click(object sender, System.EventArgs e)
{
  try
  {
    // Stops the download of the mjpeg stream
    AMC.Stop();
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

In Visual C++ 6.0:

void CMJPEGunicastDlg::OnPlayLive()
{
  // Set the media URL and the media type
  m_AMC.SetMediaURL("http://" + m_ipText + "/axis-cgi/mjpg/video.cgi");
  m_AMC.SetMediaType("mjpeg-unicast");

  // Start the download of the mjpeg stream from the Axis camera/video server
  try
  {
    m_AMC.Play();
  }
  catch (COleDispatchException *e)
  {
    if (e->m_scError == E_INVALIDARG)
    {
      MessageBox("Invalid parameters.");
    }
    else if (e->m_scError == E_ACCESSDENIED)
    {
      MessageBox("Access denied.");
    }
    else
    {
      MessageBox("Failure.");
    }
  }
}

void CMJPEGunicastDlg::OnStopPlay()
{
  // Stop the download of the mjpeg stream from the Axis camera/video server
  m_AMC.Stop();
}

In Visual Basic 6.0:

Private Sub Cmd_PlayLive_Click()

  ' Set the media URL and the media type
  AMC.MediaURL = "http://" & ipText.Text & "/axis-cgi/mjpg/video.cgi"
  AMC.MediaType = "mjpeg-unicast"

  ' Start the download of the mjpeg stream from the Axis camera/video server
  On Error GoTo ErrorHandler
  AMC.Play
  Exit Sub

ErrorHandler:
  MsgBox "Error: " & Err.Description

End Sub

Private Sub Cmd_StopPlay_Click()

  AMC.Stop

End Sub


Sample: View Live MPEG-2 Unicast Stream

View Live MPEG-2 Unicast Stream

The most basic AMC functionality is the viewing of live streams from Axis video products supporting MPEG-2. To do this, simply assign the MediaURL property a valid URL. A call to the Play method will then use the assigned media URL to retrieve the MPEG-2 stream from the Axis video product.

The MediaType property is used to determine the type of media stream. For example, when it is known that the MPEG-2 stream is retrieved over HTTP the MediaType property should be set to "mpeg2-unicast". The default value ("auto-sense") also works.

In the sample application, two buttons are used to start and stop playing the media stream from the Axis video product. When the button "Play Live" is pressed, the MediaURL is set to the MPEG-2 URL for the Axis video product. The Play method is called to start the download. When the button "Stop" is pressed, the Stop method is called to stop the live view.

If the Axis video product is configured for password protection, a valid user name and password must be used when accessing it. See Password Protected Server example for more details about this.

Note: to run the sample, change the IP address in the MediaURL to a valid IP address for an Axis video product on your network.

In C#:

private void btnPlayLive_Click(object sender, System.EventArgs e)
{
  try
  {
   // Set the media URL and the media type
    AMC.MediaURL = "http://" + ipText.Text + "/axis-cgi/mpeg2/video.cgi";
    AMC.MediaType = "mpeg2-unicast";

    // Starts the download of the mpeg2 stream from the Axis camera/video server
    AMC.Play();
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

private void btnStop_Click(object sender, System.EventArgs e)
{
  try
  {
    // Stops the download of the mpeg2 stream.
    AMC.Stop();
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

In Visual C++ 6.0:

void CMPEG2unicastDlg::OnPlayLive()
{
  // Set the media URL and the media type
  this->UpdateData();
  // Set the media URL and the media type
  m_AMC.SetMediaURL("http://" + m_ipText + "/axis-cgi/mpeg2/video.cgi");
  m_AMC.SetMediaType("mpeg2-unicast");

  // Start the download of the mpeg2 stream from the Axis camera/video server
  try
  {
    m_AMC.Play();
  }
  catch (COleDispatchException *e)
  {
    if (e->m_scError == E_INVALIDARG)
    {
      MessageBox("Invalid parameters.");
    }
    else if (e->m_scError == E_ACCESSDENIED)
    {
      MessageBox("Access denied.");
    }
    else
    {
      MessageBox("Failure.");
    }
  }
}

void CMPEG2unicastDlg::OnStopPlay()
{
  // Stop the download of the mpeg2 stream from the Axis camera/video server
  m_AMC.Stop();
}

In Visual Basic 6.0:

Private Sub Cmd_PlayLive_Click()

  ' Set the media URL and the media type
  AMC.MediaURL = "http://" & ipText.Text & "/axis-cgi/mpeg2/video.cgi"
  AMC.MediaType = "mpeg2-unicast"

  ' Start the download of the mpeg2 stream from the Axis camera/video server
  On Error GoTo ErrorHandler
  AMC.Play
  Exit Sub

ErrorHandler:
  MsgBox "Error: " & Err.Description

End Sub

Private Sub Cmd_StopPlay_Click()

  AMC.Stop

End Sub


Sample: View Live MPEG-2 Unicast Stream

View Live MPEG-4 Unicast Stream

The most basic functionality in the AXIS Media Control is the viewing of live streams from Axis video products supporting MPEG-4. To do this, simply assign the MediaURL property a valid URL. A call to the Play method will then use the assigned media URL to retrieve the MPEG-4 stream from the Axis video product.

When viewing MPEG-4 the URL-type shall be one of the types defined in Custom Protocols for MPEG-4. The MediaType shall always be auto-sense when viewing MPEG-4 streams, except when using URL-type axsdp.

The URL-type rtsp will let AMC test all MPEG-4 protocols the first time AMC connects to the MPEG-4 stream of an Axis server. The first protocol that is usable will be remembered for future connections. This URL-type is not usable in Windows Media Player to use Axis components to access Axis products.

In the sample application, a button is used to start playing the media stream from the Axis video product. When the button "Play Live" is pressed, the MediaURL is set to the MPEG-4 URL for the Axis video product. The Play method is called to start the download.

If the Axis video product is configured for password protection, a valid user name and password must be used when accessing it. See Password Protected Server example for more details about this.

Note: to run the sample, change the IP address in the MediaURL to a valid IP address for an Axis video product on your network.

In C#:

private void btnPlayLive_Click(object sender, System.EventArgs e)
{
  // Set the media URL and the media type
  AMC.MediaURL = "axrtpu://10.84.158.2/mpeg4/media.amp";
  AMC.MediaType = "auto-sense";

  try
  {
    // Start the download of the mpeg4 stream from the Axis camera/video server
    AMC.Play();
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

private void btnStop_Click(object sender, System.EventArgs e)
{
  try
  {
    // Stops the download of the mpeg4 stream.
    AMC.Stop();
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

In Visual C++ 6.0:

void CMPEG4multicastDlg::OnPlayLive()
{
  this->UpdateData();
  // Set the media URL and the media type
  m_AMC.SetMediaURL("axrtpu://" + m_ipText + "/mpeg4/media.amp");
  m_AMC.SetMediaType("auto-sense");

  // Start the download of the mpeg4 stream from the Axis camera/video server
  try
  {
    m_AMC.Play();
  }
  catch (COleDispatchException *e)
  {
    if (e->m_scError == E_INVALIDARG)
    {
      MessageBox("Invalid parameters.");
    }
    else if (e->m_scError == E_ACCESSDENIED)
    {
      MessageBox("Access denied.");
    }
    else
    {
      MessageBox("Failure.");
    }
  }
}

In Visual Basic 6.0:

Private Sub Cmd_PlayLive_Click()

  ' Set the media URL and the media type
  AMC.MediaURL = "axrtpu://" & ipText.Text & "/mpeg4/media.amp"
  AMC.MediaType = "auto-sense"

  ' Start the download of the mpeg4 stream from the Axis camera/video server
  On Error GoTo ErrorHandler
  AMC.Play
  Exit Sub

ErrorHandler:
  MsgBox "Error: " & Err.Description

End Sub


Sample: Record MPEG-2 Unicast Stream

Record MPEG-2 Unicast Stream

AMC includes functionality for recording an MPEG-2 unicast stream sent from an Axis MPEG-2 video product. When the StartRecord method is called the value of the MediaURL property is used to record the stream. When calling StartRecord a file name with a valid path is needed to specify the target file for the recording.

To stop the recording, the StopRecord method is called. Please note that the Stop method will not stop the recording.

Each instance of AMC can only retrieve one MPEG-2 stream. This means that if a live media stream is already being played, another media stream cannot be recorded. To make a recording of one MPEG-2 stream and to play an MPEG-2 stream from another Axis video product simultaneously, two instances of AMC are required in the application.

In the sample application, two buttons are used to start and stop playing the media stream from the Axis video product. When the button "Record" is pressed, the MediaURL is set to the MPEG-2 URL for the Axis video product. The StartRecord method is called to start the download. When the button "Stop" is pressed, the StopRecord method is called to stop the recording.

Note: To run the sample, change the IP address in the MediaURL to a valid IP address for an Axis video product on your network.

In C#:

private void btnRecord_Click(object sender, System.EventArgs e)
{
  // Present a dialog to select where to save the recording.
  SaveFileDialog mySaveDlg = new SaveFileDialog();
  mySaveDlg.Filter = "Movie Clip (*.mpg; *.mpeg) | *.mpg; *.mpeg ||";

  if(mySaveDlg.ShowDialog() == DialogResult.OK)
  {
    try
    {
      // Set the media URL and the media type
      AMC.MediaURL = "http://" + ipText.Text + "/axis-cgi/mpeg2/video.cgi";
      AMC.MediaType = "mpeg2-unicast";

      // Starts recording the mpeg2 stream
      AMC.StartRecord(mySaveDlg.FileName);
    }
    catch (ArgumentException ArgEx)
    {
      MessageBox.Show(ArgEx.Message,"Error");
    }
    catch (Exception Ex)
    {
      MessageBox.Show(Ex.Message,"Error");
    }
  }
}

private void btnStopRecord_Click(object sender, System.EventArgs e)
{
  try
  {
    // Stops recording the mpeg2 stream.
    AMC.StopRecord();
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

In Visual C++ 6.0:

void CMPEG2unicastDlg::OnRecord()
{
  // Present a dialog to select a file
  CFileDialog aDlg(TRUE, NULL, "C:\\axis.mpg",
                   OFN_HIDEREADONLY | OFN_OVERWRITEPROMPT,
                   "Movie Clip (*.mpg;*.mpeg)|*.mpg;*.mpeg| All Files (*.*)|*.*||");
  aDlg.DoModal();
  CString aFileName = aDlg.GetPathName();

  if (aFileName == "")
  {
    return;
  }

  // Set the media URL and the media type
  CString str;
  this->UpdateData();
  str.Format(_T("http://%s/axis-cgi/mpeg2/video.cgi"), m_ipText);
  // Set the media URL and the media type
  m_AMC.SetMediaURL(str);
  m_AMC.SetMediaType("mpeg2-unicast");

  // Start the recording of the mpeg2 stream from the Axis camera/video server
  try
  {
    m_AMC.StartRecord(aFileName);
  }
  catch (COleDispatchException *e)
  {

    if (e->m_scError == E_INVALIDARG)
    {
      MessageBox("Invalid parameters.");
    }
    else if (e->m_scError == E_ACCESSDENIED)
    {
      MessageBox("Access denied.");
    }
    else
    {
      MessageBox("Failure.");
    }
  }
}

void CMPEG2unicastDlg::OnStopRec()
{
  // Stop the recording of the mpeg2 stream from the Axis camera/video server
  m_AMC.StopRecord();
}

In Visual Basic 6.0:

Private Sub Cmd_Record_Click()

  ' Present a dialog to select a file to play
  ComDlg.Filter = "Movie Clip (*.mpg; *.mpeg) | *.mpg; *.mpeg ||"
  ComDlg.FileName = "C:\axis.mpg"
  ComDlg.ShowSave

  If ComDlg.FileName <> "" Then

    ' Set the media URL and the media type
    AMC.MediaURL = "http://" & ipText.Text & "/axis-cgi/mpeg2/video.cgi"
    AMC.MediaType = "mpeg2-unicast"

    ' Start the download of the mpeg2 stream from the Axis camera/video server
    On Error GoTo ErrorHandler
    AMC.StartRecord ComDlg.FileName

  End If

  Exit Sub

ErrorHandler:
  MsgBox "Error: " & Err.Description

End Sub

Private Sub Cmd_StopRec_Click()

  AMC.StopRecord

End Sub


MPEG-4 Video and Audio Recording

MPEG-4 Recording

To record a live media stream, simply call StartRecordMedia when the stream is playing.

In the sample application it is possible to decide where the recording will be saved and if audio will be recorded.

If the Axis video product is configured for password protection, a valid user name and password must be used when accessing it. See Password Protected Server example for more details about this.

Note: Currently, it is only possible to record live MPEG-4 streams.

In C#:

private void btnRec_Click(object sender, System.EventArgs e)
{
  // Record both video and audio as default
  int aRecMode = 16;

  if (cbNoAudio.Checked)
    aRecMode = 8;

  try
  {
    // Starts the recording to the specified file.
    AMC.StartRecordMedia(txtRecFile.Text,aRecMode,"");
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}
private void btnStopRec_Click(object sender, System.EventArgs e)
{
  try
  {
    // Stops all ongoing recordings.
    AMC.StopRecordMedia();
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

In Visual C++ 6.0:

void CRecordingDlg::OnStartRecord()
{
  // Record both video and audio as default
  int aRecMode = 16;

  if (m_NoAudio)
    aRecMode = 8;

  try
  {
    // Starts to record to the specified file.
    m_AMC.StartRecordMedia(m_File,aRecMode,"");
  }
  catch (COleDispatchException *e)
  {
    if (e->m_scError == E_INVALIDARG)
    {
      MessageBox("Invalid parameters.");
    }
    else if (e->m_scError == E_ACCESSDENIED)
    {
      MessageBox("Access denied.");
    }
    else
    {
      MessageBox("Failure.");
    }
  }
}
void CRecordingDlg::OnStopRecord()
{
  try
  {
    // Start the recording to the specified file.
    m_AMC.StopRecordMedia();
  }
  catch (...)
  {
    MessageBox("Failure.");
  }
}

In Visual Basic 6.0:

Private Sub cmdRecStart_Click()

 ' Record both video and audio as default
  Dim aRecMode As Integer
  aRecMode = 16
  If chkbDisableAudio.Value Then
    aRecMode = 8
  End If

  On Error GoTo ErrorHandler

  ' Starts the recording to the specified file.
  AMC.StartRecordMedia txtFile.Text, aRecMode, ""

  Exit Sub

ErrorHandler:
  If Err.Description <> "Cancel was selected." Then
    MsgBox "Error: " & Err.Description
  End If

End Sub

Private Sub cmdRecStop_Click()

  On Error GoTo ErrorHandler

  ' Stops all ongoing recordings.
  AMC.StopRecordMedia

  Exit Sub

ErrorHandler:
  If Err.Description <> "Cancel was selected." Then
    MsgBox "Error: " & Err.Description
  End If

End Sub


Sample: View File

View File

Viewing a media file is easy with AMC. To do this, simply assign the MediaFile property a correct path to the file to be viewed. A call to the Play method will then use the assigned media file path to display media.

The MediaType property is used to tell the type of the media to display. When media is played from a file, the MediaType property should be set to "auto-sense".

In the sample application, two buttons are used to start and stop playing the media stream from a file. When the button "Play File" is pressed, the user is asked to browse to the file. The MediaFile property is then set to the chosen file path. The Play method is called to start playing. When the button "Stop" is pressed, the Stop method is called to stop the file from being viewed.

In C#:

 private void btnPlayFile_Click(object sender, System.EventArgs e)
{
  // Present a dialog to select a file to play.
  OpenFileDialog myOpenDlg = new OpenFileDialog();
  myOpenDlg.Filter = "Movie Clip (*.mpg; *.mpeg) | *.mpg; *.mpeg ||";

  if(myOpenDlg.ShowDialog() == DialogResult.OK)
  {
    try
    {
      // Set the media URL and the media type
      AMC.MediaFile = myOpenDlg.FileName;
      AMC.MediaType = "auto-sense";

      // Starts the download of the mpeg2 stream from the Axis camera/video server
      AMC.Play();
    }
    catch (ArgumentException ArgEx)
    {
      MessageBox.Show(ArgEx.Message,"Error");
    }
    catch (Exception Ex)
    {
      MessageBox.Show(Ex.Message,"Error");
    }
  }
}

private void btnStop_Click(object sender, System.EventArgs e)
{
  try
  {
    // Stops the download of the mpeg2 stream.
    AMC.Stop();
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

In Visual C++ 6.0:

void CMPEG2unicastDlg::OnPlayFile()
{
  // Present a dialog to select a file
  CFileDialog aDlg(TRUE, NULL, "C:\\axis.mpg",
                   OFN_HIDEREADONLY | OFN_OVERWRITEPROMPT,
                   "Movie Clip (*.mpg;*.mpeg)|*.mpg;*.mpeg| All Files (*.*)|*.*||");
  aDlg.DoModal();
  CString aFileName = aDlg.GetPathName();

  if (aFileName == "")
  {
    return;
  }

  // Set the path to the file
  m_AMC.SetMediaFile(aFileName);
  m_AMC.SetMediaType("auto-sense");

  // Start the download of the mpeg2 stream from the Axis camera/video server
  try
  {
    m_AMC.Play();
  }
  catch (COleDispatchException *e)
  {
    if (e->m_scError == E_INVALIDARG)
    {
      MessageBox("Invalid parameters.");
    }
    else if (e->m_scError == E_ACCESSDENIED)
    {
      MessageBox("Access denied.");
    }
    else
    {
      MessageBox("Failure.");
    }
  }
}

void CMPEG2unicastDlg::OnStopPlay()
{
  // Stop the download of the mpeg2 stream from the Axis camera/video server
  m_AMC.Stop();
}

In Visual Basic 6.0:

Private Sub Cmd_PlayFile_Click()

  ' Present a dialog to select a file to play
  ComDlg.Filter = "Movie Clip (*.mpg; *.mpeg) | *.mpg; *.mpeg ||"
  ComDlg.FileName = "C:\axis.mpg"
  ComDlg.ShowOpen

  If ComDlg.FileName <> "" Then

    ' Set the media URL and the media type
    AMC.MediaFile = ComDlg.FileName
    AMC.MediaType = "auto-sense"

    ' Start the download of the mpeg2 stream from the Axis camera/video server
    On Error GoTo ErrorHandler
    AMC.Play

  End If

  Exit Sub

ErrorHandler:
  MsgBox "Error: " & Err.Description

End Sub

Private Sub Cmd_StopPlay_Click()

  AMC.Stop

End Sub


Sample: Snapshots from a Stream

Snapshots from a Stream

Using AMC to save a snapshot from the media stream being played is easy. When a stream is open, the method SaveCurrentImage is called with the name and path of the resulting file and the format of the image. The path to the file must be valid, e.g., the directory must exist.

A snapshot image can be saved in two different formats, JPEG or BMP.

In the sample, the user can browse to a location and provide a name for the image file. See the installed sample project to see how this is managed. The selected name and path will then be used when the "Snapshot" button is clicked.

In C#:

private void btnSnapShot_Click(object sender, System.EventArgs e)
{
  try
  {
    // Saves the image currently being displayed to the specified file.
    AMC.SaveCurrentImage(0, txtFile.Text);
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

In Visual C++ 6.0:

void CMJPEGunicastDlg::OnSnapshot()
{
  try
  {
    m_AMC.SaveCurrentImage(0, m_File);
  }
  catch (COleDispatchException *e)
  {

    if (e->m_scError == E_INVALIDARG)
    {
      MessageBox("Invalid parameters.");
    }
    else
    {
      MessageBox("Failure.");
    }
  }
}

In Visual Basic 6.0:

Private Sub Cmd_Snapshot_Click()

  On Error GoTo ErrorHandler
  AMC.SaveCurrentImage 0, Text_File
  Exit Sub

ErrorHandler:
  MsgBox "Error: " & Err.Description

End Sub


Sample: Password Protected Server

Password Protected Server

If the Axis video product is configured for password protection, a valid user name and password must be used when accessing it. When using AMC, this is managed simply by setting the properties MediaUsername and MediaPassword to valid values before calling e.g., the Play method.

The sample code uses two edit fields for handling the user name and password. See the installed sample project for further details of how this is managed. When clicking the "Play Live" button, the supplied user name and password are used when opening the session.

In C#:

private void btnPlayLive_Click(object sender, System.EventArgs e)
{
  AMC.MediaPassword = txtPassword.Text;
  AMC.MediaUsername = txtUserName.Text;

  // Set the media URL and the media type
  AMC.MediaURL = "http://" + ipText.Text + "/axis-cgi/mjpg/video.cgi";
  AMC.MediaType = "mjpeg-unicast";

  try
  {
    // Starts the download of the mjpeg stream from the Axis camera/video server
    AMC.Play();
  }
  catch (Exception Ex)
  {
    MessageBox.Show(Ex.Message,"Error");
  }
}

In Visual C++ 6.0:

void CProtectedServerDlg::OnPlayLive()
{
  this->UpdateData(true);

  m_AMC.SetMediaUsername(m_UserName);
  m_AMC.SetMediaPassword(m_Password);

  // Set the media URL and the media type
  m_AMC.SetMediaURL("http://" + m_ipText + "/axis-cgi/mjpg/video.cgi");
  m_AMC.SetMediaType("mjpeg-unicast");

  // Start the download of the mjpeg stream from the Axis camera/video server
  try
  {
    m_AMC.Play();
  }
  catch (COleDispatchException *e)
  {
    if (e->m_scError == E_INVALIDARG)
    {
      MessageBox("Invalid parameters.");
    }
    else if (e->m_scError == E_ACCESSDENIED)
    {
      MessageBox("Access denied.");
    }
    else
    {
      MessageBox("Failure.");
    }
  }
}

In Visual Basic 6.0:

Private Sub Cmd_Play_Click()

  AMC.MediaPassword = Text_Password
  AMC.MediaUsername = Text_UserName

  ' Set the media URL and the media type
  AMC.MediaURL = "http://" & ipText.Text & "/axis-cgi/mjpg/video.cgi"
  AMC.MediaType = "mjpeg-unicast"

  ' Start the download of the mjpeg stream from the Axis camera/video server
  On Error GoTo ErrorHandler
  AMC.Play
  Exit Sub

ErrorHandler:
  MsgBox "Error: " & Err.Description

End Sub


Sample: Move the Camera by Clicking

Move the Camera by Clicking

Using AMC to catch mouse clicks in the image and move the camera to center that point in the image is very easy. You need to know the URL to the PTZ control CGI in the Axis video product supporting PTZ, and also whether the PTZ driver of the camera is absolute or relative.

There are two AMC properties that need to be set: The PTZControlURL property should be set to the URL for the PTZ control CGI script in the Axis video product. The UIMode property should be set to "ptz-absolute" or "ptz-relative" - depending on the type of PTZ driver.

In the sample application, the PTZ initialization is made in the OnInitDialog() function. AMC includes a toolbar for the basic functionality. This toolbar is viewed by enabling the ShowToolbar property. No extra implementation is then needed for play, stop and saving snapshots.
The StretchToFit property is set to true so that the whole image is viewed in the application, and an appropriate size is used.

Note: To run the sample, change the IP address in the MediaURL to a valid IP address for an Axis video product on your network.

In C#:

try
{
  // Set the PTZ properties
  AMC.PTZControlURL = "http://" + ipText.Text + "/axis-cgi/com/ptz.cgi";
  AMC.UIMode = "ptz-absolute";

  // Show the status bar and the tool bar in the AXIS Media Control
  AMC.ShowStatusBar = true;
  AMC.ShowToolbar = true;
  AMC.StretchToFit = true;

  // Set the media URL and the media type
  AMC.MediaURL = "http://" + ipText.Text + "/axis-cgi/mpeg2/video.cgi";
  AMC.MediaType = "mjpeg-unicast";

  // Start the download of the mjpeg stream from the Axis camera/video server
  AMC.Play();
}
catch (ArgumentException ArgEx)
{
  MessageBox.Show(ArgEx.Message,"Error");
}
catch (Exception Ex)
{
  MessageBox.Show(Ex.Message,"Error");
}

In Visual C++ 6.0:

  this->UpdateData();
  // Set the PTZ properties
  m_AMC.put_PTZControlURL("http://" + m_ipText + "/axis-cgi/com/ptz.cgi");
  m_AMC.SetUIMode("ptz-absolute");

  // Show the status bar and the tool bar in the AXIS Media Control
  m_AMC.SetShowStatusBar(true);
  m_AMC.SetShowToolbar(true);
  m_AMC.SetStretchToFit(true);

  // Set the media URL and the media type
  m_AMC.put_MediaURL("http://" + m_ipText + "/axis-cgi/mjpg/video.cgi");
  m_AMC.SetMediaType("mjpeg-unicast");

In Visual Basic 6.0:

  ' Set the PTZ properties
  AMC.PTZControlURL = "http://" & ipText.Text & "/axis-cgi/com/ptz.cgi"
  AMC.UIMode = "ptz-absolute"

  ' Show the status bar and the tool bar in the AXIS Media Control
  AMC.ShowStatusBar = True
  AMC.ShowToolbar = True
  AMC.StretchToFit = True

  ' Set the media URL and the media type
  AMC.MediaURL = "http://10.13.9.123/axis-cgi/mjpg/video.cgi"
  AMC.MediaType = "mjpeg-unicast"


Sample: Add Parameters using the HTTP API

Add Parameters using the HTTP API

Products supporting axis-cgi/operator/param.cgi have the functionality to add parameters dynamically. The axis-cgi/operator/param.cgi script also supports listing and updating parameter values. See the Axis Video API, HTTP for more detailed information about the script.

Dynamic parameters added using param.cgi use a template for the dynamic parameter group. This template is used to add all parameters in the group, and to set default values to the parameters that are not set when the parameter group is added.

Axis MPEG-2 video products support event handling. The product can be configured to trig on a certain event, and when the event is triggered do a certain action. The action can be, for example, to upload images to an FTP server. The template used to add a new event parameter group is 'event'. To set the FTP upload an FTPClient parameter group is also required. The FTPClient group uses the template 'ftpclient'.

This sample configures an AXIS 250S of version 3.10 to trig on input 1, and upload the pre-buffer to a FTP server when the event is triggered. To do this, an FTPClient parameter group is first added, and later configured with the IP address of the FTP server, the user name and password to access the FTP server, and a name for this FTP server configuration. When this is completed, an event is added. This event is set to trig on input 1 by setting the parameter HWInputs to '1xxx'. The action of the event is set to FTP upload by setting the DoFTPUpload parameter to 'yes' and the FTPUploadTo parameter to the chosen name of the FTP server configuration. The name of the uploaded file is set to 'VideoSample' with a suffix of the time of the upload by setting the FileFormat parameter to 'VideoSample' and the Suffix parameter to time_date.

In Visual C++ .NET:

void CEventDlg::AddEvent(CString EventName, CString FTPName,
                         CString FTPServer, CString UserName, CString Password)
{
  CString parURL;

  // Add the FTP server parameters
  parURL = "axis-cgi/operator/param.cgi?action=add&group=FTPClient&template=ftpclient";
  parURL += "&FTPClient.F.Name=" + FTPName;
  parURL += "&FTPClient.F.Address=" + FTPServer;
  parURL += "&FTPClient.F.User=" + UserName;
  parURL += "&FTPClient.F.Password=" + Password;

  (void) this->SendHTTPRequest("10.13.9.123", parURL, "root", "pass");

  // Add the Event parameters
  parURL = "axis-cgi/operator/param.cgi?action=add&group=Event&template=event";
  parURL += "&Event.E.Name=" + EventName;
  parURL += "&Event.E.FileFormat=VideoSample";
  parURL += "&Event.E.HWInputs=1xxx";
  parURL += "&Event.E.Suffix=time_date";
  parURL += "&Event.E.PreTrigger=60s";
  parURL += "&Event.E.UploadLength=60s";
  parURL += "&Event.E.UploadPerFile=60s";
  parURL += "&Event.E.DoFTPUpload=yes";
  parURL += "&Event.E.FTPUploadTo=" + FTPName;

  (void) this->SendHTTPRequest("10.13.9.123", parURL, "root", "pass");
}

CString CEventDlg::SendHTTPRequest(CString IP, CString URL, CString pwd, CString user)
{
  CInternetSession aSession("Sample");
  CHttpConnection* pServer = NULL;
  CHttpFile* pFile = NULL;
  try
  {
    // Open a connection to the Axis MPEG-2 video product
    pServer = aSession.GetHttpConnection(IP, (INTERNET_PORT)80, user, pwd);

    // Set the url to the url defined to set the parameter
    //  (see the "Axis Video API, HTTP - Interface Specification".)
    pFile = pServer->OpenRequest(CHttpConnection::HTTP_VERB_GET, URL);

    // Make the request
    pFile->SendRequest();

    // Check the response to the request
    DWORD dwRet;
    pFile->QueryInfoStatusCode(dwRet);

    byte szBuff[1024];
    UINT nRead = pFile->Read(szBuff, 1024);
    szBuff[nRead] = '\0';

    delete pFile;
    delete pServer;

    CString aRet(szBuff);
    return aRet;
  }
  catch (CInternetException* pEx)
  {
    char errorMessage[1024];
    pEx->GetErrorMessage(errorMessage, 1024);
    CString strMessage;
    strMessage.Format("The session failed (error = %u) \n%s",
                      pEx->m_dwError, errorMessage);
    MessageBox(strMessage, NULL, MB_ICONERROR);
    return "";
  }
  aSession.Close();
}

In Visual C++ 6.0:

void CEventDlg::AddEvent(CString EventName, CString FTPName,
                         CString FTPServer, CString UserName, CString Password)
{
  CString parURL;

  // Add the FTP server parameters
  parURL = "axis-cgi/operator/param.cgi?action=add&group=FTPClient&template=ftpclient";
  parURL += "&FTPClient.F.Name=" + FTPName;
  parURL += "&FTPClient.F.Address=" + FTPServer;
  parURL += "&FTPClient.F.User=" + UserName;
  parURL += "&FTPClient.F.Password=" + Password;

  (void) this->SendHTTPRequest("10.13.9.123", parURL, "root", "pass");

  // Add the Event parameters
  parURL = "axis-cgi/operator/param.cgi?action=add&group=Event&template=event";
  parURL += "&Event.E.Name=" + EventName;
  parURL += "&Event.E.FileFormat=VideoSample";
  parURL += "&Event.E.HWInputs=1xxx";
  parURL += "&Event.E.Suffix=time_date";
  parURL += "&Event.E.PreTrigger=60s";
  parURL += "&Event.E.UploadLength=60s";
  parURL += "&Event.E.UploadPerFile=60s";
  parURL += "&Event.E.DoFTPUpload=yes";
  parURL += "&Event.E.FTPUploadTo=" + FTPName;

  (void) this->SendHTTPRequest("10.13.9.123", parURL, "root", "pass");
}

CString CEventDlg::SendHTTPRequest(CString IP, CString URL, CString pwd, CString user)
{
  CInternetSession aSession("Sample");
  CHttpConnection* pServer = NULL;
  CHttpFile* pFile = NULL;
  try
  {
    // Open a connection to the Axis MPEG-2 video product
    pServer = aSession.GetHttpConnection(IP, (INTERNET_PORT)80, user, pwd);

    // Set the url to the url defined to set the parameter
    //  (see the "Axis Video API, HTTP - Interface Specification".)
    pFile = pServer->OpenRequest(CHttpConnection::HTTP_VERB_GET, URL);

    // Make the request
    pFile->SendRequest();

    // Check the response to the request
    DWORD dwRet;
    pFile->QueryInfoStatusCode(dwRet);

    byte szBuff[1024];
    UINT nRead = pFile->Read(szBuff, 1024);
    szBuff[nRead] = '\0';

    delete pFile;
    delete pServer;

    CString aRet(szBuff);
    return aRet;
  }
  catch (CInternetException* pEx)
  {
    char errorMessage[1024];
    pEx->GetErrorMessage(errorMessage, 1024);
    CString strMessage;
    strMessage.Format("The session failed (error = %u) \n%s",
                      pEx->m_dwError, errorMessage);
    MessageBox(strMessage, NULL, MB_ICONERROR);
    return "";
  }
  aSession.Close();
}


Sample: View Live MPEG-2 Unicast Stream

Audio

Listening to live audio streams from Axis video products supporting audio is very easy. To do this, simply assign the AudioConfigURL and the AudioReceiveURL properties valid values. A call to the Play or AudioReceiveStart method will then use the assigned URLs to retrieve the audio stream from the Axis video product.

In the sample application, the user connects to a camera with the given address using the connect button. Various controls are used to toggle between receiving, transmitting and/or recording audio. The media is set to mjpeg so that unsynchronized audio is received.

If the Axis video product is configured for password protection, a valid user name and password must be used when accessing it. See Password Protected Server example for more details about this.

In C#:

    private void btnStartRecordMedia_Click(object sender, System.EventArgs e)
    {
      if (btnStartRecordMedia.Text.Equals("Start"))
      {
        int theFlags = 0;
        theFlags += chkbReceived.Checked == true ? 1 : 0;
        theFlags += chkbTransmitted.Checked == true ? 2 : 0;

        // Present a dialog to select where to save the recording.
        SaveFileDialog mySaveDlg = new SaveFileDialog();
        mySaveDlg.Filter = "wav files (*.wav)|*.wav|All files (*.*)|*.*";

        if(mySaveDlg.ShowDialog() == DialogResult.OK)
        {
          btnStartRecordMedia.Text = "Stop";
          panelLower.Enabled = false;
          panelUpper.Enabled = false;

          try
          {
            // Stores one or more media streams to a file.
            AMC.StartRecordMedia(mySaveDlg.FileName,theFlags ,"PCM");
          }
          catch (ArgumentException ArgEx)
          {
            MessageBox.Show(ArgEx.Message,"Error");
          }
          catch (Exception Ex)
          {
            MessageBox.Show(Ex.Message,"Error");
          }
        }
      }
      else
      {
        panelLower.Enabled = true;
        panelUpper.Enabled = true;
        btnStartRecordMedia.Text = "Start";
        try
        {
          //Ends the ongoing recording and closes the file used for storing the media streams.
          AMC.StopRecordMedia();
        }
        catch (Exception Ex)
        {
          MessageBox.Show(Ex.Message,"Error");
        }
      }
    }

    private void chkbTransmitted_CheckedChanged(object sender, System.EventArgs e)
    {
      btnStartRecordMedia.Enabled = chkbReceived.Checked | chkbTransmitted.Checked;
    }

    private void rdbTransmitOn_CheckedChanged(object sender, System.EventArgs e)
    {
      // Mute/Unmute transmitted media
      AMC.AudioTransmitMute = !rdbTransmitOn.Checked;

      chkbTransmitted.Enabled = rdbTransmitOn.Checked;
      chkbTransmitted.Checked = rdbTransmitOn.Checked;
    }

    private void chkbReceivedTransmitted_CheckedChanged(object sender, System.EventArgs e)
    {
      btnStartRecordMedia.Enabled = chkbReceived.Checked | chkbTransmitted.Checked;
    }

    private void Form1_Load(object sender, System.EventArgs e)
    {
      // Mute received media
      AMC.Mute = true;

      // Mute trasmitted media
      AMC.AudioTransmitMute = true;
    }

    private void rdbReceiveOn_CheckedChanged(object sender, System.EventArgs e)
    {
      // Mute/Unmute received media
      AMC.Mute = !rdbReceiveOn.Checked;

      chkbReceived.Enabled = rdbReceiveOn.Checked;
      chkbReceived.Checked = rdbReceiveOn.Checked;
    }

    private void btnStartTransmitMedia_Click(object sender, System.EventArgs e)
    {
      if (btnStartTransmitMedia.Text.Equals("Start"))
      {
        // Present a dialog to select the file to transmit.
        OpenFileDialog myOpenDlg = new OpenFileDialog();
        myOpenDlg.Filter = "wav files (*.wav)|*.wav|All files (*.*)|*.*";

        if(myOpenDlg.ShowDialog() == DialogResult.OK)
        {
          btnStartTransmitMedia.Text = "Stop";
          grpbReceive.Enabled = false;
          grpbTransmit.Enabled = false;
          grpbRecord.Enabled = false;

          try
          {
            // Starts to transmit the file to the server.
            AMC.StartTransmitMedia(myOpenDlg.FileName,0);
          }
          catch (ArgumentException ArgEx)
          {
            MessageBox.Show(ArgEx.Message,"Error");
          }
          catch (Exception Ex)
          {
            MessageBox.Show(Ex.Message,"Error");
          }
        }
      }
      else
      {
        btnStartTransmitMedia.Text = "Start";
        grpbReceive.Enabled = true;
        grpbTransmit.Enabled = true;
        grpbRecord.Enabled = true;

        try
        {
          // Ends the ongoing file-transmission.
          AMC.StopTransmitMedia();
        }
        catch (Exception Ex)
        {
          MessageBox.Show(Ex.Message,"Error");
        }
      }
    }

    private void connectButton_Click(object sender, System.EventArgs e)
    {
      // This URL is used to retrieve audio configuration from an Axis device with audio capability.
      AMC.AudioConfigURL = "http://" + ipText.Text + "/axis-cgi/audio/getparam.cgi";

      // The complete URL to an audio stream from an Axis video product.
      AMC.AudioReceiveURL = "http://" + ipText.Text + "/axis-cgi/audio/receive.cgi";

      // URL for transmitting audio to the server.
      AMC.AudioTransmitURL = "http://" + ipText.Text + "/axis-cgi/audio/transmit.cgi";
    }

In Visual C++ 6.0:

void CAudioSampleDlg::OnRdbReceiveOn()
{
  m_AMC.AudioReceiveStart();

  m_CheckBoxReceived.EnableWindow(true);
  m_CheckBoxReceived.SetCheck(1);

  SetRecordButtonStatus();
}

void CAudioSampleDlg::OnRdbReceiveOff()
{
  m_AMC.AudioReceiveStop();

  m_CheckBoxReceived.EnableWindow(false);
  m_CheckBoxReceived.SetCheck(0);

  SetRecordButtonStatus();
}

void CAudioSampleDlg::OnRdbTransmitOn()
{
  m_AMC.AudioTransmitStart();

  m_CheckBoxTransmitted.EnableWindow(true);
  m_CheckBoxTransmitted.SetCheck(1);

  SetRecordButtonStatus();
}

void CAudioSampleDlg::OnRdbTransmitOff()
{
  m_AMC.AudioTransmitStop();

  m_CheckBoxTransmitted.EnableWindow(false);
  m_CheckBoxTransmitted.SetCheck(0);
  SetRecordButtonStatus();
}

void CAudioSampleDlg::OnCheckBoxReceived()
{
  SetRecordButtonStatus();
}

void CAudioSampleDlg::OnCheckBoxTransmitted()
{
  SetRecordButtonStatus();
}

void CAudioSampleDlg::SetRecordButtonStatus()
{
  if (m_CheckBoxTransmitted.GetCheck() == 1 || m_CheckBoxReceived.GetCheck() == 1)
    m_StartRecordMedia.EnableWindow(true);
  else
    m_StartRecordMedia.EnableWindow(false);
}

void CAudioSampleDlg::OnConnect()
{
  CString str;

  this->UpdateData();

  // This URL is used to retrieve audio configuration from an Axis device with audio capability.
  str.Format(_T("http://%s/axis-cgi/audio/getparam.cgi"), m_ipText);
  m_AMC.SetAudioConfigURL(str);

  // The complete URL to an audio stream from an Axis product.
  str.Format(_T("http://%s/axis-cgi/audio/receive.cgi"), m_ipText);
  m_AMC.SetAudioReceiveURL(str);

  // URL for transmitting audio to the server.
  str.Format(_T("http://%s/axis-cgi/audio/transmit.cgi"), m_ipText);
  m_AMC.SetAudioTransmitURL(str);
}

In Visual Basic 6.0:

Private Sub CheckBoxReceived_Click()
  If CheckBoxReceived.Value = 1 Or CheckBoxTransmitted.Value = 1 Then
    cmdStartRecordMedia.Enabled = True
  Else
    cmdStartRecordMedia.Enabled = False
  End If
End Sub

Private Sub CheckBoxTransmitted_Click()
  If CheckBoxTransmitted.Value = 1 Or CheckBoxTransmitted.Value = 1 Then
    cmdStartRecordMedia.Enabled = True
  Else
    cmdStartRecordMedia.Enabled = False
  End If
End Sub
Private Sub rdbReceiveOff_Click()
  ' Mute received media
  AMC.Mute = True

  CheckBoxReceived.Enabled = False
  CheckBoxReceived.Value = 0
  If rdbTransmitOff.Value Then cmdStartRecordMedia.Enabled = False
End Sub

Private Sub rdbReceiveOn_Click()
  ' Unmute received media
   AMC.Mute = False

   CheckBoxReceived.Enabled = True
   CheckBoxReceived.Value = 1
   cmdStartRecordMedia.Enabled = True
End Sub

Private Sub rdbTransmitOff_Click()
  ' Mute received media
   AMC.AudioTransmitMute = True

   CheckBoxTransmitted.Enabled = False
   CheckBoxTransmitted.Value = 0
   If rdbReceiveOff.Value Then cmdStartRecordMedia.Enabled = False
End Sub

Private Sub rdbTransmitOn_Click()
  ' Unmute trasmitted media
  AMC.AudioTransmitMute = False

  CheckBoxTransmitted.Enabled = True
  CheckBoxTransmitted.Value = 1
  cmdStartRecordMedia.Enabled = True
End Sub
Private Sub connectButton_Click()
      ' This URL is used to retrieve audio configuration from an Axis device with audio capability.
  AMC.AudioConfigURL = "http://" + ipText.Text + "/axis-cgi/audio/getparam.cgi"

  ' The complete URL to an audio stream from an Axis video product.
  AMC.AudioReceiveURL = "http://" + ipText.Text + "/axis-cgi/audio/receive.cgi"

  ' URL for transmitting audio to the server.
  AMC.AudioTransmitURL = "http://" + ipText.Text + "/axis-cgi/audio/transmit.cgi"

End Sub


Microsoft Internet Explorer Samples

These descriptions and examples show how AMC can be used in Microsoft Internet Explorer.

The samples can be found under ({SDK} denotes the installation directory chosen for this SDK):

{SDK}\Samples\html

Samples

  • View Live MJPEG Unicast Stream
  • View Live MPEG-2 Unicast Stream
  • View Live MPEG-4 Unicast Stream
  • View MPEG-2 File
  • Setting properties and capture events from AMC
Notes on using AMC in JavaScript

In JavaScript the return values of the AMC methods MUST be handled like exceptions. This is done in by using try/catch blocks (see sample code).

Notes on setting properties in Internet Explorer

Due to requirements on back compatibility with Visual Basic 6, some AMC properties cannot be set using object tags. These must be set using JavaScript (see table below).

Property | HTML | JavaScript
AudioConfigURL |  | X
AudioReceiveURL |  | X
AudioTransmitURL |  | X
AudioTransmitMute |  | X
AudioTransmitVolume |  | X
AutoStart | X | X
CurrentPosition |  | X
DisplayMessages |  | X
Duration |  | X
FramesDrawn |  | X
FullScreen | X | X
MediaFile | X | X
MediaPassword | X | X
MediaType | X | X
MediaURL | X | X
MediaUsername | X | X
MotionConfigURL |  | X
MotionDataURL |  | X
MPEG2VideoDecodingMode | X | X
MPEG4VideoDecodingMode |  | X
MPEG4VideoRenderer |  | X
Mute | X | X
NetworkTimeout | X | X
PTZControlURL | X | X
ShowStatusBar | X | X
ShowToolbar | X | X
Status |  | X
StretchToFit | X | X
ToolbarConfiguration |  | X
UIMode | X | X
Volume | X | X

See Also

AXIS Media Control Usage | Microsoft Development Tool Samples


Sample: View Live MPEG-2 Unicast Stream in Internet Explorer

View Live MJPEG Unicast Stream

The most basic AMC functionality is the viewing of live streams from Axis video products supporting MJPEG. To do this, simply assign the MediaURL property a valid URL.

The MediaType property is used to determine the type of the media stream. For example, when it is known that the MJPEG stream is retrieved over HTTP the MediaType property should be set to "mjpeg-unicast". The default value ("auto-sense") also works.

By setting the AutoStart property to '1' AMC will start downloading the media stream directly.

If the Axis video product is configured for password protection, a valid user name and password must be used when accessing it. When using AMC, this is simply managed by setting the properties MediaUsername and MediaPassword to valid values.

<object id="Player" height="640" width="720" border="1"
  classid="CLSID:745395C8-D0E1-4227-8586-624CA9A10A8D">
  <param name="AutoStart" value="1">
  <param name="UIMode" value="none">
  <param name="MediaType" value="mjpeg-unicast">
  <param name="NetworkTimeout" value="5000">
  <param name="MediaUsername" value="">
  <param name="MediaPassword" value="">
  <param name="MediaURL" value="http://myserver/axis-cgi/mjpg/video.cgi">
</object>


Sample: View Live MPEG-2 Unicast Stream in Internet Explorer

View Live MPEG-2 Unicast Stream

The most basic AMC functionality is the viewing of live streams from Axis video products supporting MPEG-2. To do this, simply assign the MediaURL property a valid URL. A call to the Play method will then use the assigned media URL to retrieve the MPEG-2 stream from the Axis video product.

The MediaType property is used to determine the type of the media stream. For example, when it is known that the MPEG-2 stream is retrieved over HTTP the MediaType property should be set to "mpeg2-unicast". The default value ("auto-sense") also works.

If the Axis video product is configured for password protection, a valid user name and password must be used when accessing it. When using AMC, this is simply managed by setting the properties MediaUsername and MediaPassword to valid values.

<object id="Player" height="640" width="720" border="1"
  classid="CLSID:745395C8-D0E1-4227-8586-624CA9A10A8D">
  <param name="UIMode" value="none">
  <param name="MediaType" value="mpeg2-unicast">
  <param name="NetworkTimeout" value="5000">
  <param name="MediaUsername" value="">
  <param name="MediaPassword" value="">
  <param name="MediaURL" value="http://myserver/mpeg2/video.mpeg">
</object>

[...]

<script language="JavaScript">
<!--
  try
  {
    // return values from AMC methods are handled as exceptions in JavaScript
    document.Player.Play();
  }
  catch(e){}
//-->
</script>


Sample: View File in Internet Explorer

View MPEG-2 File

Viewing a media file is easy with AMC. Simply assign the MediaFile property a correct path for the file to view. The AutoStart property is set so that the media stream is not played until the method Play is called.

The MediaType property is used to determine the type of the media stream. When the media stream is played from a file, the MediaType property should be set to "auto-sense".

In the sample, two buttons, "Play" and "Stop", are used to start and stop viewing the file. When "Play" is pressed, the method Play is called and the file starts to play. When "Stop" is pressed, the method Stop is called, and the file is stopped.

<form name="test">
  <form name="test">
  <input type="button" name="Play" value="Play" onClick="OnPlay(); return false;">
  <input type="button" name="Stop" value="Stop" onClick="OnStop(); return false;">
</form>
<object id="Player" height="640" width="720" border="1"
  classid="CLSID:745395C8-D0E1-4227-8586-624CA9A10A8D">
  <param name="AutoStart" value="0">
  <param name="UIMode" value="none">
  <param name="MediaType" value="auto-sense">
  <param name="MediaFile" value="c:\winnt\clock.avi"><!-- your media file goes here -->
</object>

<script language="JavaScript">
<!--
function OnPlay()
{
  try
  {
    // return values from AMC methods are handled as exceptions in JavaScript
    document.Player.Play();
  }
  catch(e){}
}

function OnStop()
{
  try
  {
    // return values from AMC methods are handled as exceptions in JavaScript
    document.Player.Stop();
  }
  catch(e){}
}
//-->
</script>


Sample: Setting properties and capture events from AMC

Setting properties and capture events from AMC

AMC sends various events. One example is OnError, which is sent when an asynchronous error occurs.

When using JavaScript to access the programming interface of AMC, follow the conventions for specifying methods or properties for this language:

    AMC.Method(parameter)
    AMC.property = value
NOTICE: In JavaScript the return values of the AMC methods MUST be handled like exceptions.

NOTICE: Some properties MUST be set using JavaScript (see list).

JavaScript does not currently include event syntax for non-HTML objects. However, with Internet Explorer you can use the <SCRIPT> tag's For...Event syntax.

<script language="JavaScript" for="Player" event="OnError(theError, theMsg)">
<!--
  alert(theError + ' ' + theMsg);
//-->
</script>

<script language="JavaScript">
<!--
  //some properties must be set using JavaScript
  document.Player.EnableReconnect = false;
//-->
</script>


Sample: View Live MPEG-4 Multicast Stream in Internet Explorer

View Live MPEG-4 Multicast Stream

The most basic functionality in the AXIS Media Control is the viewing of live streams from Axis video products supporting MPEG-4. To do this, simply assign the MediaURL property a valid URL. A call to the Play method will then use the assigned media URL to retrieve the MPEG-4 stream from the Axis video product.

When viewing MPEG-4 the URL-type shall be "rtsp" or one of the types defined in Custom Protocols for MPEG-4. The MediaType shall always be auto-sense when viewing MPEG-4 streams, except when using URL-type axsdp.

The URL-type rtsp will let AMC test all MPEG-4 protocols the first time AMC connects to the MPEG-4 stream of an Axis server. The first protocol that is usable will be remembered for future connections. This URL-type is not usable in Windows Media Player to use Axis components to access Axis products.

If the Axis video product is configured for password protection, a valid user name and password must be used when accessing it. When using AMC, this is simply managed by setting the properties MediaUsername and MediaPassword to valid values.

<object id="Player" height="640" width="720" border="1"
  classid="CLSID:745395C8-D0E1-4227-8586-624CA9A10A8D">
  <param name="AutoStart" value="0">
  <param name="UIMode" value="none">
  <param name="MediaType" value="auto-sense">
  <param name="NetworkTimeout" value="5000">
  <param name="MediaUsername" value="">
  <param name="MediaPassword" value="">
  <param name="MediaURL" value="axrtpu://10.13.24.77/mpeg4/media.amp">
</object>

[...]

<script language="JavaScript">
<!--
  try
  {
    // return values from AMC methods are handled as exceptions in JavaScript
    document.Player.Play();
  }
  catch(e){}
//-->
</script>