Channel Mapping API documentation version v1.0
http://api.example.com/x-nmos/channelmapping/{version}
- version: required(v1.0)
Overview
The 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
List of paths available from this API
get /
List of paths available from this API
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/"
]Inputs
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 paths for the inputs or outputs",
"title": "Inputs or Outputs base resource",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9\\-_]+/$"
},
"uniqueItems": true
}
Example:
[
"input1/",
"input2/",
"input3/",
"input4/"
]
List of paths available from this API endpoint
get /inputs/{inputId}
List of paths available from this API endpoint
URI Parameters
- inputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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": [
"properties/",
"parent/",
"channels/",
"caps/"
]
},
"minItems": 4,
"maxItems": 4,
"uniqueItems": true
}
Example:
[
"caps/",
"parent/",
"channels/",
"properties/"
]
HTTP status code 404
Returned when the requested resource does not exist
Get information about the specified Input, such as a human-readable name and description
get /inputs/{inputId}/properties
Get information about the specified Input, such as a human-readable name and description
URI Parameters
- inputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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
Get information about the origin of the audio associated with the specified Input
get /inputs/{inputId}/parent
Get information about the origin of the audio associated with the specified Input
URI Parameters
- inputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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 information about the specified Input's channels, such as human-readable labels
get /inputs/{inputId}/channels
Get information about the specified Input's channels, such as human-readable labels
URI Parameters
- inputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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 information about the specified Input's capabilities, such as routing constraints
get /inputs/{inputId}/caps
Get information about the specified Input's capabilities, such as routing constraints
URI Parameters
- inputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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 capabilities resource",
"additionalProperties": false,
"required":[
"reordering",
"block_size"
],
"properties":{
"reordering":{
"type": "boolean"
},
"block_size":{
"type": "integer",
"minimum": 1
}
}
}
Example:
{
"reordering": true,
"block_size": 8
}
HTTP status code 404
Returned when the requested resource does not exist
Outputs
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 paths for the inputs or outputs",
"title": "Inputs or Outputs base resource",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9\\-_]+/$"
},
"uniqueItems": true
}
Example:
[
"OutA/",
"OutB/"
]
List of paths available from this API endpoint
get /outputs/{outputId}
List of paths available from this API endpoint
URI Parameters
- outputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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": [
"properties/",
"sourceid/",
"channels/",
"caps/"
]
},
"minItems": 4,
"maxItems": 4,
"uniqueItems": true
}
Example:
[
"caps/",
"sourceid/",
"channels/",
"properties/"
]
HTTP status code 404
Returned when the requested resource does not exist
Get information about the specified Output, such as a human-readable name and description
get /outputs/{outputId}/properties
Get information about the specified Output, such as a human-readable name and description
URI Parameters
- outputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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-30 IP Output"
}
HTTP status code 404
Returned when the requested resource does not exist
Get the ID of the Source associated with the specified Output
get /outputs/{outputId}/sourceid
Get the ID of the Source associated with the specified Output
URI Parameters
- outputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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 information about the specified Output's channels, such as human-readable labels
get /outputs/{outputId}/channels
Get information about the specified Output's channels, such as human-readable labels
URI Parameters
- outputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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 information about the specified Output's capabilities, such as routing constraints
get /outputs/{outputId}/caps
Get information about the specified Output's capabilities, such as routing constraints
URI Parameters
- outputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
HTTP status code 200
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Describes an output's capabilities",
"title": "Output capabilities resource",
"required":[
"routable_inputs"
],
"properties": {
"routable_inputs":{
"description": "List of Inputs that may be routed to this Output, including null if unrouted Output channels are allowed. This property MUST be set to null, if no such restrictions exist.",
"anyOf": [{
"type": "array",
"items": {
"type": [
"string",
"null"
],
"pattern": "^[a-zA-Z0-9\\-_]+$"
},
"uniqueItems": true
}, {
"type": "null"
}]
}
}
}
Example:
{
"routable_inputs": [
"input1",
"input2"
]
}
HTTP status code 404
Returned when the requested resource does not exist
Map
List of paths available from this API endpoint
get /map
List of paths available from this API endpoint
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/"
]
List pending scheduled activations
Create a new activation
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
get /map/activations
List pending scheduled 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",
"additionalPropertes": false,
"patternProperties": {
"^[a-zA-Z0-9\\-_]+$": {
"type": "object",
"additionalPropertes": false,
"required": [
"activation",
"action"
],
"properties": {
"activation":{
"$ref": "activation-response-schema.json"
},
"action:":{
"$ref": "map-entries-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
Create a new activation
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,
"required": [
"activation",
"action"
],
"properties": {
"activation":{
"$ref": "activation-schema.json"
},
"action:":{
"$ref": "map-entries-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
A 200 response is returned when a request for an immediate activation is accepted.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Activations endpoint",
"description": "Activation response",
"type": "object",
"additionalPropertes": false,
"maxProperties": 1,
"patternProperties": {
"^[a-zA-Z0-9\\-_]+$": {
"type": "object",
"additionalPropertes": false,
"required": [
"activation",
"action"
],
"properties": {
"activation":{
"$ref": "activation-response-schema.json"
},
"action:":{
"$ref": "map-entries-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 202
A 202 response is returned when a request for a scheduled activation is accepted, to indicate that while the request itself was acceptable it has not yet been acted upon by the API.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Activations endpoint",
"description": "Activation response",
"type": "object",
"additionalPropertes": false,
"maxProperties": 1,
"patternProperties": {
"^[a-zA-Z0-9\\-_]+$": {
"type": "object",
"additionalPropertes": false,
"required": [
"activation",
"action"
],
"properties": {
"activation":{
"$ref": "activation-response-schema.json"
},
"action:":{
"$ref": "map-entries-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
A 400 response is returned, for example, when the request did not meet the schema.
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
A 423 response is returned when a conflicting activation has been scheduled.
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' is locked by another activation. No changes will be made.",
"debug": null
}
Get a single pending scheduled activation
Cancel a pending scheduled activation
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
get /map/activations/{activationId}
Get a single pending scheduled activation
URI Parameters
- activationId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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,
"required": [
"activation",
"action"
],
"properties": {
"activation":{
"$ref": "activation-response-schema.json"
},
"action:":{
"$ref": "map-entries-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
Get a view of the entire active map
get /map/active
Get a view of the entire active map
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 all outputs",
"title": "Map resource",
"additionalProperties": false,
"required":[
"activation",
"map"
],
"properties": {
"activation": {
"$ref": "activation-response-schema.json"
},
"map":{
"$ref": "map-entries-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
}
}
}
}
Get the active map for the specified output. This resource allows a controller to fetch only the section of the map related to the specified output, without the need to fetch the entire map.
get /map/active/{outputId}
Get the active map for the specified output. This resource allows a controller to fetch only the section of the map related to the specified output, without the need to fetch the entire map.
URI Parameters
- outputId: required(string - pattern: ^[a-zA-Z0-9\-_]+$)
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 output",
"title": "Map resource",
"additionalProperties": false,
"required": [
"map"
],
"properties": {
"activation": {
"$ref": "activation-response-schema.json"
},
"map":{
"allOf": [{
"$ref": "map-entries-schema.json"
}, {
"minProperties": 1,
"maxProperties": 1
}]
}
}
}
Example:
{
"map":{
"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/Outputs View
Get a view on all Inputs and Outputs
get /io
Get a view on all Inputs and Outputs
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": {
"properties":{
"$ref": "input-properties-schema.json"
},
"parent":{
"$ref": "input-parent-response-schema.json"
},
"channels":{
"$ref": "input-channels-response-schema.json"
},
"caps":{
"$ref": "input-caps-response-schema.json"
}
}
}
}
},
"outputs":{
"type": "object",
"patternProperties": {
"^[a-zA-Z0-9\\-_]+$":{
"type": "object",
"additionalProperties": false,
"properties": {
"properties":{
"$ref": "output-properties-schema.json"
},
"source_id":{
"$ref": "output-sourceid-response-schema.json"
},
"channels":{
"$ref": "output-channels-response-schema.json"
},
"caps":{
"$ref": "output-caps-response-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"
}
}
}
}