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.

Below is a basic API reference for your Multiview for NDI application running on port 8901. Each endpoint is documented with its HTTP method, route, description, and details about parameters or responses where applicable.

Base URL: http://<host>:8901

Try the API

Full documentation, along with testing individual routes, is available by going to http://<host>:8901/swagger/index.html.

General Endpoints

GET /sources

  • Description: Returns the list of available sources.
  • Query Parameters:
    • forcereload (optional): When provided, forces a refresh of the source list.
  • Response: A JSON list of source objects from the SourceController.

GET /viewers

  • Description: Retrieves a list of all multiviewers with their configuration and output details.
  • Response: A JSON array of viewer objects, each containing:
    • Name: The viewer’s name.
    • ViewerIndex: The viewer’s index in the list.
    • NdiStatus: Whether NDI output is enabled.
    • LayoutModeCode: The layout mode code.
    • Layout: Custom layout data.
    • Audio Settings: (AudioChannels, AudioSampleRate, AudioPeakdBFS, AudioMonitorSourceName)
    • ProjectorSource: An object with:
      • NdiSource
      • UseLowBandwidth (always false)
      • IsHDR
    • Outputs: A collection of viewport objects, each containing:
      • NdiSource
      • Name
      • UseLowBandwidth (determined by the receiver’s bandwidth setting)
      • IsHDR
      • VideoWatchdogTripped
    • FocusedViewportIndex: The index of the currently focused viewport.

GET /receivers

  • Description: Returns an array of available NDI receivers and their current status.
  • Response: A JSON array of receiver objects with details including:
    • SourceName
    • SubscribedRenderers (number of viewports subscribed)
    • PreviewTally
    • ProgramTally
    • IsHDR
    • LowBandwidth (inverse of FullBandwidth)
    • ReceiverWatchdogTimeout
    • SupportsPtz
    • SupportsKvm

GET /current

  • Description: Provides current application state and configuration details.
  • Response: A JSON object containing:
    • Version: Application version.
    • InstanceName: Instance identifier.
    • BuildType: Returns one of "production", "beta", or "dangerous".
    • DefaultInstances: Default multiview instances.
    • NdiSenderType: The requested NDI sender type.
    • Sources: Current sources (using the same logic as /sources).
    • Viewers: Viewer details (same structure as /viewers).

Viewer Management

GET /viewer/{viewer}/shutdown

  • Description: Shuts down the specified viewer.
  • Route Parameters:
    • viewer: The index or identifier of the viewer.

GET /viewers/create

  • Description: Creates a new viewer instance.

GET /viewers/set/{count}

  • Description: Sets the total number of viewer instances.
  • Route Parameters:
    • count: The desired number of viewers.

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

  • Description: Renames a specific viewer.
  • Route Parameters:
    • viewer: The viewer index.
    • name: The new name for the viewer.

GET /viewer/{viewer}/layout/{layoutCode}

  • Description: Changes the layout of a specific viewer.
  • Route Parameters:
    • viewer: The viewer index.
    • layoutCode: The layout code to apply.

Layouts

GET /layouts

  • Description: Returns a list of available layouts from the multiview controller.
  • Response: A JSON array of layout definitions.

Source Management for Viewer Outputs

GET /viewer/{viewer}/output/{output}/sourcename/{source}

  • Description: Assigns a source to a viewer’s output based on the provided source name.
  • Route Parameters:
    • viewer: The viewer index.
    • output: The output index.
    • source: The source name.
  • Note: This endpoint replaces the older, non-deterministic version that used a source number.

GET /viewer/{viewer}/ndi/{ndiStatus}

  • Description: Toggles or sets the NDI output status for a viewer.
  • Route Parameters:
    • viewer: The viewer index.
    • ndiStatus: The status value (likely true or false).

GET /viewer/{viewer}/savepreset/{bank}

  • Description: Saves the current viewer configuration to the specified preset bank.
  • Route Parameters:
    • viewer: The viewer index.
    • bank: The preset bank identifier.

GET /viewer/{viewer}/loadpreset/{bank}

  • Description: Loads a preset configuration for the specified viewer from a given bank.
  • Route Parameters:
    • viewer: The viewer index.
    • bank: The preset bank identifier.

GET /viewer/{viewer}/output/{output}/clear

  • Description: Clears the source assigned to the specified viewer output.
  • Route Parameters:
    • viewer: The viewer index.
    • output: The output index.

GET /viewer/{viewer}/output/{output}/loadpreset/{bank}

  • Description: Loads a source preset for a specific viewer output.
  • Route Parameters:
    • viewer: The viewer index.
    • output: The output index.
    • bank: The preset bank identifier.

GET /viewer/{viewer}/output/{output}/savepreset/{bank}

  • Description: Saves the current source configuration for a viewer output into a preset bank.
  • Route Parameters:
    • viewer: The viewer index.
    • output: The output index.
    • bank: The preset bank identifier.

