0% found this document useful (0 votes)

549 views

PDS-062491_SDVoE_Developers_API_Application_Note_Library_rev2p5

Uploaded by

klin20002000

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

549 views

PDS-062491_SDVoE_Developers_API_Application_Note_Library_rev2p5

Uploaded by

klin20002000

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 224

SDVoE Solution

API Application Note Library

PDS-062491 Rev 2.5 Page 1 of 224

PDS-062491 Rev 2.5 Page 2 of 224

SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
Contents
1 PURPOSE .................................................................................................................................. 11
2 SUMMARY OF NETWORK REQUIREMENTS ................................................................................. 13
3 TIPS FOR MANAGING BANDWIDTH ............................................................................................ 15
CALCULATING BANDWIDTH ................................................................................................................. 15
VIDEO PROFILES COMPRESSION APPLIED TO.......................................................................................... 15
REDUCING BANDWIDTH USAGE ........................................................................................................... 15
3.3.1 Compression Types ..............................................................................................................................15
4 LOADING API COMMAND MODULE ........................................................................................... 17
SUMMARY OF EVENT NOTIFICATIONS ................................................................................................... 18
5 QUANTIZATION MANAGEMENT................................................................................................. 21
SDVOE APPROACH ........................................................................................................................... 21
RULES THAT THE API FOLLOWS ........................................................................................................... 22
5.2.1 Input Range..........................................................................................................................................22
5.2.2 API Control ...........................................................................................................................................22
5.2.3 Multiview Mode in Relation to Quantization .......................................................................................22
MANAGING THE QUANTIZATION MODE ................................................................................................ 23
TIPS REGARDING THE QUANTIZATION MODE ......................................................................................... 24
5.4.1 “Pluge” pattern ....................................................................................................................................26
6 MULTIVIEW MODE .................................................................................................................... 27
DESCRIPTION OF THE MULTIVIEW FEATURE ........................................................................................... 27
MULTIVIEW LAYOUTS ........................................................................................................................ 28
MANAGING THE 10GBE LINK.............................................................................................................. 29
6.3.1 Multiview Example...............................................................................................................................29
6.3.2 Scaling and Frame Rate Conversion .....................................................................................................30
6.3.2.1 Decoder (RX) Bandwidth and Scaling ...........................................................................................30
6.3.2.2 Scaled Stream (stream 1) .............................................................................................................30
6.3.2.3 Encoder (TX) Bandwidth and Frame Rate Converter ...................................................................31
6.3.2.4 Summary of Bandwidth Management .........................................................................................31
MULTIVIEW MODEL AND TERMINOLOGY .............................................................................................. 32
6.4.1 Streams and Subscriptions ...................................................................................................................32
6.4.2 Layout ..................................................................................................................................................32
6.4.3 Window ................................................................................................................................................32
6.4.4 Surface .................................................................................................................................................32
6.4.5 Tiles ......................................................................................................................................................32
ILLUSTRATION OF TERMINOLOGY ......................................................................................................... 33
DEFAULT MULTIVIEW SURFACE CONFIGURATION ................................................................................... 34
MULTIVIEW API REQUEST .................................................................................................................. 35
6.7.1 Handling the Multiview Mode .............................................................................................................35
6.7.2 Retrieving a List of Existing Layouts .....................................................................................................36
CREATING AND MANAGING LAYOUTS ................................................................................................... 36
6.8.1 Creating a Layout .................................................................................................................................36
6.8.2 Adding Windows to a Layout ...............................................................................................................40
6.8.3 Retrieving Details of a Layout ..............................................................................................................43
6.8.3.1 Retrieve List Details of an Available Layout from the API Server ................................................43
PDS-062491 Rev 2.5 Page 3 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
6.8.3.2 Retrieving Details of a Layout Currently loaded on a Decoder (RX) Device .................................48
6.8.3.3 Event MULTIVIEW_CHANGED ......................................................................................................50
6.8.4 Deleting a Layout .................................................................................................................................50
6.8.5 Managing Multiview Streams ..............................................................................................................51
6.8.5.1 Managing the Scaled Stream .......................................................................................................51
6.8.5.2 Starting streams ...........................................................................................................................52
6.8.5.3 Stopping streams .........................................................................................................................53
6.8.6 Setting a Decoder to Multiview Mode .................................................................................................54
6.8.6.1 Managing Decoder Subscriptions ................................................................................................56
6.8.7 Predefined Compatibility Layout ..........................................................................................................57
6.8.8 Managing Surfaces ..............................................................................................................................57
SUMMARY OF TASKS TO CREATE AND LOAD A LAYOUT ............................................................................ 59
VIDEO SOURCES ................................................................................................................................ 60
6.10.1 Interlaced Video Sources ......................................................................................................................60
6.10.2 Chroma Sub-Sampled Sources (YCbCr 4:2:2 and YCbCr 4:2:0) .............................................................61
6.10.3 10 or 12-bit Sources .............................................................................................................................61
MULTIVIEW USE CASE ....................................................................................................................... 61
6.11.1 Sample Multiview Scripts .....................................................................................................................61
6.11.2 Sample Use Case ..................................................................................................................................62
MULTIVIEW GUIDELINES AND LIMITATIONS ........................................................................................... 64
MULTIVIEW LAYOUT CHANGES ............................................................................................................ 65
6.13.1 Changing the Active Layout .................................................................................................................67
6.13.2 Changing the Video Mode ...................................................................................................................67
6.13.3 Achieving Seamless Transitions ...........................................................................................................67
6.13.3.1 Use Case 1: Surface Overlap ........................................................................................................67
6.13.3.2 Use Case 2: Surface Reuse ...........................................................................................................70
6.13.3.3 Use Case 3: Repositioning of Active Surfaces ..............................................................................72
6.13.3.4 Use Case 4: Maximum Layout Size...............................................................................................75
6.13.3.5 Use case 5: Simple Layout Transitions .........................................................................................75
6.13.3.6 Use Case 5: Simultaneous Source Change ...................................................................................80
6.13.4 Transition Corner Cases and Limitations ..............................................................................................84
6.13.4.1 Reconfiguration of Scaled Stream (stream 1) ..............................................................................84
6.13.4.2 Layout Changes Requiring More than 32 Surfaces ......................................................................88
6.13.4.3 Layout Change with Window Reshuffling ....................................................................................88
7 VIDEO WALL MODE ................................................................................................................... 93
INTRODUCTION TO THE VIDEO WALL MODE .......................................................................................... 93
7.1.1 Genlock Wall Mode ..............................................................................................................................94
7.1.2 Fast Switch Wall Mode ........................................................................................................................95
7.1.3 Summary of Genlock and Fast Switch Wall Modes ..............................................................................96
IMPLEMENTING A SOURCE INDEPENDENT VIDEO WALL ........................................................................... 96
7.2.1 Source Independent Video Wall Requirements ....................................................................................96
7.2.1.1 Calculating Bezel Compensation ..................................................................................................98
7.2.1.2 Illustration of Applying Wall Aspect Ratios ..................................................................................99
7.2.2 Additional Info on Configuration of a Source Independent Video Wall .............................................100
7.2.3 Source Independent Video Wall API Request .....................................................................................101
7.2.4 Frame Buffer Node in Relation to SI Wall (AUTO_WALL)..................................................................103
CONFIGURING A CUSTOM VIDEO WALL .............................................................................................. 105
7.3.1 Wall Mode Terms and Concepts ........................................................................................................105
7.3.2 Tasks to Configure Video Wall ...........................................................................................................106
7.3.3 Planning a Custom Video Wall ...........................................................................................................107

PDS-062491 Rev 2.5 Page 4 of 224

SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
7.3.4 Wall Parameters and the API .............................................................................................................107
7.3.4.1 API Set Video Requests for a Custom Wall ................................................................................108
7.3.5 Managing Bezel Compensation .........................................................................................................110
7.3.6 Managing Different Source and Wall Aspect Ratios ..........................................................................112
7.3.7 Stretch Source to Fit Wall Geometry ..................................................................................................113
7.3.8 Crop Source Horizontally or Vertically to Match Wall Aspect Ratio...................................................113
7.3.8.1 Tasks Involved to Crop the Source .............................................................................................114
7.3.8.2 Wall Parameters and API Request .............................................................................................114
7.3.8.3 Wall Parameters Computation ..................................................................................................115
7.3.8.4 Step 4: Apply Values to Decoders (RX) to Crop Image ...............................................................117
7.3.9 Applying a Viewport to Maintain Source Aspect Ratio ......................................................................118
7.3.9.1 Overview of Viewport Option ....................................................................................................118
7.3.9.2 Calculating Wall Parameters ......................................................................................................119
7.3.9.3 Wall Parameter Computations ..................................................................................................123
7.3.9.4 Applying Viewport Values to API Request .................................................................................126
7.3.10 Genlock Wall Case Studies .................................................................................................................127
7.3.10.1 Case Study 1 ...............................................................................................................................127
7.3.10.2 Case Study 2 ...............................................................................................................................135
SUMMARY OF WALL MODE .............................................................................................................. 142
CREATING A WALL WITH MULTIPLE SOURCES ...................................................................................... 143
7.5.1 Scenario 1: Multiview Layout as Wall Source ....................................................................................144
7.5.2 Scenario 2: Multiview Offset Argument Modified .............................................................................144
8 SET PROPERTY COMMAND - EXAMPLE USE CASES .................................................................... 147
DEVICE MODE PROPERTY ................................................................................................................. 147
MANAGING A DEVICE NAME............................................................................................................. 148
MANAGING FRAME RATE DIVIDER ..................................................................................................... 150
8.3.1 Enabling Frame Rate Divider on Native Video Stream .......................................................................151
8.3.2 Disabling Frame Rate Divider on the Native Video Stream................................................................152
8.3.3 Enabling/Disabling Frame Rate Divider on Scaled Video Stream ......................................................153
COMPRESSION OF HDMI:0 ALWAYS ON ............................................................................................ 155
8.4.1 Verifying Status and Video Compressor Version ................................................................................156
REMOVING AUDIO FROM HDMI VIDEO STREAM ................................................................................. 156
BLACK VIDEO GENERATOR ................................................................................................................ 157
HDCP ENCRYPTION......................................................................................................................... 158
BLUERIVER RECEIVER (HDMI TX 5V) API CONTROL ............................................................................ 159
8.8.1 Overview of HDMI TX 5V Control .......................................................................................................159
8.8.2 HDMI TX 5V Mirroring .......................................................................................................................160
9 BLUERIVER AUDIO ROUTING ................................................................................................... 163
AUDIO ROUTING USE CASES ............................................................................................................. 164
9.1.1 Routing Audio to Output with the HDMI Video .................................................................................164
9.1.1.1 HDMI Audio Routing Use Case ...................................................................................................164
9.1.2 Routing Audio to the Stereo Output ..................................................................................................165
9.1.2.1 Stereo Audio Output Use Case ..................................................................................................165
9.1.3 Routing Audio to the Multichannel Audio ..........................................................................................167
9.1.3.1 Multichannel Output Use Case ..................................................................................................168
10 SECURING CONTROL COMMUNICATION .................................................................................. 169
OVERVIEW OF SECURE CONTROL COMMUNICATION ............................................................................. 169
INTRODUCTION TO API AUTHENTICATION AND ENCRYPTION .................................................................. 170
PDS-062491 Rev 2.5 Page 5 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
KEY EXCHANGES ............................................................................................................................. 170
API SERVER CONFIGURATION............................................................................................................ 171
AUTH / UNAUTH API REQUESTS ........................................................................................................ 172
10.5.1 API Configuration Node .....................................................................................................................173
AUTHENTICATION USE CASES ............................................................................................................ 174
10.6.1 Single API Server Deployment ............................................................................................................174
10.6.2 Primary-Backup API Server Deployment ............................................................................................175
10.6.3 Segmented Deployment with Shared Authentication ........................................................................176
10.6.3.1 Claim Use Case ...........................................................................................................................177
10.6.3.2 API Configuration Node .............................................................................................................178
10.6.3.3 Managing Multicast IP Range for Multiple API Servers .............................................................179
11 PERIPHERAL COMMUNICATION ............................................................................................... 181
TASKS TO ACTIVATE USB HID ENCRYPTION......................................................................................... 181
CONFIGURING THE USB HID ENCRYPTION KEY .................................................................................... 181
CONFIGURING THE USB HID SECURITY LEVEL ...................................................................................... 182
11.3.1 API USB HID Node ..............................................................................................................................184
12 BLUERIVER ERROR CODES........................................................................................................ 187
13 ICRON API INTEGRATION ......................................................................................................... 189
SETTING THE USB 2.0 EXTENDER ROLE .............................................................................................. 189
PAIRING AND UNPAIRING ICRON USB EXTENDERS ................................................................................ 190
13.2.1 Directly Pairing Two Endpoint Devices ...............................................................................................190
13.2.1.1 Using “switch” Requests ........................................................................................................190
13.2.1.2 Using “stop” Request ..............................................................................................................191
13.2.2 Simultaneous User Interaction (SUI) Pairing ......................................................................................192
13.2.2.1 SUI Guidelines and Limitations ..................................................................................................192
13.2.2.2 SUI Pairing of Icron Extenders....................................................................................................194
USB_ICRON STATUS NODE............................................................................................................. 195
NETWORK CONFIGURATION OF ICRON NODE ....................................................................................... 198
SETTINGS FILTER FOR THE ICRON NODE .............................................................................................. 199
RECOVERY OF UNREACHABLE ICRON 2.0 EXTENDERS ............................................................................ 201
13.6.1 Visibility of a USB 2.0 Extender's IP Address ......................................................................................201
13.6.2 Resetting Icron Module ......................................................................................................................201
14 NT1000/NT2000 CHIPSET FEATURES ........................................................................................ 203
NT2000 BITMAP OVERLAY FEATURE ................................................................................................. 203
14.1.1 Bitmap Overlay Guidelines and Limitations .......................................................................................203
14.1.2 Generating a Bitmap Overlay ............................................................................................................204
14.1.3 API Bitmap Requests ..........................................................................................................................205
14.1.3.1 Applying a set overlay .......................................................................................................205
14.1.3.2 The BITMAP_OVERLAY Node .....................................................................................................208
THUMBNAIL PREVIEW ...................................................................................................................... 208
14.2.1 Important Customer Notice ...............................................................................................................209
14.2.2 Thumbnail Configuration and Setup ..................................................................................................209
14.2.3 GStreamer Installation and Configuration .........................................................................................210
14.2.3.1 Thumbnail Stream Video Resolutions ........................................................................................212
14.2.3.2 Configuring the Thumbnail Generator .......................................................................................213
14.2.3.3 HDCP Content ............................................................................................................................214
14.2.3.4 Thumbnail Generator Node .......................................................................................................215
PDS-062491 Rev 2.5 Page 6 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
14.2.4 Viewing Thumbnail Preview Streams .................................................................................................217
14.2.4.1 Unicast thumbnail ......................................................................................................................217
14.2.4.2 Multicast thumbnail ...................................................................................................................217
14.2.4.3 Video scaling: .............................................................................................................................217
14.2.5 Thumbnail Script and Executable Demo ............................................................................................218
14.2.5.1 How to Use the Thumbnail Script and Executable .....................................................................218
14.2.5.2 Guidelines and Limitations ........................................................................................................219
14.2.6 Managing Format Changes ...............................................................................................................220
14.2.6.1 General Management ................................................................................................................220
14.2.6.2 Using GStreamer as viewer ........................................................................................................221
14.2.6.3 Compile Custom GStreamer Pipeline.........................................................................................222
15 REVISION HISTORY .................................................................................................................. 223

List of Figures
Figure 1: Multiview Mode in Relation to Quantization .............................................................................. 23
Figure 2: Quantization Management .......................................................................................................... 25
Figure 3 Block Diagram of Multiview Receiver Processing ......................................................................... 27
Figure 4: Example Multiview Layouts ......................................................................................................... 28
Figure 5: Multiview Example Use Case with 3 Sources and 2 Layouts ....................................................... 29
Figure 6: Two-Source Multiview Layout ..................................................................................................... 29
Figure 7: Two Video Source Layout – Illustrates Window Overlap in 5x5 tile grid (25 Tiles) ..................... 33
Figure 8: Illustration of Default Frame Buffer Surface Configuration......................................................... 34
Figure 9: Example of Surface Assignments ................................................................................................. 35
Figure 10: Example 4x4 Multiview Layout with a PiP Overlay .................................................................... 66
Figure 11: MV Transitions Use Case 1 - Single_Layout and Surface Usage ................................................ 68
Figure 12: MV Transitions Use Case 1 - Quad_Layout and Surface Usage ................................................. 69
Figure 13: MV Transitions Use Case 1 – Illustration of Memory Allocation Overlap.................................. 70
Figure 14: MV Transitions Use Case 2 – Illustration of Memory Allocation of Current Layout .................. 70
Figure 15: MV Transitions Use Case 2 – Illustration of Memory Allocation of the Quad Layout ............... 71
Figure 16: MV Transitions Use Case 2 – Illustration of Memory Allocation during the Transition ............ 72
Figure 17: MV Transitions Use Case 3 – Illustration of Memory Allocation of Current Layout .................. 73
Figure 18: MV Transitions Use Case 3 – Illustration of Memory Allocation of New Layout ....................... 74
Figure 19: MV Transitions Use Case 3 – Illustration of Memory Reallocation ........................................... 75
Figure 20: MV Transitions Use Case 4 – Current Memory Allocation of Single_Layout ............................. 76
Figure 21: MV Transitions Use Case 4 –Memory Allocation of PiP_Layout................................................ 77
Figure 22: MV Transitions Use Case 4 –Memory Allocation of PiPCorner_Layout..................................... 78
Figure 23: MV Transitions Use Case 4 –Memory Allocation of Quad5_Layout .......................................... 79
Figure 24: MV Transitions Use Case 4 –Memory Allocation of PaP_Layout ............................................... 80
Figure 25: MV Transitions Use Case 5 –Memory Allocation of Initial Quad_Layout .................................. 82
Figure 26: MV Transitions Use Case 5 –Memory Allocation of Quad7_Layout .......................................... 83
Figure 27: MV Transitions Use Case 5 –Memory Allocation of Quad8_Layout .......................................... 84
Figure 28: Illustration of Solution 1 ............................................................................................................ 85
Figure 29: Illustration Initial Layout of Solution 2....................................................................................... 87
Figure 30: Illustration the Second Layout Configuration for Solution 2 ..................................................... 88
Figure 31: Illustration of Window Reshuffling ............................................................................................ 89
Figure 32: Window Repositioning Solution -- Memory Allocation of Current Layout ................................ 90
Figure 33: Window Repositioning Solution -- Memory Allocation of New Layout ..................................... 91
PDS-062491 Rev 2.5 Page 7 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
Figure 34: Block View of Decoder Processing ............................................................................................. 94
Figure 35: Illustration of Grid Indexes for a 3x2 Video Wall ....................................................................... 98
Figure 36: Original 16:9 Source Example .................................................................................................... 99
Figure 37: SI Wall KEEP Illustration ............................................................................................................. 99
Figure 38: SI Wall STRETCH Illustration....................................................................................................... 99
Figure 39: SI Wall CROP Illustration .......................................................................................................... 100
Figure 40: Illustration of Wall Tearing ...................................................................................................... 106
Figure 41: "Per Row Delay" to Reduce Wall Tearing ................................................................................ 106
Figure 42: Example of a 2x2 Wall Grid ...................................................................................................... 107
Figure 43: Illustration of set video Arguments Applied to RX4 of 2x2 Wall....................................... 109
Figure 44: Example without Bezel Compensation .................................................................................... 110
Figure 45: Example with Bezel Compensation.......................................................................................... 110
Figure 46: Example of Bezel Borders to Consider for a 3x3 Wall Grid ...................................................... 111
Figure 47: 2x2 Example of Rectangular Wall Grid with Bezel Compensation Applied ............................. 111
Figure 48: Example with AOI Size and x/y Coordinates Applied ............................................................... 112
Figure 49: Example of Source Different than Wall Aspect Ratio .............................................................. 112
Figure 50: Horizontal Example of Stretching Source to Fit Wall ............................................................... 113
Figure 51: Example of Cropping the Source.............................................................................................. 113
Figure 52: Example of Viewport Option Applied ...................................................................................... 118
Figure 53: Viewport Regions Illustrated for Example 3x2 16:9 Wall Grid................................................. 118
Figure 54: Viewport Wall Size ................................................................................................................... 120
Figure 55: Illustration of the Location for Viewport Parameters.............................................................. 121
Figure 56: Illustration of Addition Viewport Parameters ......................................................................... 121
Figure 57: Individual Viewport Areas Highlighted for the Sample 3x2 Wall Grid ..................................... 122
Figure 58: Example of Decoder 1 (RX1) Viewport and AOI ....................................................................... 122
Figure 59: Example of Decoder 2 (RX2) Viewport and AOI ....................................................................... 122
Figure 60: Example of Decoder 3 (RX3) Viewport and AOI ....................................................................... 123
Figure 61: 3x2 Wall Grid 16:9 Source Shown with Viewport Applied....................................................... 143
Figure 62: Example of 2x2 Wall Grid and Two Source Layout .................................................................. 143
Figure 63: Scenario 1 Multiview Layout as Wall Source ........................................................................... 144
Figure 64: Scenario 2 Multiview Layouts Applied ..................................................................................... 145
Figure 65: Block Diagram of an Encoder (TX) Illustrating Frame Division ................................................ 150
Figure 66: Flow Chart of HDMI TX 5V Behavior ........................................................................................ 161
Figure 67: Available Audio Routing for AVP2000T .................................................................................... 163
Figure 68: Communication between an API Server and Bound-Authenticated Endpoint Device ............ 171
Figure 69: Endpoint Device Authentication .............................................................................................. 171
Figure 70: Network Setup with Single API Server Instance ...................................................................... 175
Figure 71: Use Case: Backup API Server.................................................................................................... 176
Figure 72: Example of API Server/Endpoint Device Segmentation using API Claim Feature ................... 177
Figure 73: GStreamer System Variable ..................................................................................................... 211
Figure 74: Example of verifying GStreamer .............................................................................................. 211
Figure 75: Example of a Thumbnail preview............................................................................................. 219
Figure 76: Thumbnail resolution change .................................................................................................. 220
Figure 77: Video size changes with GStreamer......................................................................................... 221

PDS-062491 Rev 2.5 Page 8 of 224

PDS-062491 Rev 2.5 Page 9 of 224

PDS-062491 Rev 2.5 Page 10 of 224

PDS-062491 Rev 2.5 Page 11 of 224

PDS-062491 Rev 2.5 Page 12 of 224

PDS-062491 Rev 2.5 Page 13 of 224

PDS-062491 Rev 2.5 Page 14 of 224

Video Profiles Compression Applied To

Lightweight Video compression is automatically applied to the following video profiles:
• 4K60 8-bit RGB and YCbCr 4:4:4
• 4K60 10-bit YCbCr 4:2:2
• 4K60 12-bit YCbCr 4:2:2
• 4K60 12-bit YCbCr 4:2:0
• 4K30 12-bit RGB and YCbCr 4:4:4

Reducing Bandwidth Usage

