HTTP API Details

An instance of the Multiview tool can be controlled via a simple HTTP API. By default, the application listens for HTTP requests on port 8901.

Routes

Use HTTP GET for all requests.

Viewers and Sources

GET: /current

Returns the current list of NDI sources, viewers, and general application state.

Example JSON output:

{
  "version": "2023.11.13.1",
  "isActivated": true,
  "instanceName": "windows_x86_64_ALPHAVII",
  "buildType": "production",
  "defaultInstances": 2
  "sources": [
    {
      "name": "ALPHAVII (Test Pattern 2)",
      "sourceNumber": 0
    },
    {
      "name": "ALPHAVII (Test Pattern)",
      "sourceNumber": 1
    }
  ],
  "viewers": [
    {
      "name": "Multiview 1",
      "viewerIndex": 0,
      "ndiStatus": 0,
      "routerStatus": 0,
      "layoutModeCode": "2L8S",
      "projectorSource": {
        "ndiSource": "CAMERA A (CAM)",
        "awaitingSource": null,
        "name": null,
        "nameMode": null,
        "useLowBandwidth": false,
        "audioChannelsDBFS": [
            -20,
            -20
        ],
        "audioChannels": 2,
        "videoWidth": 1920,
        "videoHeight": 1080,
        "frameRate": 60
      },      
      "whipStatus": 0,
      "whipDetails": {
        "ingestUrl": "https://example/whip1",
        "token": null,
        "previewUrl": "https://example/preview",
        "embedUrl": "https://example/embed"
      },
      "outputs": [
        {
          "ndiSource": "CAMERA A (CAM)",
          "awaitingSource": null,
          "useLowBandwidth": true,
          "name": "Preview",
          "nameMode": 2,
          "audioChannelsDBFS": [
            -20,
            -20
          ],
          "audioChannels": 2,
          "videoWidth": 320,
          "videoHeight": 240,
          "frameRate": 30          
        },
        {
          "ndiSource": null,
          "awaitingSource": null,
          "useLowBandwidth": false,
          "name": "Program",
          "nameMode": 2,
          "audioChannelsDBFS": null
        },
      ],
      "showAudioMeters": false
    }
  ]
}

GET: /sources

Returns a list of known NDI sources. Each source has a name and SourceNumber. The source number is used to set sources on outputs.

Example JSON output:

[
  {
    "name": "ALPHAVII (Test Pattern 2)",
    "sourceNumber": 0
  },
  {
    "name": "ALPHAVII (Test Pattern)",
    "sourceNumber": 1
  }
]

GET: /viewers

Note: Deprecated. Will be removed in a future revision.

Returns a list of multiview instances, their NDI output status, their NDI router status, whether audio meters should be shown, and which sources are assigned to which outputs.

If a source is not present or not discovered on the network but is part of a preset, it will be listed as an awaitingSource on the output.

Example JSON output:

[
  {
    "name": "Multiview 1",
    "viewerIndex": 0,
    "ndiStatus": 2,
    "routerStatus": 2,
    "showAudioMeters": true,
    "layoutModeCode": "2L8S",
    "projectorSource": {
        "ndiSource": "CAMERA A (CAM)",
        "awaitingSource": null,
        "name": null,
        "nameMode": null,
        "useLowBandwidth": false,
        "audioChannelsDBFS": [
            -20,
            -20
        ],
        "audioChannels": 2,
        "videoWidth": 1920,
        "videoHeight": 1080,
        "frameRate": 60
    },  
    "whipStatus": 0,
    "whipDetails": {
        "ingestUrl": "https://example/whip1",
        "token": null,
        "previewUrl": "https://example/preview",
        "embedUrl": "https://example/embed"
    },    
    "outputs": [
      {
          "ndiSource": "CAMERA A (NDI HX2, 192.168.1.149)",
          "awaitingSource": null,
          "name": "Output 1",
          "nameMode": 2,
          "useLowBandwidth": true,
          "audioChannelsDBFS": [
              -20,
              -20
          ],
          "audioChannels": 2,
          "videoWidth": 320,
          "videoHeight": 240,
          "frameRate": 30
      },
      {
          "ndiSource": null,
          "awaitingSource": null,
          "name": "Output 5",
          "nameMode": 2,
          "useLowBandwidth": false,
          "audioChannelsDBFS": null,
          "audioChannels": null,
          "videoWidth": 0,
          "videoHeight": 0,
          "frameRate": 0
      },
    ]
  }
]

GET: /viewers/create/{name}

