🚧 UNDER DEVELOPMENT

SDIWare API Documentation

WebDecoder Public API - REST Interface for Video Decoder Control

Table of Contents

Overview

The WebDecoder API provides a simple REST interface for external applications to control web-based video decoders. This API allows you to decode web content (URLs) and output to SDI hardware using simple integer-based indexing.

Base URL: http://your-server:port/api/WebDecoder

Content-Type: application/json

Getting Started

Device and Port Indexing

The API uses simple zero-based integer indices instead of internal device IDs:

Note: Only available (inactive) output ports are counted in the indexing. Active ports are excluded from the index count.

API Endpoints

Start WebDecoder

Start a web decoder on a specific device and output port.

POST /api/WebDecoder/simple/start

Request Body

{
  "deviceIndex": 0,
  "outputIndex": 0,
  "url": "https://example.com",
  "width": 1920,
  "height": 1080,
  "framerate": 50.0,
  "interlacedOutput": true,
  "enableKey": true
}

Parameters

Parameter Type Required Default Description
deviceIndex integer Yes 0 Device index (0 = first device)
outputIndex integer Yes 0 Output port index (0 = first available output)
url string Yes - URL to decode (e.g., https://example.com)
width integer Yes 1920 Video width in pixels (must be > 0)
height integer Yes 1080 Video height in pixels (must be > 0)
framerate number Yes 50.0 Framerate in fps (must be > 0)
interlacedOutput boolean No false Enable interlaced output (false = progressive)
enableKey boolean No false Enable fill+key output (uses 2 consecutive ports)
Fill+Key Mode: When enableKey is true:
  • Two consecutive output ports are paired automatically
  • outputIndex specifies the fill port (first port)
  • The next consecutive port is used for the key (alpha channel)
  • Both ports must be available

Success Response (HTTP 200)

{
  "message": "WebDecoder started successfully",
  "deviceIndex": 0,
  "deviceId": "DeckLink_4K_Extreme_12G_00000000",
  "deviceInfo": "Blackmagic DeckLink 4K Extreme 12G",
  "outputIndex": 0,
  "outputPorts": [2, 3],
  "mode": "Fillkey",
  "usedOutputs": 2,
  "settings": {
    "url": "https://example.com",
    "resolution": "1920x1080",
    "framerate": 50.0,
    "interlaced": false,
    "keyOutput": true
  }
}

Error Responses

  • 400 Bad Request: Invalid parameters (missing URL, invalid dimensions, etc.)
  • 404 Not Found: Device or output port not found, or insufficient ports for fill+key
  • 500 Internal Server Error: Server error

Stop WebDecoder

Stop a running web decoder on a specific device and output port.

POST /api/WebDecoder/simple/stop/{deviceIndex}/{outputIndex}

URL Parameters

Parameter Type Description
deviceIndex integer Device index (0 = first device)
outputIndex integer Output index of the active decoder to stop
Note: Use the active decoder index, not the available port index. Active decoders are indexed separately (0 = first active decoder, 1 = second active decoder).

Success Response (HTTP 200)

{
  "message": "WebDecoder stopped successfully",
  "deviceIndex": 0,
  "deviceId": "DeckLink_4K_Extreme_12G_00000000",
  "outputIndex": 0,
  "stoppedPorts": [2, 3],
  "mode": "Fillkey"
}

Update URL

Update the URL of a running web decoder without stopping/restarting (seamless transition).

POST /api/WebDecoder/simple/update-url/{deviceIndex}/{outputIndex}

URL Parameters

Parameter Type Description
deviceIndex integer Device index (0 = first device)
outputIndex integer Output index of the active decoder to update

Request Body

{
  "url": "https://new-url.com"
}
Note: All other settings (resolution, framerate, interlaced mode, key mode) are preserved from the current configuration.

Success Response (HTTP 200)

{
  "message": "WebDecoder URL updated successfully",
  "deviceIndex": 0,
  "deviceId": "DeckLink_4K_Extreme_12G_00000000",
  "outputIndex": 0,
  "updatedPorts": [2, 3],
  "mode": "Fillkey",
  "newUrl": "https://new-url.com"
}

Data Models

SimpleWebDecoderSettings

Complete model for starting a web decoder:

{
  deviceIndex: number;        // 0-based device index
  outputIndex: number;        // 0-based output port index
  url: string;               // URL to decode
  width: number;             // Video width (pixels, > 0)
  height: number;            // Video height (pixels, > 0)
  framerate: number;         // Framerate (fps, > 0)
  interlacedOutput: boolean; // false = progressive, true = interlaced
  enableKey: boolean;        // false = fill only, true = fill+key
}

UpdateUrlRequest

Model for updating a decoder's URL:

{
  url: string;  // New URL to navigate to
}

Error Responses

All error responses follow this format:

{
  "error": "Error category",
  "message": "Detailed error message"
}

Or simplified:

{
  "message": "Error message"
}

Common Error Scenarios

Invalid Device Index

{
  "message": "Device index 5 out of range. Available devices: 0-2"
}

Invalid Output Index

{
  "message": "Output index 3 out of range. Available outputs on device 0: 0-1"
}

Insufficient Ports for Fill+Key

{
  "message": "Fill+Key output requires at least 2 available outputs, but only 1 available on device 0"
}

No Active Decoders

{
  "message": "No active web decoders found on device 0 (Blackmagic DeckLink 4K Extreme 12G)"
}

Examples

Example 1: Start Simple Decoder (1080p50, Progressive)

Request:

POST /api/WebDecoder/simple/start
Content-Type: application/json

{
  "deviceIndex": 0,
  "outputIndex": 0,
  "url": "https://example.com",
  "width": 1920,
  "height": 1080,
  "framerate": 50.0,
  "interlacedOutput": false,
  "enableKey": false
}

Response (200 OK):

{
  "message": "WebDecoder started successfully",
  "deviceIndex": 0,
  "deviceId": "DeckLink_4K_Extreme_12G_00000000",
  "deviceInfo": "Blackmagic DeckLink 4K Extreme 12G",
  "outputIndex": 0,
  "outputPorts": [2],
  "mode": "Single",
  "usedOutputs": 1,
  "settings": {
    "url": "https://example.com",
    "resolution": "1920x1080",
    "framerate": 50.0,
    "interlaced": false,
    "keyOutput": false
  }
}

Example 2: Start Fill+Key Decoder (1080i50)

Request:

POST /api/WebDecoder/simple/start
Content-Type: application/json

{
  "deviceIndex": 0,
  "outputIndex": 0,
  "url": "https://graphics.example.com",
  "width": 1920,
  "height": 1080,
  "framerate": 50.0,
  "interlacedOutput": true,
  "enableKey": true
}

Example 3: Update URL While Running

Request:

POST /api/WebDecoder/simple/update-url/0/0
Content-Type: application/json

{
  "url": "https://new-content.example.com"
}

Example 4: Stop Decoder

Request:

POST /api/WebDecoder/simple/stop/0/0

Usage Workflow

Typical Usage Pattern

  1. Start a decoder: POST /api/WebDecoder/simple/start
  2. Change content dynamically (optional): POST /api/WebDecoder/simple/update-url/{deviceIndex}/{outputIndex}
  3. Stop the decoder: POST /api/WebDecoder/simple/stop/{deviceIndex}/{outputIndex}
Important: When stopping decoders, the outputIndex refers to active decoders (which are re-indexed after each stop operation).

Best Practices

  1. Check error responses: Always handle 400, 404, and 500 status codes
  2. Validate parameters: Ensure width, height, and framerate are positive numbers
  3. URL format: Use fully qualified URLs with protocol (http:// or https://)
  4. Fill+Key requirements: Ensure at least 2 consecutive ports are available
  5. Interlaced output: Always uses Upper Field First (most common broadcast standard)
  6. Configuration persistence: Settings are automatically saved and restored on system restart

Support

For issues or questions about the API, please refer to the main SDIWare documentation or contact support.

Version: 1.0
Last Updated: 2025
API Base Path: /api/WebDecoder