To help reduce overall bandwidth usage, light compression can be applied to all HDMI video signals.
• Refer to section 8.4 Compression of HDMI:0 Always On for an example of applying compression
to the Native stream (stream 0).
Reminder, a compressed video source cannot be used by decoders (RX) operating in multiview mode.
However, frame rate conversion can be applied on the encoder (TX) side. Refer to section 8.3 Managing
Frame Rate Divider for information on applying this property.
• It is also possible to remove the HDMI audio from the native HDMI video stream. Refer to
section 8.5 Removing Audio from HDMI Video Stream.
TIP: For additional information on these and other configurable properties, refer to the SDVoE
Developers API Reference Guide, section Command set property.

3.3.1 Compression Types

The BlueRiver chipsets support two types of compression:
Compression Version 2 Recommended. Select for best quality in all situations, the
proprietary light compression engine was improved.
Compression Version 1 Original compression version, apply if backwards compatibility is of
concern. Applicable generally only for NT1000/NT2000 chipset-based
devices running API version 2.18 or earlier.
When the factory default settings are configured one of these two compression types is applied as the
default. The API supports changing the compression type through an API request.

PDS-062491 Rev 2.5 Page 15 of 224

PDS-062491 Rev 2.5 Page 16 of 224

Summary of Event Notifications

