AVP Contribution API

REST Interface for Contribution and DSNG encoders

SP0006 SNMP XPO2b External Contribution

Standard Practice Interfaces API

NBI

SNMP HTTP/DCP1 XML-RPC Contribution

NetSNMP Web Server Web Server Web Server

Alarm MIB Config MIB tcf xmlrpc.cgi API

FM CM CM CM CM

Parameter Store

Device XML

Config Manager

Map

Option card

Rev PC3
 AVP Contribution API

Abstract
The AVP Contribution API is designed to be used by third-party control
systems. The goals are:

- To provide an easy-to-use Configuration Management (CM) interface over

HTTP

- To facilitate integration of third-party control system with Contribution

encoders and News Gathering encoders by exposing the adequate
configuration resources

The intended audience of this document is:

Software developers and system integrators

2
 AVP Contribution API

Contents
1 Terminology ................................................................................ 4
2 Requirements .............................................................................. 5
2.1 Hardware requirements................................................................. 5
2.2 Common API requirements ........................................................... 6
2.3 Configuration at base .................................................................... 7
2.4 Configuration in the field ............................................................... 8
3 General concepts ........................................................................ 8
3.1 Base URL ..................................................................................... 9
3.2 Methods supported ....................................................................... 9
3.3 HTTP status codes ..................................................................... 10
3.4 Timeout....................................................................................... 11
3.5 HTTP request headers ................................................................ 11
3.6 HTTP response headers ............................................................. 12
3.7 HTTP Authentication ................................................................... 12
4 Carrier ID configuration ............................................................ 13
4.1 Reading the Carrier ID ................................................................ 13
4.2 Setting the Carrier ID .................................................................. 13
4.3 CarrierID object ........................................................................... 14
5 System operation ...................................................................... 15
5.1 Setting the system operations ..................................................... 15
6 Device Status ............................................................................ 16
6.1 Reading the Device Status.......................................................... 16
7 Services ..................................................................................... 17
7.1 List all services ........................................................................... 17
7.2 Service update ............................................................................ 18
7.3 Service object ............................................................................. 20
8 Pre-stored configurations ........................................................ 34
8.1 List all the pre-sets ...................................................................... 35
8.2 Read a single pre-set .................................................................. 35
8.3 Saving the current parameters in a pre-set ................................. 36
8.4 Re-calling a pre-set ..................................................................... 36
8.5 Clear a pre-set ............................................................................ 37
8.6 Pre-set Object ............................................................................. 37
9 Alarms ....................................................................................... 37
9.1 List all the alarms ........................................................................ 37
9.2 Alarm object ................................................................................ 38
10 Error messages ......................................................................... 38
11 References ................................................................................ 41
12 Change information .................................................................. 41

3
 AVP Contribution API

1 Terminology
ACM Adaptive Coding and Modulation

API Application Programming Interface

BISS Basic Interoperable Scrambling System

CBR Constant Bit-Rate

DSNG Digital Satellite News Gathering

DVB-S2 Digital Video Broadcasting Satellite 2nd generation

DVB-S2X Optional Extensions to the DVB-S2 system

FEC Forward Error Correction

HD High Definition

HEVC High Efficiency Video Coding

HTTP HyperText Transfer Protocol

JSON JavaScript Object Notation

MPEG Moving Picture Experts Group

PID Packet Identifier, in MPEG-2 TS terms

PMT Program Map Table, in MPEG2-TS terms

QPSK Quadrature Phase Shift Keying

REST Representational State Transfer

RF Radio Frequency

SD Standard Definition

SDI Serial Digital Interface

SPTS Single Program Transport Stream

URL Uniform Resource Locator

VCM Variable Coding and Modulation

XML eXtensible Markup Language

XPO eXtensible Programming Objects, proprietary legacy

protocol

4
 AVP Contribution API

2 Requirements

2.1 Hardware requirements

This API shall support CE-x, CE-x Analogue, CE-a J2K and CE-HEVC cards
in an AVP3000 or AVP2000 chassis.

External sync card shall be present in the chassis in order to use External
clock-mode in the Modulation object.

Note: CE-a option cards are currently not supported.

2.1.1 Single PSU chassis

The API shall be supported on devices following the recommended Option

Card configuration:

Option Card Maximum number of Slot number

modules

CE-x (or CE-xA) 2 pair Fitted as a pair

in slot 3 & 4 and
slot 1 & 2 (slot 3
or 1 = pre-processor,
slot 4 or 2 = encoder)

HEVC 1 Any available

SatMod (optional) 1 6

ASI (optional) 1 Any available

2.1.2 Dual PSU chassis

The API shall be supported on devices following the recommended Option

Card configuration:

Option Card Number of modules Slot number

CE-x (or CE-xA) 1 pair Fitted as a pair in slot 3

& 4 (slot 3 = pre-
processor, slot 4 =
encoder)

HEVC 1 Any available

5
 AVP Contribution API

SatMod (optional) 1 2

ASI (optional) 1 Any available

2.2 Common API requirements

The API shall be compact. This means that the API shall be focused on the
elements of configuration specific to Contribution Encoders and News
Gathering to allow for fast integration cycles with third-party control systems.
Internal parameters or elements belonging to other market segments (e.g.
Direct-To-Home) shall not be exposed through this API.

The API shall be orthogonal. This means when changing a parameter on a

device, the device cannot autonomously change another parameter
somewhere else in the configuration.

The API shall provide a configuration counter, incrementing every time a new
configuration has been successfully applied. This is to allow a third-party
control system to detect changes made through the Web User Interface or
other interfaces into the configuration of the device.

Access to this API shall be activated by a license. MediaKind uses this to track
API usage. Once activating this API by license, use of the web interface and
existing control interfaces are allowed but with the following limitations:

• The two first services will be controlled by this API, as well as editable
through the user interface and the front panel.

A global On/Off switch shall be available in the user interface to activate

access to this API. Enabling the API shall create the two services max.
Disabling the API will not modify the service configuration.

When the API is disabled, either by using the global On/Off switch or by not
applying the license, the device shall return 404 Not Found on all URLs
specified in the document.

If the API license is not present on the device, the device shall return:
HTTP/1.1 404 Not Found
Content-Length: nnn
Content-Type: application/json

The content of the response is arbitrary.

If the API is disabled via the global On/Off switch, the device shall return:
HTTP/1.1 403 Forbidden
Content-Length: nnn
Content-Type: application/json

6
 AVP Contribution API

