AMWA NMOS Audio Channel Mapping API documentation version v1.0
http://example.api.com/x-nmos/channelmapping/{version}
- version: required(v1.0)
Overview
The Audio Channel Mapping API is exposed by NMOS Devices as a standard control interface for management of audio matrix mapping inside Devices.
Further Documentation
Further normative documentation covering the behaviour of this API is contained in the docs folder of this repository.
Base
get
get /
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Describes the Channel Mapping API base resource",
"title": "Channel Mapping API base resource",
"items": {
"type": "string",
"enum": [
"inputs/",
"outputs/",
"map/",
"io/"
],
"minItems": 4,
"maxItems": 4,
"uniqueItems": true
}
}Example:
[
"inputs/",
"outputs/",
"map/",
"io/"
]Input/Output view
get
get /io
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "IO Information view for entire API",
"type": "object",
"additionalProperties": false,
"required": [
"inputs",
"outputs"
],
"properties": {
"inputs":{
"type": "object",
"patternProperties": {
"^[a-zA-Z0-9\\-_]+$":{
"type": "object",
"additionalProperties": false,
"properties": {
"parent":{
"$ref": "input-parent-response-schema.json"
},
"channels":{
"$ref": "input-channels-response-schema.json"
},
"caps":{
"$ref": "input-caps-response-schema.json"
},
"properties":{
"$ref": "input-properties-schema.json"
}
}
}
}
},
"outputs":{
"type": "object",
"patternProperties": {
"^[a-zA-Z0-9\\-_]+$":{
"type": "object",
"additionalProperties": false,
"properties": {
"source_id":{
"$ref": "output-sourceID-response-schema.json"
},
"channels":{
"$ref": "output-channels-response-schema.json"
},
"caps":{
"$ref": "output-caps-response-schema.json"
},
"properties":{
"$ref": "output-properties-schema.json"
}
}
}
}
}
}
}
Example:
{
"inputs":{
"input1":{
"parent": {
"id": "f6b34356-9885-4db8-bdeb-3141e23f443c",
"type": "source"
},
"channels":[
{"label": "outA"},
{"label": "outB"},
{"label": "outC"},
{"label": "outD"}
],
"caps": {
"reordering": false,
"block_size": 2
},
"properties":{
"name": "Input 2",
"description": "Four channel input 2"
}
},
"input2":{
"parent": {
"id": "3286c499-3e78-4125-b0e2-d465354d11e6",
"type": "receiver"
},
"channels":[
{"label": "FL"},
{"label": "FR"},
{"label": "LS"},
{"label": "RS"},
{"label": "C"},
{"label": "S"}
],
"caps": {
"reordering": true,
"block_size": 1
},
"properties":{
"name": "5.1 Input",
"description": "Surround sound input"
}
},
"input3":{
"parent": {
"id": null,
"type": null
},
"channels":[
{"label": "L"},
{"label": "R"}
],
"caps": {
"reordering": true,
"block_size": 1
},
"properties":{
"name": "Stereo Input 1",
"description": "Stereo input on rear of unit"
}
},
"input4":{
"parent":{
"id": "6dea8109-9e27-49e7-81eb-65a74e964414",
"type": "source"
},
"channels":[
{"label": "a"},
{"label": "b"},
{"label": "c"}
],
"caps": {
"reordering": false,
"block_size": 1
},
"properties":{
"name": "Input 4",
"description": "RTP Input"
}
}
},
"outputs":{
"output1":{
"source_id": "bdebfc73-6f43-497a-a9c3-c822ea34a4c9",
"channels":[
{"label": "outA"},
{"label": "outB"}
],
"caps":{
"routable_inputs":[
"input1",
"input2",
"input4"
]
},
"properties":{
"name": "Output 1",
"description": "RTP Output One"
}
},
"output2":{
"source_id": "491de650-c47e-4b70-9597-72ebbf23372a",
"channels":[
{"label": "L"},
{"label": "R"}
],
"caps":{
"routable_inputs":[
"input3"
]
},
"properties":{
"name": "Stereo Output",
"description": "Stereo output on rear of unit"
}
}
}
}Map entity root
get
get /map
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Describes the Channel Mapping API map base resource",
"title": "Channel Mapping API map base resource",
"items": {
"type": "string",
"enum": [
"activations/",
"active/"
],
"minItems": 2,
"maxItems": 2,
"uniqueItems": true
}
}Example:
[
"activations/",
"active/"
]
get
post
options
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
get /map/activations
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Activations endpoint",
"description": "List of all currently pending activations",
"type": "object",
"patternProperties": {
"^[0-9]+$": {
"type": "object",
"additionalPropertes": false,
"properties": {
"activation":{
"$ref": "activation-response-schema.json"
},
"action:":{
"$ref": "map-tableentry-schema.json"
}
}
}
}
}
Example:
{
"1" :{
"activation":{
"mode": "activate_scheduled_absolute",
"requested_time": "1544448739:0",
"activation_time": "1544448739:0"
},
"action":{
"OutA":{
"0":{
"input": "input1",
"channel_index": 2
},
"3":{
"input": "input1",
"channel_index": 1
}
}
}
},
"2" :{
"activation":{
"mode": "activate_scheduled_relative",
"requested_time": "2:0",
"activation_time": "1544448736:0"
},
"action":{
"OutA":{
"0":{
"input": "input2",
"channel_index": 1
},
"3":{
"input": "input2",
"channel_index": 1
}
}
}
}
}
post /map/activations
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Activations endpoint",
"description": "Add a new activation to the activations list",
"type": "object",
"additionalPropertes": false,
"properties": {
"activation":{
"$ref": "activation-schema.json"
},
"action:":{
"$ref": "map-tableentry-schema.json"
}
}
}
Example:
{
"activation":{
"mode": "activate_scheduled_absolute",
"requested_time": "1544448739:0"
},
"action":{
"OutA":{
"0":{
"input": "input1",
"channel_index": 2
},
"3":{
"input": "input1",
"channel_index": 1
}
}
}
}
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Activations endpoint",
"description": "Activation response",
"type": "object",
"maxProperties": 1,
"patternProperties": {
"^[0-9]+$": {
"type": "object",
"additionalPropertes": false,
"properties": {
"activation":{
"$ref": "activation-response-schema.json"
},
"action:":{
"$ref": "map-tableentry-schema.json"
}
}
}
}
}
Example:
{
"3": {
"activation":{
"mode": "activate_scheduled_absolute",
"requested_time": "1544448739:0",
"activation_time": "1544448739:0"
},
"action":{
"OutA":{
"0":{
"input": "input1",
"channel_index": 2
},
"3":{
"input": "input1",
"channel_index": 1
}
}
}
}
}
HTTP status code 400
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes the standard error response which is returned with HTTP codes 400 and above",
"title": "Error response",
"required": [
"code",
"error",
"debug"
],
"properties": {
"code": {
"description": "HTTP error code",
"type": "integer",
"minimum": 400,
"maximum": 599
},
"error": {
"description": "Human readable message which is suitable for user interface display, and helpful to the user",
"type": "string"
},
"debug": {
"description": "Debug information which may assist a programmer working with the API",
"type": ["null", "string"]
}
}
}
Example:
{
"code": 400,
"error": "Could not match the request to the schema",
"debug": null
}
HTTP status code 423
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes the standard error response which is returned with HTTP codes 400 and above",
"title": "Error response",
"required": [
"code",
"error",
"debug"
],
"properties": {
"code": {
"description": "HTTP error code",
"type": "integer",
"minimum": 400,
"maximum": 599
},
"error": {
"description": "Human readable message which is suitable for user interface display, and helpful to the user",
"type": "string"
},
"debug": {
"description": "Debug information which may assist a programmer working with the API",
"type": ["null", "string"]
}
}
}
Example:
{
"code": 423,
"error": "Output `OutA` channel 2 is locked by another activations. No changes will be made.",
"debug": null
}
get
delete
options
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
get /map/activations/{activation-id}
URI Parameters
- activation-id: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Single activation endpoint",
"description": "A single pending activation",
"type": "object",
"additionalPropertes": false,
"properties": {
"activation":{
"$ref": "activation-response-schema.json"
},
"action:":{
"$ref": "map-tableentry-schema.json"
}
}
}
Example:
{
"activation":{
"mode": "activate_scheduled_relative",
"requested_time": "2:0",
"activation_time": "1544448736:0"
},
"action":{
"OutA":{
"0":{
"input": "input2",
"channel_index": 1
},
"3":{
"input": "input2",
"channel_index": 1
}
}
}
}HTTP status code 404
Could not find the requested resource
delete /map/activations/{activation-id}
URI Parameters
- activation-id: required(string)
HTTP status code 204
Resource deleted successfully
HTTP status code 400
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes the standard error response which is returned with HTTP codes 400 and above",
"title": "Error response",
"required": [
"code",
"error",
"debug"
],
"properties": {
"code": {
"description": "HTTP error code",
"type": "integer",
"minimum": 400,
"maximum": 599
},
"error": {
"description": "Human readable message which is suitable for user interface display, and helpful to the user",
"type": "string"
},
"debug": {
"description": "Debug information which may assist a programmer working with the API",
"type": ["null", "string"]
}
}
}
Example:
{
"code": 400,
"error": "Could not match the request to the schema",
"debug": null
}
HTTP status code 404
Could not find the requested resource
get
get /map/active
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes the map table object",
"title": "Map table resource",
"additionalProperties": false,
"required":[
"activation",
"map"
],
"properties": {
"activation": {
"$ref": "activation-response-schema.json"
},
"map":{
"$ref": "map-tableentry-schema.json"
}
}
}
Example:
{
"activation": {
"mode": null,
"requested_time": null,
"activation_time": null
},
"map":{
"outA":{
"0":{
"input": "input1",
"channel_index": 1
},
"1":{
"input": "input1",
"channel_index": 2
},
"2":{
"input": "input1",
"channel_index": 3
},
"3":{
"input": "input1",
"channel_index": 4
},
"4":{
"input": null,
"channel_index": null
},
"5":{
"input": null,
"channel_index": null
},
"6":{
"input": null,
"channel_index": null
},
"7":{
"input": null,
"channel_index": null
}
},
"outB":{
"0":{
"input": "input4",
"channel_index": 0
},
"1":{
"input": "input4",
"channel_index": 1
}
}
}
}
This resource allows a controller to fetch only the section of the map related to the named output, without the need to fetch the entire map.
get
get /map/active/{outputId}
URI Parameters
- outputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes the map for one specific outputId",
"title": "Map table resource",
"properties": {
"activation": {
"$ref": "activation-response-schema.json"
},
"map":{
"$ref": "map-tableentry-schema.json"
}
}
}
Example:
{
"outB":{
"0":{
"input": "input4",
"channel_index": 0
},
"1":{
"input": "input4",
"channel_index": 1
}
}
}
HTTP status code 404
Returned when the requested resource does not exist
Inputs
get
List all inputs available
get /inputs
List all inputs available
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "List of inputs/outputs",
"title": "Input/Outputs root resource",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9\\-_]+/$"
}
}
Example:
[
"input1/",
"input2/",
"input3/",
"input4/"
]
get
get /inputs/{inputId}
URI Parameters
- inputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Describes the Channel Mapping API input base resource",
"title": "Channel Mapping API input base resource",
"items": {
"type": "string",
"enum": [
"caps/",
"parent/",
"channels/",
"properties/"
],
"minItems": 4,
"maxItems": 4,
"uniqueItems": true
}
}Example:
[
"caps/",
"parent/",
"channels/",
"properties/"
]
HTTP status code 404
Returned when an the input name does not exist
get
get /inputs/{inputId}/caps
URI Parameters
- inputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes an input's capabilities",
"title": "Input parameter capability resource",
"additionalProperties": false,
"required":[
"reordering",
"block_size"
],
"properties":{
"reordering":{
"type": "boolean"
},
"block_size":{
"type": "integer",
"min": 1
}
}
}
Example:
{
"reordering": true,
"block_size": 8
}
HTTP status code 404
Returned when the requested resource does not exist
get
get /inputs/{inputId}/parent
URI Parameters
- inputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"additionalProperties": false,
"description": "Gives details of where media connected to an Input came from",
"title": "Input Parent Resource",
"required":[
"id",
"type"
],
"properties": {
"id":{
"type": [
"string",
"null"
],
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
},
"type":{
"type": [
"string",
"null"
],
"enum":[
"source",
"receiver",
null
]
}
}
}
Example:
{
"id": "91762591-9e46-48db-bd08-f8450248f02c",
"type": "source"
}
HTTP status code 404
Returned when the requested resource does not exist
get
get /inputs/{inputId}/channels
URI Parameters
- inputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "List of channels in an input",
"title": "Input channel resource",
"minItems": 1,
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
}
}
}
}
Example:
[
{
"label": "Left Channel"
},
{
"label": "Right Channel"
}
]
HTTP status code 404
Returned when the requested resource does not exist
get
get /inputs/{inputId}/properties
URI Parameters
- inputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Properties of the input",
"title": "Input properties resource",
"required":[
"name",
"description"
],
"properties": {
"name":{
"type": "string",
"description": "Human readable name for the input"
},
"description":{
"type": "string",
"description": "Human readable description of the input"
}
}
}
Example:
{
"name": "AES-2",
"description": "AES digital audio input 2"
}HTTP status code 404
Returned when the requested resource does not exist
Outputs
get
List all outputs available
get /outputs
List all outputs available
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "List of inputs/outputs",
"title": "Input/Outputs root resource",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9\\-_]+/$"
}
}
Example:
[
"OutA/",
"OutB/"
]
HTTP status code 404
Returned when the requested resource does not exist
get
get /outputs/{outputId}
URI Parameters
- outputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Describes the Channel Mapping API output base resource",
"title": "Channel Mapping API output base resource",
"items": {
"type": "string",
"enum": [
"sourceid/",
"channels/",
"caps/",
"properties/"
],
"minItems": 4,
"maxItems": 4,
"uniqueItems": true
}
}Example:
[
"caps/",
"sourceid/",
"channels/",
"properties/"
]
HTTP status code 404
Returned when the requested resource does not exist
get
get /outputs/{outputId}/sourceid
URI Parameters
- outputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": ["string", "null"],
"description": "Gives an output's source ID",
"title": "Output source ID resource",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
}Example:
"066cde2f-a525-417b-9177-20ae536265bc"
HTTP status code 404
Returned when the requested resource does not exist
get
get /outputs/{outputId}/channels
URI Parameters
- outputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "List of channels in an output",
"title": "Output channel resource",
"minItems": 1,
"items": {
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string"
}
}
}
}
Example:
[
{
"label": "Left Channel"
},
{
"label": "Right Channel"
}
]
HTTP status code 404
Returned when the requested resource does not exist
get
get /outputs/{outputId}/caps
URI Parameters
- outputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "List of Inputs that may be routed to a given output",
"title": "Output capabilities resource",
"required":[
"routable_inputs"
],
"properties": {
"routable_inputs":{
"items": {
"type": [
"string",
"null"
],
"pattern": "^[a-zA-Z0-9\\-_]+$"
}
}
}
}
Example:
{
"routable_inputs": [
"input1",
"input2"
]
}
get
get /outputs/{outputId}/properties
URI Parameters
- outputId: required(string)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Properties of the output",
"title": "Output properties resource",
"required":[
"name",
"description"
],
"properties": {
"name":{
"type": "string",
"description": "Human readable name for the output"
},
"description":{
"type": "string",
"description": "Human readable description of the output"
}
}
}
Example:
{
"name": "IP Output",
"description": "SMPTE 2110-20 IP Output"
}HTTP status code 404
Returned when the requested resource does not exist