End User Licenses Agreement (EULA)

Decoder API

Description

The Network video decoder gives the user the ability to control the content displayed on the decoder. This API is focused on the view configuration, in which a view describes the layout of the screen that the decoder is connected to. The view is configured when it is about to be displayed, meaning that there isn’t any need to configure each video source prior to displaying them.

The VAPIX® Decoder API methods
MethodUsage
getCapabilitiesShow what the decoder is capable of.
getSupportedVersionsGet a list of supported API versions.
getViewConfigurationGet the current configuration.
setViewConfigurationConfigure what the decoder shall display.

Model

The API consists of the single CGI decoder.cgi and can be called with a JSON body using HTTP POST. The JSON body contains information about which method that should be invoked and supplies the parameters for that method.

The different methods will allow a client application to:

  • query what capabilities the decoder has and what versions of the API that is supported.

  • get and set the configuration.

The configuration that is uploaded with the CGI defines the view of the decoder. One view fills the entire screen. If several views are defined, then the decoder will loop through them in a sequence.

View configuration

The view is divided into one or more segments. Each segment consists of a pane and a video stream (panel-within-a-panel). The pane describes where the video stream should be drawn in the view. Putting multiple views together creates a sequence, with a run-time (duration), which is measured in seconds.

The coordinate system for the view has its origin in the upper left corner. The view is one unit wide and one unit high giving the coordinates for the bottom right corner 1, 1 and the center of the view 0.5, 0.5.

Identification

Property

Properties.API.Decoder.Decoder=yes

Product category

Network Video Decoder

Obsoletes

/axis-cgi/alarm.cgi

/axis-cgi/videocontrol.cgi

Limitations

  • This API does not support sequences if they are in a split view.

  • This API supports Vapix 3 cameras only.

  • This API does not support the P7701 decoder.

Common examples

Display a single video stream

Use this example to define what video should be displayed on the decoder.

1. Set up the view configuration.

http://myserver/axis-cgi/decoder.cgi
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "params": {
    "panes": [
      {
        "paneId": 0,
        "left": 0.0,
        "top": 0.0,
        "right": 1.0,
        "bottom": 1.0
      }
    ],
    "streams": [
      {
        "streamId": 0,
        "url": "rtsp://192.168.0.90/axis-media/media.amp?resolution=1920x1080",
        "videoCodec": "H264",
        "audioCodec": "",
        "username": "viewer",
        "password": "pass"
      }
    ],
    "views": [
      {
        "viewId": 0,
        "duration": 0,
        "segments": [
          {
            "stream": 0,
            "pane": 0
          }
        ]
      }
    ]
  }
}

2. Parse the JSON response to retrieve the configuration ID.

a. Successful response example.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "data": {
    "configurationId": "1042"
  }
}

b. Failure response example.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "errors": [
    {
      "code": 200,
      "message": "Internal error"
    }
  ]
}

For further instructions, see setViewConfiguration.

Display multiple video streams

Use this example to monitor all the cameras in, for example, a store, from a screen.

1. Configure the view

http://myserver/axis-cgi/decoder.cgi
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "params": {
    "panes": [
      {
        "paneId": 0,
        "left": 0.0,
        "top": 0.0,
        "right": 0.5,
        "bottom": 0.5
      },
      {
        "paneId": 1,
        "left": 0.5,
        "top": 0.0,
        "right": 1.0,
        "bottom": 0.5
      },
      {
        "paneId": 2,
        "left": 0.0,
        "top": 0.5,
        "right": 0.5,
        "bottom": 1.0
      },
      {
        "paneId": 3,
        "left": 0.5,
        "top": 0.5,
        "right": 1.0,
        "bottom": 1.0
      }
    ],
    "streams": [
      {
        "streamId": 0,
        "url": "rtsp://192.168.0.90/axis-media/media.amp?resolution=1280x720...",
        "videoCodec": "H264",
        "audioCodec" "AAC",
        "username": "viewer",
        "password": "pass"
      },
      {
        "streamId": 1,
        "url": "rtsp://192.168.0.91/axis-media/media.amp?resolution=1280x720...",
        "videoCodec": "H264",
        "username": "viewer",
        "password": "pass"
      },
      {
        "streamId": 2,
        "url": "rtsp://192.168.0.92/axis-media/media.amp?resolution=1280x720...",
        "videoCodec": "H264",
        "username": "viewer",
        "password": "pass"
      },
      {
        "streamId": 3,
        "url": "rtsp://192.168.0.93/axis-media/media.amp?resolution=1280x720...",
        "videoCodec": "H264",
        "username": "viewer",
        "password": "pass"
      }
    ],
    "views": [
      {
        "viewId": 0,
        "duration": 0,
        "segments": [
          {
            "stream": 0,
            "pane": 0
          },
          {
            "stream": 1,
            "pane": 1
          },
          {
            "stream": 2,
            "pane": 2
          },
          {
            "stream": 3,
            "pane": 3
          }
        ]
      }
    ]
  }
}