Audio Monitoring (Added 2024-04-04)

GET /viewer/{viewer}/listen/viewport/{viewport}

  • Description: Begins audio monitoring for the specified viewport.
  • Route Parameters:
    • viewer: The viewer index.
    • viewport: The viewport index.

GET /viewer/{viewer}/listen/source/{sourceName}

  • Description: Begins audio monitoring for a specified source by name.
  • Route Parameters:
    • viewer: The viewer index.
    • sourceName: The name of the source to monitor.

GET /viewer/{viewer}/listen/stop

  • Description: Stops any active audio monitoring for the specified viewer.
  • Route Parameters:
    • viewer: The viewer index.

Projection (Added 2023-12-21)

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

  • Description: Projects the specified viewport for a viewer.
  • Route Parameters:
    • viewer: The viewer index.
    • viewport: The viewport index.

GET /viewer/{viewer}/project/stop

  • Description: Stops any active projection for the specified viewer.
  • Route Parameters:
    • viewer: The viewer index.

GET /viewer/{viewer}/project/source/{sourceName}

  • Description: Projects a specified source (by name) for the viewer.
  • Route Parameters:
    • viewer: The viewer index.
    • sourceName: The name of the source to project.

Captions (Added 2025-01-01)

POST /viewer/{viewer}/caption/update

  • Description: Adds or updates a caption on the specified viewer.
  • Route Parameters:
    • viewer: The viewer index.
  • Request Body: Caption details (format defined by implementation).

GET /viewer/{viewer}/caption/update/{captionCode}/{caption}

  • Description: Updates the text of a caption identified by captionCode on a viewer.
  • Route Parameters:
    • viewer: The viewer index.
    • captionCode: The unique caption identifier.
    • caption: The new caption text.

GET /viewer/{viewer}/caption/updatebg/{captionCode}/{backgroundRgba}

  • Description: Updates the background color (RGBA) for a specific caption.
  • Route Parameters:
    • viewer: The viewer index.
    • captionCode: The caption identifier.
    • backgroundRgba: The new background color in RGBA format.

GET /viewer/{viewer}/caption/updatepos/{captionCode}/{x}/{y}

  • Description: Updates the position (x and y coordinates) of a caption.
  • Route Parameters:
    • viewer: The viewer index.
    • captionCode: The caption identifier.
    • x: Horizontal coordinate.
    • y: Vertical coordinate.

GET /viewer/{viewer}/caption/hide/{captionCode}

  • Description: Hides the specified caption.
  • Route Parameters:
    • viewer: The viewer index.
    • captionCode: The caption identifier.

GET /viewer/{viewer}/caption/show/{captionCode}

  • Description: Shows (or unhides) the specified caption.
  • Route Parameters:
    • viewer: The viewer index.
    • captionCode: The caption identifier.

DELETE /viewer/{viewer}/caption/remove/{code}

  • Description: Removes a caption from the specified viewer.
  • Route Parameters:
    • viewer: The viewer index.
    • code: The caption identifier.
  • Note: The same removal functionality is also accessible via a GET endpoint.

GET /viewer/{viewer}/caption/clearall

  • Description: Clears all captions from the specified viewer.
  • Route Parameters:
    • viewer: The viewer index.

GET /viewer/{viewer}/exportlayout

  • Description: Exports the current layout configuration of the specified viewer.
  • Route Parameters:
    • viewer: The viewer index.

POST /viewer/{viewer}/importlayout

  • Description: Imports a layout configuration file for the specified viewer.
  • Route Parameters:
    • viewer: The viewer index.
  • Request Body: Layout file content (format defined by implementation).

POST /viewer/{viewer}/layout

  • Description: Changes the viewer layout using a provided template.
  • Route Parameters:
    • viewer: The viewer index.
  • Request Body: Layout template data.

Additional Routes (Added 2025-02-27)

GET /shutdown

  • Description: Initiates a shutdown of the entire application.

GET /viewer/{viewer}/focus/{viewport}

  • Description: Sets the focus to a specific viewport within the specified viewer.
  • Route Parameters:
    • viewer: The viewer index.
    • viewport: The viewport index to focus.

Debug and Diagnostics

GET /expressions

  • Description: Retrieves debug output from the expression engine.
  • Response: Debug information in JSON or plain text.

GET /debug/launchoptions

  • Description: Returns a formatted table of all public static launch options and their values.
  • Response: Plain text table.

GET /debug/diagnostics

  • Description: Provides detailed diagnostics, including information about receivers and viewers.
  • Response: A plain text summary with diagnostic details.

GET /debug

  • Description: Returns performance metrics and other debugging details (e.g., iteration times, receiver statuses).
  • Response: Plain text output containing performance data.