Note: Deprecated. Will be removed in a future release.

Creates a new Multiview output with the given name. Each output can provide an NDI output, and perform source routing.

Parameters

name: The name of the new multiview. Used as the NDI output name as well.

GET: /viewers/create

Creates a new Multiview output with a default name.

GET: /viewers/set/{count}?persist={true|false}&writeonly={true|false}

Sets the default number of viewers to be created when the program starts up.

Parameters

count: The number of viewers to be opened. Default is 1.
persist: If set to true, saves this value to the settings. Required.
writeonly: If set to true, will only change the setting. Otherwise, the multiview will launch and/or kill instances until there are count number of instances active.

GET: /viewer/{viewer}/rename/{name}

Renames a viewer.

Parameters

viewer: The viewer index number to use.
name: The new name of the viewer.

GET: /viewer/{viewer}/renameviewport/{viewport}/{name}

Renames a viewer’s viewport.

Parameters

viewer: The viewer index number to use.
viewport: The viewer viewport index number to use, starting at 0.
name: The new name of the viewport.

GET: /viewer/{viewer}/namemode/{viewport}/{mode}

Sets whether nothing, the name of the source, or the friendly label should be displayed for a given viewport.

Parameters

viewer: The viewer index number to use.
viewport: The viewer viewport index number to use, starting at 0.
mode: Either none, friendly, or source. None hides the label. Friendly shows the viewport label regardless of the selected source. Source shows the NDI source name.

GET: /viewer/{viewer}/shutdown

Shuts down a viewer. Note that the first viewer, viewer 0, cannot be shut down.

Parameters

viewer: the number of the viewer to shut down. Viewer 0 is the main, first viewer.

GET: /viewer/{viewer}/project/viewport/{viewport}

Projects a viewport’s source as a full-screen overlay. NOTE: This will use the full-bandwidth version of the NDI feed, regardless of whether the viewpost is tuned into a low-bandwidth feed.

Attempting to project a viewport with no source set will do nothing.

Parameters

viewer: the index of the viewer to project upon. Viewer 0 is the main, first viewer.
viewport: the number of the viewport to project. Viewport 0 is the first viewport.

GET: /viewer/{viewer}/project/stop

Stops any projection of a viewport on a given viewer.

Attempting to stop projecting a viewport with no projector active does nothing.

Parameters

viewer: the index of the viewer to project upon. Viewer 0 is the main, first viewer.

GET: /viewer/{viewer}/project/source/{source}

Projects an NDI source as a full-screen overlay. NOTE: This will use the full-bandwidth version of the NDI feed. The multiview does not need to be tuned into this source on any viewport in order to view it.

Parameters

viewer: the index of the viewer to project upon. Viewer 0 is the main, first viewer.
source: the name of the source to project.

Changing Multiview Layouts

GET: /layouts

View a list of valid layouts for Multiview instances.

Example JSON Output:

[
  {
    "name": "2 Large + 8 Small",
    "code": "2L8S",
    "viewports": [
      {
        "x": 0,
        "y": 0,
        "width": 960,
        "height": 540,
        "defaultName": null
      },
      ...
    ]
  }
]

GET: /viewer/{viewerNumber}/layout/{layoutCode}

Sets the layout to be used on the specified instance.

Parameters

viewerNumber: The viewer index number to use.
layoutCode: The layout to use. See the /layouts route for valid codes.

Setting Sources

GET: /viewer/{viewerNumber}/output/{outputNumber}/source/{sourceNumber}?low=true

Sets the NDI source to be used for a given output on a multiview.

Parameters

viewerNumber: The viewer instance to use. Use the viewerIndex from the /viewers GET call (default: 0).
outputNumber: The output on the viewer instance to set a source for. The first output is 0.
sourceNumber: The NDI source to use. Use the sourceNumber provided by /sources.

GET: /viewer/{viewerNumber}/output/{outputNumber}/sourcename/{sourceName}?low=true

Sets the NDI source to be used for a given output on a multiview by source name.

Added in v2023.10.31

viewerNumber: The viewer instance to use. Use the viewerIndex from the /viewers GET call (default: 0).
outputNumber: The output on the viewer instance to set a source for. The first output is 0.
sourceName: The NDI source name to use.

GET: /viewer/{viewerNumber}/output/{outputNumber}/clear

Removes the NDI source assigned to an output.

Parameters

viewerNumber: The viewer instance to use. Use the viewerIndex from the /viewers GET call (default: 0).
outputNumber: The output on the viewer instance to remove the source for. The first output is 0.