2. Parse the JSON response to retrieve the configuration ID.

a. Successful response example.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "data": {
    "configurationId": "1042"
  }
}

b. Failure response example.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "errors": [
    {
      "code": 400,
      "message": "Failed to connect",
      "viewId": 0,
      "streamId": 2
    },
    {
      "code": 100,
      "message": "15"
    }
  ]
}

For further instructions, see setViewConfiguration.

Display multiple video streams in a sequence

Use this example to watch videos from several camera sources, some of which can be viewed at the same time.

1. Configure the view by calling:

http://myserver/axis-cgi/decoder.cgi
Note
The time must be set in seconds for the duration parameter to work.
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "params": {
    "panes": [
      {
        "paneId": 0,
        "left": 0.0,
        "top": 0.0,
        "right": 0.5,
        "bottom": 0.5
      },
      {
        "paneId": 1,
        "left": 0.5,
        "top": 0.0,
        "right": 1.0,
        "bottom": 0.5
      },
      {
        "paneId": 2,
        "left": 0.0,
        "top": 0.5,
        "right": 0.5,
        "bottom": 1.0
      },
      {
        "paneId": 3,
        "left": 0.5,
        "top": 0.5,
        "right": 1.0,
        "bottom": 1.0
      },
      {
        "paneId": 4,
        "left": 0.0,
        "top": 0.0,
        "right": 1.0,
        "bottom": 1.0
      }
    ],
    "streams": [
      {
        "streamId": 0,
        "url": "rtsp://192.168.0.90/axis-media/media.amp?resolution=1280x720...",
        "videoCodec": "H264",
        "username": "viewer",
        "password": "pass"
      },
      {
        "streamId": 1,
        "url": "rtsp://192.168.0.91/axis-media/media.amp?resolution=1280x720...",
        "videoCodec": "H264",
        "username": "viewer",
        "password": "pass"
      },
      {
        "streamId": 2,
        "url": "rtsp://192.168.0.92/axis-media/media.amp?resolution=1280x720...",
        "videoCodec": "H264",
        "username": "viewer",
        "password": "pass"
      },
      {
        "streamId": 3,
        "url": "rtsp://192.168.0.93/axis-media/media.amp?resolution=1280x720...",
        "videoCodec": "H264",
        "username": "viewer",
        "password": "pass"
      },
      {
        "streamId": 4,
        "url": "rtsp://192.168.0.94/axis-media/media.amp?resolution=1280x720...",
        "videoCodec": "H264",
        "username": "viewer",
        "password": "pass"
      }
    ],
    "views": [
      {
        "viewId": 0,
        "duration": 60,
        "segments": [
          {
            "stream": 0,
            "pane": 0
          },
          {
            "stream": 1,
            "pane": 1
          },
          {
            "stream": 2,
            "pane": 2
          },
          {
            "stream": 3,
            "pane": 3
          }
        ]
      },
      {
        "viewId": 1,
        "duration": 60,
        "segments": [
          {
            "stream": 4,
            "pane": 4
          }
        ]
      }
    ]
  }
}

2. Parse the JSON response to retrieve the configuration ID.

a. Success response example.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "data": {
    "configurationId": "1042"
  }
}

b. Failure response example.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "errors": [
    {
      "code": 200,
      "message": "Internal error"
    }
  ]
}

For further instructions, see setViewConfiguration.

Get decoder capabilities

Use this example to check what is supported on the decoder.

1. Get the capabilities by calling:

http://myserver/axis-cgi/decoder.cgi
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getCapabilities"
}

2. Parse the JSON response to retrieve the capabilities.

a. Successful response example.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getCapabilities",
  "data": {
    "resolution": "1920x1080",
    "maxStreams": 16,
    "videoCodecs": ["H.264", "MJPEG", "MPEG4"],
    "audioCodecs": [],
    "overlappingPanes": false
  }
}
Note
The resolution in this the response refers to the decoder resolution setting that is currently in use.

For further instructions, see getCapabilities.