To receive asynchronous notifications for events and command requests a WebSocket connection
is required.
Reminder: On a WebSocket connection, notifications are enabled by default. Details available in the
Developers Introduction to SDVoE API User Guide and SDVoE Control Server
Administrators Guide.
Alternatively, it is possible to poll for events using the event command. Events are
assigned an “event type” and most have further associated data available. Events
with more data available are assigned a “request ID” that is then used with the
request command to retrieve additional data.
As reviewed in the Developers Introduction to SDVoE API User Guide, when a device is
discovered by the API, an asynchronous event notification DEVICE_CONNECTED is
generated. In addition, a DEVICE_INFO_AVAILABLE event is also generated notifying
of the availability of detailed information about the discovered device, such as if it is a
receiver or transmitter, firmware version and the chipset type the board is built-on.
Example of events generated when a device is discovered by the API:
{
"status" : "NOTIFICATION",
"request_id" : null,
"result" : {
"events" : [
{
"device_id" : "801f124307b7",
"event_id" : 1,
"event_type" : "DEVICE_CONNECTED",
"timestamp" : 1601042767,
"request_id" : 1
},
{
"device_id" : "801f124307b7",
"event_id" : 2,
"event_type" : "DEVICE_INFO_AVAILABLE",

PDS-062491 Rev 2.5 Page 18 of 224

PDS-062491 Rev 2.5 Page 19 of 224

PDS-062491 Rev 2.5 Page 20 of 224

SDVoE Approach
When a decoder (RX) is operating in Fast Switch, Genlock Scaling or Wall processing modes, the
quantization range is programmed according to a series of rules. This section outlines the behavior of
quantization in relation to the SDVoE endpoint devices.
Color ranges:
Limited Range = 16 - 235
Full Range = 0 - 255
Definition of quantization modes (CEA-861-F standard) in relation to the API:
STANDARD
The output quantization range is set according to the video format (as per CEA-861-F
standard section 5.1). The AVI InfoFrame is set to DEFAULT(0) as per the same standard.
AUTO
The output quantization range is set according to video format (as per CEA-861-F standard section
5.1) but the AVI InfoFrame is set explicitly to LIMITED(1) or FULL(2) depending on the output
quantization for this output format.

PDS-062491 Rev 2.5 Page 21 of 224

Rules that the API Follows

5.2.1 Input Range
In all cases the following applies:
i. When a source reports FULL or LIMITED, the output of SDVoE endpoint follows the source.
ii. When a source reports DEFAULT and is an RGB source then:
a. Assume LIMITED if the input resolution is a video (CE) resolution.
b. Assume FULL if the input resolution is graphics (IT) resolution.
iii. Above is not applicable to the multiview mode. Refer to section 5.2.3 Multiview Mode in
Relation to Quantization.
iv. If the source is DVI, the input format range is always assumed to be RGB Full.

5.2.2 API Control

When the API quantization option is set to:
STANDARD (default option) the behavior is as described above in section 5.1, specifically:
i. AVI InfoFrame set to DEFAULT.
ii. If output resolution is a video resolution (CE), then the range set to LIMITED.
iii. If output resolution is a graphics resolution (IT), then the range is FULL.
In regards to AUTO, again the behavior is as described above but to be specific the following occurs:
i. If the output resolution is a video resolution (CE), the output range is set to LIMITED and the
AVI InfoFrame is also set to LIMITED.
ii. If the output resolution is a graphics resolution (IT), then the output range is set to FULL and
the AVI InfoFrame is set to FULL.
When LIMITED or FULL range are applied, they behave as outlined above in section 5.1 SDVoE
Approach, that is range and AVI InfoFrame set to LIMITED or FULL respectively.

5.2.3 Multiview Mode in Relation to Quantization

When the decoder (RX) is operating in multiview mode, this is a special case where the decoder can
receive up to 32 video streams and each could have a different quantization range.
The HDMI Source of an encoder (TX) device can be BT.2020 or BT.709, HDR or SDR, RGB or YCbCr,
Limited or Full.
Note: If the output of the scaled stream (stream 1) is required to be FULL range (versus
LIMITED) it is necessary that the source stream be configured as FULL range and not set to
DEFAULT. This is because the BlueRiver AVP chipset doesn’t convert the original source from
LIMITED to FULL when in multiview mode.
TIP: Sources can be forced to output FULL range through the use of the EDID file
presented to it.

PDS-062491 Rev 2.5 Page 22 of 224

Native Stream
(Stream 0)

HDMI Source
• BT.2020/BT.709
• HDR/SDR
• RGB/YCbCr
• Limited/Full Stream 1 output
Scaled Stream (Stream 1) • BT.709
• SDR
• RGB
Color Converter
• Limited or Full (if source
configured as FULL and
not DEFAULT, refer to
note.)

10GbE
Network

Decoder (RX)

RGB stream
Multiview Layout converted
Compositor RX Scaler • Full HDMI Out
• Limited or
• Auto
Stream
API controlled
• RGB
• Full

Figure 1: Multiview Mode in Relation to Quantization

Managing the Quantization Mode

The quantization range is managed by applying the video format argument, quantization_range
to a set video request when specifying the decoder (RX) video mode.
Command syntax:
POST /api/device/{target}
{
"op" : "set:video",
"display_mode" : String,
"video" : VideoFormatArgument (conditional),
}
PDS-062491 Rev 2.5 Page 23 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
The "quantization_range" option is part of the video arguments (VideoFormatArgument)
and the supported modes are AUTO, FULL, LIMITED and STANDARD. If not specified, the behavior is
same as if STANDARD was specified. Refer to the SDVoE Developers API Reference Guide for more
information than provided in this application note.
The first example shown here sets a receiver in Fast Switch mode, with an output resolution of
1920x1080@60 and the quantization range to FULL.
POST /api/device/010203040506 HTTP/1.1
…
{
"op" : "set:video",
"display_mode" : "FAST_SWITCHED",
"video" : {
"width" : 1920,
"height" : 1080,
"fps" : 60,
"quantization_range" : ”FULL”
}
}
The second example shown here sets a receiver in Fast Switch mode, also with an output resolution of
1920x1080@60 but the quantization range is set to AUTO.
POST /api/device/010203040506 HTTP/1.1
…
{
"op" : "set:video",
"display_mode" : "FAST_SWITCHED",
"video" : {
"width" : 1920,
"height" : 1080,
"fps" : 60,
"quantization_range" : ”AUTO”
}
}

Tips Regarding the Quantization Mode

Reminder when a decoder is operating in genlock mode (scaling disabled), the pixels are not modified
nor are the AV Info Frames associated to the original stream. Therefore, what is received by the
decoder is passed through ‘as is’. It’s basically the same result as being connected directly to a display.
When a decoder is operating in Fast Switch mode because transformations are done to the pixels, the
chipset’s processing engine needs to understand these pixels (color space, pixel depth, range,
encryption, etc.). More specifically, if the source device is reporting LIMITED range, SDVoE endpoints
expand it to process it.

PDS-062491 Rev 2.5 Page 24 of 224

Figure 2: Quantization Management

After processing but prior to sending the pixel out on HDMI, it is possible to restore the LIMITED range
by forcing the LIMITED range through the API. At this point the SUPER BLACK and the SUPER WHITE is
removed, which is the intended behavior. When set to LIMITED mode, source devices (except perhaps a
test pattern generator) do not use codes 0-15 and 236-255.
TIPS:
i. The difference between the quantization AUTO and STANDARD modes is that, while STANDARD
puts the value DEFAULT (Q=0) in the AVI InfoFrame, AUTO instead puts either LIMITED or FULL
in the AVI InfoFrame depending on whether the video format is a CE format or not. AUTO is
intended as a workaround for displays that take the wrong decision when they see DEFAULT in
the AVI InfoFrame.
ii. The decoder always sends the AVI InfoFrame.
• Unless specified otherwise through the API (LIMITED, FULL or AUTO values of the
quantization argument using set video request), the Q field is set to value 0 “DEFAULT”.
• This indicates to the monitor/sink that the quantization range is the default one
(depending on whether the video format is a CE format or not).
iii. Since scaling is supported, it enables use cases where the input is an IT format but the output is
a CE format.
• On the decoder side, CEA-861 default operation means deciding on the quantization
range based on the requested output format (CE or IT) and then converting it if the
source has a different quantization range.

PDS-062491 Rev 2.5 Page 25 of 224

5.4.1 “Pluge” pattern

The “pluge” pattern is a special pattern used to help in quantifying the video range, where:
• The brightest white band is a white with a code higher than 235, therefore “whiter than white”
in LIMITED. Absolute White is 235
• The darkest black band is a black with a code lower than 16, therefore “darker than black” in
LIMITED. Absolute Black is 16.
When a monitor is displaying the “pluge” pattern it should:
When operating in LIMITED range:
1. Clip the SUPER Black to Black
2. Clip the SUPER White to White
When operating in FULL range:
1. Show all Blacks with different intensity
2. Show all Whites with different intensity

PDS-062491 Rev 2.5 Page 26 of 224

Description of the Multiview feature

Definition:
Multiview is the ability to take multiple independent sources and composite them into a single output
stream that is then displayed on a single display.
• When set in Multiview mode, the decoder (RX) adjusts and/or scales source signals, placing
them into a predefined layout of a specified dimension.
• It then composites the scene and generates a video signal of the required resolution and
framerate, which is then sent out to the connected display.
• Sources can have different resolutions and/or frame rates.
Video Stream 1

Video Stream 2
Frame Black
10G Scaler Display
Buffer Generator
Video Stream 32

Compositor
(layout generator)

Figure 3 Block Diagram of Multiview Receiver Processing

PDS-062491 Rev 2.5 Page 27 of 224

Source 2 Source 1

Source 1
Source 2

PiP PaP

Source 1

Source 2 Source 3

Grid Arbitrary
Figure 4: Example Multiview Layouts

Note: An SDVoE multiview implementation supports any layout style, so long as the total
subscribed bandwidth on any network link does not exceed the 10GbE network pipe. This is
the implicit bandwidth restriction for any 10GbE network.

PDS-062491 Rev 2.5 Page 28 of 224

Picture-in-Picture
Encoder
10GbE Switch
Security Camera

Decoder

Encoder
Security Camera Arbitrary Layout

Figure 5: Multiview Example Use Case with 3 Sources and 2 Layouts

Managing the 10GbE Link

A key to successfully implementing multiview layouts is to respect and correctly manage the 10GbE
bandwidth link. This applies to a decoder (RX) where multiple streams are received to create the
multiview composition, as well as to an encoder (TX) where the native stream (stream 0) and scaled
stream (stream 1) coexist.

6.3.1 Multiview Example

The scenario below illustrates a multiview layout, where two sources are combined into a single scene.
• Encoder 1 is connected to a computer outputting the Ski-racer video.
• Encoder 2 is connected to a media player outputting the Race car video.
The two HDMI streams are subscribed to by a single decoder (RX) where they are combined into a single
layout composition. The scene is then rendered into a new video stream that in turn is sent to the
output display attached to the decoder (RX).

Figure 6: Two-Source Multiview Layout

PDS-062491 Rev 2.5 Page 29 of 224

PDS-062491 Rev 2.5 Page 30 of 224

PDS-062491 Rev 2.5 Page 31 of 224

6.4.1 Streams and Subscriptions

Streams are a sending endpoint while subscriptions are a receiving endpoint.
Each stream or subscription has an assigned type and only streams and subscriptions of the same type
can be associated/joined together.

6.4.2 Layout
A layout represents the multiview configuration that is to be composited by a decoder (RX). It has an
assigned name which is used to identify it when a multiview API request is issued. It also specifies the
total output resolution of the layout.

6.4.3 Window
A window is a high-level abstraction provided by the API. It is a rectangular area on the screen that
contains either the rectangular area of a surface or black. Windows can overlap, when this occurs the
content of the window with the lowest index is shown in the overlapping area.

6.4.4 Surface
A surface is a rectangular area within a decoder’s (RX) frame buffer reserved for use by a specific video
source. Each decoder (RX) running in multiview mode, supports up to 32 surfaces and each surface is
associated with the HDMI subscription with the same index.
Example, the video from HDMI subscription 4 is forwarded into surface 4.

6.4.5 Tiles
The chipset divides a screen into tiles, which represent the smallest unit on the screen to which content
can be assigned. Each tile contains either a rectangular area of a surface or is black.
Multiple tiles may be required to represent an individual window (example when windows overlap), as
well as black areas that are not directly a part of any window. Refer to the Figure 7: Two Video Source
Layout – Illustrates Window Overlap in 5x5 tile grid (25 Tiles for an illustration of tiles.

PDS-062491 Rev 2.5 Page 32 of 224

Figure 7: Two Video Source Layout – Illustrates Window Overlap in 5x5 tile grid (25 Tiles)

PDS-062491 Rev 2.5 Page 33 of 224

Figure 8: Illustration of Default Frame Buffer Surface Configuration

Illustrated here is a quad layout example, where the layout contains four windows. Each window is
assigned to an individual surface. In this example, surfaces 0 through 3 are assigned to the windows
contained within the layout.

PDS-062491 Rev 2.5 Page 34 of 224

For situations where the default configuration is not adequate, the allocation of the surfaces in a
decoder (RX) frame buffer can be customized using layout surface requests. Refer to section 6.8.8
Managing Surfaces for more information on adding or removing surfaces.

Multiview API Request

API requests are used to create, configure and apply multiview layouts.

6.7.1 Handling the Multiview Mode

The table below shows the API command list that is relevant to multiview. The commands outlined here
are used to implement multiview configurations, such as picture-in-picture (PiP) or a matrix grid.
Table 1 Multiview Command List

How to... Multiview API command

List all layouts list layout
Create a layout layout create
Describe a layout layout describe
Specify surfaces layout surface
Specify window/tile content layout window
Delete a layout layout delete
Apply a layout to decoder (RX) set multiview
Set scaler resolution of a source set scaler
Join a source join

PDS-062491 Rev 2.5 Page 35 of 224

6.7.2 Retrieving a List of Existing Layouts

It is possible to view a list of layouts that currently exist from the API server using a list layout request.
Request syntax: GET /api/multiview/layout
Example of retrieving a listing of currently existing layouts:
GET /api/multiview/layout
{
"status": "SUCCESS",
"request_id": null,
"result": {
"layout": [
{
"name": "compatibility_4k_2x2"
}
]
},
"error": null
}
Two return values are provided:
• First member is “layout” which contains the LayoutItemObject.
An array of the object, each representing a multiview layout.
• Second is a string providing the layout name.

Creating and Managing Layouts

When planning and implementing multiview layouts there is a series of tasks required. The following
section reviews these tasks as well as some additional options that are applicable to configuring and
implementing multiview layouts.

6.8.1 Creating a Layout

To create a new multiview layout or reset an existing layout with the specified name, a layout
create request is used.
The syntax for creating a layout request is shown below:
POST /api/multiview/layout/{name}
{
"op" : "create",
"width" : Integer,
"height" : Integer
}
The name argument specifies the name of the multiview layout. While the width and height
arguments respectively specify the total width and height of the multiview composition.

PDS-062491 Rev 2.5 Page 36 of 224

PDS-062491 Rev 2.5 Page 37 of 224

PDS-062491 Rev 2.5 Page 38 of 224

PDS-062491 Rev 2.5 Page 39 of 224

6.8.2 Adding Windows to a Layout

Once a layout is created, a layout window request is used to add windows to the layout. This
request is also used to modify or delete windows.
POST /api/multiview/layout/{name}/window/{index}
{
"op" : "create",
"horizontal_position" : Integer,
"vertical_position" : Integer,
"width" : Integer,
"height" : Integer,
"horizontal_offset" : Integer (optional),
"vertical_offset" : Integer (optional),
"target_surface" : Integer (optional)
}
The name argument is the name of the multiview layout.
The index argument represents the index of the window itself and must be between 0 and 31.

PDS-062491 Rev 2.5 Page 40 of 224

PDS-062491 Rev 2.5 Page 41 of 224

PDS-062491 Rev 2.5 Page 42 of 224

6.8.3 Retrieving Details of a Layout

It is possible to retrieve information related to a given layout in one of two methods. The first is to
retrieve details of a layout currently stored within the API server and the second to retrieve details of a
layout currently loaded on a decoder (RX) device operating in multiview mode. Below reviews the two
independent API commands used for these purposes. Also, in this subsection introduction to the
MULTIVIEW_CHANGED event included.
6.8.3.1 Retrieve List Details of an Available Layout from the API Server
To retrieve details from the API about an existing layout a layout describe request is used. Data
provided includes total layout size along with the information for each window including their position,
surface, target and size. Three tables are provided below outlining details on the provided data.
Request syntax: GET /api/multiview/layout/{name}
The name argument is name of the multiview layout.
The structure of the Layout description object (LayoutDescription) is as follows:
{
"name" : String
"width" : Integer,
"height" : Integer,
"read_only" : Boolean,
"surfaces" : [SurfaceDescription, ...],
"windows" : [WindowDescription, ...]
}
The table below provides a description of the data received describing the layout description object.
Table 2: Table Describing the Layout Description Object

Member name Type Description

name String The name of the layout.
width Integer Display width in pixels.
height Integer Display height in pixels.
read only Boolean Whether the layout is protected against
modifications.
Currently, only the predefined layout,
compatibility_4k_2x2 layout, is read-only.
surfaces Array of SurfaceDescription Description of all surfaces in the layout.
windows Array of WindowDescription Description of all windows in the layout.

PDS-062491 Rev 2.5 Page 43 of 224

Member name Type Description

index Integer The surface index.
horizontal_position Integer Horizontal start position of surface in pixels.
vertical_position Integer Vertical start position of surface in pixels.
width Integer Surface width in pixels.
height Integer Surface height in pixels
Window description object (WindowDescription) has the following structure:
{
"index" : Integer,
"horizontal_position" : Integer,
"vertical_position" : Integer,
"width" : Integer,
"height" : Integer,
"horizontal_offset" : Integer,
"vertical_offset" : Integer,
"content" : String,
"target_surface" : Integer,
}
Table 4: Table Describing the Window Description Object

Member name Type Description

index Integer The surface index.
horizontal_position Integer Horizontal start position of window on screen, in pixels.
vertical_position Integer Vertical start position of window on screen, in pixels.
width Integer Window width in pixels.
height Integer Window height in pixels
horizontal_offset Integer Horizontal offset from the start of the surface.
vertical_offset Integer Vertical offset from the start of the surface.
content Integer Type of content of this window, either:
VIDEO window has video content
BLACK window is black
target_surface Integer Index of the surface to which the window refers.
Only meaningful when content member is VIDEO.
Following shows an example request for retrieving details for the some_layout example:
i. The layout description includes the name and size of the layout.
ii. Surfaces list each of the surfaces that exist in the layout, includes details of their index

PDS-062491 Rev 2.5 Page 44 of 224

PDS-062491 Rev 2.5 Page 46 of 224

PDS-062491 Rev 2.5 Page 47 of 224

PDS-062491 Rev 2.5 Page 48 of 224

PDS-062491 Rev 2.5 Page 49 of 224

6.8.4 Deleting a Layout

The layout delete command is used to remove the entire layout including all its related properties
from the API server.
Command syntax: DELETE /api/multiview/layout/{name}
A delete request removes the layout completely, including the window and surface configuration.
The name argument represents the name of the multiview layout that is to be removed/deleted.
Potential Errors
ILLEGAL_ARGUMENT Occurs when arguments entered invalid.
MULTIVIEW_LAYOUT_STATE Occurs if specified layout is read-only.

PDS-062491 Rev 2.5 Page 50 of 224

6.8.5 Managing Multiview Streams

To successfully stream a layout from a decoder to its attached display besides creating the layout, there
are some additional actions required. Specifically from the encoder side this includes configuring the
scaled streams as well as managing the status of both the native and scaled streams (start/stop); while
at the decoder side need to manage subscriptions and set the video display mode to multiview.
6.8.5.1 Managing the Scaled Stream
When creating layouts containing multiple windows, the assigned destination streams are usually the
HDMI scaled stream (stream 1) of an encoder (TX). The size of the destination stream must match the
specified window size of the layout. The scaled stream is managed using a set scaler request.
TIP: The scaler resolution should be set before starting the scaled video stream.
Syntax for a set scaler request is as follows:
POST /api/device/{target}
{
"op" : "set:scaler",
"width" : Integer,
"height" : Integer
}
The target argument is either the device ID of a single encoder (TX) or the name of a device group.
The supported device groups are:
ALL All devices
ALL_TX All transmitter devices
The width and height arguments respectively specify width and height of the scaled video, in pixels.
Example of setting the HDMI scaled stream (stream 1) of encoder d88039e83991 to an output
resolution of 640 x 480:
POST /api/device/d88039e83991
{
"op" : "set:scaler",
"width" : 640,
"height" : 480
}

PDS-062491 Rev 2.5 Page 51 of 224

PDS-062491 Rev 2.5 Page 52 of 224

Manually managing Multicast IP allocation

When it is preferred to manually manage the multicast IP address allocation, this is completed by
specifying an IP address using the dest_address argument of the start command.
When manually managing the multicast IP allocation, the IP entered must be an available unused
multicast IP address within the allocation range configured in the configuration file of the API server.
The default range is [224.1.1.1 to 224.1.3.255].
The following are invalid in regards to the dest_address argument:
• 224.1.1.253 is the default address reserved for the “ALL_TX” multicast IP address. The
default may be modified through the API server configuration file.
• 224.1.1.254 is the default address reserved for the “ALL_RX” multicast IP address. The
default may be modified through the API server configuration file.
• Multicast IP address 225.225.225.225.
• Any multicast address in the following ranges defined in IETF RFC 3171:
o An address in the Local Network Control Block (224.0.0.0/24).
o An address in the Internetwork Control Block (224.0.1.0/24).
• Any of the following special use IPv4 addresses as defined in IETF RFC 5735:
o An address on the “This” network (0.0.0.0/8).
o A loopback address (127.0.0.0/8).
TIP: For more information on managing default multicast ranges, refer to the SDVoE Control Server
Administrators Guide.
If dest_address is not specified, the API server uses either the address already assigned to each
stream by a previous invocation of the start command that has not been released by a stop request,
otherwise it allocates an unused multicast address.
6.8.5.3 Stopping streams
As referred to earlier, stopping an HDMI stream is useful in managing the output bandwidth of an
encoder (TX). It should however be kept in mind that when a stream is stopped it is no longer available
to any subscribed decoder (RX) device.
A stop request is used to stop one or more stream(s) on one or more devices and optionally free the
multicast address associated with each stopped stream. The syntax of a stop request is as follows:

PDS-062491 Rev 2.5 Page 53 of 224

6.8.6 Setting a Decoder to Multiview Mode

A set multiview request is used to set one or more decoders (RX) to operate in multiview mode, as
well as to load the specified layout.
The request syntax for this action is as follows:
POST /api/device/{target}
{
"op" : "set:multiview",
"layout" : String,
"video" : VideoFormatArguments (conditional),
"subscriptions" : [SubscriptionObject,...] (optional)
}
The target argument is either the device ID of a single decoder (RX) or the name of a device group. The
supported device groups are:
ALL All devices. Only affects decoders (RX).
ALL_RX All decoders (RX) are set to multiview mode and the specified layout is loaded.
The layout argument specifies the multiview layout to load.
The video argument specifies video format arguments, in regards to managing layouts this argument
must be implicitly specified as multiview. Refer to the SDVoE API Developer Reference Guide,
section Specifying a Video Output Format for more information on video output formats.
It is possible to specify the output resolution to be applied. If the output resolution (video arguments) is
not specified, the total layout size is applied.
Reminder: It is possible to specify the output resolution either by using video arguments of size
width height fps or specifying the Video Identification Code (VIC) or the
HDMI VIC. For list of supported VIC and HDMI VIC codes, refer to the SDVoE Developers
API Reference Guide.
PDS-062491 Rev 2.5 Page 54 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
Potential Errors
ILLEGAL_ARGUMENT Occurs when target argument entered is not a valid device ID or
group name.
ILLEGAL_ARGUMENT Also occurs in the following cases:
• When no subscriptions in the subscription array (i.e. empty list).
• A subscription source is not a valid device ID.
• A subscription source does not exist, device disconnected or is
not a transmitter or transceiver device.
• The source stream index is missing or invalid.
• The subscription index is missing or invalid.
• A source stream or a subscription index is duplicated.
RESOURCE_NOT_FOUND Occurs when the specified layout does not exist.
MULTIVIEW_LAYOUT_STATE Occurs when the specified layout does not satisfy either the
hardware or API limitations. Refer to section 6.12 Multiview
Guidelines and Limitations for details.
The request may also fail for individual devices for the following reasons:
DEVICE_TYPE This error occurs if the specified device is not a receiver device.
DEVICE_TYPE Also occurs when the device does not support the full multiview capabilities,
such as an AVP1000 or NT1000 device. In addition, this error is received if
device is a legacy BlueRiver NT device and the specified layout is not the
compatibility_4k_2x2 layout.
INVALID_STATE Indicates that the source stream of a subscription is stopped.
Reminder: The AVP1000 and NT1000 chipsets do not support the multiview mode.
Command example loading the some_layout multiview layout with a frame rate of 60 applied:
POST /api/device/010203040506
{
"op" : "set:multiview",
"layout" : "some_layout",
"video" :
{
"width" : 1920,
"height" : 1080,
"fps" : 60
}
}
{
"status" : "PROCESSING",
"request_id" : 41,
"result" : null,
"error" : null
}
The return values for the set command are the same as for the get settings command. Refer to
Appendix A of the SDVoE Developers API Reference Guide for an example. For more information on the
set command refer to the SDVoE Developers API Reference Guide.

PDS-062491 Rev 2.5 Page 55 of 224

PDS-062491 Rev 2.5 Page 56 of 224

6.8.8 Managing Surfaces

In the event that the default surface configuration does not meet the needs of a given layout, such as
the layout contains more windows than the default surface configuration contains, it is possible to
modify the default surface configuration.
TIP: The frame buffer has a limited physical buffering capacity of 10880x4096 pixels.
A surface request is used to create, modify or delete the surface configuration of a layout.
Syntax for creating/modifying a surface:
POST /api/multiview/layout/{name}/surface/{index}
{
"op" : "create",
"horizontal_position" : Integer,
"vertical_position" : Integer,
"width" : Integer,
"height" : Integer
}
Syntax for deleting a surface:
DELETE /api/multiview/layout/{name}/surface/{index}
The name argument is the name of the multiview layout.
The index argument is the index of the surface and must be a numerical number between 0 and 31.
The horizontal_position and vertical_position arguments are respectively the horizontal
and vertical start positions of the surface in the frame buffer, in pixels.
Note: The horiz_position argument cannot be less than 8-pixels and is applied in increments
of two pixels, so for example 8, 10, 12, etc.
The width and height arguments are respectively the width and height of the surface, in pixels.
Note: The width argument can also not be less than 8-pixels and is applied in increments of two
pixels, so for example 8, 10, 12, etc.
If the method selected is DELETE, then if the surface specified exists it is deleted.
PDS-062491 Rev 2.5 Page 57 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
Potential Errors
ILLEGAL_ARGUMENT Occurs when the arguments entered are invalid.
MULTIVIEW_LAYOUT_STATE Occurs when the specified layout exists but is read-only.
RESOURCE_NOT_FOUND Occurs when the specified layout does not exist.
Example specifying the surface, position and size of surface 23 for the layout named some_layout:
POST /api/multiview/layout/some_layout/surface/23
{
"op" : "create",
"horizontal_position" : 3872,
"vertical_position" : 0,
"width" : 1920,
"height" : 1080
}

{
"status" : "SUCCESS",
"request_id" : null,
"result" : {
"layout_surface" : {
"index" : 23,
"horizontal_position" : 3872,
"vertical_position" : 0,
"width" : 1920,
"height" : 1080
}
},
"error" : null
}
This second example deletes surface 23 from the layout named some_layout.
DELETE /api/multiview/layout/some_layout/surface/23
{
"status" : "SUCCESS",
"request_id" : null,
"result" : null,
"error" : null
}
Refer to the SDVoE Developers API Reference Guide for more information on the surface command.

PDS-062491 Rev 2.5 Page 58 of 224

PDS-062491 Rev 2.5 Page 59 of 224

Video Sources
The above case study reviewed the steps involved in creating and loading a PiP layout and applying it to
a decoder (RX).
To manage the multiview mode, there are conditions that relate to video sources that need to be kept in
mind when working with and configuring multiview layouts. This section reviews these conditions in
relation to:
• Interlaced sources
• Chroma sub-sampled sources (YCbCr)
• 10-bit and 12-bit sources

6.10.1 Interlaced Video Sources

As described earlier, all HDMI video streams used by decoders (RX) running in the multiview mode must
be in progressive format. This means, if the HDMI source being fed as the native stream (Stream 0) is an
interlaced video source it cannot be assigned to a decoder (RX) operating in multiview mode. It is
necessary to assign the scaled stream (Stream 1), as it is always in progressive format.
Also, should be noted that in regards to an interlaced video source, the frame rate divider option built
into an encoder (TX) cannot be applied as it does not handle interlaced video sources. Refer to section
6.3.2.3 Encoder (TX) Bandwidth and Frame Rate Converter for more information.

PDS-062491 Rev 2.5 Page 60 of 224

6.10.2 Chroma Sub-Sampled Sources (YCbCr 4:2:2 and YCbCr 4:2:0)

Reminder, all video streams assigned to a multiview layout must be fully color sampled.
So, this means in the case of a YCbCr 4:2:2 or YCbCr 4:2:0 source, use the scaled stream (stream 1) which
is always converted to YCbCr 4:4:4 and therefore compatible with the multiview mode.

6.10.3 10 or 12-bit Sources

All video streams used in multiview layouts must be 8-bit. This means that for any 10 or 12-bit video
source, the native stream (Stream 0) cannot be used. The scaled stream (Stream 1) must instead be
selected as it is always output in 8-bit progressive format.

Multiview Use Case

To manage and apply a multiview layout requires a series of API commands. It is likely an application
client will read a script and send the requests to the API server, who in turn completes the request itself
or forwards it to the appropriate endpoint device(s).

6.11.1 Sample Multiview Scripts

Scripts can contain multiview layout requests as well as other API requests. For example, scripts
could contain:
Example of commands that could be included in a multiview script:
• Create a layout
• Load a layout
• Create or modify windows
• Assign sources to surfaces
• Join encoders to layout subscriptions
• Start streams
• Scale the native stream
• Reduce video frame rate of a native and/or scaled stream of an encoder (TX)
The following section provides a sample user case.

PDS-062491 Rev 2.5 Page 61 of 224

PDS-062491 Rev 2.5 Page 62 of 224

PDS-062491 Rev 2.5 Page 63 of 224

PDS-062491 Rev 2.5 Page 64 of 224

Multiview Layout Changes

When a layout change request is issued, generally the transition change is seamless. To ensure a
seamless transition occurs, the following conditions must be met:
• The total number of tiles of the current layout and the requested layout remains below 255.
• The total number of tiles of the requested layout must also remain below 128.
In the event the decoder (RX) cannot guarantee a seamless transition, a glitch-less transition of
approximately 6-frames of black occurs between the current and requested layout change. When a
video source (subscription) change occurs, the decoder (RX) will have a seamless transition within the
impacted tiles.
On a video source (subscription) change, unaffected tiles of the decoder (RX) remain unchanged.
The figure below shows an example that would result in the approximate 6-frames of black during the
transition of the current and new layouts. In the use case demonstrated here, a 4x4 layout is shown
with a PiP window. The sources are 1920x1080 and 960x540 (PiP). The output stream resolution is
3840x2160@60. This layout uses 144 tiles, surpassing the requirements mentioned above.
For information regarding layout transitions, refer to section 6.13.3 Achieving Seamless Transitions.

PDS-062491 Rev 2.5 Page 65 of 224

Stream A Stream A Stream A Stream A

Stream B Stream B Stream B Stream B

Stream A Stream A Stream A Stream A

Stream B Stream B Stream B Stream B

Stream A Stream A Stream A Stream A

Stream B Stream B Stream B Stream B

Stream A Stream A Stream A Stream A

Figure 10: Example 4x4 Multiview Layout with a PiP Overlay

When establishing subscriptions for the sources to be composited within a layout, this task can be
completed using one of two methods.
1. The first method is to send independent requests, one request to set the decoder to operate in
multiview mode and then a separate join request for each required source subscription.
For example, if loading an existing picture-in-picture layout, three API requests are required.
One to set the decoder into multiview mode and two join requests, one for each of the sources
to be included in the composited layout.
2. The second option, outlined in this application note, is to include a request for each required
source subscription with the set video request.
• Subscriptions can be added with a set multiview request, allowing for a layout to loaded
quicker than when individual requests are sent.
• Refer to section 6.8.6 Setting a Decoder to Multiview Mode for details on loading a
layout and establishing subscriptions in a single step.
Note: If there are unassigned windows in the layout that is loaded, the windows will contain
black until video subscriptions are established.

PDS-062491 Rev 2.5 Page 66 of 224

6.13.2 Changing the Video Mode

Changing a decoder (RX) from multiview mode to another operating mode, such as genlock or fast
switch, is completed using a set video request. The API server unsubscribes the decoder (RX)
stream subscriptions from the sources, leaving only subscription 0 subscribed, preventing any required
action if this source is to remain subscribed. Otherwise, if the subscription is to be changed it is
necessary to send a join request to subscribe the decoder (RX) to the desired stream. Refer to the
SDVoE Developers API Reference Guide for more information on the join command.

6.13.3 Achieving Seamless Transitions

As mentioned above, when layouts are loaded the action is typically seamless. However, there are some
instances when this is not the case and black is present during the transition period for approximately
6-frames.
To assist with having a good understanding when the above occurs, details on requirements required to
have layouts load seamlessly are outlined below. The examples below outline the constraints and
limitations that must be respected to achieve seamless transitions.
6.13.3.1 Use Case 1: Surface Overlap
When building a request to load a new multiview layout, it must be ensured that the memory space to
be used by the new layout does not physically overlap memory space currently is in use.
The following example illustrates a use case in which the sole factor preventing seamless multiview
transition is the overlapping of surfaces within the framebuffer.

PDS-062491 Rev 2.5 Page 67 of 224

Illustration of the surface assigned for the above layout:

Figure 11: MV Transitions Use Case 1 - Single_Layout and Surface Usage

PDS-062491 Rev 2.5 Page 68 of 224

Illustration of the surface allocation in the decoder’s frame buffer:

Figure 12: MV Transitions Use Case 1 - Quad_Layout and Surface Usage

PDS-062491 Rev 2.5 Page 69 of 224

Figure 13: MV Transitions Use Case 1 – Illustration of Memory Allocation Overlap

6.13.3.2 Use Case 2: Surface Reuse

Another requirement for a seamless transition is that when loading a new multiview layout, it must be
ensured that the surfaces requested for the new layout are not already in use by the current layout.
Note that for the following example, a custom surface configuration is in use for the currently loaded
layout, Single_Window.
Initial Layout Loaded
For this second use case, the summary for the currently loaded layout, Single_Window, is as follows:
Total layout size is 3840 2160
Includes a single window, window 0 position 0 0 size 4096 2160 target surface 1
The subscription of the decoder (RX) is to stream index 1 and subscription_index (surface) 0.

Figure 14: MV Transitions Use Case 2 – Illustration of Memory Allocation of Current Layout

PDS-062491 Rev 2.5 Page 70 of 224

Surface assignments and configuration:

Figure 15: MV Transitions Use Case 2 – Illustration of Memory Allocation of the Quad Layout

PDS-062491 Rev 2.5 Page 71 of 224

Figure 16: MV Transitions Use Case 2 – Illustration of Memory Allocation during the Transition

6.13.3.3 Use Case 3: Repositioning of Active Surfaces

When requesting a new Multiview Layout, the requester must ensure that surfaces remaining in use do
not move inside the frame buffer.
Initial Layout Loaded
The summary of the Quad3_Layout currently loaded on the decoder (RX) is as follows:
Total size 3840 2160
Includes four windows as follows:
Window 0 position 0 0 size 1920 1080 target surface 17
Window 1 position 1920 0 size 1920 1080 target surface 18
Window 2 position 0 1080 size 1920 1080 target surface 19
Window 3 position 1920 1080 size 1920 1080 target surface 20
The decoder which is operating in multiview mode with the Quad3_Layout loaded, has an output
resolution of 3840 2160 fps 30 and the following active subscriptions:
Encoder A: stream index 1 subscription_index (surface) 17
Encoder B: stream index 1 subscription_index (surface) 18
Encoder C: stream index 1 subscription_index (surface) 19
Encoder D: stream index 1 subscription_index (surface) 20
Example of the decoder output stream for the Quad3_Layout:

PDS-062491 Rev 2.5 Page 72 of 224

Figure 17: MV Transitions Use Case 3 – Illustration of Memory Allocation of Current Layout

New Layout Request

Summary details of the new layout to be loaded, Quad4_Layout:
Total size 3840 2160
Includes four windows as follows:
Window 0 position 0 0 size 1920 1080 target surface 17
Window 1 position 1920 0 size 1920 1080 target surface 2
Window 2 position 0 1080 size 1920 1080 target surface 19
Window 3 position 1920 1080 size 1920 1080 target surface 5
This layout request also includes two surface configuration changes:
Surface 17 position 4096 0 size 2048 1080
Surface 19 position 4096 1080 size 2048 1080
When the set multiview request is sent for the decoder to load the new layout
Quad4_Layout, the total output resolution is 3840 2160 fps 30 and the requested
subscriptions are as follows:

PDS-062491 Rev 2.5 Page 73 of 224

Illustration of the surface allocation for this layout:

Figure 18: MV Transitions Use Case 3 – Illustration of Memory Allocation of New Layout

During the multiview transition, there is no overlap and all requested surfaces were not previously in
use, however, surfaces 17 and 19 were moved within the decoder’s frame buffer, preventing a
seamless transition.

PDS-062491 Rev 2.5 Page 74 of 224

6.13.3.4 Use Case 4: Maximum Layout Size

As previously defined at the beginning of this section, for a seamless multiview transition to occur, the
sum of the quantity of tiles in the current and requested layouts must be equal to or less than 255.
Furthermore, transitioning to a layout containing more than 128 tiles, results in black being displayed
during the layout transition. Refer to 6.13.3 Achieving Seamless Transitions for more information.
6.13.3.5 Use case 5: Simple Layout Transitions
The following example navigates an AVP2000 decoder through five (5) different multiview layouts, for a
total of four (4) layout transitions. These transitions are seamless when the layouts are loaded in the
order outlined here, as all the conditions outlined in the previous sections are met. This means the
surface allocations are unique and the set multiview request includes the subscription requests.
Initial Layout Loaded
The initial layout in this series is a single window layout.
The summary of the initial active layout Single_Window, is as follows:
Total layout size is 3840 2160
Includes a single window:
Window 0 position 0 0 size 3840 2160 target surface 0
The subscription of the decoder (RX) is to stream index 1 and subscription_index (surface) 0.

PDS-062491 Rev 2.5 Page 75 of 224

Figure 20: MV Transitions Use Case 4 – Current Memory Allocation of Single_Layout

PiP Layout Request Loaded

Summary details of the second layout, PiP_Layout:
Total size 3840 2160
Includes two windows as follows:
Window 0 position 2240 1400 size 960 540 target surface 12
Window 1 position 0 0 size 3840 2160 target surface 1
This layout request also includes a surface configuration change:
Surface 1 position 4096 0 size 4096 2160
When the set multiview request is sent for the decoder to load the PiP_Layout with total
size of 3840 2160 fps 30, the requested subscriptions are as follows:
Encoder B: stream index 1 subscription_index (surface) 1
Encoder C: stream index 1 subscription_index (surface) 12

PDS-062491 Rev 2.5 Page 76 of 224

Illustration of the surface allocation:

Figure 21: MV Transitions Use Case 4 –Memory Allocation of PiP_Layout

PiP Corner Window Layout Request Loaded

This third layout overlays four smaller windows over a fifth larger window, creating a form of a PiP
layout. For this illustration, this layout is referred to as the PiPCorner_Layout.
Summary details of a third layout, PiPCorner_Layout:
Total size 3840 2160
Includes four windows as follows:
Window 0 position 3200 0 size 640 360 target surface 13
Window 1 position 0 0 size 640 360 target surface 14
Window 2 position 3200 1800 size 640 360 target surface 15
Window 3 position 0 1800 size 640 360 target surface 16
Window 4 position 0 0 size 4096 2160 target surface 1
This layout request also includes a surface configuration change:
Surface 1 position 4096 0 size 4096 2160

PDS-062491 Rev 2.5 Page 77 of 224

Illustration of the surface allocation:

Figure 22: MV Transitions Use Case 4 –Memory Allocation of PiPCorner_Layout

Quad Layout Request Loaded

Summary details of the fourth layout request, referred to as Quad5_Layout:
Total size 3840 2160
Window 0 position 0 0 size 1920 1080 target surface 7
Window 1 position 0 1080 size 1920 1080 target surface 8
Window 2 position 1920 0 size 1920 1080 target surface 9
Window 3 position 1920 1080 size 1920 1080 target surface 10

PDS-062491 Rev 2.5 Page 78 of 224

Illustration of the surface allocation:

Figure 23: MV Transitions Use Case 4 –Memory Allocation of Quad5_Layout

Layout request PaP

The fifth layout in this sequence is a Picture-and-Picture layout, referred to as PaP_Layout.
This layout contains two windows which are configured side by side and use two surface allocations.
Details of this layout are as follows:
Total size 3840 2160
Window 0 position 0 540 size 1920 1080 target surface 3
Window 1 position 1920 540 size 1920 1080 target surface 6

PDS-062491 Rev 2.5 Page 79 of 224

Illustration of the surface allocation:

Figure 24: MV Transitions Use Case 4 –Memory Allocation of PaP_Layout

Summary: This series of layout changes transition cleanly as the constraints outlined previously are
avoided and the update of required subscriptions are established when the new layout is
loaded as part of the set multiview request. Refer to section 6.8.6.1 Managing
Decoder Subscriptions for details on managing stream subscriptions.
6.13.3.6 Use Case 5: Simultaneous Source Change
It is possible to simultaneously change more than one video subscription by applying the same
multiview layout configuration while specifying different subscriptions.
This is particularly useful when a visually sequential transition is not acceptable. For example, when the
video stream subscription requests are sent individually using a join request, each change takes an
interval of approximately 150-200ms.

PDS-062491 Rev 2.5 Page 80 of 224

Surface Allocation of the Quad6_Layout:

PDS-062491 Rev 2.5 Page 81 of 224

The second layout in this series, Quad7_Layout, again has new surface allocations and subscriptions.
Details of the layout itself are as follows:
Total size 3840 2160
Window 0 position 0 0 size 1920 1080 target surface 1
Window 1 position 0 1080 size 1920 1080 target surface 2
Window 2 position 1920 0 size 1920 1080 target surface 4
Window 3 position 1920 1080 size 1920 1080 target surface 5
When the set multiview request is sent to load the above Quad7_Layout, it requested the
output resolution of 3840 2160 fps 30 and established subscriptions as follows:
Encoder E: stream index 1 subscription_index (surface) 1
Encoder F: stream index 1 subscription_index (surface) 2
Encoder G: stream index 1 subscription_index (surface) 4
Encoder H: stream index 1 subscription_index (surface) 5
Example of the decoder output stream:

Illustration of the requested surface allocations:

PDS-062491 Rev 2.5 Page 82 of 224

The next layout, Quad8_Layout, changes two of the four current surface allocations and
subscriptions.
Details of the layout itself are as follows:
Total size 3840 2160
Window 0 position 0 0 size 1920 1080 target surface 1
Window 1 position 0 1080 size 1920 1080 target surface 17
Window 2 position 1920 0 size 1920 1080 target surface 4
Window 3 position 1920 1080 size 1920 1080 target surface 19
When the set multiview request is sent to load the Quad8_Layout, it requests the output
resolution of 3840 2160 fps 30 with the following subscriptions:
Encoder E: stream index 1 subscription_index (surface) 1
Encoder J: stream index 1 subscription_index (surface) 17
Encoder G: stream index 1 subscription_index (surface) 4
Encoder K: stream index 1 subscription_index (surface) 19
Example of the decoder output stream, note the windows 1 and 3 subscriptions were modified:

PDS-062491 Rev 2.5 Page 83 of 224

Figure 27: MV Transitions Use Case 5 –Memory Allocation of Quad8_Layout

6.13.4 Transition Corner Cases and Limitations

In this section, some specific corner cases and limitations of the multiview mode are reviewed that
should be considered when creating and applying multiview layouts. This information is of particular
importance when planning applications where seamless transitions are preferred and avoiding these
types of scenarios will prevent outputting black during transition periods.
6.13.4.1 Reconfiguration of Scaled Stream (stream 1)
A decoder (RX) cannot be expected to synchronize an active multiview layout application with the live
scaling reconfiguration of an encoder (TX) video source to which it is currently subscribed. For example,
if the scaled stream resolution is modified, the layout windows do not automatically resize. The two
events happen asynchronously on two distinct and separate devices. However, there are solutions that
have the potential to offer the desired system behavior.
For the following examples, the initial video output of the decoder is as illustrated below:

The requested video output:

PDS-062491 Rev 2.5 Page 84 of 224

Figure 28: Illustration of Solution 1

PDS-062491 Rev 2.5 Page 85 of 224

PDS-062491 Rev 2.5 Page 86 of 224

Figure 29: Illustration Initial Layout of Solution 2

New Layout Request

A new layout configuration is requested for the LShape layout loaded above. Note that windows 0
and 4 target index assignments are modified as well as their associated subscriptions and that surface 1
is also being modified.
Total layout size is 3840 2160
Window 0 position 0 0 size 2560 1440 target 1
Window 1 position 0 1440 size 1280 720 target 12
Window 2 position 1280 1440 size 1280 720 target 13
Window 3 position 2560 1440 size 1280 720 target 14
Window 4 position 2560 0 size 1280 720 target 10
Window 5 position 2560 720 size 1280 720 target 16
Surface 1 position 4096 0 size 4096 2160
When the set multiview request is sent to load the new LShape_Layout layout, it requests the
output resolution of 3840 2160 fps 30 and establishes the following subscriptions:
Encoder A: stream index 1 subscription_index (surface) 10
Encoder B: stream index 1 subscription_index (surface) 12
Encoder C: stream index 1 subscription_index (surface) 13
Encoder D: stream index 1 subscription_index (surface) 14
Encoder E: stream index 0 subscription_index (surface) 1
Encoder F: stream index 1 subscription_index (surface) 16

PDS-062491 Rev 2.5 Page 87 of 224

Illustration of the surface allocation for the new layout request:

Figure 30: Illustration the Second Layout Configuration for Solution 2

6.13.4.2 Layout Changes Requiring More than 32 Surfaces

Due to the surface reuse constraint, any layout transition that requires more than 32 shared surfaces
between the current and requested layout cannot be completed seamlessly.
For example, when transitioning from a 5X5 layout to a 3X3 layout with new subscriptions, the 5X5
layout requires 25 surfaces and the 3X3 layout requires 9 for a total of 34 surfaces. In this case, the
reuse of surfaces cannot be avoided.
6.13.4.3 Layout Change with Window Reshuffling
To ensure a seamless transition, when loading an alternate layout with new subscriptions, they must be
attached to unused surfaces. Moving and/or rotating subscriptions between active windows must be
completed by moving the window placement of the multiview layout, not through reassigning currently
active subscriptions to active surfaces. This section will review some proposed solutions for the issue
described above.

PDS-062491 Rev 2.5 Page 88 of 224

Shuffling of the layout window positions:

Figure 31: Illustration of Window Reshuffling

Solution – Window Repositioning + Single Added Subscription

A solution to this problem is illustrated below using a quad layout as an example.
Initial Layout
The summary of the currently loaded layout on the decoder (RX) is as follows:
Total size 3840 2160
Includes four windows as follows:
Window 0 position 0 0 size 1920 1080 target surface 17
Window 1 position 0 1080 size 1920 1080 target surface 18
Window 2 position 1920 0 size 1920 1080 target surface 19
Window 3 position 1920 1080 size 1920 1080 target surface 20
The decoder running the current quad layout described above is set to an output resolution of 3840
2160 fps 30 and has the following active subscriptions:
Encoder A: stream index 1 subscription_index (surface) 17
Encoder B: stream index 1 subscription_index (surface) 18
Encoder C: stream index 1 subscription_index (surface) 19
Encoder D: stream index 1 subscription_index (surface) 20

PDS-062491 Rev 2.5 Page 89 of 224

Surface allocation of the initial layout:

Figure 32: Window Repositioning Solution -- Memory Allocation of Current Layout

New Layout Request

Summary details of the new layout to be loaded:
Total size 3840 2160
Includes four windows as follows:
Window 0 position 0 1080 size 1920 1080 target surface 17
Window 1 position 1920 1080 size 1920 1080 target surface 18
Window 2 position 0 0 size 1920 1080 target surface 19
Window 3 position 1920 0 size 1920 1080 target surface 1
When the set multiview request is sent for the decoder to load the new layout, the total
output resolution is 3840 2160 fps 30 and the requested subscriptions are as follows:
Encoder A: stream index 1 subscription_index (surface) 17
Encoder B: stream index 1 subscription_index (surface) 18
Encoder C: stream index 1 subscription_index (surface) 19
Encoder E: stream index 1 subscription_index (surface) 1

PDS-062491 Rev 2.5 Page 90 of 224

Illustration of the surface allocation for this layout:

Figure 33: Window Repositioning Solution -- Memory Allocation of New Layout

PDS-062491 Rev 2.5 Page 91 of 224

PDS-062491 Rev 2.5 Page 92 of 224

Introduction to the Video Wall Mode

The Video Wall mode renders a single video source across multiple displays.
• The SDVoE solution supports video wall capabilities without the use of additional equipment.
• Each display is connected to a decoder (RX).
• The video source is connected to an encoder (TX) that sends the source video to each of the
subscribed decoders (RX) that assimilate the wall grid.
• Each decoder (RX) crops an “Area of Interest” according to its position in the wall grid and then
uses the scaling engine to generate an output raster to display the cropped area on screen.
• A black pillarbox or letterbox can be applied to keep the aspect ratio of the source intact.
When in Wall mode, a decoder (RX) uses multiple processing blocks inside the AV processing engine.
Refer to Figure 34: Block View of Decoder Processing below for illustration. The decoder’s cropping
engine is used to crop the Area of Interest (AOI) from the initial source. The AOI is presented to the
scaler to display the cropped region.
To compensate for the display bezels, cropping regions are adjusted, virtually hiding the source pixels.
The goal of bezel compensation is to make the source image appear to continue behind the bezels, as if
the bezels are part of a window frame that is overlaid on top of the displayed source image. Bezel
compensation is reviewed in more detail in section 7.3.5 Managing Bezel Compensation.

PDS-062491 Rev 2.5 Page 93 of 224

Video Chroma Color Space Color Depth

10G
Decompression Resampler Converter Converter

Area of
Frame Black
Interest Scaler Display
Buffer Generator
Crop

Figure 34: Block View of Decoder Processing

Two video wall modes are available:

Genlock Wall (synchronized)
Fast Switch Wall (asynchronous)
The same programming and control options are available for both wall modes, including cropping,
scaling and viewports, as well as bezel and overlap management.
The Genlock and Fast Switch Wall video modes can coexist within the same system, although only one
mode can be assigned to a single decoder device (RX).
Regardless of the wall mode applied, the output of a decoder (RX) operating in wall mode is always in
RGB 8-bit format and BT.709 color space.

7.1.1 Genlock Wall Mode

When set in Genlock wall mode, the decoders (RX) are all synchronized (time-locked) to the source and
therefore to one another.
Benefits:
i. Deterministic latency. First row is 1 frame behind the source, then each subsequent row is
slightly delayed reducing screen tearing such that the bottom of last row is full frame behind the
beginning of the first row.
ii. Each display is synchronized (genlocked) to the source and thus to each other.
iii. Video quality of a genlock wall is better overall when compared to a fast switch wall.
PDS-062491 Rev 2.5 Page 94 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
Limitations:
i. Genlock wall mode has been validated for three network hops.
• When more than three network hops are required, synchronization issues could occur. A
suggested workaround is to arrange the system such that the required source and all wall
displays are connected to the same network switch (switch segment).
• The other option is to implement the video wall using the Fast Switch Wall mode.
ii. Fast switching between different sources is not possible. Due to the nature of Genlock,
switching from once source to another source requires the decoder (RX) and its attached display
to resynchronize to the new source.
iii. Frame rate conversion is not available in this mode.
• For a decoder (RX), this means that the frame rate of the RX must match the frame rate of
the source to which it is subscribed. For example, if the source is 60 fps then the output
frame rate must also be 60 fps.
• For an encoder (TX), the divide frame rate by two is not supported.

7.1.2 Fast Switch Wall Mode

The Fast Switch wall mode is an asynchronous video wall. It does not have the limitations of the
Genlock video wall in regards to transporting streams through more than three network hops or
changing sources on-the-fly.
While the Genlock video provides better overall visual quality, a Fast Switch video wall is comparable to
the video wall functionality offered by most matrix switches (not including dedicated video wall
processors). The Fast Switch Wall mode uses the chipset’s frame buffer, allowing for fast switching
between sources and for signals to cross multiple switches but does result in individual screens that are
not in sync with each other.
Benefits:
The primary benefits of a Fast Switch wall are:
i. Using the built-in scaler means that each display is always synchronized to the decoder (RX) and
the display does not have to resynchronize when switching between sources.
ii. The option of a video wall is always available regardless of network topology (single switch
versus multiple switches).
iii. Source changes occur quickly and cleanly (Fast Switch).
iv. Frame rate conversion is available in this mode.
• For a decoder (RX), this means that the frame rate can be different than the frame rate of
the source it is subscribed to.
• For an encoder (TX), the divide frame rate by two is supported and can be applied to either
the native stream (stream 0) and/or scaled stream (stream 1).
Limitations:
The main limitation of this mode is that displays are not in sync with each other by up to 1 frame. This
implementation uses an independent frame buffer on each receiver, which generates latency that is
between 1-2 frames.

PDS-062491 Rev 2.5 Page 95 of 224

Implementing a Source Independent Video Wall

The “Source Independent Video Wall” or “SI Wall” for short, deals with common resolution changes so
that control clients do not need to. For AVP2000(T) endpoint devices, the required SI Wall values
automatically adjust as a function of the input source resolution.
Since the SI Wall configuration supports configuring video walls without the need to calculate the
cropping region of the source resolution, it simplifies both the software design process and
implementation of video wall applications. This allows AV integrators to implement wall grids quicker
and easier when compared to configuring a video wall manually. This option is applicable to both Wall
modes, the Fast Switch Wall mode and the Genlock Wall mode.
Why not base calculations on the source resolution? When implementing a video wall manually,
defining cropping regions is dependent on the source resolution, so each time a resolution change
occurs it is required to recalculate the wall values. Source resolution changes can occur not only when
the source itself is changed but also when a display is operating in menu mode or when a different
presentation laptop or device is connected, such as in a meeting or presentation/conference room.

7.2.1 Source Independent Video Wall Requirements

The following are required when configuring an SI Wall:
• The decoder (RX) device contains either an AVP2000 or AVP2000T chipset.
Reminder: Since an encoder (TX) device does not manage the video display mode, the source
can originate from any encoder regardless of type, such as an AVP1000 or
NT1000/NT2000 device.
• The wall is rectangular.
• The video source vertical resolution is always even.
• The video source horizontal resolution divided by two is always even.
• Video source pixels are assumed to always be square (1:1) (This is currently the case in Genlock
Scaling and Fast Switch modes).
• Monitor display pixels are always assumed to be square (1:1).
• All displays are identical, including display bezel borders and output resolution.
Reminder, a SI Wall API request is applicable to BlueRiver AVP2000/AVP2000T chipsets. It is also
backwards compatible with video walls previously configured manually. However, a wall must be
applied using either the API requests for the SI Wall or a Custom Wall but not a combination of both.
PDS-062491 Rev 2.5 Page 96 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
When configuring an SI Wall through an API request, all required arguments along with their appropriate
values are specified in a single API request. This includes the following arguments:
• aspect ratio mode
• grid width
• grid height
• grid index (horizontal and vertical)
• bezel (horizontal and vertical)
• wall name
When planning the configuration of an SI Wall, the following information is required:
• Wall Information:
o The grid size (wall grid) is measured in units of displays, such as 2x2, 3x2, 3x3, etc. This
number is always a positive integer value above zero.
o Bezel compensation to apply.
o Aspect Ratio (Keep, Stretch or Crop) to apply.
o A wall name can be configured allowing the control software to determine which
devices are part of a given wall configuration.
o With respect to SI Wall information, all displays that are part of a given wall are
configured using the specified display values, including the bezel, output resolution and
framerate.
▪ This includes the specified output resolution, whether it is a resolution or
VIC/HDMI VIC code, it is applied to all displays comprising the SI Wall.
• Display Information:
o The Grid Index defines the location (column/row) of a specific display within the wall.
o With respect to the “area of interest” of original source for each display location, as well
as the viewport to apply (if appropriate), each API request applies the appropriate
values based on a display’s Grid Index.
o Grid Index values:
▪ Are positive integer values above 0 and may go up to a maximum value equal to
the grid size dimensions.
▪ They are calculated increasing grid size within the wall display from left to right
and from top to bottom.
▪ Values are 1-based, with the column being specified first, followed by the row.
For example, a 2x2 wall display has values 1-1, 1-2, 2-1 or 2-2.
o The wall_name argument was added in API 3.5 allowing for control software to
determine which devices are part of a given wall configuration. Useful for applications
where multiple video wall configurations exist.
TIPS
i. Spaces are allowed, tailing space will be included in wall_name.
ii. To clear the wall_name it is required to send the API wall request without the
wall_name argument.
iii. For the wall processing mode, when the wall_name is being set using a TCI
command it must be the last argument specified in the API request.

PDS-062491 Rev 2.5 Page 97 of 224

1,1 2,1 3,1

1,2 2,2 3,2

1,3 2,3 3,3

Figure 35: Illustration of Grid Indexes for a 3x2 Video Wall

7.2.1.1 Calculating Bezel Compensation

Wall bezels are determined by measuring the display bezel and then calculating the display pixel density.
• For example, if the display’s bezel equals 0.2 inches and the display pixel density is 120 pixels
per inch, then the bezel thickness would be: 120*0.2 = 24 pixels
• Pixel density varies depending on the display manufacturer and model. Be sure to confirm the
correct pixel density to apply when calculating the bezel thickness.
• Measure the display borders located within the inside of the wall grid. Also, keep in mind the
thickness of a display border could vary. For example, the bottom border of a display could be
wider in relation to the top border if it has a manufacturer logo present.

PDS-062491 Rev 2.5 Page 98 of 224

Figure 36: Original 16:9 Source Example

Illustration of the KEEP aspect ratio applied to a 3x2 Video Wall grid. Advantage is that the original
source is shown in its entirety without distortion. Black pillar bars have been added.

Figure 37: SI Wall KEEP Illustration

The second example illustrates the STRETCH option where the wall content is stretched to fill the wall
without regard for maintaining the aspect ratio. The advantage is that the entire wall displays video
content, however the user experience may be impacted by the distortion that is present.

Figure 38: SI Wall STRETCH Illustration

PDS-062491 Rev 2.5 Page 99 of 224

Hidden Pixels

Figure 39: SI Wall CROP Illustration

7.2.2 Additional Info on Configuration of a Source Independent Video Wall

When decoders (RX) are operating in Genlock Wall mode with a Source Independent Video Wall
configuration applied, changes to the wall configuration or video source result in a black, glitch-less
transition on the decoder devices constituting the wall display until the entire video path is stable. That
is the decoders and displays resynchronize to the source change or configuration settings loaded.
With respect to the Fast Switch Wall mode, there are two different reactions that could be noted during
a transition, depending on the argument values impacted by the change.
1. When decoders (RX) are operating in Fast Switch Wall, changes to the following elements result
in a black, glitch-less transition on the decoder devices constituting the wall display until the
entire video path is stable:
o Video source change (timings/resolution)
o Monitor Resolution
o Monitor Framerate
Note: This is the same behavior as outlined earlier for the Genlock Wall mode with respect
to transitions. For details refer to section 7.1.1 Genlock Wall Mode.
2. When decoders (RX) are operating in Fast Switch Wall, changes to the following elements do not
result in black, instead a seamless, glitch-less transition occurs for the decoders (RX) that
constitute the wall display:
o Grid Size
o Bezel
o Grid Index
o Aspect Ratio Mode
o Wall Name
o Video Subscription
Note: For the second set of arguments, this is the same behavior as outlined earlier for the
Fast Switch Wall mode with respect to transitions.

PDS-062491 Rev 2.5 Page 100 of 224

7.2.3 Source Independent Video Wall API Request

A set video request is used to set the video display mode that a decoder device (RX) is to operate in.
Regarding the video wall mode, two modes are supported the Fast Switch Wall
(WALL_FAST_SWITCHED) and the Genlock Wall (WALL_GENLOCKED) mode. The API arguments
supported for these wall modes are the same, the difference in the API request is whether the wall
command being issued is for a manual wall configuration or a source independent wall configuration.
In this section, the source independent wall configuration is reviewed. As mentioned earlier it is
necessary to enter the required arguments for an SI Wall in a single API request.
Note: For information on implementing a custom video wall refer to section 7.3 Configuring a
Custom Video Wall.
The POST API request includes the following arguments:
POST /api/device/{RX_DEVICE_ID}
{
"op" : "set:video",
"display_mode" : WALL_FAST_SWITCHED|WALL_GENLOCKED,
"video" :{
"aspect_ratio_mode" : [KEEP|CROP|STRETCH],
"grid_width" : [COLUMNS] (integer),
"grid_height" : [ROWS] (integer),
"grid_index_horiz" : [COLUMNS] (integer),
"grid_index_vert" : [ROWS] (integer),
"bezel_horiz" : [THICKNESS_H] (integer),
"bezel_vert" : [THICKNESS_V] (integer)
“wall_name” : [“wall_name”] (string)
}
}
Note: The wall_name option supports a maximum 19 characters. All displayable characters in the
ASCII character set are allowed, meaning a to z, A to Z, 0 to 9, space, as well as symbols.

PDS-062491 Rev 2.5 Page 101 of 224

PDS-062491 Rev 2.5 Page 102 of 224

7.2.4 Frame Buffer Node in Relation to SI Wall (AUTO_WALL)

Below is an example return of the FRAME_BUFFER node type, outlining details of the wall settings
currently applied to the encoder (RX) D88039636626.
get D88039636626 settings
{
"status" : "SUCCESS",
"request_id" : null,
"result" : {
[...]
"nodes" : [
{
"type" : "FRAME_BUFFER",
"index" : 0,
"configuration" : {
"display_mode" : "WALL_FAST_SWITCHED",
"width" : 3840,
"height" : 2160,
"horiz_offset" : 0,
"vert_offset" : 0,
"frames_per_second" : 30,
"keep_width" : 700,
PDS-062491 Rev 2.5 Page 103 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
"keep_height" : 524,
"viewport_horiz" : 960,
"viewport_vert" : 0,
"viewport_width" : 2880,
"viewport_height" : 2160,
"aspect_ratio_mode" : "KEEP",
"has_auto_wall_configurations" : true,
"auto_wall_configurations" : {
"grid_width" : 2,
"grid_height" : 2,
"grid_index_horiz" : 1,
"grid_index_vert" : 2,
"bezel_horiz" : 5,
"bezel_vert" : 5
"wall_name" : “abcdefg”
}
},
[...]
}
}
}

PDS-062491 Rev 2.5 Page 104 of 224

7.3.1 Wall Mode Terms and Concepts

The following is terms and concepts referred to in Semtech documentation relating to the Wall mode.
Table 5: Wall Mode Terms and Concepts

Term/Concept Definition
Frame Rate The frequency (rate) that consecutive images, called frames, appear on a
display. Expressed in frames per second (fps).
Area of Represents the source Area of Interest (AOI) for a decoder (RX) to output.
Interest (AOI) The AOI is defined using two arguments:
Offset defining the upper left corner of the AOI (horizontal/vertical).
Size defines the width/height of the AOI.
Display Bezel This is the area of a display (frame) that surrounds the screen.
Bezel Hides a portion of the source image behind the bezel. This creates a better
Compensation viewing experience for the end user.
Viewport A defined rectangular area of a display, where source AOI is shown.
• Used when displaying a source on a wall that has a different aspect
ratio between the source aspect ratio and the wall aspect ratio.
Viewport is also defined in display pixel coordinates using two parameters:
• Viewport offset defining upper left corner of viewport
(horizontal/vertical).
• Viewport size of viewport (width/height).
Output Refers to the resolution received by a display connected to a decoder (RX).
resolution It is specified per decoder (RX).
Columns and rows In this document, the wall grid is referred to in columns and rows:
x-axis of wall is defined as columns.
y-axis of the wall is defined as rows.
• The number of columns refers to number of horizontal (x-axis)
displays that make up a given video wall.
• The number of rows refers to number of vertical displays (y-axis)
that make up a given video wall.
Wall tearing Horizontal visual artifact seen between wall rows.
Refer to Figure 40: Illustration of Wall Tearing for an example of wall
tearing and to Figure 41: "Per Row Delay" to Reduce Wall Tearing for the
solution applied by BlueRiver chipsets to reduce it.

PDS-062491 Rev 2.5 Page 105 of 224

Decoders (RX) apply “per row delay” to reduce Wall Tearing. This advanced function is usually found
only in dedicated high end video wall processors.

Figure 41: "Per Row Delay" to Reduce Wall Tearing

7.3.2 Tasks to Configure Video Wall

There are three main tasks required to create a Video Wall using the API:
1. Configure appropriate decoders (RX) into Wall mode.
a. Calculate the values to apply. Refer to section 7.3.9.3 Wall Parameter Computation.
b. The set video command is used to configure mode, wall size, fps, read offset, keep
region size, as well as if applicable to set the viewport.
c. Requires the device ID of each of the decoders included in the wall grid.
2. Start the encoder (TX) video stream that is to feed the wall.
a. The API start command is used to enable the source stream.
3. Subscribe the appropriate decoders (RX) to the encoder (TX) that is to feed the display wall.
a. The API join command is used.

PDS-062491 Rev 2.5 Page 106 of 224

Figure 42: Example of a 2x2 Wall Grid

WARNING! It is critical that the correct Area of Interest (AOI) offset value be assigned to the
appropriate decoder. If applied incorrectly, it will result in an incorrect position of an
image segment in the displayed video wall grid.

7.3.4 Wall Parameters and the API

In this section, the following assumptions are made:
1. The wall is rectangular.
2. All displays are identical and all are outputting the same resolution.
3. To preserve the aspect ratio, no display is required to be completely black (this excludes
extreme wall configurations such as 5x2 or sources that have an unusual aspect ratio).

PDS-062491 Rev 2.5 Page 107 of 224

Argument Description
device_ID The decoder ID that the specified arguments are to be applied to, including the
offset, keep and if appropriate, the viewport.
Reminder: A separate set video request is sent to each decoder (RX) of the wall,
specifying the appropriate values for the part of the grid.
display_mode Specify the display mode that the decoder is to operate in. As described earlier in
the wall mode introduction, two wall modes are supported, genlock
(WALL_GENLOCKED) and fast switch (WALL_FAST_SWITCHED). Refer to
section 7.1 Introduction to the Video Wall Mode for more information.
Note: The genlock wall mode is used in the case studies provided.
width/height Specifies the output resolution (size) of a specified decoder (RX).
Fps fps is the frame rate per second to be applied to the specified decoder (RX).
• Can be either integer (e.g. 60) or real number (e.g. 60.000).
• Optionally if it is a fractional frame rate (i.e. multiplied by 1000/1001)
follow it with letter “m” (e.g. 60m or 30.00m).
Reminder: In genlock wall mode, the frame rate specified must be equal to
source’s frame rate.
Alternately, a VIC or HDMI_VIC code can replace the size and fps arguments.
TIP: Refer to the SDVoE Developers API Reference Guide for a list of the
supported VIC and HDMI_VIC codes.

PDS-062491 Rev 2.5 Page 108 of 224

Figure 43: Illustration of set video Arguments Applied to RX4 of 2x2 Wall

PDS-062491 Rev 2.5 Page 109 of 224

Without bezel compensation

Figure 44: Example without Bezel Compensation

To resolve the discrepancy to the video caused by the display bezels while maintaining the aspect ratio
of the source, the adjustment of the bezel is applied to all “inside” borders of the video wall grid.
Bezel compensation is supported by using the set video command to adjust the size (keep) and/or
location (offset) of the area of interest (AOI) for each of the decoders (RX) involved in a given wall grid.
The adjustment applied compensates for the pixel thickness of these borders.
Reminder: The area of interest (AOI) is defined in source pixels.

With bezel compensation

Figure 45: Example with Bezel Compensation

PDS-062491 Rev 2.5 Page 110 of 224

Tip: Wall bezels are determined by measuring the display bezel, then calculating and applying the
display pixel density.
For example, if the display’s bezel equals 0.2 inches and the display pixel density is 120 pixels
per inch, then the bezel thickness would be: 120*0.2 = 24 pixels
Pixel density varies depending on the display manufacturer and model. Be sure to confirm the
correct pixel density to apply when calculating the bezel thickness.
Measure the display borders located within the inside of the wall grid. Also, keep in mind the
thickness of a display border could vary. For example, the bottom border of a display could be
wider in relation to the top border if it has a manufacturer logo present.
The figure below shows an example of bezel compensation using a 2x2 wall, with the source resolution
of 3840x2160 and applying a 20-pixel bezel compensation to both the horizontal and vertical borders.

Figure 47: 2x2 Example of Rectangular Wall Grid with Bezel Compensation Applied

PDS-062491 Rev 2.5 Page 111 of 224

Figure 48: Example with AOI Size and x/y Coordinates Applied

7.3.6 Managing Different Source and Wall Aspect Ratios

What if the source and wall aspect ratios differ?
Such as…
4:3 source and 16:9 wall
16:9 source and 16:10 wall
Number of display rows and columns are not equal. Example: 3x2 wall.
BlueRiver chipsets, which implement the AV Processing Engine manage scenarios such as these, without
the addition of expensive equipment.
There are three potential options available to deal with a scenario where the source and wall aspect
ratios are different:
• Stretch the source to fit the wall geometry.
• Crop the source horizontally or vertically to match the wall aspect ratio.
• Use the Viewport option to maintain the source aspect ratio.

Figure 49: Example of Source Different than Wall Aspect Ratio

PDS-062491 Rev 2.5 Page 112 of 224

Figure 50: Horizontal Example of Stretching Source to Fit Wall

7.3.8 Crop Source Horizontally or Vertically to Match Wall Aspect Ratio

A second option to managing a different source and wall aspect ratio, is to crop the source either
horizontally or vertically to match the wall’s aspect ratio. With this option, there is no distortion present
but part of the image is not displayed.
In the example below, the shaded area, outlined by an orange dashed line, is the only part of the source
that is displayed. The lighter teal area is hidden. This approach is useful when it is desired to fill the
entire wall, for example to show a 4:3 source on a 16:9 wall.

Figure 51: Example of Cropping the Source

In this section, details of computing the parameters needed to configure a device in wall mode when the
source picture is cropped to preserve the picture aspect ratio is reviewed.

PDS-062491 Rev 2.5 Page 113 of 224

PDS-062491 Rev 2.5 Page 114 of 224

Parameter Description
C Represents the number of columns of displays (horizontal) in the wall grid.
R Represents the number of rows of displays (vertical) in the wall grid.
W Represents each display's horizontal output resolution (aka. output width).
H Represents each display's vertical output resolution (aka. output height).
Bw Represents the width of the bezel, in equivalent pixels of the output resolution.
Bh Represents the height of the bezel, in equivalent pixels of the output resolution.
Sh Represents the horizontal scaling ratio.
Sv Represents the vertical scaling ratio.
Ws Represents the horizontal resolution of the source.
Hs Represents the vertical resolution of the source.
Fs Represents the frame rate of the source.
Wtot Represents the total width of the wall, including all displays and their bezel.
Htot Represents the total height of the wall, including all displays and their bezel.
S The scaling ratio.
i The row in which a display is located in the wall grid, with the displays in the first row
being numbered i=0
j The column in which a display is located in the wall grid, with the displays in the first
column being numbered j=0
Kw The width or a display's area of interest (AOI) in the source's coordinates system
(i.e. the horizontal keep)

PDS-062491 Rev 2.5 Page 115 of 224

Step 1: Total Wall Size

First step is calculating the total width (Wtot) and total height (Htot) of the wall grid, including all the
displays and their bezels. These are computed using the following formulas:
Wtot = C * W + (C - 1) * Bw
Htot = R * H + (R - 1) * Bh
Step 2: Horizontal and Vertical Scaling Ratios
It is required to determine if it is necessary to preserve the aspect ratio, that is whether and where the
source picture needs to be cropped. Before determining if cropping of the source is required, first need
to determine the scaling ratio, as this value is used in the next set of calculations.
The following formulas are used to compute the horizontal and vertical scaling ratios:
Sh = Wtot / Ws
Sv = Htot / Hs
Step 3: Scaling Ratio and Area of Interest
In this step, the scaling ratio and area of interest (AOI) are computed.
Calculating offset Values
To calculate the offset parameters, the following intermediate results are required to first
be computed, specifically the column width, column height and scaling ratio.
There are three cases to consider when computing the cropped width (Cw), cropped height (Ch) and
scaling ratio. The intuition behind this is that, if the horizontal and vertical scaling factors are different,
the one to use is the one that "stretches" the image the most (i.e. the largest). When the other
dimension is "stretched" by the same amount, the source image needs to be cropped accordingly for
this dimension so that it fits in the wall.
Case 1: Sh = Sv
If Sh = Sv then
S = Sh = Sv
Cw = 0
Ch = 0

PDS-062491 Rev 2.5 Page 116 of 224

PDS-062491 Rev 2.5 Page 117 of 224

Figure 52: Example of Viewport Option Applied

Each decoder has a set of arguments added to the API set video wall request to manage not only the
size, keep and offset (AOI) but also to specify the viewport. Adding the viewport argument prevents
sections of the wall from being stretched incorrectly. Instead, the AOI video is contained in the viewport
region and the areas outside of the viewport are filled with black pixels.

Figure 53: Viewport Regions Illustrated for Example 3x2 16:9 Wall Grid

The API set command syntax with the viewport arguments added:
POST /api/device/{target}
{
"op" : "set:video",
"display_mode" : "{WALL_GENLOCKED/WALL_FAST_SWITCHED}",
"video" : {
"width" : integer,
"height" : integer,
"fps" : integer,
"horiz_offset" : integer,
"vert_offset" : integer,
"keep_width" : integer,
"keep_height" : integer,

PDS-062491 Rev 2.5 Page 118 of 224

PDS-062491 Rev 2.5 Page 119 of 224

Before proceeding to investigate calculating the required argument values, it is first necessary to know
some information related to a wall grid.
Note: It is assumed some of this data is known, such as number of columns and rows as well as the
source and output resolutions.
The table provided below outlines some of the definitions referred to in the sample formulas provided.
Table 8: Definition of Parameters Used in Wall Calculations

Parameter Description
C Represents the number of columns of displays (horizontal) in the wall grid.
R Represents the number of rows of displays (vertical) in the wall grid.
W Represents each display's horizontal output resolution (aka. output width).
H Represents each display's vertical output resolution (aka. output height).
Wtot Represents the total width of the wall, including all displays and their bezel.
Htot Represents the total height of the wall, including all displays and their bezel.
Bw Represents the width of the bezel, in equivalent pixels of the output resolution.
Bh Represents the height of the bezel, in equivalent pixels of the output resolution.
Sh Represents the horizontal scaling ratio.
Sv Represents the vertical scaling ratio.
Ws Represents the horizontal resolution of the source.
Hs Represents the vertical resolution of the source.
S The scaling ratio.
WB The width, in pixels, of each of the black bars on both sides of the wall that are added
to preserve the aspect ratio, if applicable.
HB The height, in pixels, of each of the black bars on the top and bottom of the wall,
if applicable.
Vhp The horizontal position of the viewport on a specific display.
Vvp The vertical position of the viewport on a specific display.
Vw The width of the viewport on a specific display.
Vh The height of the viewport on a specific display.
Fs Represents the frame rate of the source.

PDS-062491 Rev 2.5 Page 120 of 224

Figure 55: Illustration of the Location for Viewport Parameters

Figure 56: Illustration of Addition Viewport Parameters

To gain a solid understanding of the concepts of viewports and the area of interest (AOI) using the top
row of the example 3x2 wall grid shown earlier, RX1, RX2 and RX3, we’ll look closer at the regions that
apply to a video wall. Refer to Figure 57: Individual Viewport Areas Highlighted for the Sample 3x2 Wall
. The following concepts shown for row one would apply to the second row of displays as well.
In this example, the wall aspect ratio is larger than the source aspect ratio (Aw>As), therefore black
pillars are added to the left and right displays.
Reminder: With the exception of size, each set of values to be applied to video set command is
calculated for each individual decoder (RX). The offset, keep and viewport values are
different for each display.
In the following figure, each viewport area is outlined by orange dashes, for this sample 3x2 wall grid
there is six decoders (RX) involved that require their values to be calculated.

PDS-062491 Rev 2.5 Page 121 of 224

For the first row looking at the display located in the upper left corner, the figures below show the
viewport and area of interest (AOI) for decoder 1 (RX1). The source is displayed to the right and a black
pillarbox fills the remaining pixels of the display on the left.

Figure 58: Example of Decoder 1 (RX1) Viewport and AOI

For the second (middle) display of the first row, the viewport covers the entire display.
Therefore, it is possible to either:
• Not specify the viewport arguments in the set command (recommended).
• Specify the viewport with the size equal to the display size and viewport offset set to 0.

Figure 59: Example of Decoder 2 (RX2) Viewport and AOI

For the third display (RX3) on the top row of the sample wall grid of 3x2, the source is displayed on the
left side of display with the black pillarbox filling the remaining pixels to the right. Therefore, there is no
viewport offset adjustment required.

PDS-062491 Rev 2.5 Page 122 of 224

Now that we’ve introduced the concepts involved in applying a viewport, example computations of the
wall values required for a set video request in relation to the wall mode will be reviewed.
7.3.9.3 Wall Parameter Computations
The following sub-sections review calculating each of the required five items: wall size, scaling ratios,
borders, viewport and area of interest.
Once these values are calculated, then the final step is to apply the values to the API set video wall
request arguments for each of the decoders (RX) used in the wall grid.
Note: These are sample formulas only and not necessarily the only formulas available to calculate
the values needed for the video set command arguments.
Step 1: Total Wall Size
It is first necessary to calculate the total wall size. This can be done using the formulas shown below to
compute the total wall size for the width and height respectively.
Wtot = C * W + (C - 1) * Bw
Htot = R * H + (R - 1) * Bh
Step 2: Horizontal and Vertical Scaling Ratios
Although not yet known, it is possible that the aspect ratio will need to be preserved. That is black
borders, pillars or envelope, will need to be added to the wall grid.
This is determined in the next step but in the event black borders are required, proceed to compute the
following horizontal and vertical scaling ratios:
Calculate the horizontal and vertical scaling ratios as follows:
Sh = Wtot / Ws
Sv = Htot / Hs
Reminder: Refer to Table 8: Definition of Parameters Used in Wall Calculations for description of
parameters used in these formulas.
Step 3: Scaling Ratio and Borders
To calculate if black borders are required, black pillarbox or an envelope, the scaling ratio needs to be
calculated along with the width or height of the black borders, in pixels. If calculation result equals 0,
then no border is required.

PDS-062491 Rev 2.5 Page 123 of 224

Parameter Description
i The row in which a display is located in the wall grid, with the displays in the first row
being numbered i=1.
j The column in which a display is located in the wall grid, with the displays in the first
column being numbered j=1.
Oh The horizontal position of a display area of interest origin in the source coordinates
system. That is the horizontal offset.
Ov The vertical position of a display area of interest origin in the source coordinates
system. That is the vertical offset.
Kw The width of a display area of interest in the source coordinates system. That is
the horizontal keep.
Kh The height of a display area of interest in the source coordinates system. That is the
horizontal keep.
Using the row and column index, it is necessary to compute the following:
horizontal keep (width)
vertical keep (height)
horizontal offset
vertical offset
The keep parameters are calculated as follows:
Kw = Vw / S
Kh = Vh / S
When calculating the keep, the appropriate viewport value (Vw or Vh) must be inserted based on the
special case column, row or default that applies. Refer to the Step 4: Viewport.

PDS-062491 Rev 2.5 Page 125 of 224

PDS-062491 Rev 2.5 Page 126 of 224

PDS-062491 Rev 2.5 Page 127 of 224

PDS-062491 Rev 2.5 Page 128 of 224

PDS-062491 Rev 2.5 Page 129 of 224

PDS-062491 Rev 2.5 Page 130 of 224

PDS-062491 Rev 2.5 Page 131 of 224

PDS-062491 Rev 2.5 Page 132 of 224

PDS-062491 Rev 2.5 Page 134 of 224

PDS-062491 Rev 2.5 Page 135 of 224

PDS-062491 Rev 2.5 Page 136 of 224

PDS-062491 Rev 2.5 Page 137 of 224

PDS-062491 Rev 2.5 Page 139 of 224

PDS-062491 Rev 2.5 Page 140 of 224

Summary of Wall Mode

To summarize Wall mode functionality, it is the ability to display a single source across multiple displays,
each showing an assigned section of the source defined with an Area of Interest (AOI) and when
appropriate, fill part of a display with black bars.
Two wall modes are supported, the genlock wall and fast switch wall modes.
1. When Genlock Wall mode is implemented, the decoders (RX) are synchronized to the source,
therefore to each other.
2. Fast Switch Wall mode is an alternative when fast switching so a clean switch between sources
is needed or when signals need to cross multiple network switches. Keep in mind this may
result in individual screens that are not in sync with each other.
Bezel compensation equaling the inside borders of the displays should be applied to calculations to
provide a more realistic viewing experience for end users.
If the Wall aspect ratio is different when compared to the source aspect ratio, black bars referred to as
“viewports” are available to show the entire source without geometric distortion.
A wall configuration can be applied using a Source Independent Wall API request that automatically
builds the wall configuration for a AVP2000(T) decoder (RX) device. Refer to section 7.2 Implementing a
Source Independent Video Wall for details. Alternately a video wall can be custom configured, refer to
section 7.3 Configuring a Custom Video Wall for details.
Tips for when entering values into a set video request:
i. The video mode of a decoder (RX) is set to WALL_GENLOCKED or WALL_FAST_SWITCHED.
Reminder: The set video arguments use for wall mode are not applicable to other
processing modes.
ii. Be sure the appropriate values are applied to the set video request in relation to the position of
the decoder (RX) outputting to a display mounted in the wall grid.
a. For instance, if the wrong values are applied in relation to the position of a display, the
video output would be located in an incorrect position on the video wall.
b. If the bezel compensation is not accurate, the viewing experience would be unrealistic
in that the video would not align cleanly between the displays.
iii. In regards to the output frame rate, when operating in Genlock Wall mode the frame rate (fps)
must be equal to the source frame rate.
TIP: If a different output frame rate is needed, the Fast Switch wall mode can be applied.

PDS-062491 Rev 2.5 Page 142 of 224

Creating a Wall with Multiple Sources

If it is desired to create a wall that is to display multiple sources, such as the example shown below, this
is possible using SDVoE technology. There are two approaches available to complete this scenario, with
both approaches outlined in this section, including advantages and disadvantages.
This section will use the following 2x2 wall grid as an example.

Display 1 Display 2

Source 1

Source 2

Display 3 Display 4

Figure 62: Example of 2x2 Wall Grid and Two Source Layout

The Multiview and Wall mode sections of this application note library supply details on the use of these
respective processing modes. An understanding of these sections is a prerequisite to applying either of
the scenarios outlined below.

PDS-062491 Rev 2.5 Page 143 of 224

Encoder (TX) Display 1 Display 2

Source 1 Decoder (RX)
10G Network switch

10G Network switch

Multiview
Source
layout
1
RX1 RX2

Display 3 Display 4

Encoder (TX) Encoder (TX))

Source 2 Wall source
RX3 RX4

Figure 63: Scenario 1 Multiview Layout as Wall Source

The figure above illustrates our example, where the decoder (RX) labeled in the above figure as
“Multiview layout” subscribes to the two sources assigned in the multiview layout. Based on the API
multiview layout requests issued, it creates the output multiview composite.
This decoder’s output is then fed to the encoder labeled as “Wall source”.
The four decoders that are involved directly in the wall grid then subscribe to this stream. API requests
are then applied to each of the decoders (RX) specifying the area of interest (AOI) that each is to display.

7.5.2 Scenario 2: Multiview Offset Argument Modified

The second option would utilize the multiview mode and apply a unique layout to each individual
decoder (RX). Each decoder that is part of the wall grid will operate in multiview mode and each will
load a layout displaying the source(s) with the offset location (area of interest) specified.
When creating and managing the layouts, an offset (location) is calculated and applied to the “layout
window” for each decoder (RX). The offset values applied are unique for each decoder.

PDS-062491 Rev 2.5 Page 144 of 224

Encoder (TX) Display 1 Display 2

Source 1 Multiview layout 1 Multiview layout 2
10G Network switch

Source 1

RX1 RX2

Display 3 Display 4

Multiview layout 3 Multiview layout 4

Encoder (TX)
Source 2
RX3 RX4

Figure 64: Scenario 2 Multiview Layouts Applied

The setup above illustrates that the two HDMI sources required for our example are fed to two encoder
devices (TX). As mentioned previously, the decoder devices (RX) must be operating in multiview mode
and be joined/subscribed to the appropriate sources.
Each decoder is sent a multiview API request containing details on the layout it is to display, including
the size, offset and position information appropriate for the layout. The source will then be cropped to
the values specified, resulting in the wall grid being output as shown in Figure 62: Example of 2x2 Wall
Grid and Two Source Layout.

PDS-062491 Rev 2.5 Page 145 of 224

PDS-062491 Rev 2.5 Page 146 of 224

Device Mode Property

In the case of either an AVP endpoint device, it is possible to modify the active device mode of an
endpoint device that has been deployed in the field, allowing a device to behave specifically as a
transmitter (TX) or receiver (RX). It is required however, that the endpoint device have both an HDMI
Input connector and an HDMI Output connector. It is also required that the hardware manufacturer
enabled this ability for the device, this can be confirmed by retrieving the device capabilities using a get
device request. Refer to the Developers API Reference Guide for details on get requests.
The device mode is managed using a set property request along with the property key
“configuration.device_mode”. The value entered is TRANSMITTER, RECEIVER or
TRANSCEIVER. The target is the device ID of endpoint whose mode is to be changed.
Syntax for a set property request to set the device mode:
POST /api/device/{target}
{
"op" : "set:property",
"key" : “configuration.device_mode”,
"value" : “TRANSMITTER/RECEIVER/TRANSCEIVER”
}
Table 10: Valid Device Mode Changes

Chipset Hardware** TRANSMITTER RECEIVER TRANSCEIVER

AVP2000T Video In/Out Transmitter Receiver Transceiver
Video In Transmitter Invalid, no change Invalid, no change
Video Out Invalid, no change Receiver Invalid, no change
AVP2000/AVP1000 Video In/Out Transmitter Receiver Invalid, no change
Video In Transmitter Invalid, no change Invalid, no change
Video Out Invalid, no change Receiver Invalid, no change
** Important to note that hardware refers to the HDMI connectors present on the BlueRiver AVP
endpoint device, possible that hardware will have only a Video In or Video Out for transmitter and
receiver devices, respectively.

PDS-062491 Rev 2.5 Page 147 of 224

Managing a Device Name

The default Device Name is the device id (MAC address) of the endpoint device, it is often useful to
modify this to something more meaningful to the end users. This is done using a set property
request with the property key, configuration.device_name.
Starting in API version 3.5 the device name may be used when issuing an API request in place of the
device ID (MAC address). Also, worth noting that since BlueRiver AVP firmware 1.5, the device name is
also persistent following a factory reset, that is it does not revert back to the device’s MAC address as in
previous firmware versions but keeps the updated device name.
Syntax for a set property request to set the device mode:
POST /api/device/{target}
{
"op" : "set:property",
"key" : “configuration.device_name”,
"value" : “specify device name”
}
Note: When using the device name to issue an API request, it is case sensitive.
Warning! When issuing an API request that has a device name containing a special reserved
character or unsupported character in the URL of the request, the application must
encode the character(s) with a % escape sequence. For example a space is encoded as
%20. To illustrate the URL of an API request that includes a space in the device name,
Peter Pan, would be encoded as follows:
http://localhost:8080/api/device/Peter%20Pan/
Note: This article assumes that the reader is familiar with the issuing commands using
encoded characters. The table below provides a list of commonly used reserved
characters for reference purposes.

PDS-062491 Rev 2.5 Page 148 of 224

Symbol Escape Sequence Description

%20 Space
! %21 Exclamation Mark
# %23 Pound Sign
$ %24 Dollar Sign
% %25 Percent
& %26 And Sign
' %27 Single Quote
( %28 Left Parenthesis
) %29 Right Parenthesis
* %2A Star
+ %2B Plus Sign
, %2C Comma
/ %2F Forward Slash
: --- Not supported, see note below(1).
; %3B Semi Colon
= %3D Equal Sign
? %3F Question Mark
@ %40 At Sign
[ ] %5D Square Bracket
(1)
Colon character (:) is not supported as part of the "Device Name" as a colon is often used to
separate individual parts of an API request command. For example when managing the frame
rate divider of the native stream (stream 1) a colon (:) is used in property key.
streams[stream_type:0].configuration.source.value
Looking at the earlier example device name, Peter:Pan would not be allowed. When an
unsupported character is detected, the set name command will fail with an
ILLEGAL_ARGUMENT error containing the message: Device name contains
unsupported character.
API Warning Logged
If there are multiple MAC addresses mapped to the same Device Name, the API logs a warning. For
example, if Peter Pan was assigned to two devices with the MAC addresses of d8803962e132 and
d88039e7a4ee, the API would log the warning:
WARNING: Device name 'Peter Pan' is mapped to multiple mac
addresses: d8803962e132 d88039e7a4ee
Generally a "Device Name" is mapped to a single device, that is to a single device ID (MAC address).
If more than one is mapped, the first one registered is used by default.
For the illustrated example shown above where two endpoint devices have mac addresses (1)
d8803962e132 and (2) d88039e7a4ee, respectively. If both are named "Peter Pan", when an
API request is sent to "Peter Pan", it will be sent only to mac address (1) d8803962e132.

PDS-062491 Rev 2.5 Page 149 of 224

Managing Frame Rate Divider

Applying a frame rate divider to either the native stream (stream 0) and/or scaled stream
(stream 1) is a useful tool when managing bandwidth. A set property request is used to apply
the frame rate converter to either or both HDMI input streams of an encoder (TX) device. Each input
stream is managed independently and have different property nodes and keys. The figure below
illustrates the paths for each the native and scaled streams of an encoder.
Reminder: The frame rate divider is available to devices that support the AV processing engine,
specifically devices based on the AVP2000, AVP2000T and NT2000 chipset series.

Figure 65: Block Diagram of an Encoder (TX) Illustrating Frame Division

PDS-062491 Rev 2.5 Page 150 of 224

{
"status" : "PROCESSING",
"request_id" : 9,
"result" : null,
"error" : null
}
A SETTINGS_CHANGED event is received from the API to indicate that the first device's settings have
been modified. Also, a REQUEST_COMPLETED event is generated once the request is complete. If
other API clients are connected to the API server, monitoring SETTINGS_CHANGED events allows
clients to stay up to date with device settings.
{
"status": "SUCCESS",
"request_id": null,
"result": {
"events": [
{
"device_id": "801f124389e7",
"event_id": 1,
"event_type": "DEVICE_CONNECTED",
"timestamp": 1610735915,
"request_id": 1
},
{
"device_id": "801f124389e7",
"event_id": 2,
"event_type": "DEVICE_INFO_AVAILABLE",
"timestamp": 1610735915,
"request_id": 2
},
{
PDS-062491 Rev 2.5 Page 151 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
"device_id": "801f124307b7",
"event_id": 3,
"event_type": "DEVICE_CONNECTED",
"timestamp": 1610735916,
"request_id": 3
},
{
"device_id": "801f124307b7",
"event_id": 4,
"event_type": "DEVICE_INFO_AVAILABLE",
"timestamp": 1610735916,
"request_id": 4
},
{
"device_id": "801f124307b7",
"event_id": 7,
"event_type": "SETTINGS_CHANGED",
"timestamp": 1610736876,
"request_id": 8
},
{
"device_id": null,
"event_id": 9,
"event_type": "REQUEST_COMPLETE",
"timestamp": 1610737063,
"request_id": 9
}
]
},
"error": null
}
TIP: If a device does not support frame rate conversion, there is an entry in the error array of the
result with a reason of DEVICE_TYPE, indicating that the request failed for the device because
it does not support this feature. For example, the device does not include a chipset such as an
AVP2000T or NT2000 supporting the feature or the device ID entered was a decoder.

8.3.2 Disabling Frame Rate Divider on the Native Video Stream

Frame rate conversion is also disabled using the set property command. For our earlier example,
using the device ID of 801f124307b7, the command issued is similar but the value entered is now “0”
to disable/turn off the frame rate divider.
POST /api/device/801f124307b7
{
"op" : "set:property",
"key" : “streams[HDMI:0].configuration.source.value”,
"value" : 0
}

PDS-062491 Rev 2.5 Page 152 of 224

PDS-062491 Rev 2.5 Page 153 of 224

PDS-062491 Rev 2.5 Page 154 of 224

Compression of HDMI:0 Always On

When lowering the bandwidth usage is of concern, it is possible to compress the native stream
(stream 0) of an encoder(s), even if the bandwidth of the stream does not surpass 10Gbps. A set
property request is used to enable compression.
The API request is as follows:
POST /api/device/{target}
{
"op" : "set:property",
"key" : "
nodes[VIDEO_COMPRESSOR:index].configuration.always_compress",
"value" : true|false
}
The target argument is the device ID of a single encoder (TX) device or the all transmitters
device group. The supported device groups are:
ALL All devices
ALL_TX All transmitter devices
The key for this property is
“nodes[VIDEO_COMPRESSOR:index].configuration.always_compress”, where the
index is always 0 as this property is applicable to the native stream only (stream 0). The value is either
true or false, where true enables the feature and false disables it.
Example of sending a request to enable HDMI compression for the encoder (TX) 801f124307b7:
POST /api/device/801f124307b7
{
"op" : "set:property",
"key" : "
nodes[VIDEO_COMPRESSOR:index].configuration.always_compress
",
"value" : true
}
For more information on the video compressor node, refer to the SDVoE Developers API Reference
Guide, specifically the set property and Video Compressor Node Configuration sections.

PDS-062491 Rev 2.5 Page 155 of 224

Removing Audio from HDMI Video Stream

By default, the original HDMI audio is carried within the native HDMI video stream (stream 0) coming
from an encoder (TX) as auxiliary data. However, only a decoder (RX) running in Genlock mode can
make use of this auxiliary data. When a decoder is operating in any other video display mode, the HDMI
source audio is received twice. Once as the auxiliary audio embedded in the HDMI video stream (stream
0) and again when a decoder (RX) is subscribed/joined separately to the HDMI audio stream.
The benefit of enabling this option is removing the auxiliary audio data from the HDMI video stream
saves bandwidth usage. Estimated bandwidth savings is ~200 Mbps in the case of eight LPCM channels
at 192 kHz. Saving such bandwidth can be crucial for certain use cases, such as multiview layouts using
the native source video, USB or 1GbE heavy applications, even for AV distribution applications living on
either a 2.5 Gbps or 5 Gbps network (NBASE-T) infrastructure.
However should be noted that when this property is applied decoders (RX) operating in any video mode,
including Genlock, need to subscribe/join to the HDMI audio stream for playout as the source audio.
The API request for this set property option is as follows:
POST /api/device/{target}
{
"op" : "set:property",
"key" : "streams[HDMI:index].configuration.remove_audio",
"value" : true|false
}

PDS-062491 Rev 2.5 Page 156 of 224

Black Video Generator

For applications where the decoder (RX) is to drive audio only at the HDMI output, it is possible to tie the
audio to a black video output. When an endpoint device includes the AV Processor Engine, such as an
NT2000 or AVP2000(T), this can be done by setting the output display mode to fast switch mode and
subscribing the decoder to the appropriate audio source.

However, if the endpoint device includes an NT1000 or AVP1000 chipset, it does not include the
AV Processor Engine and so a black output stream is generated by enabling the Black Video
Generator property. This feature allows a dummy black video signal to be generated, it enables the
selected audio stream to be embedded into a dummy stream for HDMI playout. For example, audio
player functionality or for transitions/temporary audio transitions.
The black generator supports two modes:
• Maintain Output
• Force Output
When set property key nodes[COLOR_GENERATOR:0].configuration.force_output
is specified with the value set as true, then a blank video output with a uniform color and a fixed
resolution video signal of 720P60 is output.
The API request to enable the forced output is as follows:
POST /api/device/{target}
{
"op" : "set:property",
"key" :
"nodes[COLOR_GENERATOR:0].configuration.force_output",
"value" : true
}
When the black generator is disabled, set to false, value equal to false, the device returns to the
default video display mode, Genlock.
Reminder: This feature supported only for devices that do not support the AV Processor Engine, such
as AVP1000 based devices.

PDS-062491 Rev 2.5 Page 157 of 224

HDCP Encryption
On decoder (RX) devices operating in fast switch or multiview mode changing from one HDCP encryption
level to another, causes either a glitch in the sink or a short black period during the authentication of the
HDCP keys.
To limit such glitches and black periods, it is best to authenticate at the highest HDCP level supported by
the sink. For example, if the sink supports HDCP 2.2 and the authentication with the sink is done with
HDCP 2.2 then switching between NO HDCP and/or HDCP 1.4 sources to a source with HDCP 2.2 does
not cause a glitch. If the sink only supports HDCP 1.4, it is still best to output HDCP 1.4 when possible to
prevent glitches when switching from a source with NO HDCP to a source with HDCP 1.4. Note that in
such a case, sources with HDCP 2.2 will fail the authentication with the sink and black is displayed
on the sink.
The HDCP output modes outlined in this section are only applicable to decoders (RX) operating in one of
the following video processing modes:
Fast Switch
Multiview
Fast Switch Wall
There are three (3) HDCP output modes supported:
• Follow Sink 1
If the monitor supports HDCP 2.2, this mode tries to negotiate HDCP 2.2. If HDCP 2.2
authentication fails, it automatically tries HDCP 1.4 or NO HDCP based on the sink capabilities.
This mode is the default HDCP encryption mode of operation and covers most use cases.
• Follow Sink 2
This mode is similar to the “Follow Sink 1” outlined above but limits the HDCP level requirement
to HDCP 1.4 when possible.
It is applicable in special cases when there is equipment located between the decoder and an
output display, such as an AVR that does not expose the HDCP capability of the display. For
example, the AVR is HDCP 2.2 capable but is connected to a display capable only of HDCP 1.4.
• Follow Source
In this mode, the output encryption follows the HDCP mode of the source.
In all HDCP output modes, the HDCP encryption level at the output cannot be lower than the HDCP
encryption level of the source (which in multiview is the highest HDCP encryption level out of all current
subscriptions). If it surpasses the maximum capability of the sink, the video output is black.

PDS-062491 Rev 2.5 Page 158 of 224

BlueRiver Receiver (HDMI TX 5V) API Control

8.8.1 Overview of HDMI TX 5V Control
The SDVoE API supports controlling the configuration of the HDMI TX 5V output mode of the
HDMI_ENCODER node.
Reminder, the HDMI transceiver IC acts as a transmitter on a BlueRiver decoder (RX) endpoint device;
therefore, this command is applicable only to BlueRiver decoder (RX) and transceiver (TR) devices but to
BlueRiver encoder (TX) devices.
The status of the hdmi_tx_5v is provided in the HDMI_ENCODER configuration node:
"type": "HDMI_ENCODER",
"index": 0,
"configuration": {
"hdcp_output_mode": "FOLLOW_SINK_1",
"hdmi_tx_5v": <API control value>
},
The hdmi_tx_5v parameter will be either AUTO or LOW.

PDS-062491 Rev 2.5 Page 159 of 224

8.8.2 HDMI TX 5V Mirroring

HDMI TX 5V mirroring applies only when the HDMI_TX_5V property is set to AUTO.
When the decoder (RX) is operating in a video processing mode (Fast Switch, Fast Switch Wall or
Multiview), the HDMI TX 5V output is always high. This is regardless of the network link state or
10GbE connection type (switch or point-to-point).
When the decoder (RX) is not operating in a video processing mode, so is operating in Genlock, Genlock
Wall or Genlock Scaling:
• When operating in loopback mode (applicable to transceiver (TR) devices only), the HDMI TX 5V
output follows the input 5V state from HDMI RX side (i.e. video source HDMI 5V output value).
• When not in loopback:
o If the 10GbE interface is down, the HDMI TX 5V output is set low (same as if the HDMI
cable was disconnected).
o If connected to a switch, when the 10GbE interface link goes up, the HDMI TX 5V output
is set high.
o If connected in point-to-point, the HDMI TX 5V output follows the point-to-point remote
HDMI RX 5V state (i.e. remote video source HDMI 5V output value). However, if the
remote P2P device does not support this feature (i.e. older firmware version), the HDMI
TX 5V output value is set to high for legacy compatibility.

PDS-062491 Rev 2.5 Page 160 of 224

PDS-062491 Rev 2.5 Page 161 of 224

PDS-062491 Rev 2.5 Page 162 of 224

Figure 67: Available Audio Routing for AVP2000T

As mentioned, when managing audio routing one needs to consider the device type that is to be
managed as well as the audio type to be routed. The table below summarizes the supported audio
routing for AVP devices referencing the audio indexes for encoders (TX), decoders (RX) and transceiver
(TR).
Table 12: Summary of Audio Output Routing

Summary of Audio Output

Device Type Transmitter (TX) Receiver (RX) Transceiver (TR)
Multi- Multi- Multi-
Stereo Stereo HDMI Stereo HDMI
channel channel channel
Net HDMI aux 2 2
Net HDMI 14 7 7 7 7
Net HDMI Downmix 15 15 2 6 6 2 6 6
Net Stereo 13 13 3 3 3 3 3 3
Net Multichannel 8 8 8 8 8 8 8 8
Local HDMI 7 11
Local HDMI Downmix 2 6 12 12
Local Stereo 3 10 10
Local Multichannel 9 9 9 9 9

PDS-062491 Rev 2.5 Page 163 of 224

9.1.1 Routing Audio to Output with the HDMI Video

To output audio with the HDMI video, a join request is used to subscribe the decoder (RX) device to
the desired HDMI audio source. The audio source could be an encoder (TX) or transceiver (TR) device.
Note: In regards to HDMI Video, refer to the SDVoE Developers API Reference Guide for details of
subscribing video streams, either the native stream (HDMI:0) or scaled stream (HDMI:1) as
they are not covered in this article as it is devoted to audio routing only.
The target argument can be the device ID of a single decoder (RX) device or a device group. The
supported device groups for a join request are:
ALL All devices
ALL_RX All decoder devices.
The source_device argument is the device ID of a single device. As mentioned above, this can be an
encoder (TX) or transceiver (TR) device, applicable to all audio stream types (HDMI audio, Stereo audio
and Multichannel audio) or a decoder (RX) device for Stereo and Multichannel stream sources only.
Therefore based on the device type, the stream_type argument can be one of the following:
STEREO_AUDIO Stereo audio stream
HDMI_AUDIO HDMI audio stream
MULTICH_AUDIO Multichannel audio stream
The stream_index argument must the valid index of a stream of the specified type available on the
source device.
TIP: For the command to succeed, the source stream must currently be started/running. Refer to
the SDVoE Developers API Reference Guide, section “Command start”, for details on starting
device streams.
The subscription_index argument must be a valid index of a subscription of specified type on the
destination device.
9.1.1.1 HDMI Audio Routing Use Case
In the use case example shown below, the decoder (RX) device 0016c04e05fd is being subscribed to
the HDMI audio stream (HDMI_AUDIO) of the encoder (TX) device 0016c04e1c0c.
Note: The subscription index for HDMI audio is 0.

PDS-062491 Rev 2.5 Page 164 of 224

9.1.2 Routing Audio to the Stereo Output

If it is desired to route audio out the Stereo Audio Output port of a decoder (RX) device, it is necessary
to potentially complete three steps:
1. Set direction through a set property request to output.
TIP: If the OUTPUT node is not listed in the return of get device request under capabilities, it
is likely because the STEREO direction is currently set to INPUT.
If you have questions about the device itself, contact the hardware manufacturer for
details on the interfaces available in their design, such as if a stereo interface is present.
2. Specify the audio type to be output the Stereo audio port using a set property command.
Options for the audio output subscription include:
2 -- HDMI audio (stereo downmix)
3 -- Stereo audio
8 – Multichannel audio
3. Next subscribe to the STEREO_AUDIO source stream using a join request.
Refer to the SDVoE Developers API Reference Guide, section Stereo Audio Input/Output
Node Configuration for details on supported audio input options. Specifically, refer to the table
“Outputs Supported for the Audio Output Node”.
9.1.2.1 Stereo Audio Output Use Case
Based on the three steps outlined above, a use case will be illustrated to configure the Stereo audio
output. This use case uses the Device ID 0016c04e1c0c for the encoder (TX) source device and
0016c04e05fd for the decoder (RX) device.
Also, it is assumed that the STEREO port is currently set as an INPUT, therefore it is required to first
set it as an OUTPUT. Then specify the audio type to be output from the decoder (RX), for this use case
the HDMI audio (stereo downmix) is being used, so the value is 2. Finally to output the audio
it is necessary to subscribe (join) the receiver to the audio source.
Reminder: Although the presence of hardware interfaces is managed by the hardware
manufacturer through factory settings, the direction of the Stereo audio port can be
modified using an API set property request and the property key:
nodes[STEREO_AUDIO_INPUT_OUTPUT:index].configuration.direction
The value for the direction is specified as either INPUT to set the stereo audio port as
an input or OUTPUT to set it as an output.

PDS-062491 Rev 2.5 Page 165 of 224

PDS-062491 Rev 2.5 Page 166 of 224

PDS-062491 Rev 2.5 Page 167 of 224

Terms Definition
bound-authenticated When a device is "bound-authenticated", it communicates with a
specific API server, securing communication between the API server
and the device.
friend API servers A pair of API servers configured with the same secure API key. When
one API server is bound-authenticated to an endpoint device(s), the
other API server is also authenticated to the same endpoint device(s).
Auth An API request that enables an endpoint device(s) to be bound-
authenticated to the API server that the request initiated from.
unauth Disables a device from being bound-authenticated to the API server.
Claim Useful to implement when it is desired to segment devices within a
given network, such as group resources for a classroom or operating
room. Also, prevents an adversary from using an unauthorized API
server instance — for example running on a laptop connected to a
network port in an installation—to control devices. When a device is
claimed, it is controlled exclusively by the API server instance from
which the request was issued.
release Used to release an endpoint device to an unclaimed state.

Overview of Secure Control Communication

Secure communication allows two entities to communicate without a third-party listening in, allowing
information to be shared in a way that is unsusceptible to eavesdropping or interception. The API
provides the ability to pass data securely through authentication and/or encryption as it passes between
registered endpoint devices.
Securing communication between the API server and endpoints is accomplished using an auth request,
which initiates a security protocol involving standard algorithms and best practices, such as ECDH,
AES128-CTR, POLY1305-AES, SHA256 and anti-replay attack counters.

PDS-062491 Rev 2.5 Page 169 of 224

Key Exchanges
The bound-authentication process dynamically exchanges a security key between the API server and its
authenticated endpoints. When bound authentication is enabled by an API auth request, the security
key is saved on endpoint devices in nonvolatile memory. If the option is disabled using an API unauth
request or a factory reset is applied to an endpoint device, authentication needs to be re-enabled.

PDS-062491 Rev 2.5 Page 170 of 224

The figure below shows the relationship of an endpoint device that has been bound-authenticated and
when a device has had an API unauth or factory request applied.

Figure 69: Endpoint Device Authentication

API Server Configuration

To allow an API server to bound-authenticate devices, a unique key is added to the API server
configuration file. This key is added to the configuration file to ensure that, should the API server be
restarted, it applies the same identifier after the restart as was set previously.
Server key (secure_comm_secret) best practices:
1. This configuration option can be set to any alphanumeric string (0-9, the letters A-Z, uppercase
and lowercase, no special character, no space) but must be unpredictable.
2. A randomly generated string of 24 to 64 alphanumeric ASCII characters and symbols is a
good choice.
3. Maximum of 64-characters can be used, if the string entered is longer than 64-characters it is
internally truncated to 64 characters.

PDS-062491 Rev 2.5 Page 171 of 224

auth / unauth API Requests

An API request is used to enable and disable bound authentication between the API server and an AVP
endpoint device, where auth is used to enable the feature and unauth to remove the authentication.
Note: The API auth command is not applicable to NT1000/NT2000 devices; however, the claim
command can be implemented on all SDVoE endpoint devices regardless of the chipset.
When an auth or unauth request is successful, the endpoint device(s) triggers a
DEVICE_DISCONNECTED event followed by a DEVICE_CONNECTED event as the device
communication is reset. For details on event types and tracking notifications, refer to the Developers
Introduction to the SDVoE API User Guide. An auth request also only succeeds if the device is not
currently bound to another API server instance.
The command syntax for auth (enabling of bound authentication) is as follows:
POST /api/device/{target}
{
"op" : "auth"
}
The target argument must be either the device ID of a single device or the name of a device group.
The supported device groups are:
ALL All devices
ALL_TX All transmitter devices
ALL_RX All receiver devices
For details on the auth/unauth API requests, refer to the SDVoE Developers API Reference Guide and
for details related to the security key refer to the SDVoE Control Server Administrators Guide.
Example of enabling bound authentication for a single device with the target ID of 001ec0f03668.
POST /api/device/001ec0f03668
{
"op" : "auth"
}

PDS-062491 Rev 2.5 Page 172 of 224

10.5.1 API Configuration Node

If authentication has been enabled, the API device configuration return member “authenticated”
indicates TRUE. If the member displays FALSE, the device has not had this option enabled. Example
shows device settings return for a configuration node with authenticated member reporting true:
"configuration": {
"device_name": "0016C04C3D9F",
"locate_mode": false,
"secure_av": "default",
"resume_streaming": true,
"claimed": true,
"authenticated": true,
"device_mode": "TRANSCEIVER"
…
For information on the device mode and associated members, refer to the Developers Introduction to
the SDVoE API User Guide and for details on retrieving device information refer to the SDVoE
Developers API Reference Guide “Command get” section.
PDS-062491 Rev 2.5 Page 173 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
Authentication Use Cases
This section reviews use cases where authentication could be useful if implemented. Two use cases are
reviewed: the first is a backup API deployment example and the second is resource segmentation. Prior
to proceeding with review of use cases, a high-level look at normal communication is reviewed.

10.6.1 Single API Server Deployment

Normal communication between a client, single API server and endpoint devices is demonstrated in the
figure below. When an API request is issued, it is sent to the API server instance specified in the request.
The API forwards the request to the appropriate endpoint device(s), who proceeds to complete it.
A single API server instance can manage all transceiver (TR), encoder (TX) and decoder (RX) devices on a
given subnet.
Warning! Only one API server instance should control an endpoint device at a given time, multiple
API instances are not aware of each other. Therefore, using multiple instances to control
signal routing can result in routing and multicast address conflicts, although this scenario
can be avoided by implementing the claim feature. Refer to section 10.6.3 Segmented
Deployment with Shared Authentication for an example use case.
Multiple client instances can connect and simultaneously communicate with an API server. An API
server uses a FIFO to manage requests from multiple client sessions.
When an endpoint device completes a request, it issues a message notifying the API server. Under
normal conditions all API server instances currently running on the network segment will receive the
message notification. Each of the API servers will then take appropriate action, generating an event and
asynchronous message notification, which is then forwarded to online client applications potentially
generating unnecessary network traffic.
When bound authentication is enabled, the endpoint sends the message result to the API server to
which it is bound, allowing data transfer to this single API instance not only applying the encryption
between the API server and the endpoint, but also limiting the generation of event notifications.
Reminder: Details on event types, polling and event notifications are provided in the Developers
Introduction to the SDVoE API User Guide.

PDS-062491 Rev 2.5 Page 174 of 224

Endpoint RX

Endpoint RX
Clients

10GbE Network

Endpoint TX

Endpoint TX API Server

Figure 70: Network Setup with Single API Server Instance

10.6.2 Primary-Backup API Server Deployment

Some SDVoE systems include a primary API server instance running with a backup API available. As
mentioned previously, it is possible for both API servers to be configured with the same security key. In
the event the primary server is unavailable and the backup becomes the active API, the shared security
data allows the backup API server to exchange messages with the same pool of authenticated endpoint
devices as the original primary API server, without additional authentication API requests.
In the case of a primary-backup scenario, the primary API server manages the polling of endpoint
devices, managing command requests and monitoring for event notifications while the Friend API server
is a dormant backup API server. Should the primary server become unreachable, since the two servers
are using the same secure key data, the backup can take over control the endpoint devices originally
handled by the primary server.

PDS-062491 Rev 2.5 Page 175 of 224

Endpoint RX

Endpoint RX
Clients

10GbE Network

Endpoint TX

X
Endpoint TX

Primary API
Endpoint TX Server
Backup API
Server

Figure 71: Use Case: Backup API Server

10.6.3 Segmented Deployment with Shared Authentication

In a large installation as well as some specific use cases, such as conference rooms, operating rooms and
lecture halls, it is often desired to group resources. For API servers and endpoint devices, they can be
grouped by sharing the same security authorization key and implementing the API claim feature. This
allows end users to segment API servers and devices into groups, often referred to as “pools”. Sharing a
bound-authentication security key among all segments allows for moving and sharing of endpoint
devices to be more easily managed, while registering devices to a specific API server allows for them to
be controlled by the specified API instance.
Implementing bound authentication would be done using an API auth request, refer to section 10.5
auth / unauth API Requests for example. Below the use of the claim API request is reviewed.
Note: For details on auth/unauth or claim/release API requests, refer to the Developers API
Reference Guide and the Control Server Administrators Guide.
Reminder: When a device is claimed, it is controlled exclusively by the API server instance from which
the command was issued.
• The claim command only succeeds if the device(s) is/are currently unclaimed or already
claimed by the API server issuing the command.
• The release command returns the device(s) to unclaimed state. It only succeeds if the
device(s) is/are claimed by the current API server or already unclaimed.

PDS-062491 Rev 2.5 Page 176 of 224

POST /api/device/{target}
{
"op" : "release"
}
The target argument must be either the device ID of a single device or the name of a device group.
The supported device groups are:
ALL All devices
ALL_TX All transmitter devices
ALL_RX All receiver devices

Endpoint RX

Endpoint TX

Endpoint TX
10GbE Network

Endpoint TX CLAIMED SEGMENT B API Sever B

Endpoint TX

Endpoint RX

API Sever A
CLAIMED SEGMENT A

Figure 72: Example of API Server/Endpoint Device Segmentation using API Claim Feature

PDS-062491 Rev 2.5 Page 177 of 224

PDS-062491 Rev 2.5 Page 178 of 224

# IP address range to use for multicast channel allocations

multicast_range_start = 224.1.1.1
multicast_range_end = 224.1.3.255
3. Save the controlserver.conf file.
4. Stop and relaunch the API server to apply the changes.

PDS-062491 Rev 2.5 Page 179 of 224

PDS-062491 Rev 2.5 Page 180 of 224

Tasks to Activate USB HID Encryption

To activate USB HID Encryption, there are multiple tasks that need to be completed:
1. Set secure_comm_secret in the API server configuration file. Refer to section 10.4 API
Server Configuration for example of configuring this key.
2. Set the usb_hid_encryption_default_key in the API server configuration file.
3. Restart or if not currently running start the API server instance for whom the above security
data was modified.
4. Enable secured communication between the API server and the AVP endpoint device(s) using an
auth request. Refer to section 10.5 auth / unauth API Requests for details completing this
task, as well as the SDVoE Developers API Reference Guide.
5. Set the USB HID security level for the appropriate AVP devices using a set usb security
level API request.
6. Set the USB-HID security key using a set security_key API request for each of the
appropriate endpoint devices.
Note: For this feature to successfully be enabled, the feature must be enabled by the hardware
manufacturer in the hardware configuration settings for the endpoint device. Contact the
manufacturer for more information.

Configuring the USB HID Encryption Key

The default USB HID encryption key is defined in the secure communication section of the API server
configuration file (controlserver.conf).
This secret key shares the same characteristics and best practices as described for the authentication
feature but is referred to as the usb_hid_encryption_default_key.
This configuration option can be set to any alphanumeric string (0-9, the letters A-Z, uppercase and
lowercase, no special characters or spaces) but must be unpredictable. A random string that contains at
least 24 to 32 characters is a good choice with maximum of 64 characters. If the string is longer than 64
characters it will be internally truncated to 64 characters. Refer to the SDVoE Control Server
Administrators Guide for more details
Warning! As the API server configuration file contains security information, special attention should
be given to the access rights of this file.
Example of the secure communication settings from the API server configuration file with the
secure_comm_secret and usb_hid_encryption_default_key bolded for emphasis:

PDS-062491 Rev 2.5 Page 181 of 224

# Default secret encryption key phrases to be used to encrypt network

# data streams between devices supporting such data streams.

#usb_hid_encryption_default_key = nRAENMxzHhzZe!!22sr<`DTejvCT%z

Configuring the USB HID Security Level

An API set usb request is to configure the security settings regarding USB HID device IP
communication, it is also used to configure as the role of a device USB HID extender.
Notes:
i. Applicable to BlueRiver AVP series chipsets, this includes the AVP1000, AVP2000 and AVP2000T.
ii. Only supported on a device if the device JSON object for that device reports a USB_HID node.
If this security option is implemented it must be applied to all appropriate endpoint devices, that is both
the LOCAL and REMOTE USB HID extenders of paired devices.
Note: To enable USB HID encryption, this feature must be enabled in the product configuration
settings by the hardware manufacturer.
The command syntax for auth (enabling of bound authentication) is as follows:
POST /api/device/{target}
{
"op" : "set:usb",
"role" : String (optional)
"security” : {
"level" : “security_level_value” (optional)
}
}
PDS-062491 Rev 2.5 Page 182 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
The following examples, show the syntax for API requests enabling and disabling USB HID encryption, as
well an example setting the role and encryption through a single API request.
Reminder: It is required that this option be enabled by the hardware manufacturer in the product
configuration. Contact the manufacturer for more information.
POST /api/device/010203040506
{
"op" : "set:usb",
"security” :
"level" : “ENABLED”
}
}

POST /api/device/010203040506
{
"op" : "set:usb",
"security” :
"level" : “DISABLED”
}
}
Request below sets the extender role to REMOTE and enables USB HID security encryption for a
specific device.
POST /api/device/010203040506
{
"op" : "set:usb",
"role" : REMOTE
"security” : {
"level" : “ENABLED”
}
}
The target argument must be either the device ID of a single device or the name of a device group.
The supported device groups are:
ALL All devices
ALL_TX All transmitter devices
ALL_RX All receiver devices
The role argument sets role of device when acting as a USB HID extender, can be one of the following:
DISABLED USB HID support is disabled.
OTG The device automatically detects the type of the connected USB HID device and
set its role to LOCAL or REMOTE accordingly.
LOCAL The device acts as USB device that connects to a USB host (e.g. a PC).
REMOTE The device acts as USB host to which USB HID devices connect (keyboard,
mouse, etc.)

PDS-062491 Rev 2.5 Page 183 of 224

11.3.1 API USB HID Node

Example below is a USB HID extender node JSON object returned as part of a get device” request.
{
"type" : "USB_HID",
"index" : 0,
"configuration" : {
"role" : "HOST"
},
"status" : {
"usb_devices" : [
{
"status" : "CONNECTED"
},
{
"status" : "UNSUPPORTED",
},
{
"status" : "DISCONNECTED",
}
],
"usb_host" : {
"status" : "CONNECTED"
},
"role" : "REMOTE" },
"inputs" : {}
}
This example is of the USB HID extender node with IP communication security enabled:
{
"type" : "USB_HID",
"index" : 0,
"configuration" : {
"role" : "REMOTE",
"security" : {
"level" : "ENABLED",
"encryption_key_type" : "DEFAULT"
}
},
"status" : {
"usb_devices" : [
{

PDS-062491 Rev 2.5 Page 184 of 224

PDS-062491 Rev 2.5 Page 185 of 224

PDS-062491 Rev 2.5 Page 186 of 224

Code Number Description

E00 Box is going back to factory settings
E01 Device running from golden firmware image
E04 Error writing into flash memory
E07 Answer settings throttling
E08 Invalid flash request
E09 Key storage failure
E12 USB chip didn’t initialize correctly
E20 HDMI IC didn't initialize correctly
E21-E24 Impossible to communicate with HDMI IC (read)
E25-E28 Impossible to communicate with HDMI IC (write)
E29 Impossible to Flash HDMI IC
E30 10G PHY IC didn't initialize correctly
E31-E34 Errors when accessing the 10G PHY
E40 EDID's checksum doesn't match calculated checksum
E51 Impossible to initialize MAC IC
E52 MAC is busy
E53 Impossible to communicate with MAC IC (write)
E54 Impossible to communicate with MAC IC (read)
E60 SFP+ didn't initialize correctly
E61 Impossible to communicate with SFP+
Example of an error contained within a JSON return array:
"status" : {
"active" : true,
"point_to_point" : false,
"point_to_point_peer" : "",
"boot_status" : "PRIMARY",
"update_in_progress" : false,
"igmp_reporting_mode" : "QUERY",
"error_status" : {
"has_error_code" : true,
"error_code" : 51
},
Note, that when an error has been reported the has_error_code field indicates true and the
error_code field reports the actual error, in this example it was 51.

PDS-062491 Rev 2.5 Page 187 of 224

PDS-062491 Rev 2.5 Page 188 of 224

Setting the USB 2.0 Extender Role

A default USB 2.0 extender role is configured for devices during production by the hardware
manufacturer, refer to manufacturer documentation for details on the default role applied to endpoint
devices. That is if for example an encoder is set as Local Extender and decoders as Remote Extender.
This data can also be retrieved from the API using a get request.
The assigned extender role can be managing using an API request. This is done using a set
property request and the USB Icron key specifying the role to be assigned, either LOCAL or REMOTE.
Request syntax to set the role of the ICRON_USB extender role:
POST /api/device/{target}
{
"op" : "set:property",
"key" : nodes[USB_ICRON:index].configuration.extender_type,
"value" : [LOCAL|REMOTE]
}
The target is the associated device ID of the endpoint device whose role is to set. The target can be
the device ID of a specific endpoint device or a device group, ALL, ALL_RX or ALL_TX.
The USB_ICRON index is always 0 as only one Icron USB extender is supported per device.
Refer to the Developers API Reference Guide for additional information on the set property command
and Icron USB Extender Node.

PDS-062491 Rev 2.5 Page 189 of 224

PDS-062491 Rev 2.5 Page 190 of 224

13.2.2 Simultaneous User Interaction (SUI) Pairing

Icron extenders can be configured to act as a virtual hub. This feature is useful when it is desired to
facilitate the integration of KVM-like solution. This Icron feature is called “Simultaneous User
Interaction” or SUI for short and supports up to seven remote extenders (REX) to be paired to a local
extender (LEX). Simultaneous User Interactions is also sometimes referred to as VHub, or Virtual Hub
Note: Mass Storage Acceleration (MSA) enables faster data transfers from Mass Storage devices
from remote extenders (REX) to local extenders (LEX). Important to note that this feature is
incompatible with SUI.
13.2.2.1 SUI Guidelines and Limitations
1. The Simultaneous User Interaction (SUI) configuration should not be changed during runtime.
The API reads and returns the configuration presented by the device but it doesn’t report any
changes made to the active configuration during runtime.
2. Mass Storage Acceleration (MSA) must be disabled on Icron extenders.
3. Simultaneous User Interaction (SUI) must be enabled on local extenders (LEX).

PDS-062491 Rev 2.5 Page 192 of 224

PDS-062491 Rev 2.5 Page 193 of 224

USB_ICRON Status Node

{
"chip_present" : Boolean,
"mac_address" : String,
"reachable" : Boolean,
"revision" : String,
"ip_mode" : String,
"ip_address" : String,
"peer_mac_address" : String,
"peer_device_id" : String,
"link_status_support" : Boolean,
"linked" : Boolean
“sui_enabled” : Boolean

PDS-062491 Rev 2.5 Page 195 of 224

Member name Since Type Description

chip_present 3.0 Boolean TRUE indicates that an Icron module is
detected. Property is FALSE if Icron USB
enabled in the hardware configuration but
has not been populated.
mac_address 3.0 String MAC address of the Icron module. If the
module has not been detected, this field is
blank ("").
reachable 3.2 Boolean Indicates that the USB extender network
interface is reachable (TRUE) or not (FALSE)
with an IP address.
revision 3.3 String The revision level of the Icron firmware.
ip_mode 3.3 String The active IP mode, either DHCP, AUTO_IP or
MANUAL (static).
peer_mac_address 3.2 String If paired, provides MAC address of the peer
extender. If the extender is not paired or an
Icron module has not been detected then this
field is blank ("").
peer_device_id 3.3 String If currently paired, the device ID of the paired
AVP chipset is shown that is associated with
the peer Icron device. If the extender is not
paired or an Icron module has not been
detected then this field is blank (“”).
link_status_support 3.3 Boolean Indicates whether the Icron supports the
linked attribute.
linked 3.3 Boolean Indicates if bidirectional communication is
currently established. Devices need to
negotiate the link before they can
successfully link. TRUE indicates this
negotiation successful.
If extenders are not currently paired or an
Icron module is not detected, the status is
FALSE. The field is also FALSE if the
link_status_support field reports
FALSE.
sui_enabled 3.4 Boolean Indicates if the Icron module has
Simultaneous User Interaction (SUI) enabled.
TRUE indicates it is enabled and FALSE that
it is not.
sui_peers 3.4 Array of Provides details of Icron pairings related to
SUIPeersDescription local extender (LEX) that a remote extender is
paired with. If device set as remote, its own

PDS-062491 Rev 2.5 Page 196 of 224

"mac_address": "123123123123",
"device_id": "",
"linked": false
},
]
},

PDS-062491 Rev 2.5 Page 197 of 224

Settings Filter for the Icron Node

The API supports an argument to send a get settings request filtering the data returned only for
the USB_ICRON node type. The result lists the details of the USB_ICRON device node for one or more
endpoint devices. For details on the settings filters, refer to the event command in the SDVoE
Developers API Reference Guide.
POST /api/device/target
{
"op" : "get",
"subset" : "settings",
"node_type" : "usb_icron"
}
The target argument can be the device ID of a single device or the name of a device group. The
supported device groups are as follows:
ALL All devices
ALL_RX All decoder/receiver devices
ALL_TX All encoder/transmitter devices
The subset of the get request is settings and the node type is set to usb_icron.
Example return of a get settings request filtered for the USB_ICRON node type for the paired
endpoint devices 0016c035566e and 0016c035566f:
{
"status" : "SUCCESS",
"request_id" : null,
"result" : {
"device_nodes" : [
{
"device_id" : "0016c035566e",
{
"type" : "USB_ICRON",
"index" : 0,
"configuration" : {
"extender_type" : "REMOTE",
"program_mode" : "NONE",
"rs232_port" : 0
},
"status" : {
"chip_present" : true,
"mac_address" : "0016c35571d",
PDS-062491 Rev 2.5 Page 199 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
"reachable" : true,
"revision" : "1.9.4",
"ip_mode" : "DHCP",
"ip_address" : "192.168.100.20",
"peer_mac_address" : "192.168.100.20",
"peer_device_id" : "d8803962e132",
"link_status_support" : true,
"linked" : true
“sui_enabled” : false
“sui_peers” : []
},
"inputs" : []
}
},
{
"device_id" : "d8803962e132",
{
"type" : "USB_ICRON",
"index" : 0,
"configuration" : {
"extender_type" : "LOCAL",
"program_mode" : "NONE",
"rs232_port" : 0
},
"status" : {
"chip_present" : true,
"mac_address" : "0016c035566f",
"reachable" : true,
"revision" : "1.9.4",
"ip_mode" : "DHCP",
"ip_address" : "192.168.100.20",
"peer_mac_address" : "192.168.100.22",
"peer_device_id" : "0016c035566e",
"link_status_support" : true,
"linked" : true
“sui_enabled” : false
“sui_peers” : []
},
"inputs" : []
}
}
],
"error" : []
},
"error" : null
}

PDS-062491 Rev 2.5 Page 200 of 224

13.6.1 Visibility of a USB 2.0 Extender's IP Address

The IP address of an Icron extender is stored in the API server as part of the device info. This internal
information is visible to the control application through the API as it is returned as part of the Icron
Node information. The API server also provides a reachable/unreachable status, paired status, the
current IP mode and MAC address of the extender(s) to which it is paired. Refer to the settings filter
example provided in section 13.5 Settings Filter for the Icron Node for an example.

13.6.2 Resetting Icron Module

The icron:reset is used to reset an Icron extender module that has been incorporated into a
BlueRiver endpoint device, for example the module’s reported state is unreachable.
POST /api/device/0016c035566e
{
"op" : "icron:reset",
"index" : 0 (optional)
}
The target argument can be the device ID of a single device or the name of a supported device group.
The supported device groups are as follows:
ALL All devices
ALL_RX All decoder/receiver devices
ALL_TX All encoder/transmitter devices
The index argument represents the Icron module, since there is only one Icron module mounted the
index value is always 0. If the index is not specified the default is 0.

PDS-062491 Rev 2.5 Page 201 of 224

PDS-062491 Rev 2.5 Page 202 of 224

NT2000 Bitmap Overlay Feature

This section provides information regarding the Bitmap Overlay feature and is applicable only to devices
based on BlueRiver NT2000 chipsets. The target audience for this section is software developers,
project managers and others that are involved in the implementation of the Bitmap Overlay feature.
The Bitmap Overlay feature allows a monochrome (two-color) bitmap to be overlaid on video.
Specifically, it is supported:
• On a decoder (RX) device’s HDMI video output; and
• On an encoder (TX) device’s scaler video stream (HDMI stream 1).
The bitmap overlay can be positioned arbitrarily inside the picture. The foreground and background
colors are configurable to arbitrary RGB values. The transparency level is also configurable
independently for both the foreground and background colors.
If required, pixel replication by a factor of 2 or 4 is also supported. This provides a rudimentary form of
scaling to allow the size of the overlay to be adapted to the picture resolution.
Whenever the picture resolution changes, the bitmap overlay is disabled, which provides the application
an opportunity to modify its parameters before re-enabling the overlay. In this context, the picture
resolution refers to the scaler resolution on an encoder (TX) or the output resolution on a decoder (RX).
The source bitmap is a file in BMP format that is encoded into a hexadecimal string and specified directly
as a part of the relevant API command.

14.1.1 Bitmap Overlay Guidelines and Limitations

The following section outlines limitations that apply to the bitmap overlay feature.
1. Only devices including a BlueRiver NT2000 chipset support this feature.
2. On a decoder (RX) device, the bitmap overlay feature cannot be applied when the device is
operating in Genlock mode, as this feature requires the AV Processor Engine.
Reminders:
i. A decoder running in Genlock mode does not implement the AV Processor Engine.
ii. A bitmap overlay is available to NT2000 decoders operating in an advanced processing
mode, that is Fast Switch, Genlock Scaling, Wall and Multiview modes.
3. Only one bitmap overlay is supported per device.
However, since encoder (TX) devices support the bitmap overlay feature this limitation does not
preclude a multiview application where each video source is identified with a bitmap overlay
that specifies e.g. a source number or a short name.
PDS-062491 Rev 2.5 Page 203 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
4. The width of the bitmap must be an even number of pixels. This also applies to the horizontal
position of the overlay.
5. Subject to the previous requirement, the bitmap overlay can be positioned arbitrarily as long as
it is completely within the picture.
a. However, a bitmap overlay cannot be positioned in such a way that it requires cropping
due to lying outside the video window.
b. In this situation, both the size of the bitmap image as well as the pixel replication
factor need to be taken into account.
6. The maximum total number of pixels of the bitmap image is 65536.
For example, 256x256, 4096x16, 64x1024 and 64x64 bitmaps are all acceptable bitmap sizes,
but 260x256 is not.
7. The specified bitmap must be a valid BMP monochrome bitmap file; that is a BMP file with a
1-bit per pixel representation.
• Multiple variations of the BMP file format exist with different versions of the bitmap header.
• The following versions of the bitmap header are supported, which in practice covers all
formats supported by modern applications:
BITMAPCOREHEADER / OS21XBITMAPHEADER (header size: 12 bytes)
BITMAPV4HEADER (header size: 108 bytes)
BITMAPV5HEADER (header size: 124 bytes)
For more information on each of these headers, refer to:
https://docs.microsoft.com/en-us/windows/desktop/gdi/bitmap-
header-types

14.1.2 Generating a Bitmap Overlay

If an application is to generate bitmaps on the fly rather than load existing files, for example text with a
specific font, it is recommended to generate the variant with the BITMAPCOREHEADER bitmap header
as it is the simplest.
For more details on this header, the BITMAPFILEHEADER that precedes it and the general structure
of a BMP file, refer to:
https://docs.microsoft.com/en-us/windows/desktop/gdi/bitmap-
header-types
Implementation Tips:
• Although the start of all versions of the bitmap header look similar, should be noted that the
width and height fields are 16-bits in BITMAPCOREHEADER, while it is 32-bits in the
other versions.
• As expected, the height field is unsigned in BITMAPCOREHEADER but should be noted that it is
a signed value in other versions.
• A positive value for the height indicates that the lines are stored bottom first, while a
negative value indicates lines are stored top first.
• BITMAPCOREHEADER bitmap files are always bottom first.
• In a bitmap file, the length of each image line must be a multiple of four bytes, with padding
added as necessary to meet this requirement.
PDS-062491 Rev 2.5 Page 204 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
• For BITMAPCOREHEADER bitmap files, the color table that follows the bitmap header uses
three bytes per entry, i.e. one per color component (red, green and blue). Bitmap files with
other header versions have four bytes per entry.

14.1.3 API Bitmap Requests

The API set command supports the bitmap overlay feature as follows:
• The set overlay command allows for the configuration of the bitmap overlay.
• The BITMAP_OVERLAY node reports the current bitmap overlay configuration,
when applicable.
o An NT2000 device supporting the bitmap overlay feature will include the
BITMAP_OVERLAY node.
o A device that does not support this feature will not have this node present.
14.1.3.1 Applying a set overlay
POST /api/device/{target}
{
"op" : "set:overlay:on",
"horiz_position" : Integer (conditional),
"vert_position" : Integer (conditional),
"scaling_factor" : Integer (optional),
"fg_color" : String (conditional),
"bg_color" : String (conditional),
"fg_transparency" : Integer (conditional),
"bg_transparency " : Integer (conditional),
"bmp_hex" : String (optional),
"invert" : Boolean (conditional)
}

POST /api/device/{target}
…
{
"op" : "set:overlay:off"
}
Two forms of the command are supported with the first being used to enable and configure the bitmap
overlay and the second to disable it. A bitmap overlay is supported on the scaled stream (stream 1)
of an encoder and on the HDMI output of a receiver device.
Reminders:
i. This command is only applicable to endpoint devices utilizing BlueRiver NT2000 chipsets and
that include the AV Processor Engine.
ii. Refer to the following sources for information about the BMP file format:
Bitmaps: https://docs.microsoft.com/en-
ca/windows/desktop/gdi/bitmaps
BMP file format: https://en.wikipedia.org/wiki/BMP_file_format

PDS-062491 Rev 2.5 Page 205 of 224

PDS-062491 Rev 2.5 Page 206 of 224

Disabling an active bitmap overlay:

POST /api/device/d80102030405 HTTP/1.1
…
{
"op" : "set:overlay:off"
}
HTTP/1.1 201 Created
Location: /api/request/125
…
{
"status" : "PROCESSING",
"request_id" : 125,
"result" : null,
"error" : null
}
14.1.3.2 The BITMAP_OVERLAY Node
The table below shows the BITMAP_OVERLAY node configuration members.
Table 16: BITMAP_OVERLAY node configuration members

Member Name Type Description

background_color String Background color in format RRGGBB.
background_transparency Integer Background transparency level in percent.
enable Boolean Whether bitmap overlay is enabled or disabled.
foreground_color String Foreground color in format RRGGBB.
foreground_transparency Integer Foreground transparency level in percent.
height Integer Height of the overlay bitmap.
horiz_position Integer Horizontal position, in pixels, of the overlay
scaling_factor Integer Scaling factor (1, 2 or 4)
vert_position Integer Vertical position, in pixels, of the overlay
width Integer Width of the overlay bitmap.

Thumbnail Preview
The SDVoE solution supports the ability to stream an unencrypted source as a thumbnail from a
BlueRiver NT2000 or NT1000 encoder device (TX) to a host computer.
For details on setup of this feature please refer to section 14.2.2 Thumbnail Configuration and Setup
which includes setting up GStreamer which can be used as the pipeline-based multimedia framework to
implement thumbnails as well as the configuration and setup of thumbnail streams through the API.
Should be noted that the thumbnail streams propagate through the 10GbE port.
Reminder: This feature is available to encoder devices that include either a BlueRiver NT1000 or
NT2000 chipset only, it is not available to devices based on the AVP chipset series.

PDS-062491 Rev 2.5 Page 208 of 224

14.2.2 Thumbnail Configuration and Setup

This section reviews the installation and demonstration of the thumbnail preview feature.
Note: This document uses GStreamer, so it is necessary to install this tool prior to configuring a
preview stream. A different tool can be used in place of GStreamer, in such cases refer to the
appropriate resources for the configuration of the tool.
The following characteristics apply to the Thumbnail Preview feature:
• Thumbnail streams:
o Are an RTP stream that can be received using open-source multimedia frameworks, such
as GStreamer.
▪ The RTP payload type is fixed to 112 uncompressed video.
▪ The RTP synchronization source (SSRC) identifier is configurable and must be
provided by the user.
o Always YCbCr 4:2:2 8-bit uncompressed video.
o Always started through the API server.
o Contains video only.
o Are not encrypted.
• Thumbnails must be enabled in the product configuration, done during production by the
hardware manufacturer.
• The width applied is the largest width appropriate to the maximum supported width of
320 pixels; the original picture width is always divided evenly.
• Frame rate per second (fps) control:
o FPS is controllable and can range from 0.5 fps to full source frame rate.
o The maximum frame rate of the thumbnail stream is the original frame rate of the
video source.
• Thumbnail streams can be sent to a unicast IP address, as well the UDP port is configurable.
o If left unspecified, the default port applied is 6972.
PDS-062491 Rev 2.5 Page 209 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
• For thumbnail streams sent to a multicast IP address, as well the UDP port is also configurable.
o If left unspecified, the default port applied is 6972.
Notes:
i. If the original video source is HDCP-encrypted a thumbnail stream of the video source is
available. However, important to note to enable this type of source an API start request is
required to be issued to the appropriate encoder(s), specifying the stream type as THUMBNAIL.
Refer to the 14.2.3.3 HDCP Content for more information.
ii. Also, refer to section 14.2.1 Important Customer Notice to review the important customer
notice.

14.2.3 GStreamer Installation and Configuration

This section reviews the configuration of GStreamer in relation to the thumbnail preview streams on a
64-bit Windows host computer.
Note: GStreamer is a pipeline-based multimedia framework that links together a wide variety of
media processing systems to complete complex workflows.
Download and install GStreamer to the client computer that will be outputting the thumbnails. Select
the typical installation:
gstreamer-1.0-mingw-x86_64-XXX.msi
GStreamer can be downloaded from the following link:
https://gstreamer.freedesktop.org/data/pkg/windows/
1. Install GStreamer as Typical installation, default settings are acceptable for purpose of
demonstrating thumbnail previews.
2. Once the installation is complete, it is necessary to add GStreamer executable binaries directory
to the System variables "Path" in Environment Variables of the host Windows computer:
C:\gstreamer\1.0\x86_64\bin\
Refer to figure below for example.

PDS-062491 Rev 2.5 Page 210 of 224

3. Once the installation is completed and the variable is configured, verify that the gst-launch-
1.0.exe executable can be launched from any directory location using a Windows command line.
To verify the installation:
a. Open a Windows command line.
b. At the prompt type:
gst-launch-1.0.exe -help
c. The gstreamer help should then be displayed.

Figure 74: Example of verifying GStreamer

PDS-062491 Rev 2.5 Page 211 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
Helpful Tips:
i. For information on installing GStreamer on an alternate Operating System than Windows, refer
to the web page provided below to be directed to the GStreamer official web site:
https://gstreamer.freedesktop.org/documentation/installing/index.html
ii. If it is experienced that a thumbnail video is not received when an IGMP request (version 3) is
sent from a client computer to a Netgear M4300 8X8F network switch, this issue may be
resolved by activating the IGMP Querier on the VLAN.
14.2.3.1 Thumbnail Stream Video Resolutions
The maximum image width size of 320-pixels is used to determine the thumbnail image size. The Video
Aspect ratio is always respected. The table below shows supported stream resolutions and the output
size for the thumbnail streams.
Table 17: Thumbnail stream resolutions and thumbnail resolution output

Video Width Video Height Interlaced Output H Size Output V Size

SD
1440 480 X 180 120
720 480 240 160
1440 576 X 180 144
720 576 240 192
HD
1280 720 320 180
1920 1080 X 320 180
1920 1080 320 180
4K
3840 2160 320 180
4096 2160 292 154
Other
640 480 320 240
800 600 266 200
1024 768 256 192
1280 800 320 200
1280 960 320 240
1280 1024 320 256
1360 768 272 153
1366 768 273 153
1400 1050 280 210
1440 900 288 180
1600 900 320 180
1600 1200 320 240
1680 1050 280 175
1920 1200 320 200

PDS-062491 Rev 2.5 Page 212 of 224

PDS-062491 Rev 2.5 Page 213 of 224

POST /api/device/d88001020405 HTTP/1.1

…
{
"op" : "set:thumbnail",
"fps" : "60m",
"ssrc" : 12236
}
HTTP/1.1 201 Created
Location: /api/request/13134
…
{
"status" : "PROCESSING",
"request_id" : 13134,
"result" : null,
"error" : null
}
14.2.3.3 HDCP Content
To enable the streaming of HDCP content, once the thumbnail generator is configured it is necessary to
send an API start request to enable streaming of HDCP content. To discontinue the transmission of
HDCP content a stop request is used. By default, thumbnail support for HDCP sources is disabled.
Warning! Prior to enabling HDCP content to stream, refer to section 14.2.1 Important Customer
Notice for a critical legal notification.
For detailed information on start and stop requests related to other stream types, refer to the
SDVoE Developers API Reference Guide.
Enabling an HDCP Thumbnail Stream
To enable the streaming of HDCP content, an API start request is used.
POST /api/device/{target}
{
"op" : "start",
"stream_type" : String,
"stream_index" : Integer,
"dest_address" : String (optional),
"hdcp_thumbnail" : Boolean (optional) (NT1000/NT2000 only),
}
PDS-062491 Rev 2.5 Page 214 of 224
SDVoE Developers API Application March 2023 The information contained herein is the exclusive property of Semtech and shall not
Note Library be distributed, copied, reproduced or disclosed in whole or in part without prior
written permission of Semtech or its licensees.
In relation to thumbnail preview streams, a start request modifies the behavior of a THUMBNAIL
stream in regards to HDCP sources. If a start request is issued then no video is streamed when the
source is HDCP-protected.
Reminder: Prior to starting a thumbnail preview stream, the thumbnail generator must have
been configured.
Arguments
The target argument must be either the device ID of a single encoder (TX) or the device group,
ALL_TX to apply to all encoder (TX) devices. Regarding thumbnail preview streams, the stream type is
THUMBNAIL and the stream_index is 0.
The ip_address argument specifies the IP address to be used. It can be either a unicast address or a
multicast address within the API stream address range. If not specified, the API automatically assigns
the next available multicast address.
For the hdcp_thumbnail the option is a Boolean entry of either TRUE to enable the HDCP content or
FALSE to disable passing HDCP content. If this argument is not specified then FALSE is the default and
HDCP content will not be streamed.
Disabling HDCP Content from Streaming with Thumbnail Stream
Regarding thumbnail streams, to discontinue streaming HDCP content, an API stop request is used.
POST /api/device/{target}
{
"op" : "stop",
"stream_type" : String (optional),
"stream_index" : Integer (optional),
"free" : Boolean
}
Arguments
The target argument must be either the device ID of a single encoder (TX) or the device group,
ALL_TX to apply to all encoder (TX) devices. In regards to a thumbnail preview stream the stream type
entered is THUMBNAIL and the stream_index is always 0.
If the free argument is true then the multicast IP address associated with a THUMBNAIL stream is
freed/unassigned. If the free keyword is entered but the stream is a unicast address, not a multicast
address, the argument is allowed but ignored.
14.2.3.4 Thumbnail Generator Node
The node object with the type member set to THUMBNAIL_GENERATOR provides details of thumbnail
configuration settings. Applicable to devices containing a BlueRiver NT1000 or NT2000 chipsets only.
Table 18: Thumbnail Generator Node object members

Name Type Configuration Member Description

frame_rate Real The requested frame rate for the thumbnail stream.
ssrc Integer RTP synchronization source (SSRC) identifier. This 32-bit value must be
unique for each thumbnail source. Refer to RFC-3550, section 8 for details.
udp_port Integer Destination UDP port.

PDS-062491 Rev 2.5 Page 215 of 224

Name Type Status Member Description

width Integer
Width of each thumbnail.
height Integer
Height of each thumbnail.
frame_rate Real
Actual frame rate for the thumbnail stream.
bits_per_comp Value 8 indicates that there are 8-bits per color component.
Integer
color_space String YCBCR_422 indicates thumbnail stream is in the YCbCr color
String
space with 4:2:2 Chroma subsampling.
colorimetry String The colorimetry of thumbnail stream. Will be one of the following:
BT709 for BT.709
BT601 for BT.601
The example shown below shows a thumbnail generator node JSON object as returned as part of the
output of a “get device” request for an NT2000 endpoint device.
{
"type" : "THUMBNAIL_GENERATOR",
"index" : 0,
"configuration" : {
"frame_rate" : 10.00,
"hdcp" : false,
"ssrc" : 1234,
"udp_port" : 6972
},
"status" : {
"width" : 320,
"height" : 180,
"frame_rate" : 10.00,
"bits_per_comp" : 8,
"color_space" : "YCBCR_422",
"colorimetry" : "BT601"
},
"inputs" : []
}

PDS-062491 Rev 2.5 Page 216 of 224

PDS-062491 Rev 2.5 Page 217 of 224

PDS-062491 Rev 2.5 Page 218 of 224

14.2.5.2 Guidelines and Limitations

The purpose of the thumbnail preview demo script is to start thumbnail viewing on an NT1000 or
NT2000 encoder (TX) and client computer. Below outlines guidelines and limitations to keep in mind
when using the demo script:
• No video encryption or compression is done.
• Video needs to be present and valid on the encoder (TX) device before executing the demo
script. The script needs to retrieve the thumbnail stream video dimensions prior to being able
to start the GStreamer with the proper window size.
• Once the stream is started, there is no dynamic management of this stream. The script does not
monitor for changes in the Thumbnail stream.
• The GStreamer window is kept opened with the same size even if the stream is stopped on the
encoder (TX) device.
• The GStreamer window needs to be manually closed. Once the window is closed, the demo
script will automatically send the IGMP leave message in case a multicast address was used as a
destination address of the thumbnail script.
• The GStreamer window size will remain the same even if the input video size on the encoder
(TX) device is changed.
o In the case of a smaller image size being implemented, a "ghost" image could be present
if extra pixels are displayed.
o For a larger image size, some pixels could be missing, resulting in only a portion of the
stream be shown in the GStreamer window.
• Not able to be shown by VLC. The library version used by VLC to read streaming video does not
support RTP RAW videos data.

PDS-062491 Rev 2.5 Page 219 of 224

Start

No Video Stable

Yes

Thumbnail resolution
No
changed?

Yes

Stop Thumbnail view process

Update RTP Receiver with new

Thumbnail Resolution

Restart the Thumbnail Viewer

Figure 76: Thumbnail resolution change

PDS-062491 Rev 2.5 Page 220 of 224

Start

No Video Stable

Yes

Thumbnail resolution
No
changed?

Yes

Stop Thumbnail view process:

Close GStreamer call

Restart the Thumbnail Viewer:

Restart GSteamer command line with
new video resolution.

Figure 77: Video size changes with GStreamer

PDS-062491 Rev 2.5 Page 221 of 224

PDS-062491 Rev 2.5 Page 222 of 224

PDS-062491 Rev 2.5 Page 223 of 224

For more information contact: [email protected]

PDS-062491 Rev 2.5 Page 224 of 224

Vissim 2024 - Manual
No ratings yet
Vissim 2024 - Manual
1,248 pages
PDS-062489_SDVoE_Developers_API_Reference_Guide_rev1p6
No ratings yet
PDS-062489_SDVoE_Developers_API_Reference_Guide_rev1p6
352 pages
Manual Vissim 2022
100% (2)
Manual Vissim 2022
1,376 pages
2016 - SW PDM - Api Professional
No ratings yet
2016 - SW PDM - Api Professional
221 pages
NDI SDK Documentation
100% (1)
NDI SDK Documentation
49 pages
Vissim 2022 Manual 1 191
No ratings yet
Vissim 2022 Manual 1 191
191 pages
Solidworks API Fundamentals Course Content
No ratings yet
Solidworks API Fundamentals Course Content
10 pages
Vissim 11 - Manual
60% (5)
Vissim 11 - Manual
1,219 pages
DWC Hdmi TX Databook PDF
No ratings yet
DWC Hdmi TX Databook PDF
340 pages
Cummins 6LT9.3 162 KW (220 HP) at 2,200 RPM 146 KW (199 HP) at 2,200 RPM 16,700 KG 3.6 M 155 KN 2,950 MM
100% (8)
Cummins 6LT9.3 162 KW (220 HP) at 2,200 RPM 146 KW (199 HP) at 2,200 RPM 16,700 KG 3.6 M 155 KN 2,950 MM
2 pages
Impact of Media On Culture
No ratings yet
Impact of Media On Culture
13 pages
PDS-062488_Developers_Introduction_to_SDVoE_API_User_ Guide_rev1p2
No ratings yet
PDS-062488_Developers_Introduction_to_SDVoE_API_User_ Guide_rev1p2
76 pages
EBUS SDK C++ API Quick Start Guide
No ratings yet
EBUS SDK C++ API Quick Start Guide
44 pages
eBUS SDK C++ API Quick Start Guide PDF
No ratings yet
eBUS SDK C++ API Quick Start Guide PDF
39 pages
Software Patterns Made Easy
From Everand
Software Patterns Made Easy
Justice Nanhou
No ratings yet
Device Network SDK Programming Manual Decoder PDF
No ratings yet
Device Network SDK Programming Manual Decoder PDF
43 pages
Device Network SDK Programming Manual (Decoder)
No ratings yet
Device Network SDK Programming Manual (Decoder)
43 pages
Nvidia Purevideo Decoder User'S Guide: Applications For Windows
No ratings yet
Nvidia Purevideo Decoder User'S Guide: Applications For Windows
36 pages
eBUS Player UG For Windows and Linux PDF
No ratings yet
eBUS Player UG For Windows and Linux PDF
68 pages
Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ Scripting
From Everand
Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ Scripting
Vladimir Kiselev
No ratings yet
XNS ActiveX API EN PDF
No ratings yet
XNS ActiveX API EN PDF
342 pages
Device Network SDK Programming Manual (IPC) PDF
No ratings yet
Device Network SDK Programming Manual (IPC) PDF
142 pages
XMC Vadc
No ratings yet
XMC Vadc
75 pages
PDS-062492_SDVoE_Control_Server_Administrators_Guide_rev1p1
No ratings yet
PDS-062492_SDVoE_Control_Server_Administrators_Guide_rev1p1
48 pages
DS-6916UDIC_Datasheet_20241203
No ratings yet
DS-6916UDIC_Datasheet_20241203
6 pages
DS-6916UDI Datasheet 20231102
No ratings yet
DS-6916UDI Datasheet 20231102
6 pages
Device Network SDK (Display and Control) - Developer Guide - V6.1.4.X - 20230330
No ratings yet
Device Network SDK (Display and Control) - Developer Guide - V6.1.4.X - 20230330
260 pages
Content Creation Revolution with chatGPT
From Everand
Content Creation Revolution with chatGPT
Maria Cowen
No ratings yet
Video SDK UserGuide PDF
No ratings yet
Video SDK UserGuide PDF
18 pages
Vissim 6 - Manual
No ratings yet
Vissim 6 - Manual
694 pages
Vissim 6 - Manual
No ratings yet
Vissim 6 - Manual
704 pages
DS-6916UDI(C)_Datasheet_20240223
No ratings yet
DS-6916UDI(C)_Datasheet_20240223
7 pages
eBUS SDK Programmer's Guide
No ratings yet
eBUS SDK Programmer's Guide
98 pages
DaVis D82 Manual
No ratings yet
DaVis D82 Manual
336 pages
Toc Pmtxx33-Eng Pdmapi
No ratings yet
Toc Pmtxx33-Eng Pdmapi
6 pages
NetSDK Programming Manual
No ratings yet
NetSDK Programming Manual
48 pages
DECODER - DS-6910UDI - Datasheet
No ratings yet
DECODER - DS-6910UDI - Datasheet
6 pages
Vdisplay HDI-Pro User Guide
No ratings yet
Vdisplay HDI-Pro User Guide
88 pages
NVQFX4600-5600SDI UG v010 v1
No ratings yet
NVQFX4600-5600SDI UG v010 v1
94 pages
DS-6910UDIC DECODER
No ratings yet
DS-6910UDIC DECODER
6 pages
DaVis D72
No ratings yet
DaVis D72
316 pages
NDI SDK Documentation
No ratings yet
NDI SDK Documentation
53 pages
Software Manual
No ratings yet
Software Manual
37 pages
NVAPI R300 Public SDK RelNotes
No ratings yet
NVAPI R300 Public SDK RelNotes
7 pages
NVAPI R343 Public SDK RelNotes v01
No ratings yet
NVAPI R343 Public SDK RelNotes v01
8 pages
Vissim 9 - Manual PDF
No ratings yet
Vissim 9 - Manual PDF
1,055 pages
5.1 Mega Pixel Camera Module
No ratings yet
5.1 Mega Pixel Camera Module
107 pages
software-manual
No ratings yet
software-manual
37 pages
eBUS SDK For Linux Quick Start Guide PDF
No ratings yet
eBUS SDK For Linux Quick Start Guide PDF
27 pages
Vimba NET Manual
No ratings yet
Vimba NET Manual
22 pages
NetSDK Programming Manual
No ratings yet
NetSDK Programming Manual
49 pages
Vision Pro Quick Reference
No ratings yet
Vision Pro Quick Reference
18 pages
Digital Video Recorder: User Manual
No ratings yet
Digital Video Recorder: User Manual
186 pages
Vissim 9 - Manual
100% (7)
Vissim 9 - Manual
1,065 pages
Vissim 6 - Manual
100% (2)
Vissim 6 - Manual
660 pages
Vissim 6 Manual PDF
No ratings yet
Vissim 6 Manual PDF
660 pages
DAHUA HTTP API FOR IPC Version 1.40
100% (1)
DAHUA HTTP API FOR IPC Version 1.40
106 pages
Web Services API UserGuide 19.3.0
No ratings yet
Web Services API UserGuide 19.3.0
275 pages
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
From Everand
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
Michael Basler
No ratings yet
Cloud Computing : Beginners And Intermediate User Guide
From Everand
Cloud Computing : Beginners And Intermediate User Guide
David comer
No ratings yet
User Manual of DS-6101HFI-IP V2.0
No ratings yet
User Manual of DS-6101HFI-IP V2.0
28 pages
SF 114063 CD Ef Vi User Guide
No ratings yet
SF 114063 CD Ef Vi User Guide
268 pages
Review On Latest Trends and Techniques in Predictive Analytics
No ratings yet
Review On Latest Trends and Techniques in Predictive Analytics
6 pages
Bresse 1860. Diámetro Nominal Optimo..
No ratings yet
Bresse 1860. Diámetro Nominal Optimo..
8 pages
EBAU CyL Inglés 2015 Septiembre Opción A
No ratings yet
EBAU CyL Inglés 2015 Septiembre Opción A
1 page
Maintenance and Repair Manual
No ratings yet
Maintenance and Repair Manual
15 pages
DBCC DMV Commands
No ratings yet
DBCC DMV Commands
6 pages
Pisah Trafik Nemu
No ratings yet
Pisah Trafik Nemu
3 pages
Clutch Problems 332
100% (2)
Clutch Problems 332
3 pages
The Lot or Part of Fortune Robert Hand
100% (4)
The Lot or Part of Fortune Robert Hand
7 pages
Lab Report 4
100% (1)
Lab Report 4
16 pages
Z19DT and DTH Fuel Filter PDF
No ratings yet
Z19DT and DTH Fuel Filter PDF
11 pages
Assembly Drawing & Parts List: Ser - No. Part No. Name & Specification Quantity
No ratings yet
Assembly Drawing & Parts List: Ser - No. Part No. Name & Specification Quantity
3 pages
Chapter 15
No ratings yet
Chapter 15
7 pages
Analysis of Radiation Patterns of Log-Periodic Dipole Array Using Transmission Line Matrix Model
100% (1)
Analysis of Radiation Patterns of Log-Periodic Dipole Array Using Transmission Line Matrix Model
9 pages
Batch 17
No ratings yet
Batch 17
22 pages
Self-Regulated Learning The Effect On Students Ma
No ratings yet
Self-Regulated Learning The Effect On Students Ma
8 pages
4th PT in Math 9-2022-2023
No ratings yet
4th PT in Math 9-2022-2023
5 pages
Atollic TrueSTUDIO Installation Guide
No ratings yet
Atollic TrueSTUDIO Installation Guide
35 pages
Malhotra MR6e 01
No ratings yet
Malhotra MR6e 01
28 pages
Edited Gfi Seminar Report
No ratings yet
Edited Gfi Seminar Report
18 pages
EntropyandLife (Final) PDF
No ratings yet
EntropyandLife (Final) PDF
19 pages
PROJECT ENGINEER (MECHANICAL) - WEST RIVER ENGINEERING SDN BHD - 4426843 - JobStreet
No ratings yet
PROJECT ENGINEER (MECHANICAL) - WEST RIVER ENGINEERING SDN BHD - 4426843 - JobStreet
3 pages
AM Asphalt & RMC Concrete LTD.: Daily RMC Supply (As Per Challan)
No ratings yet
AM Asphalt & RMC Concrete LTD.: Daily RMC Supply (As Per Challan)
1 page
Technical Data Sheet
No ratings yet
Technical Data Sheet
2 pages
Bar Clamp
No ratings yet
Bar Clamp
19 pages
Negotiation: Key Concepts
No ratings yet
Negotiation: Key Concepts
7 pages
Mercedes C230 Operators Manual
No ratings yet
Mercedes C230 Operators Manual
442 pages
Writing Introductions, Jan, 23
No ratings yet
Writing Introductions, Jan, 23
3 pages
Module 18 (Blue) : (What I Know) Pre-Test
No ratings yet
Module 18 (Blue) : (What I Know) Pre-Test
7 pages