{
"error" : {
"status" : "403 Forbidden",
"title" : "Third-party API is disabled. Enable it through
the user interface."
}

The use of this API shall be subject to explicit acceptance of “Terms of

Service”. The “Terms of Service” will be agreed with MediaKind Legal.

The API shall provide the developer the ability to create encoding services,
without having to specify on which physical resource each phase of the
encoding process (e.g. SDI de-embedding, Encoding, MUX, Satellite
Modulation) will be achieved.

The API shall be the only point of contact for configuration. This API is
dedicated to third-party control system and does not provide the same
features as the web user interface or the front panel, if available.

The Contribution device shall support every item exposed in the API.

This Contribution API shall provide configuration management for up to two

services. No remux. Number of audios per service is constrained so that
configuration rejections due to over-allocation do not occur. Each service is
generated as an SPTS.

This Contribution API shall provide configuration management for up to 64

pre-sets.

The API shall be provided over HTTP, in a REST-like manner.

The API shall use clean URLs. E.g: Error! Hyperlink reference not valid.

The body of the HTTP requests and responses uses JSON, which is an easy
interchange format and faster to parse than XML. JSON is completely
independent of the programming language. In many cases, JSON is smaller
than XML.

The current version of this API should be backwards compatible with previous
releases. Commands implemented now should continue to work in future
releases of this API.

2.3 Configuration at base

The API shall provide the ability to setup the device with a limited number of
Contribution services. The maximum number of services supported depends
on the hardware configuration of the device.

The API shall provide the ability to store configurations on the device.

The API shall allow enabling and disabling of audio components.

7
 AVP Contribution API

2.4 Configuration in the field

The API shall provide the ability to:

• Re-call pre-stored configurations on the device

• For the Satellite Modulator Output:

o Set RF parameters:

o Carrier low power (Modulation = OFF)

o Carrier Nominal power (Modulation = OFF)

o Modulation = ON

• For the ASI Output

o Set output = ON

o Set output = OFF

• For the IP Output

o Set output = ON

o Set output = OFF

The API shall support bit-rate tracking.

In bit-rate tracking, the video rate shall be calculated as a function of the TS

rate – PSI – Audio ES Rate – other components.

For satellite modulator output, the TS rate shall be calculated as a function of

the DVB S/S2/S2X/DSNG, FEC, Carrier and Symbol Rate. For other outputs,
the bitrate is explicitly set through a property in the output object.

The traffic generated by the API shall allow control over slow links (e.g.
56Kbit/s dial-up connections).

Access to the API shall be limited to 10 requests per minute.

3 General concepts
This API is based on the Hypertext Transfer Protocol, as defined in [1]. The
bodies of HTTP request and responses are encoded in JSON, as defined in
[2], and carried in the HTTP body as defined in [3].

Note: The HTTP Host header and the \r\n at the end of each line (as defined in
[1]) are omitted from the examples, but shall still be inserted accordingly:
GET /API/Contribution/CarrierID HTTP/1.1\r\n

8
 AVP Contribution API

Host: 10.0.0.1\r\n
Accept: application/json\r\n
\r\n

3.1 Base URL

The base URL used by HTTP clients to access the Contribution API is:
http://<hostname>/API/Contribution

3.2 Methods supported

The HTTP client methods supported are GET, PUT, POST and DELETE.

A Collection URI contains several items. Each item can be another Collection
or an Object. Items in a Collection are addressed by index number.

An Object URI contains a list of name/value pairs, referred to as parameters.

Method General description Collection URI Object URI

GET Retrieve data from the device. List all the Items and Retrieve a
This method is ’safe’ in the sense Collections contained representation of the
that it does not modify the device in the URI. object at the URI.
configuration.

PUT Update the addressed data with Update items in order Update the object by
provided representation. This is of appearance in the replacing the values
method is ‘idempotent’, as multiple array. Each object is of properties with
identical requests shall have the updated as if it were values in the object
same effect that a single request PUT as an object. supplied. Omitted
properties will be left
in their previous state.

POST Not allowed. The device shall Not allowed. The Not allowed. The
respond 405 Method Not device shall respond device shall respond
Allowed, with the Allow header 405 Method Not 405 Method Not
set to GET, PUT Allowed, with the Allowed, with the
Allow header set to Allow header set to
GET, PUT GET, PUT

DELETE Not allowed. The device shall Not allowed. The Not allowed. The
respond 405 Method Not device shall respond device shall respond
Allowed, with the Allow header 405 Method Not 405 Method Not
set to GET, PUT Allowed, with the Allowed, with the
Allow header set to Allow header set to
GET, PUT GET, PUT.

The Collection URIs provided by this API are:

9
 AVP Contribution API

http://<hostname>/API/Contribution/Services/
http://<hostname>/API/Contribution/Presets/
http://<hostname>/API/Contribution/Alarms/

Requests to Collection URIs shall provide JSON arrays.

The Object URIs provided by this API are:

http://<hostname>/API/Contribution/CarrierID
http://<hostname>/API/Contribution/System
http://<hostname>/API/Contribution/Status
http://<hostname>/API/Contribution/Services/<service-index>
http://<hostname>/API/Contribution/Presets/<preset-index>
http://<hostname>/API/Contribution/Alarms/<alarm-index>

Requests to Object URIs shall provide JSON objects. Note: JSON Objects are
naturally un-ordered.

The service-index is the index number of the service within the Services
collection.

The preset-index is the index number of the pre-set within the Pre-sets
collection.

3.2.1 Notes on PUT behavior

When attempting to PUT an object into a URI, it is valid to send an incomplete

or empty object. Properties that are specified in the sent object are applied to
the object at the specified URI and existing properties are left unchanged.

When attempting to PUT a collection of objects into a collection URI, it is

possible to use the above behavior to update an item in an arbitrary location in
the collection. As an example, to update the bitrate of the third audio
component in the audio collection of the first service, the following can be PUT
to /API/Contribution/Services/0:

[
{},
{},
{"bitrate": 192}
]

The use of empty objects means that audio components 1 and 2 will not be
updated, only the third component will be updated.

3.3 HTTP status codes

The device shall reply to a request with the following status codes:
Status Code Description
200 OK Successful request. This acknowledges that device has received the
request and that the request is well-formed.

10
 AVP Contribution API

Status Code Description

201 Created The resource has been created and persisted. The URI of the newly
created resource shall be found in the Location response header.
400 Bad Request The request could not be understood by the server due to malformed
syntax. The client SHOULD NOT repeat the request without modifications.
The addressed resource has not been modified.
401 Unauthorized Returned when a request requires authentication or the authentication
failed.
403 Forbidden Authentication unsuccessful. The request has failed authentication.
Further connection attempts using the same URL will fail.
404 Not Found The server has not found anything matching the request URI.
405 Method Not The method specified is not allowed for the resource identified by the
Allowed Request-URI. The response shall include an Allow header containing a
list of valid methods for the requested resource.
500 Internal Returned when the device web server fails because of an internal device
Server Error error. The details of the error are found in the device’s logs and alarms.

3.4 Timeout
The default HTTP timeout is 15 seconds. Some messages may require an
adjusted timeout, which will be specified in this documentation.

3.5 HTTP request headers

The Accept field shall be set to application/json.

Where a HTTP request body is provided, the Content-Type field shall be set
to application/json.

Where a HTTP request body is provided, the Content-Length shall be set

to the size of the body of the HTTP request, in decimal number of bytes. See
[1].

3.5.1 X-API-Key

The device may accept the X-API-Key HTTP header in every API call made.

The device shall allow API access for every call made with the special API
key.

If the X-API-Key is not present in the request or invalid and the API license is
on the device, the device shall allow API requests.

If the X-API-Key is not present in the request or invalid and the API license is
not on the device, the device shall not allow API requests and shall return the
following error:
HTTP/1.1 404 Not Found
Content-Length: nnn

11
 AVP Contribution API

Content-Type: application/json

The X-API-Key header shall be constructed as:

md5(api_key + md5(url + api_key))

The api_key parameter is the user's secret API key that can be retrieved from
the API Key Database. The url parameter is the path of the URL being
requested (minus any parameters, host name, IP address, and http://), e.g.
http://<server>/API/Services/1 would be simply /API/Services/1. The '+'
indicates string concatenation without any delimiters.

Example:

The following request consist of

GET /API/Contribution/CarrierID HTTP/1.1
Accept: application/json

Assuming the API key is 12345, the X-API-Key is equal to:

md5(“12345” + md5(“/API/Contribution/CarrierID” +
“12345”)

md5(“12345” + “bac1e7b7404eb51559d37b0dc6caa196”)

3bb206cf18b469b5e4ddb7c05ececbd4

3.6 HTTP response headers

Where a HTTP response body is provided, the Content-Type field shall be
set to application/json.

Where a HTTP response body is provided, the Content-Length shall be set

to the size of the body of the HTTP request, in decimal number of bytes. See
[1].

When creating resources, the Location field shall be set to the URI of newly
created resources.

3.7 HTTP Authentication

HTTP authentication shall not be supported when integrating with third-party
control systems.

If authentication is enabled on the device, the device will respond with:

HTTP/1.1 401 Unauthorized
Content-Length: nnn

Or:
HTTP/1.1 403 Forbidden

12
 AVP Contribution API

Content-Length: nnn

Accessing the API will require disabling Web Authentication on the device.

4 Carrier ID configuration
The carrier ID uniquely identifies the transmitting station. The inclusion of this
information in the transport stream is activated through the user interface for
each service.

4.1 Reading the Carrier ID

4.1.1 Request

To read the current Carrier ID, the HTTP client shall send the following
request:
GET /API/Contribution/CarrierID HTTP/1.1
Accept: application/json

4.1.2 Response

The device shall answer with the following response:

HTTP/1.1 200 OK
Content-Length: nnn
Content-Type: application/json

{
"operator": "DSNG1",
"phone": "+44 2380 48 4000",
"user-info": "User defined string",
"longitude": 50.916203,
"latitude": -1.3222
}

The Carrier ID fields are described in 4.3.

4.2 Setting the Carrier ID

4.2.1 Request

To update the Carrier ID, the HTTP client shall send to the server:
PUT /API/Contribution/CarrierID HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: nnn

13
 AVP Contribution API

"operator": "Operator",
"phone": "+44 2380 48 4000",
"user-info": "Another user defined string",
"longitude": 50.916203,
"latitude": -1.3222
}

The Carrier ID fields are described in 4.3.

4.2.2 Response

When the request is successful, the device shall return the following HTTP
response:
HTTP/1.1 200 OK
Content-Length: 0

When the request is malformed (e.g. contains one or several parameters

outside the range specified), the device shall return the following HTTP
response:
HTTP/1.1 400 Bad Request
Content-Length: nnn

4.3 CarrierID object

The Carried ID object is defined as following:

Field Name Description JSON type

operator Name of the operator string

Up to five characters

phone Phone number up to 17 characters string

user-info User-defined information of up to 15 characters string

latitude Latitude coordinate of the transmitting station: number

+00.0000 to +/- 90.0000

longitude Longitude coordinate of the transmitting station: Number

+000.0000 to +/- 180.0000

14
 AVP Contribution API

5 System operation

5.1 Setting the system operations

5.1.1 Request

To update the system parameters, the HTTP client shall send to the server:
PUT /API/Contribution/System HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: nnn

{
"reboot": true,
"name": "System name",
"default-view": "simple"
}

5.1.2 System object

Name Description JSON type

reboot true, false string

true executes a reset and reboot of the unit; all other values
(or if the value is omitted) do not cause the reboot to be
executed.
Default: false

name System name. Same as systemName OID in SP0006 SNMP String

Support Standard Practice

default-view ‘simple’ or ‘advanced’.

When the value is ‘simple’, the default GUI loaded by the

device is the AVP2000/Voyager Dashboard.

When the value is ‘advanced’, the default GUI loaded by the

device is the advanced GUI.

5.1.3 Response

NOTE that for a reboot command, the unit may reset before sending the
response, so no reply may be received.

When the request is successful, the device shall return the following HTTP
response:

15
 AVP Contribution API

HTTP/1.1 200 OK
Content-Length: 0

When the request is malformed, the device shall return the following HTTP
response:
HTTP/1.1 400 Bad Request
Content-Length: nnn

6 Device Status

6.1 Reading the Device Status

6.1.1 Request

To read the current Device status, the HTTP client shall send the following
request:
GET /API/Contribution/Status HTTP/1.1
Accept: application/json

6.1.2 Response

The device shall answer the following response:

HTTP/1.1 200 OK
Content-Length: nnn
Content-Type: application/json

{
"config-count": 154,
"highest-alarm-severity": "normal",
"last-preset-restored": "Preset 1",
"alarm-count": 3
}

Where:

config-count is a read-only counter of the configurations performed on the

device. This counter increases by 1 (one) every time the device configuration
is changed. Changes in configuration covered by this counter are through:

- the User Interface

- the SNMP interface

- the Front Panel

- the XPO interface, if available

16
 AVP Contribution API

highest-alarm-severity is a read-only string representing the highest

alarm severity raised on the device:

‘critical’, ‘major’, minor’, ‘warning’, ‘indeterminate’, ‘normal’, ‘information’

The highest alarm severity level shall be calculated as the maximum level of
all active alarms. The level of an alarm is defined according to:

Alarm severity Level

normal or information 1

indeterminate 2

warning 3

minor 4

major 5

critical 6

alarm-count is a read-only number incrementing by 1 (one) every time an

alarm is raised or cleared.

7 Services
This API provides access to a maximum of two services per device.

The number of services depends on the number of compression option

modules fitted in the chassis.

7.1 List all services

To list all services configured on the device, the HTTP client shall request:
GET /API/Contribution/Services HTTP/1.1
Accept: application/json

The device shall respond with a JSON array of all the service Objects. For
example:
HTTP/1.1 200 OK
Content-Length: nnn
Content-Type: application/json

[
{
"name" : "My Service 1",
...
},
{
"name" : "My Service 2",

17
 AVP Contribution API

...
}
]

The Service object is abbreviated in the example. The full service Object is
defined in 7.3.

Each index in the returned Collection corresponds to a Service Object. E.g.

Object at index zero in the JSON array corresponds to the first Service.

Note: The index of a JSON array starts at zero. Services 1 and 2 are
accessed in the JSON array as index 0 and 1. The Service Object URI uses
the same index.

When multiple compression modules are present in a chassis, it is

recommended that the services in the main output are configured such that
they use each card in order. This way, the service array will be organized as
following:

Index in service JSON array Compression module used

0 First by slot number

1 (not available if only one Second by slot number

compression module is fitted)

7.2 Service update

To update a Contribution service, the client shall send a HTTP PUT request
containing a service object.
PUT /API/Contribution/Services/0 HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: nnn

{
"name": "My Service 1",
"transport-stream-id": 3001,
"original-network-id": 3002,
"service-id": 3003,

"input": [
{
"type": "SDI" ,
"format": "HD 1080i25"
}
],
"video": [
{
"PID" : 101,
"aspect-ratio" : "16/9",
"encoding" : "H264",
"profile" : "4:2:0",
"BISS" : "Off",

18
 AVP Contribution API

"BISS-key" : "************”
"bitrate-tracking" : "Off",
"manual-bitrate" : "7.5",
"GOP-structure" : "Auto",
"GOP-length" : "Auto",
"buffer-mode" : "CBR"
}
],
"audio" : [
{
"PID" : 102,
"encoding" : "MPEG Layer II",
"channel-mode" : "2/0",
"bitrate" : "128"
},
{
"PID" : 103,
"encoding" : "HE-AAC",
"channel-mode" : "2/0",
"bitrate" : "128"
}
],
"data": [
{
"type" : "VANC",
"PID" : 104,
"mode" : "On",
"max-bitrate" : 1500
}
]
"output": [
{
"type" : "modulator",
"relation" : "main",
"output-select" : "LBand",
"carrier-mode" : "Off",
"standard" : "DVB-S2",
"modulation" : "QPSK",
"uplink-frequency" : 12079,
"symbol-rate" : 4,
"FEC" : "3/4",
"low-power" : -20,
"nominal-power" : 5,
"clock-mode" : "Internal",
"roll-off" : 20,
"frame-size" : "Normal",
"RAS" : "On",
"RAS-key" : "",
"BISS" : "On",
"pilots" : "Off",
},
{
"type" : "IP",
"relation" : "mirror",
"destination-address" : "239.0.0.1",
"destination-port" : 5500,
"gateway" : "0.0.0.0",
"source-address" : "0.0.0.0",
"source-port" : 5000,

19
 AVP Contribution API

"subnet" : "255.255.0.0",
"FEC-row" : 4,
"FEC-col" : 1,
"mode" : "On",
"BISS" : "On"
},
{
"type" : "ASI",
"relation" : "mirror"
"mode" : "On",
"ASI-bitrate" : 8.5,
"BISS" : "On"
}
]
}

7.3 Service object

The service array contains up to two services. The service array is populated
from the service of the main output. See the relation property in the output
objects’ common properties section for more information on output
relationships.

Note: Editing properties within a service will adjust those properties for mirror
outputs, but may not have an effect on independent outputs.

Structure of a service object:

Name Description JSON type

Name User-defined service name string

transport-stream-id 0 to 65535 number

Applies to DVB outputs only. Defines the corresponding

value found in the SDT for DVB-SI.

original-network-id 0 to 65535 number

Applies to DVB outputs only. Defines the corresponding

value found in the SDT for DVB-SI.

service-id 0 to 65535 number

Applies to DVB outputs only. Defines the corresponding

value found in the SDT for DVB-SI.

Input Input array, as defined in 7.3.1. array

Video Mixed array of video objects, as defined in 7.3.2 array

Audio Mixed array of audio objects, as defined in 7.3.3 array

20
 AVP Contribution API

Name Description JSON type

Data Mixed array of data objects, as defined in 7.3.4 array

Output Mixed array of modulation objects, as defined in 7.3.4 array

7.3.1 Input array

The input array contains with a single object:

Name Description JSON type

Type ‘SDI’, ’Analog’, ‘Color bars’, ‘Black’, ‘Moving object’, ‘Slate’ string

Default: ‘SDI’

Note: ‘Analog’ is only present when an analog card is

present.

Format ‘SD 576i25’, ‘SD 480i29.97’, ‘HD 720p50’, ‘HD 720p59.94’, string
‘HD 1080i25’, ‘HD 1080i29.97’, ‘3G 1080p50’, ‘3G
1080p59.94’, ‘UHD 2160p50’, ‘UHD 2160p59.94, ‘Auto’

Default: ‘’ ‘SD 576i25

If ‘Analog’ input is selected, then only ‘SD 576i25’, ‘SD

480i29.97’ and ‘Auto’ are valid.

7.3.2 Video object

Note that the output video resolution shall be the same as the input video
resolution.

Name Description JSON type

PID Integer in the range of [16..8190]. number

The PID must be unique within the Service.

aspect-ratio ‘4/3’, ‘16/9’ string

Default: ‘16/9’

‘4/3’ is only allowed for SD resolutions.

profile ‘Off’, ‘4:2:2’, ‘4:2:0’ string

Default: ‘4:2:0’

21
 AVP Contribution API

Name Description JSON type

‘Off’ is used in the case when the encode profile is set to

‘Off’ in the advanced GUI.

format ‘SD’, ‘HD’, ‘UHD’ string

Default ‘SD’

Defines whether the output video will be HD, SD or UHD.

The device will select the highest SD, HD or UHD resolution
available based on the input format and the value set in this
property.

Note: When input format is SD the output format can only be

SD

When input format is HD the output format can be SD or HD

When input format is 3G the output format can only be HD

When input format is UHD the output format can only be

UHD

encoding ‘Off’, ‘MPEG2’, ‘H264’, ‘J2K’, ‘HEVC’ string

Default: ‘H264’

‘MPEG2’ means MPEG2 Main Profile

‘H264’ means H264 High Profile

‘HEVC’ means HEVC Main Profile.

‘Off’ is used in the case when the encode profile is set to

‘Off’ in the advanced GUI.

BISS ‘Off’, ‘On’ string

Default: ‘Off’

Note: This is now a mirrored property of the ‘main’ output

object. If it is set at the same time as the BISS property on
the main output, then the value in the main output takes
precidence.

BISS-key Hexadecimal session key string

14 hexadecimal digits for BISS mode 1

16 hexadecimal digits for BISS mode E

22
 AVP Contribution API

Name Description JSON type

Default: Empty string

scrambling ‘Off’, ‘On’ string

Default ‘On’

Note: for component to be scrambled, BISS must be

enabled for the service.

bitrate-tracking ‘Off’, ‘On’ string

Default: Off

manual-bitrate Manual bitrate value used when bitrate-tracking is ‘Off’. number

Precision: 00.0000 Mbit/s.
Limit depends on video profile. See [4].

GOP-structure ‘IP’, ‘IBP’, ‘IBBP’, ‘IBBBP’, ‘IBBBBBBBP’ string

Default: ‘IBBBP’
Sets the number of B frames between reference frames.
IBBBBBBBP can only be used for 720p video format
encoded with a H.264 video profile.

GOP-length Length of GOP in the range [8...250]. number

Default: 32

buffer-mode ‘CBR’, ‘Low Delay’, ‘Mega Low Delay’, ‘Stripe Refresh’, string
‘Stripe Refresh (+Audio Encode)’

Default: ‘CBR’

bit-depth 0, 8, 10 number

Default: 8

0 (zero) is used to signify ‘Off’ in the case when the encode

profile is set to ‘Off’ in the advanced GUI.

Note that some of the above are really service-level parameters, however
since there is assumed to always be a single video component, they are
placed within that video object.

Note that if any of bit-depth, profile, or encoding are set to the ‘Off’ value (or
equivalent), all three properties must be set to the ‘Off’ value (or equivalent)
when sending updated values to the device, or the values will be rejected.

Note: The combination of input format, encoding, profile and bit-depth is

defined in [4] as following:

23
 AVP Contribution API

Input format encoding profile bit-depth

<Any>
Off Off 0
‘SD 576i25’, ‘SD
480i29.97’ MPEG2 4:2:0 8
‘SD 576i25’, ‘SD
480i29.97’ MPEG2 4:2:2 8
‘SD 576i25’, ‘SD
480i29.97’ H264 4:2:0 8
‘SD 576i25’, ‘SD
480i29.97’ H264 4:2:0 8
‘SD 576i25’, ‘SD
480i29.97’ H264 4:2:2 10
‘HD 720p50’, ‘HD
720p59.94’, ‘HD MPEG2 4:2:0 8
1080i25’, ‘HD
1080i29.97’
‘HD 720p50’, ‘HD
720p59.94’, ‘HD MPEG2 4:2:2 8
1080i25’, ‘HD
1080i29.97’
‘HD 720p50’, ‘HD
720p59.94’, ‘HD H264 4:2:0 8
1080i25’, ‘HD
1080i29.97’
‘HD 720p50’, ‘HD
720p59.94’, ‘HD H264 4:2:2 8
1080i25’, ‘HD
1080i29.97’
‘HD 720p50’, ‘HD
720p59.94’, ‘HD H264 4:2:2 10
1080i25’, ‘HD
1080i29.97’
‘SD 576i25’, ‘SD
480i29.97’ J2K 4:2:2 10
‘HD 720p50’, ‘HD
720p59.94’, ‘HD J2K 4:2:2 10
1080i25’, ‘HD
1080i29.97’
‘HD 720p50’, ‘HD
720p59.94’, ‘HD HEVC 4:2:0 8
1080i25’, ‘HD
1080i29.97’
‘HD 720p50’, ‘HD
720p59.94’, ‘HD HEVC 4:2:2 8
1080i25’, ‘HD
1080i29.97’
‘HD 720p50’, ‘HD
720p59.94’, ‘HD HEVC 4:2:0 10

24
 AVP Contribution API

1080i25’, ‘HD
1080i29.97’
‘HD 720p50’, ‘HD
720p59.94’, ‘HD HEVC 4:2:2 10
1080i25’, ‘HD
1080i29.97’
‘3G 1080p50’, ‘3G
1080p59.94 H264 4:2:0 8
‘3G 1080p50’, ‘3G
1080p59.94 H264 4:2:2 8
‘3G 1080p50’, ‘3G
1080p59.94 H264 4:2:2 10
‘3G 1080p50’, ‘3G
1080p59.94 HEVC 4:2:0 8
‘3G 1080p50’, ‘3G
1080p59.94 HEVC 4:2:2 8
‘3G 1080p50’, ‘3G
1080p59.94 HEVC 4:2:2 10
‘UHD 2160p50’,
‘UHD 2160p59.94’ HEVC 4:2:0 10
‘UHD 2160p50’,
‘UHD 2160p59.94’ HEVC 4:2:2 10

7.3.3 Audio array

The audio array contains up to eight audio objects. If there are zero audio
components created in the service, the audio array will not be present (the
property itself will not be present).

Name Description JSON type

PID Integer in the range of [16..8190]. number

The PID must be unique within the Service.

‘Off’, ‘Mute’, ‘Test Tone’, ‘Embedded 1-16 SDI 1-4’, ‘Input 1-
input-type 4’, ‘Analog 1-2’ String

Default: ‘Off’

‘Off’ means that the audio component is removed from the

output, as well as from all associated tables like the PMT.

Note: Embedded 9-16 are only available for 3G & UHD

inputs. SDI 1-4 are only available for UHD. If SDI is omitted,
then SDI 1 is assumed.

25
 AVP Contribution API

Name Description JSON type

Encoding ‘MPEG Layer II’, ‘HE-AAC’, ‘Dolby E Pass-through’, ‘LPCM string

Pass-through’, ‘Dolby Digital Pass-through’, ‘Dolby Digital’,
‘AAC-LC’, ‘MPEG-H’, ‘MPEG-H Pass-through’

Default: ‘MPEG Layer II’

Note: AAC-LC, HE-AAC, Dolby Digital and MPEG-H are

only available if licensed

Note: MPEG-H allows audio channels to be specified in

groups. Currently only a single MPEG-H group is supported.

channel-mode ‘1/0 (L – input)’, ‘1/0 (R – input)’, ‘2/0’ (string) String

For ‘MPEG Layer II’ encoding: ‘2/0 (Joint)’, ‘1+1

(L/CH1,R/CH2)’, ‘6 Channel Aligned’, ‘8 Channel Aligned’,
‘1/0 (L+R)/2’

For ‘Dolby E Pass-through’ encoding: ‘3/2L (5.1 surround)’

For ‘Dolby Digital’ encoding: ‘1/0 (L+R)/2’

For ‘MPEG-H’ encoding: ‘3/2L (5.1 surround)’, ‘5/2L (7.1

surround)’, ’10 Channel Mono’

Default: ‘2/0’

Note: Phase-aligned audio ‘6 Channel Aligned’, ‘8 Channel

Aligned’ are available on both SD and HD services.

Bitrate Value in Kbit/s: 32 | 48 | 56 | 64 | 80 | 96 | 112 | 128 | 148 | number

160 | 168 | 192 | 224 | 256 | 320 | 384 | 448 | 512 | 576 | 640
and 1536

Possible range values depend on encoding: ‘MPEG Layer

II’, ‘HE-AAC’, ‘AAC-LC’, ‘Dolby Digital’, ‘Dolby Digital Pass-
through’, ‘MPEG-H’, ‘MPEG-H Pass-through’

Default: 128

Note: The bitrate specified for MPEG-H is applied per

channel. An MPEG-H group configured as ‘5/2L (7.1
surround)’ will use six channels, so the resulting bitrate will
be six times that configured.

bit-depth ‘16-bit’, ’20-bit’, ’24-bit’ String

Unit: bits

Applicable for Dolby E Pass-through or LPCM Pass-through

26
 AVP Contribution API

Name Description JSON type

Default: ’20-bit’

lipsync-offset Integer in the range of [-500..+500] number

Unit: ms

Default: 0

scrambling ‘Off’, ‘On’ string

Default ‘Off’‘

Note: for component to be scrambled, BISS must be

enabled for the service.

7.3.4 Data array

Contains data components. Currently, only one data component is supported

and will be present, the VANC object. If there are zero supported data
components created in the service, the data array will not be present (the
property itself will not be present).

7.3.5 ANC object

The ANC object will appear in the data array. Note that this object will relate
to the VBI Output component and it is assumed the component is configured
to provide ANC output.

Name Description JSON type

type Identifies the object as a ANC object. String

Read-only, the value is always ‘ANC’. Attempts to write to it

will fail with an error code 17.

PID Integer in the range of [16..8190]. number

The PID must be unique within the Service.

mode ‘Off’, ‘On’ String

max-bitrate Range 100kbit/s to 2000kbit/s in steps of 100kbit/s number

scrambling ‘Off’, ‘On’ string

Default ‘Off’

27
 AVP Contribution API

Name Description JSON type

Note: for component to be scrambled, BISS must be

enabled for the service.

7.3.6 Output array

7.3.6.1 Common properties

The following properties will be present in each object in the output array:

Name Description JSON type

type Denotes the type of output string

Note: This field is read-only. Attempts to write to it will fail

with an error code 17.

relation ‘main’, ‘mirror’ or ‘independent’. string

Note: This field is read-only. Attempts to write to it will fail

with an error code 17.

BISS ‘Off’, ‘On’ string

Default: ‘Off’

The “relation” property will denote what relation the output has to the other
outputs:

• “main” denotes the primary output. This is the output that the services
(and therefore the components) have been fetched from

• “mirror” denotes an output that is a mirror of the “main” output. This

means the output is explicitly a “mirror transport stream” in the
advanced GUI

• “independent” denotes an output that has no relation to the “main”

output.

If there are multiple outputs defined, the main output is found by searching for
mux (i.e. standard rather than mirror or pass-through) transport streams on the
following outputs, in order:

1. Satellite Modulator Output

2. IP Data Port 3-4

28
 AVP Contribution API

3. ASI Output 1 (not Output 2)

Generally speaking, a mirror that is higher up the above list than its main is not
a supported output and may not appear in the output list.

The following combinations of relations are supported:

“main” Output Mirror/Independent Outputs

Satellite Modulator IP ASI

Satellite Modulator   

IP    

ASI    

The semantics for the BISS property are as follows:

• For all outputs, the property operates to/from the nth service in the
transport stream, where n is the index of service object in the services
array.

• For “main” and “independent” outputs, this property can be written to

and it will enable/disable BISS on that service

• For “mirror” outputs, this property is read-only and attempts to write to

it will be rejected. This property will always reflect the BISS state of the
main output.

7.3.6.2 Modulator object

The ‘output’ array contains a single Modulator object, if a Satellite Modulator

card is fitted and a transport stream is present on the output.

Name Description JSON type

type ‘modulator’ string

output-select ‘LBand’ or ‘IF’ string

carrier-mode ‘Off’, ‘Low’, ‘Nominal’, ‘Modulated’ or ‘Modulated Low’ string

Default: ‘Off’
See Table 1 Carrier modes for other values.

Standard ‘DVB-S’, ‘DVB-DSNG’, ‘DVB-S2’, ‘DVB-S2X’ string

Default: ‘DVB-S2’

Modulation Default: ‘QPSK’ string

29
 AVP Contribution API

Name Description JSON type

Valid modulation values depends on ‘standard’:

DVB-S2 DVB-DSNG DVB-S DVB-S2X

QPSK QPSK QPSK QPSK

8PSK 8PSK 8PSK

16APSK 16QAM 8APSK-L

32APSK 16APSK

16APSK-L

32APSK

32APSK-L

64APSK

64APSK-L

uplink-frequency Uplink frequency in MHz number

See [4] for LBand and IF ranges.

symbol-rate Symbol rate in MSym/s number

Range: 0.132000 to 66.000000 MSym/s

FEC 1/41,4, 1/31,4, 2/51,4, 1/2, 3/51,4, 2/3, 3/4, 4/51,4, 5/6, 7/82,3, string
8/91,4, 9/101,4,

13/45,4 , 9/20,4, 8/15,4, 11/20,4, 5/9,4, 26/45,4, 28/45,4,

23/36,4, 25/36,4, 32/45,4, 13/18,4, 11/15,4, 7/9,4, 77/90,4

Available options depend upon Moduation Standard and

Modulation Mode as per Table 2 FEC Rates

low-power Reduced power level in dBm number

Range: -40.0 to 5.0 dBm, steps of 0.5dBm, default of 0.

LBand range: -40.0 to 5.0 dBm

IF range: -30.0 to 5.0 dBm

nominal-power Range: -40.0 to 5.0 dBm, steps of 0.5dBm, default of 0. number

30
 AVP Contribution API

Name Description JSON type

LBand range: -40.0 to 5.0 dBm

IF range: -30.0 to 5.0 dBm

clock-mode ‘Internal’ or ‘External’ string

Default: ‘Internal’

External requires an external sync Option Card with a

valid 10MHz reference clock.

roll-off 51,4 101,4, 151,4, 20, 25, 35 in % number

Default: 20

frame-size ‘Normal’ or ‘Short’ string

Default: ‘Normal’

RAS ‘Off’ or ‘On’ string

RAS-key 7-byte RAS hexadecimal key string

pilots1 ‘Off’ or ‘On’ string

1 Applies to DVB-S2

2 Applies to DVB-DSNG

3 Applies to DVB-S

4 Applies to DVB-S2X

The carrier mode determines the power, as well as whether to enable

modulation. See Table 1 Carrier modes.

Carrier Mode Power Modulation

‘Off’ Off Off

‘Low’ low-power Off

‘Nominal’ nominal-power Off

‘Modulated’ nominal-power On

‘Modulated Low’ low-power On

Table 1 Carrier modes

31
 AVP Contribution API

Modulation Mode Frame Size FEC Rate

Standard
DVB-S QPSK N/A 1/2, 2/3, 3/4, 5/6, 7/8

DVB-DSNG QPSK N/A 1/2, 2/3, 3/4, 5/6, 7/8

8PSK N/A 2/3, 5/6, 8/9

16QAM N/A 3/4, 7/8

DVB-S2 QPSK Normal 1/4, 1/3, 2/5, 1/2, 3/5, 2/3, 3/4, 4/5, 5/6, 8/9, 9/10

Short 1/4, 1/3, 2/5, 1/2, 3/5, 2/3, 3/4, 4/5, 5/6, 8/9

8PSK, Normal 3/5, 2/3, 3/4, 5/6, 8/9, 9/10

Short 3/5, 2/3, 3/4, 5/6, 8/9

16APSK Normal 2/3, 3/4, 4/5, 5/6, 8/9, 9/10

Short 2/3, 3/4, 4/5, 5/6, 8/9

32APSK Normal 3/4, 4/5, 5/6, 8/9, 9/10

Short 3/4, 4/5, 5/6, 8/9

DVB-S2X QPSK Normal 1/4, 1/3, 2/5, 1/2, 3/5, 2/3, 3/4, 4/5, 5/6, 8/9, 9/10,
13/14, 9/20, 11/20

Short 1/4, 1/3, 2/5, 1/2, 3/5, 2/3, 3/4, 4/5, 5/6, 8/9

8APSK-L Normal 5/9, 26/45

8PSK, Normal 3/5, 2/3, 3/4, 5/6, 8/9, 9/10, 23/36, 25/36, 13/18

Short 3/5, 2/3, 3/4, 5/6, 8/9

16APSK-L Normal 1/2, 8/15, 5/9, 3/5, 2/3

16APSK Normal 2/3, 3/4, 4/5, 5/6, 8/9, 9/10, 26/45, 3/5, 28/45, 23/36,
25/36, 13/18, 7/9, 77/90

Short 2/3, 3/4, 4/5, 5/6, 8/9

32APSK-L Normal 2/3

32APSK Normal 3/4, 4/5, 5/6, 8/9, 9/10, 32/45, 11/15, 7/9

Short 3/4, 4/5, 5/6, 8/9

32
 AVP Contribution API

64APSK-L Normal 32/45

64APSK Normal 11/15, 7/9, 4/5, 5/6

Table 2 FEC Rates

7.3.6.3 ASI object

The ‘output’ array contains a single ASI object, if an ASI card is present and a
transport stream has been created on it.

Name Description JSON type

type ‘ASI’ string

mode ‘Off’ or ‘On’ string

ASI-bitrate Range 0.04Mbit/s to 34.368Mbit/s steps of 1kbit/s number

Note: This field is read-only if “relation” is “mirror”.

7.3.6.4 IP object

The ‘output’ array contains a single IP Data Output object, if an output

transport stream has been created on the IP output.

Name Description JSON type

type ‘IP’ string

mode ‘Off’ or ‘On’ string

The destination multicast address for the transport
destination-address stream. Must be of the form x.x.x.x where x is 0-254. string

gateway The gateway address to use. Leave at 0.0.0.0 to use the string
default gateway. Default is 0.0.0.0.

Note: This affects all outputs on the same data ports.

destination-port The destination UDP port. 1-65535. Default is 5000. string

source-port The source UDP port. 0-65535. Default is 5000. string

source-address The source IP address of the stream. Leave at 0.0.0.0 to string

use the interface’s default.

subnet The subnet mask for the interface. string

33
 AVP Contribution API

Name Description JSON type

Note: This affects all outputs on the same data ports.

FEC-row Range 4 to 20 steps of 1 number

Note: This property is always present, but it will have no

effect on the output without an appropriate FEC license.

FEC-col Range 1 to 20 steps of 1 Number

Note: This property is always present, but it will have no

effect on the output without an appropriate FEC license.

IP-bitrate Range: 0.01Mbit/s to 216Mbit/s steps of 0.001Mbit/s Number

Note: This field is read-only if “relation” is “mirror”.

7.3.7 BISS Configuration

The BISS key for each service is unique. Setting the BISS key for each
service will set the following BISS keys in the device’s BISS key store:

1. Service 1 – BISS Key 1

2. Service 2 – BISS Key 2

• Toggling BISS (through the “BISS” property either in the video

component or an output object) on an output in Service n (where n is
the service’s index) will have the following effect based on the type of
output:“main” – Toggles BISS on the service associated with the output
and that service on all mirrored outputs

• “mirror” –Attempts to set this to a value different from the BISS value
for the main output will produce a 400 error.

• “independent” – Toggles BISS on the service at index n of the

independent transport stream. Note that this output is not guaranteed
to have any meaningful relation to the main output.

8 Pre-stored configurations
In addition to the current running configuration, Contribution devices offer up
to 64 pre-set slots.

34
 AVP Contribution API

Parameters part of the running configuration can be modified. Once the

running configuration has been stored into a pre-set slot, parameters cannot
be accessed anymore.

The current configuration can be saved in a pre-set slot. This will replace to
existing content of the pre-set with the current running configuration.

The configuration stored in a pre-set can be re-called. The configuration

contained in the pre-set slot will become the currently running configuration.

8.1 List all the pre-sets

To request the list of current pre-sets, the HTTP client shall send to the server:
GET /API/Contribution/Presets HTTP/1.1
Accept: application/json

The server shall return the Collection of all 64 pre-set Objects. For example:
HTTP/1.1 200 OK
Content-Length: nnn
Content-Type: application/json

[
{
"name" : "My Preset 1",
"description" : "Describes the content of preset 1",
"timestamp" : 1627893
},
...
{
"name" : "My Preset 64",
"description" : "Describes the content of preset 64",
"timestamp" : 24892123
}
]

Each index in the returned Collection corresponds to a pre-set Object. E.g.

Object at index zero in the JSON array corresponds to the first pre-set.

Note: The index of a JSON array starts at zero. Pre-sets 1 to 64 are accessed
in the JSON array as index 0 to 63. The same index is used later in the Pre-
set Object URI.

8.2 Read a single pre-set

To request a single pre-set, the HTTP client shall send to the server:
GET /API/Contribution/Presets/0 HTTP/1.1
Accept: application/json

The server shall return the Collection of all 64 pre-set Objects. For example:
HTTP/1.1 200 OK
Content-Length: nnn
Content-Type: application/json

35
 AVP Contribution API

{
"name" : "My Preset 1",
"description" : "Describes the content of preset 1",
"timestamp" : 1627893
}

Each index in the returned Collection corresponds to a pre-set Object. E.g.

Object at index 0 in the JSON array corresponds to pre-set 1.

Note: The index of a JSON array starts at 0. Pre-sets 1 to 64 are accessed in

the JSON array as index 0 to 63. The same index is used later in the Pre-set
Object URI.

8.3 Saving the current parameters in a pre-set

To save the current device configuration in the first pre-set, the HTTP client
shall send to the server:
POST /API/Contribution/Presets/0 HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: nnn

{
"name" : "My Preset 1",
"description" : "Describes the content of preset 1"
}

The index specified in the URL must be within the following range: [0 - 63].

8.4 Re-calling a pre-set

To re-call pre-set 1, the HTTP client shall send to the server the following
HTTP request:
PUT /API/Contribution/Presets/0 HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: nnn
{
"recall-options" :
{
"keep-modulation" : true,
"set-carrier-off" : true
}
}

The index specified in the URL must be within the following range: [0 - 63].

Warning: This will replace the current device configuration with the
configuration from the pre-set!

36
 AVP Contribution API

8.4.1 recall-options object

When recalling a pre-set, the recall-options object is optional.

Name Description JSON type

keep-modulation true leaves existing modulation parameters intact (doesn’t value

overwrite with recalled parameters). If absent, inferred to
mean false

set-carrier-off true forces carrier into the “Off” state. If absent, is inferred value
to mean false

8.5 Clear a pre-set

To clear the content of a pre-set, the HTTP client shall to the server:
DELETE /API/Contribution/Presets/0 HTTP/1.1
Accept: application/json

The index specified in the URL must be within the following range: [0 - 63].

8.6 Pre-set Object

Name Description JSON type

name User-defined name of the pre-set string

description User-defined description for the pre-set string

timestamp UTC time of creation in seconds. Read-only. number

9 Alarms

9.1 List all the alarms

To request the list of current pre-sets, the HTTP client shall send to the server:
GET /API/Contribution/Alarms HTTP/1.1
Accept: application/json

The device shall return the Collection of all active Alarms. For example:
HTTP/1.1 200 OK
Content-Length: nnn
Content-Type: application/json

[
{
"severity" : "critical",

37
 AVP Contribution API

"description" : "Describes the content of preset 1",

"timestamp" : 1627893,
"slot" : 1,
"port" : 1,
"type" : "port"
},
...
{

9.2 Alarm object

Name Description JSON type

severity ‘information’, ‘critical’, ‘major’, minor’, ‘warning’, string

‘indeterminate’, ‘normal’

description Alarm description string

timestamp NTP 64-bit timestamp at the time the alarm was raised number

slot 0 for the host card, 1 to 6 for option cards number

port Number of the port on the board. Ports are to be number

numbered left to right, bottom to top

type ‘input’, ‘internal’, ‘output’ string

alarm-id Same number as defined in SP0006 SNMP Support number

Standard Practice

10 Error messages
The API may return the following error messages:

Services / Components missing. After enabling the API, some services

and/or components were removed by the user (by using the user interface, or
restoring a pre-set without that given service or component).

Invalid combination of parameters. The API shall return the object(s)

passed, highlighting the invalid parameters. If an invalid combination of
parameters was passed, then the device configuration shall not be changed.

Parameter value out-of-range. The API shall return the object(s) passed,
highlighting the invalid parameters. If an invalid combination of parameters
was passed, then the device configuration shall not be changed.

38
 AVP Contribution API

Unlicensed features. The API shall indicate that a particular object wasn’t
modified because of a missing license.

The format is as following:

{
"error" : {
"status" : "403 Forbidden",
"title" : "Third-party API is disabled. Enable it through the user
interface.",
"code" : 14
}
}

The list of errors is:

Status Title Code Comment

500 Internal Server "An unknown error has 1 The request has failed
Error occurred." because of an internal
device error
"Request body of
400 Bad Request HTTP %1% shall be 3 Repeat the same request
empty." without the HTTP request
body.

400 Bad Request “Request body of 4 Repeat the same request

HTTP %1% cannot be with a HTTP request body.
empty."

405 Method Not Unsupported request 5 Use one of the methods in

Allowed method: %1%." the Allow HTTP response
header

400 Bad Request "JSON input is invalid." 6 Check the JSON syntax is
correct and only attempt to
write properties that are
not read-only

400 Bad Request "JSON input is 7 Check the JSON syntax is

malformed." well formed.

400 Bad Request "JSON root must be 8 Make sure the JSON root
an object." object is present.

400 Bad Request "An index must be 9 Specify a valid index for
specified to use this this collection
method."

400 Bad Request "Failed to enable the 10

RestAPI in the loaded
configuration. All
changes are rolled
back."

39
 AVP Contribution API

Status Title Code Comment

400 Bad Request "An invalid value has 11 Specify a valid index for
been specified as this collection
index."

400 Bad Request "%1% with index %2% 12 Specify a valid index for
not found." this collection

403 Forbidden "HTTP authentication 13 Disable HTTP

is enabled on the unit. authentication in the web
Integrating with third- user interface.
party control systems
is not supported in this
mode."

403 Forbidden "Third-party API is 14 Enable third-party API in

disabled. Enable it the web user interface.
through the user
interface."

404 Not Found "Path '%1%' not found" 15 Check the Path given
in %1% is a valid API path

405 Method Not "Path '%1%' shall be 16 Make sure the method
Allowed called with %2% given in %2% is used for
(got %3%)." Path given in %1%

Note: In some cases, the error “400 Bad request” “JSON input is invalid” with
Code 6 may also return a body containing a “details” object:
{
"error" : {
"status" : "400 Bad Request",
"title" : " JSON input is invalid.",
"code" : 6,
"details" : {
"name" : "<-- OK",
"input" : [
{
"format" : "<-- invalid value",
"type" : "<-- OK"
}
]
}
}
}

40
 AVP Contribution API

11 References
[1] HTTP/1.1: http://www.ietf.org/rfc/rfc2068.txt
[2] JSON: http://www.json.org
[3] application/json: http://www.ietf.org/rfc/rfc4627.txt
[4] AVP2000, AVP3000 Reference Guide http://www.mediakind.com

12 Change information
Version Date Author Comments
PB2 06/08/2013 EJEROCH Added RAS, output-select
PB3 29/03/2013 EJEROCH Added DVB triplet in Service
PB4 25/09/2013 EJEROCH Merged Web UI and 3PP REST API
PB5 27/11/2013 EJEROCH Added ‘Stripe Refresh (+Audio
Encode)’ and ‘1/0 (L+R)/2’ options.
Clarified audio ‘Off’.
PB6 10/12/2013 EJEROCH Updated to support eight audios.
PB7 16/04/2014 EJEROCH Updated to support additional roll-offs
in DVB-S2
PB8 9/10/2014 EANNRUT Updated to support DVB-S2X and off
profile for video
PB9 07/04/2015 EANNRUT Updated to include:
& • support for ASI and IP outputs
EDARWIN • support for VANC components
• configurable default GUI

PB10 27/05/2015 EDARWIN Added “Format” property to video

& object for down-conversion.
EANNRUT Minor corrections from spec review
• Merged error code 17 into
error code 6
• Removed POST and
DELETE methods as the
REST API doesn’t actually
implement them
• Clarified SatMod output
object to require a transport
stream on the output
PB11 20/07/2015 EANNRUT Changed priority order of ASI and IP
outputs.
Renamed VANC to ANC component.
PB12 13/11/2015 EANNRUT Added support for enabling or
disabling BISS for each component
of a service that has BISS enabled.
PB13 6/06/16 EANNRUT Added support for HEVC option card.

41
 AVP Contribution API

PB14 02/02/18 EGLEMED Added support for MPEG-H Audio

Encode.

PC1 03/09/2018 ESALBUS Added support for MPEG-H 3D Audio

Pass-through
PC2 03/09/2018 ESALBUS Added missing audio bit rates
PC3 10/09/2019 Rebranded MediaKind

42