Retrieve running configuration

Use this example to receive status information on a configuration after restarting the video stream and whether the configuration is still in use.

1. Get the running configuration by calling:

http://myserver/axis-cgi/decoder.cgi
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getViewConfiguration"
}

2. A successful request returns the ID of the active configuration.

a. Successful response example.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getViewConfiguration",
  "data": {
    "configurationId": "23"
  }
}

For further instructions, see getViewConfiguration.

API specification

getCapabilities

List all the capabilities that the decoder supports.

Capabilities table
FieldPossible valuesDescription
resolution1920x1080, 1280x720, 720x480, 640x480One of the supported resolutions for the decoder and the one currently in use.
maxStreams1, ...The maximum supported amount of open video streams.
videoCodecsH264, MPEG4, MJPEGList of video codecs supported by the decoder.
audioCodecsAAC, G711, G726List of video codecs supported by the decoder.
overlappingPanestrue, falseWhether the decoder supports overlapping panes in a picture in picture feature or not.

Request

Security level

Operator

Method

POST

http://myserver/axis-cgi/decoder.cgi

The following table lists the JSON parameters for this CGI method.

getCapabilities parameters table
ParameterTypeDescription
apiVersionStringThe requested API version in the format Major.Minor.
contextStringOptional context string. Client sets this value and the cgi echoes it back in the response.
methodStringThe operation to perform.

Return value - Success

Returns the decoder capabilities.

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getCapabilities",
  "data": {
    "resolution": resolution,
    "maxStreams": maxStreams,
    "videoCodecs": [videoCodecs],
    "audioCodecs": [audioCodecs],
    "overlappingPanes": true/false
  }
}

Error information

The method can return the following errors:

Error codes
CodeTitle
200Internal error.
201Unsupported API version.
202Invalid JSON.

See General event codes for more information.

getSupportedVersions

A CGI method for retrieving the supported API versions. The returned lists consists of the supported major versions, together with the highest supported minor versions. Note that the version is for the API as a whole, i.e. for all methods in the CGI.

Request

Security level

Operator

Method

POST

http://myserver/axis-cgi/decoder.cgi

The following table lists the JSON parameters for this CGI method.

getSupportedVersions data parameters table
ParameterTypeDescription
apiVersionStringThe requested API version in the format Major.Minor.
contextStringOptional context string. Client sets this value and the CGI echoes it back in the response.
methodStringThe operation to perform.

Return value - Success

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["1.0"]
  }
}

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getSupportedVersions",
  "error": [
    {
      "code": 200,
      "message": "Internal error"
    }
  ]
}

Error information

The method could return the following errors:

Error codes
CodeTitle
200Internal error.
201Unsupported API version.
202Invalid JSON.

See General event codes for more information.

getViewConfiguration

Request

Security level

Operator

Method

POST

http://myserver/axis-cgi/decoder.cgi

The following table lists the JSON parameters for this CGI method.

getViewConfiguration parameters table
ParameterTypeDescription
apiVersionStringThe requested API version in the format Major.Minor.
contextStringOptional context string. Client sets this value and the CGI echoes it back in the response.
methodStringThe operation to perform.

Return value - Success

Returns the ID of the currently running configuration.

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getViewConfiguration",
  "data": {
    "configurationId": "23",
  }
}

Error information

The method could return the following errors:

Error codes
CodeTitle
200Internal error.
201Unsupported API version.
202Invalid JSON.

See General event codes for more information.

setViewConfiguration

This method sets the configuration of the current view. The decoder will only have one running configuration. The current configuration will be overwritten in the next successful call to setViewConfiguration. The running configuration is saved on the decoder so that it is able to recover after a restart.

Note
Camera credentials are not encrypted. Consider using HTTPS for increased security.

Request

Security level

Operator

Method

POST

http://myserver/axis-cgi/decoder.cgi

The following table lists the JSON parameters for this CGI method.

