Documentation Center

Viz Plug-ins User Guide

Version 5.1 | Published December 12, 2023 ©

viz_probel

The viz_probel plug-in allows the dynamic assignment of IP streams (2110) to the Viz Engine input channel.

Viz Engine manages a number of external sources to map them to a smaller number of available input channels. Viz Engine maintains control over which input channels have fixed sources from startup and which input channels can request a new source. The viz_probel plug-in maintains a table that maps a source to the Viz Engine input channel. Since each input channel in the Viz Engine corresponds to a physical Matrox connection. The plug-in effectively maps external sources to a particular Matrox physical connection.

The external component that communicates with viz_probel plug-in is usually a Virtual Studio Monitor (VSM) which communicates with the viz_probel plug-in via SW-P-08 general remote protocol.

VSM has a matrix composed of the sources and its corresponding output. This matrix state is saved in the viz_probel plug-in.

The viz_probel plug-in has the following tables:

  • VSM output and corresponding sources.

  • VSM output and corresponding Viz Engine input channel.

  • Matrox physical connection and Viz Engine input channel. Configured by the user.

  • Matrox physical connection and VSM output. Configured by the user.

Message Interface

Communication via message passing is supported which is similar to a REST API. Messages can be sent via Request(location, message) in the Viz Script.

The response is asynchronous and is only given to the plug-in user when there is change in the internal mappings.

Register

The following must be called at least once to be able to connect to the VSM.

Location: /Extensions/Probel/register

Response:

[{"error": false}]

Unregister

The following must be called to disconnect from VSM.

Location: /Extensions/Probel/unregister

Response:

[{"error": false}]

Sources

The following returns the corresponding Viz Engine input channel. This generally changes the matrix in VSM but not always. {} can also be releaseall or requestall.

releaseall attempts to release all sources while requestall attempts to request all available sources.

Location: /Extensions/Probel/sources/{}

Response:

[{"error": false}]

The following releases a channel in the matrix in VSM.

Location: /Extensions/Probel/sources/{}/release

Response:

[{"error": false}]

The following releases an all channel in the matrix in VSM except a few of them. {} can have multiple sources separated by "-". Example /Extensions/Probel/sources/releaseall/except/3-4-5-6

Location: /Extensions/Probel/sources/releaseall/except/{}

Response:

[{"error": false}]

Debug

The following is used for debugging SW-P-08 implementation. If {} is 0, it sends an ImplementationRequest. If {} is 1, it sends a CrossPointTallyDumpRequest.

Location: /Extensions/Probel/debug/{}

Response:

[{"error": false}]

The following is used for debugging SW-P-08 implementation. If {} is 0, it sends a CrossPointInterrogate, the next {} is a parameter indicating the output. If {} is 1, it sends a AllSourceNamesRequest, the next {} is a parameter indicating the names length.

Location: /Extensions/Probel/debug/{}/{}

Response:

[{"error": false}]

The following is used for debugging SW-P-08 implementation. If {} is 0, it sends a CrossPointConnect, the next {} are parameters indicating the output and source. If {} is 1, it sends a SingleSourceNameRequest, the next {} are parameters indicating the names length and source.

Location: /Extensions/Probel/debug/{}/{}/{}

Response:

[{"error": false}]

Response

The following is how the asynchronous response looks like. {} corresponds to the source.

Location: /Extensions/Probel/sources/{}/change

Response:

[
{
"channelId": 0,
"sourceId": 0
}
]

Configuration

To Configure this plug-in create a file called {VizEngine-Config-dir}/extensions/Probel.json. This file is used for every running instance of Viz Engine. To have a specific configuration for a running instance you can create configuration files like {VizEngine-Config-dir}/extensions/Probel-{Instance-Number}.json.

Supported config parameters:

  • address: Defines the port that should be used in VSM if connection mode is configured as server (depending on the connection-mode configuration), or the address and port of VSM if configured as client.

  • backup-address: Defines the port that should be used in VSM backup if connection mode is configured as server (depending on the connection-mode configuration), or the address and port of VSM backup if configured as client.

  • connection-mode: Determines whether the plug-in should act as a server or client. 0 for server or 1 for client.

  • fixed-entry-offset: Sources that should not be changed. This sources can not be released by plug-in the user.

  • delay-in-fields: Sets the field delay before giving the response to the plug-in user.

  • disconnected: Defines what should be considered as disconnected sources. Several sources can be defined separated by comma.

  • range: Limits the range at which the plug-in user can operate. This is used in the event multiple Viz Engine instances are operating using the same VSM server but must operate only on a subset of sources.

  • vizch-vsmout: Shows which Viz Engine input channel corresponds to which VSM output.

  • vizch-matroxch: Shows which Viz Engine input channel corresponds to which Matrox physical connector. This should match with the configuration in the usual Viz Engine configuration file.

  • extended-message: Enables extended support for Probel which adds support for a large matrix with more than 1024 sources.