GET: /viewer/{viewerNumber}/swap/{output1}/{output2}

Swaps NDI sources for two outputs.

Parameters

viewerNumber: The viewer instance to use. Use the viewerIndex from the /viewers GET call (default: 0).
output1: The first output viewer to use.
output2: The second output viewer to use.

GET: /viewer/{viewerNumber}/savepreset/{bank}

Saves the current selection of NDI sources as a preset in the specified bank.

Parameters

viewerNumber: The viewer instance to use. Use the viewerIndex from the /viewers GET call (default: 0).
bank: The preset bank to save, from 0 to 9. Bank 0 is the default bank loaded at startup.

GET: /viewer/{viewerNumber}/loadpreset/{bank}

Loads a preset bank and overwrites the current selection of NDI sources.

Parameters

viewerNumber: The viewer instance to use. Use the viewerIndex from the /viewers GET call (default: 0).
bank: The preset bank to load, from 0 to 9. Bank 0 is the default bank loaded at startup.

NDI Routing, Output, and Audio Monitoring

GET: /viewer/{viewerNumber}/audiometers/{meterState}

Used to turn on or off the audio meters for a viewer.

Parameters

viewerNumber: The viewer instance to use. Use the viewerIndex from the /viewers GET call (default: 0).
meterState: Use on to turn on audio meters, or off to turn off audio meters.

GET: /viewer/{viewerNumber}/ndi/{ndiStatus}

Used to turn on or off the NDI output for a multiview instance.

Parameters

viewerNumber: The viewer instance to use. Use the viewerIndex from the /viewers GET call (default: 0).
ndiStatus: Use on to turn on NDI output, or off to turn off NDI output.

GET: /viewer/{viewerNumber}/ndirouter/{ndiStatus}

Used to turn on or off NDI source routing for a multiview instance.

Parameters

viewerNumber: The viewer instance to use. Use the viewerIndex from the /viewers GET call (default: 0).
ndiStatus: Use on to turn on NDI source routing, or off to turn off NDI source routing.

Source Control

Note: in order for these commands to work, at least one viewer must be tuned into the selected source.

GET: /source/{sourceName}/loadpreset/{bank}

Loads a PTZ preset for a given NDI source.

Parameters

sourceName: the name of the NDI source.
bank: the preset number to load.

GET: /source/{sourceName}/savepreset/{bank}

Saves the current settings as a PTZ preset for a given NDI source.

Parameters

sourceName: the name of the NDI source.
bank: the preset number to save.

GET: /source/{sourceName}/pan/{direction}

Pans the PTZ source left or right. If the direction given is non-zero, the source will likely continue to pan until it receives a pan command with direction set to 0.0.

Parameters

sourceName: the name of the NDI source.
direction: a value from -1.0 to 1.0, indicating the speed of the pan.

GET: /source/{sourceName}/tilt/{direction}

Tilts the PTZ source up or down. If the direction given is non-zero, the source will likely continue to tilt until it receives a tilt command with direction set to 0.0.

Parameters

sourceName: the name of the NDI source.
direction: a value from -1.0 to 1.0, indicating the speed of the tilt.

GET: /source/{sourceName}/zoom/{direction}

Zooms the PTZ source in or out. If the direction given is non-zero, the source will likely continue to zoom until it receives a zoom command with direction set to 0.0.

Parameters

sourceName: the name of the NDI source.
direction: a value from -1.0 to 1.0, indicating the speed of the zoom.

GET: /source/{sourceName}/stopallptz

Issues a speed command of 0.0 to pan, tilt, and zoom for the given PTZ source.

Parameters

sourceName: the name of the NDI source.

GET: /source/{sourceName}/autofocus

Sets the PTZ source’s focus mode to auto-focus.

Parameters

sourceName: the name of the NDI source.

GET: /source/{sourceName}/focus/{speed}

Adjusts the PTZ source’s manual focus by the speed given. If the speed given is non-zero, the source will likely continue to adjust focus until it receives a focus command with speed set to 0.0.

Parameters

sourceName: the name of the NDI source.
speed: a value from -1.0 to 1.0, indicating the speed of the focus adjustment. Small values are recommended.

GET: /source/{sourceName}/whitebalance/{mode}/{red}/{blue}

Sets the white balance mode of the source. Optionally, if supported by the device, the red/blue levels can be specified when in manual mode.

Parameters