setViewConfiguration parameters table
ParameterTypeDescription
apiVersionStringThe requested API version in the format Major.Minor.
contextStringOptional context string. Client sets this value and the CGI echoes it back in the response.
methodStringThe operation to perform.
paramsJSON ObjectContainer for the method specific parameters listed below.
panesArrayA pane is a canvas on which a video stream is drawn upon. The pane object contains size and position for where the video stream should be drawn on the view. The video stream should always keep its own aspect ratio when drawn on a pane. The coordinate for the upper left corner of the view is 0,0 and the coordinate for the bottom right corner is 1,1.
streamsArrayThe stream object contains the necessary information about the video stream. Each stream must have a url that specifies where the decoder can reach the video, and which video codec the decoder should use. Should the camera require a login, then the username and password credentials must be provided. If the decoder supports audio then one of the streams may have the audioCodec parameter set. The audioCodec parameter is empty by default.
viewsArrayThe view is the model of the entire screen area. The coordinate system of a view is one unit wide and one unit high. The origin is located in the upper left corner, the lower right corner has the coordinate 1,1. A configuration can contain several views, i.e. screen areas consisting of several view areas. In the case that the views are displayed in a sequence, each view is displayed for the amount of seconds stated in the duration parameter. If the duration is set to 0, then the view will be displayed continuously. The view is divided into segments that could either fit the whole view, or just a part of it. One pane object and one stream object will together form a view segment.
durationArrayThe duration object contains the run time of a sequence, measured in seconds. If the value is set to 0, only the current view will be shown.

Return value - Success

Returns the ID of the newly created configuration.

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "data": {
    "configurationId": "1042"
  }
}

Return value - Failure

Returns an array of errors. The errors are in the same format as the events in the event stream.

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "errors": [
    {
      "code": 200,
      "message": "Internal error"
    }
  ]
}

The decoder could choose to use the provided configuration if the errors are not serious enough, and will then also return the new configuration ID. This could be if the configuration contains several video streams and the decoder can’t connect to one or more of them. The decoder will try to reconnect to all of the video sources, and if the information provided by the software is correct it will eventually be able to connect. In this case it is up to the software to choose if it should re-send a new configuration or continue with the current configuration.

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setViewConfiguration",
  "errors": [
    {
      "code": 400,
      "message": "Failed to connect",
      "viewId": 0,
      "streamId": 2
    },
    {
      "code": 100,
      "message": "15"
    }
  ]
}

Error information

The method could return the following errors:

Event method codes
CodeTitle
100Configuration changed.
200Internal error.
201Unsupported API version.
202Invalid JSON.
210Illegal view ID.
211Illegal pane ID.
212Pane out of bound.
400Failed to connect.
401Not authenticated.
402Out of resources.
403Unsupported protocol.
410Illegal stream ID.

See General event codes for more information.

General event codes

There are two types of events in the API: base- and stream-events and are currently only sent as errors. The base event gives general information about the request and decoder status. The stream event will give specific information regarding a certain video stream.

The events are specified as follows:

Base event:
{
  "code": {"type": "integer", "minimum":0},
  "message": {"type": "string"}
}

Stream event:
{
  "code": {"type": "integer", "minimum": 0},
  "message": {"type": "string"},
  "viewId": {"type": "integer", "minimum": 0},
  "streamId": {"type": "integer", "minimum": 0},
}
Event status code ranges
CodeType
1xxInformation.
2xxError.
3xxReserved for stream information.
4xxStream error.

The following table lists general event codes that can occur for any CGI method. Events that are specific for a method are listed under the API description for that method. The message field will in some cases contain data instead of a message, these events are specified in the following table as well. Title may be used as a message in all the other cases.

General event codes
CodeTitleMessageDescription
100Configuration changedConfiguration IDThe configuration has been changed. The ID of the new configuration is provided in the message field.
200Internal errorGeneric error.
201Unsupported API versionThe decoder does not support the API version provided in the request.
202Invalid JSONThe decoder could not parse the provided JSON object.
210Illegal view IDID is either a duplicate or not a positive integer.
211Illegal pane IDID is either a duplicate or not a positive integer.
212Pane out of boundPane IDParts of the pane are outside of the view.
213Overlapping panePane IDThe pane is overlapping another pane and the decoder does not support picture-in-picture (overlappingPanes=false in getCapabilities).
400Failed to connectThe decoder could not connect to the streaming device.
401Not authenticatedThe provided credentials were not accepted.
402Out of resourcesGeneric error when the decoder does not have enough resources to render the provided configuration.
403Unsupported protocolThe decoder is not able to play the video or audio provided in the configuration.
410Illegal stream IDID is either a duplicate or not a positive integer.
DayNight API
Dewarped views
Cookie settings
 • 
My Axis
 • 
Developer community
 • 
About

©2008 - 2024 Axis Communications AB. AXIS COMMUNICATIONS, AXIS, ARTPEC and VAPIX are registered trademarks of Axis AB in various jurisdictions. All other trademarks are the property of their respective owners. We reserve the right to introduce modifications without notice.