The Probel .json file could then look like this:

{
"address": "10.29.39.11:4211",
"backup-address": "0.0.0.0:27015",
"connection-mode": "1",
"delay-in-fields": "10",
"disconnected": "1022,65535",
"fixed-entry-offset": "4",
"range": "0-15",
"vizch-matroxch": "0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,26,27,28,29,30,31",
"vizch-vsmout": "0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31"
}

Sample Script

The following is an example of most of the functionality presented above:

sub OnInitParameters()
RegisterParameterInt("req", "ReqSource", 1, 1, 1023)
RegisterPushButton("request", "Request Source", 1)
RegisterPushButton("release", "Release Source", 2)
RegisterPushButton("releaseall", "Release All", 3)
RegisterPushButton("requestall", "Request All", 4)
RegisterPushButton("register", "Register", 5)
RegisterPushButton("unregister", "Unregister", 6)
end sub
 
sub OnResponse(location as string, message as string)
PrintLn "OnResponse triggered..."
Println location
Println message
end sub
 
sub OnExecAction(buttonId As Integer)
if buttonId = 1 Then
Request("/Extensions/Probel/sources/"&cstr(getParameterInt("req")-1), "")
elseif buttonid = 2 Then
Request("/Extensions/Probel/sources/"&cstr(getParameterInt("req")-1)&"/release", "")
elseif buttonid = 3 Then
for x = 0 to 31
println "Release : "&x
Request("/Extensions/Probel/sources/"&cstr(x)&"/release", "")
next
elseif buttonid = 4 Then
for x = 0 to 32
println "Request : "&(x mod 32)
Request("/Extensions/Probel/sources/"&cstr((x mod 32)), "")
next
elseif buttonid = 5 Then
Request("/Extensions/Probel/register", "")
elseif buttonid = 6 Then
Request("/Extensions/Probel/unregister", "")
end if
end sub

As per the documentation, the user needs to call first register to be able to use the other functions.

Debug

To enable debug logs go to the usual Viz Engine configuration file and enable ACE logging:

ACELogParams = -f OSTREAM|STDERR|VERBOSE_LITE|VERBOSE -p STARTUP|SHUTDOWN|~TRACE|DEBUG|INFO|WARNING|NOTICE|ERROR|CRITICAL|ALERT|EMERGENCY

This allows for the user to see the raw messages that are being sent and received between the VSM and the plug-in.

Troubleshooting

To be able to troubleshoot it is important to understand the console log messages.

Suppose we have the following tables:

(MatroxCh#, VSMOut#): (0, 15), (1, 0), (2, 3), (3, 12), (4, 4), (5, 5), (6, 6), (7, 7).
(MatroxCh#, VizCh#): (0, 1), (1, 0), (2, 3), (3, 2), (4, 4), (5, 5), (6, 6), (7, 7).
(VSMOut#, VizCh#): (0, 0), (3, 3), (4, 4), (5, 5), (6, 6), (7, 7), (12, 2), (15, 1).
(VSMOut#, SourceId#): (0, 3), (1, 2), (2, -1), (3, 10), (4, 0), (5, 12), (6, 8), (7, 5), (8, 0), (9, -1), (10, -1), (11, -1), (12, 11), (13, -1), (14, -1), (15, 4).

All operations are done only with the tables (VSMOut#, VizCh#) and (VSMOut#, SourceId#). (MatroxCh#, VSMOut#) and (MatroxCh#, VizCh#) are redundant.

First case: Requested SourceId# has a VSMOut# that is associated with VizCh#:

INFO: VizEngine-0[15996]:viz::swp08::Probel_SWP08_Handler::PrintMap: (MatroxCh#, VSMOut#): (0, 15), (1, 0), (2, 3), (3, 12), (4, 4), (5, 5), (6, 6), (7, 7).
INFO: VizEngine-0[15996]:viz::swp08::Probel_SWP08_Handler::PrintMap: (MatroxCh#, VizCh#): (0, 1), (1, 0), (2, 3), (3, 2), (4, 4), (5, 5), (6, 6), (7, 7).
INFO: VizEngine-0[15996]:viz::swp08::Probel_SWP08_Handler::PrintMap: (VSMOut#, VizCh#): (0, 0), (3, 3), (4, 4), (5, 5), (6, 6), (7, 7), (12, 2), (15, 1).
INFO: VizEngine-0[15996]:viz::swp08::Probel_SWP08_Handler::PrintMap: (VSMOut#, SourceId#): (0, 3), (1, 2), (2, -1), (3, 10), (4, 0), (5, 12), (6, 8), (7, 5), (8, 0), (9, -1), (10, -1), (11, -1), (12, 11), (13, -1), (14, -1), (15, 4).
INFO: VizEngine-0[15996]:viz::swp08::Probel_SWP08_Handler::RequestChannelFromSourceId: found vsmout (0) in (VSMOut#, SourceId#) that has an associated vizch (0) in (VSMOut#, VizCh#) with given sourceId (3).
INFO: VizEngine-0[15996]:viz::swp08::Probel_SWP08_Handler::RequestChannelFromSourceId: (VSMOut#, SourceId#) = (0, 3) (VSMOut#, VizCh#) = (0, 0). 

Second case: Requested SourceId# does not have a VSMOut# that is associated with VizCh#. In this case we need to do a CrossPointConnect using VSMOut that is both associated with a non-used SourceId# and is also associated with VizCh#. In this case we could not find it: None of the VSMOut in (VSMOut#, VizCh#) has a SourceId# = -1 in (VSMOut#, SourceId#). A release is needed first.

INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::PrintMap: (MatroxCh#, VSMOut#): (0, 15), (1, 0), (2, 3), (3, 12), (4, 4), (5, 5), (6, 6), (7, 7).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::PrintMap: (MatroxCh#, VizCh#): (0, 1), (1, 0), (2, 3), (3, 2), (4, 4), (5, 5), (6, 6), (7, 7).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::PrintMap: (VSMOut#, VizCh#): (0, 0), (3, 3), (4, 4), (5, 5), (6, 6), (7, 7), (12, 2), (15, 1).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::PrintMap: (VSMOut#, SourceId#): (0, 3), (1, 2), (2, -1), (3, 10), (4, 0), (5, 4), (6, 8), (7, 5), (8, 0), (9, -1), (10, -1), (11, -1), (12, 3), (13, -1), (14, -1), (15, 4).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::RequestChannelFromSourceId: vsmout NOT found in (VSMOut#, SourceId#) that has an associated vizch in (VSMOut#, VizCh#) with given sourceId (12).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::RequestChannelFromSourceId: could not find first vsmout in (VSMOut#, VizCh#) with sourceId (-1) in (VSMOut#, SourceId#).

Third case: From the above state, after releasing we can request again.

INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::PrintMap: (MatroxCh#, VSMOut#): (0, 15), (1, 0), (2, 3), (3, 12), (4, 4), (5, 5), (6, 6), (7, 7).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::PrintMap: (MatroxCh#, VizCh#): (0, 1), (1, 0), (2, 3), (3, 2), (4, 4), (5, 5), (6, 6), (7, 7).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::PrintMap: (VSMOut#, VizCh#): (0, 0), (3, 3), (4, 4), (5, 5), (6, 6), (7, 7), (12, 2), (15, 1).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::PrintMap: (VSMOut#, SourceId#): (0, -1), (1, 2), (2, -1), (3, 10), (4, 0), (5, 4), (6, 8), (7, 5), (8, 0), (9, -1), (10, -1), (11, -1), (12, -1), (13, -1), (14, -1), (15, 4).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::RequestChannelFromSourceId: vsmout NOT found in (VSMOut#, SourceId#) that has an associated vizch in (VSMOut#, VizCh#) with given sourceId (12).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::RequestChannelFromSourceId: found first vsmout (0) in (VSMOut#, VizCh#) with sourceId (-1) in (VSMOut#, SourceId#).
INFO: VizEngine-0[16012]:viz::swp08::Probel_SWP08_Handler::RequestChannelFromSourceId: (VSMOut#, VizCh#) = (0, 0) (VSMOut#, SourceId#) = (0, 12).