sourceName: the name of the NDI source.
mode: the white balance mode. The following are supported.
  • auto: Sets the white balance mode to the device’s automatic setting.
  • indoor: Sets the white balance mode to the device’s indoor setting - typically a warmer mode.
  • outdoor: Sets the white balance mode to the device’s outdoor setting.
  • center: Commands the device to set white balance based on the center of the image.
  • manual: Sets a specific white balance given the red and blue parameters.
red: the amount of “warmth” of the white balance. Ranges from 0.0 to 1.0.
blue: the amount of “coolness” of the white balance. Ranges from 0.0 to 1.0.

GET: /source/{sourceName}/exposure/auto

Sets the exposure mode of the source to be the device’s automatic mode.

Parameters

sourceName: the name of the NDI source.

GET: /source/{sourceName}/exposure/manual/{iris}/{gain}/{shutterSpeed}

Sets the exposure mode of the source to be the device’s manual mode.

Parameters

sourceName: the name of the NDI source.
iris: adjusts the aperture of the device. Ranges from 0.0 to 1.0.
gain: adjusts the gain of the image. Ranges from 0.0 to 1.0.
shutterSpeed: adjusts the shutter speed of the device. Ranges from 0.0 to 1.0.

GET: /source/{sourceName}/ndiperformance

Gets the internal performance details of the NDI receiver for the given source. Useful for troubleshooting if your device is dropping frames or unable to process frames fast enough.

Parameters

sourceName: the name of the NDI source.

Note: the audio level returned is in dBFS.

Example JSON output:

{
  "totalFrames": {
    "videoFrames": 1033,
    "audioFrames": 10328,
    "metadataFrames": 2
  },
  "droppedFrames": {
    "videoFrames": 0,
    "audioFrames": 0,
    "metadataFrames": 0
  },
  "numberConnections": 1,
  "frameQueue": {
    "videoFrames": 0,
    "audioFrames": 0,
    "metadataFrames": 0
  },
  "audioLevel": -20
}

WHIP Output (Experimental)

Important: WHIP Support in Progress

WebRTC HTTP Ingestion Protocol (WHIP) support is experimental. It will require GStreamer to be installed, along with the WHIP plugin. In addition, gst-launch-1.0 will need to be part of your PATH environment variable.

GET: /viewer/{viewer}/whip/settings

Gets the current WHIP configuration, including the bearer token.

Parameters

viewer: The viewer index to use.

Example JSON output:

{
  "ingestUrl": "https://localhost/whip1",
  "token": "token",
  "previewUrl": "https://localhost/preview",
  "embedUrl": "https://localhost/embed"
}

POST: /viewer/{viewer}/whip/set

Updates the viewer’s WHIP settings.

Note: If the token is not set in the JSON body, the value stored in the multiview will be persisted.

Parameters

viewer: The viewer index to use.

JSON Body Example

{
  // The WHIP ingest URL. 
  "ingestUrl": "https://localhost/whip1",

  // The bearer/auth token, if needed.
  "token": "token",

  // A URL to a web-based player. Optional.
  "previewUrl": "https://localhost/preview",

  // A URL to a web-based player that will be hosted
  // in an iframe on the web controller. Optional.
  "embedUrl": "https://localhost/embed"
}

GET: /viewer/{viewer}/whip/start

Starts WHIP streaming for the viewer.

Parameters

viewer: The viewer index to use.

GET: /viewer/{viewer}/whip/stop

Stops WHIP streaming for the viewer.

Parameters

viewer: The viewer index to use.

Licensing

GET: /activate/{key}

Attempts to activate the multiview app using the specified license key.

Parameters

key: The license key, as provided upon purchase.

GET: /deactivate

Deactivates the multiview app if a license key is present and activated.

GET: /activate/status

Checks the current activation status of the installed license key.

{
    "licenseKey":"...",
    "isActivated":true
}

Miscellaneous

GET: /source/{sourceName}/ndiperformance

Returns NDI performance details about a given source the multiview is tuned into. This route is provided for debugging purposes only. If a source is not being used by any multiview outputs, this route returns nothing.

{
  "totalFrames": {
    "videoFrames": 38607,
    "audioFrames": 55424,
    "metadataFrames": 0
  },
  "droppedFrames": {
    "videoFrames": 0,
    "audioFrames": 0,
    "metadataFrames": 0
  },
  "numberConnections": 1,
  "frameQueue": {
    "videoFrames": 0,
    "audioFrames": 0,
    "metadataFrames": 0
  },
  "audioLevel": -67
}

GET: /debug

Shows performance metrics and all known sources. Note that this route is used for debugging purposes and does not have a set format. Any output it produces is subject to change and should not be relied upon.