image-20240919-105138.png

The Control Object plug-in provides control channels for subtrees of Viz Scenes.

To create a Viz Trio page template, a Viz Pilot template or a Viz Ticker template; each Scene must have at least one instance of Control Object. The control channel information is stored in the subtree itself, so the Scene subtree can be merged and stored as objects in the object pool. When a Control plug-in is added to a Scene, a Control Object plug-in is automatically added to the root container of the scene subtree to be controlled. Control Object stores and gathers field definitions which describe how values are processed and applied to various properties of the subtree. The easiest way to define fields is to place one or more Control plug-ins on containers within the subtree. These Control plug-ins find the Control Object and register properties related to the container they are placed on.

Note: For Viz Ticker it is possible to have more than one Control Object plug-in. It should be on the root container for the tab objects in the scene.

Note: This plug-in is located in: Plugins -> Container plug-ins -> Control

This page contains information on the following topics:

Overview

ControlObject is the backbone of Vizrt's template-based broadcast workflow. It serves four primary roles:

  1. Field collection: Discovers child Control* plug-ins (ControlText, ControlImage, ControlNum, etc.) and registers their editable fields into a unified field map.

  2. Command protocol: Exposes an in parameter that external applications (Viz Trio, Viz Pilot, Viz Multichannel, automation) use to read, write, list, and focus fields.

  3. VDF data model: Generates an XML schema describing all fields, types, defaults, and metadata consumed by newsroom systems for template editing.

  4. Transition Logic integration: Declares how the object scene should be loaded onto a master scene layer, which state to target, and which background scene to use.

Tip: In a Transition Logic workflow, the master scene(background scene) contains Toggle layers and directors. Object scenes (templates) each have a ControlObject on their root container that declares which layer and state they belong to.

Control Object without Transition Logic

In the simple scene based mode, Control Object should be put on the root container for the page tab-field containers. A description, which is used as template description in the control clients, should also be entered. To load the graphics in another rendering layer than the Middle (default), choose Front or Back. By using different layers up to three items can be on screen simultaneously without having to design a Transition Logic setup.

Note: Objects in the Back layer are rendered behind objects in the Middle and Front layer and so on, so the scenes must then be designed with that in mind.

Control Object with Transition Logic Enabled

With Transition Logic enabled, logical layer and state can be defined for the scene. These are used by the control clients to find out which transitions and animations to trigger when a page is put On Air or Off Air. These transitions and layers must all be defined in the background scene. A background scene name can also be set if a background scene other than the default (named default) is used.

Control Object Properties

Transition Logic Off

  • Description: Provides the description of the object the scene subtree represents. This description is typically presented to users in GUI applications that allow the user to fill in data that should be presented by the controlled object.

  • Transition Logic: Specifies whether the controlled object uses transition logic. Transition logic loads objects onto layers in a background scene, and runs animations to change the background scene layer into a required state.

  • Viz Layer: Determines the Viz layer to load the scene which contains the scene tree which contains this Control Object. This parameter is only used when transition logic is set to Off.

  • Use All Directors: Controls whether to play every director or only the default director in a non-transition logic scene, and takes effect when the Vizrt Media Sequencer triggers the TAKE command. When loading the scene into a control application such as Viz Trio, all directors in the stage start automatically when the scene is taken in. By changing this to Off, only directors with Auto Start enabled in the Director Editor start when the scene is taken in. This parameter is only used when Transition Logic is set to Off.

Example: The scene design incorporates an animated background which starts automatically when the scene is loaded. To avoid the background animation restarting when the scene is played out, set Use All Directors to Off .

  • Show advanced: See Control Object Advanced Properties.

  • Is Prototpye: By default, the VDF data model automatically collect all properties from all loaded subscenes and exposes them to the control application.
    Sometimes you do not want this to be visible, for example if a scene is used as a prototpye or placeholder. Enabling this option will prevent any control object of such a scene inside a host scene when being used e.g. as Subscene.

This does not affect scenes being loaded from GFX or Superchannels

Transition Logic On

Quick Start: Transition Logic Template

  1. Create an object scene with a root container named object.

  2. Add ControlObject to the root container.

  3. Set Description to a human-readable name (for example, "Lower Third – Breaking News").

  4. Enable Transition Logic.

  5. Set Layer identifier to match a Toggle container on your master scene (for example, BannerLyr).

  6. Set State identifier to a stop-point on the layer director (for example, LOWERTHIRD).

  7. Set Background scene to the master scene name (for example, default).

  8. Add child containers with ControlText, ControlImage, etc.: each with a field_id. ControlObject auto-discovers them.

Parameter Reference

Basic

Parameter

Default

Description

Description

empty

Human-readable template description shown in Viz Trio / Viz Pilot GUI.

Transition Logic

Off

Enables Transition Logic mode. When on, reveals layer/state/background fields.

Layer identifier

empty

Must match a Toggle container name and its director on the master scene. Case-sensitive.

State identifier

empty

Stop-point name on the layer director to animate to (for example, $LOWERTHIRD).

Background scene

empty

Master scene name (name only, not a full path). Must not contain / or \.

Filter Continues

Off

Filters CONTINUE commands from Toggle, preventing unintended director advances.

Viz Layer

MIDDLE

Renderer layer for non-TL scenes: FRONT, MIDDLE, or BACK.

Use All Directors

On

When on, triggers the entire stage (all directors). When off, only the Default director plays.

Is Prototype

Off

Exposing parameters to a host scene if used as subscene

Advanced

Revealed when Show advanced is enabled.

Parameter

Default

Description

Enable GFX subscene

Off

Allows this ControlObject to discover and forward commands to ControlObjects in GFX channels.

Subscene field definition

Merge

How GFX subscene fields are combined: Merge (flat), Merged subfield (grouped under one prefix), or Subfields (per-channel prefix).

Subscene field id/prefix

gfx

Prefix for subscene field IDs (for example, gfx1, gfx2).

Use custom duration

Off

Enables a custom display duration for interstitial/sponsor elements.

Duration

5.0

Display duration in seconds (only visible when custom duration is enabled).

Bind with Unreal Engine

Off

Maps field entries to Unreal Engine exposed ControlObjects.

Namespace prefix

empty

Prefix for propagating field IDs upward. Child field 1 becomes Prefix.1 on a parent ControlObject.

Script (deprecated)

empty

Trio client script name. Deprecated, use Logicmaker instead.

Entries (manual)

template

Manually defined field entries in key:location:type:min:max:maxchar:description format.

Remap fields

Off

Gives the control clients the list of entries in a map. For use in scenes with nested control object plug-ins. This feature is mainly for advanced integration use. When On, Control Object gives the control clients the list of entries in map, rather than the list of entries registered by control plug-ins below the Control Object in the scene tree, and manually entered entries from entries. When actions are performed on fields, the Control Object uses map to rename the field identifier before dispatching the action.

Input command/request

empty

The "in" protocol endpoint. Writing to this triggers command execution.

Result

empty

Read-only output of the last command.

Error

empty

Error output from the last command (max 64 KB).

Pending Result Chunks

0

Number of remaining result chunks for payloads exceeding 64 KB.

Actions

Action

Description

Store Stop Points

Serialises director stop-points into a hidden parameter so they survive object-pool merge.

Restore Stop Points

Recreates stop-points from stored data on the Toggle object director.

Refresh UE Control Objects

Reloads Unreal Engine ControlObject entries (only visible when Bind with Unreal is on).

The "in" Protocol

External applications communicate with ControlObject by writing commands to the in parameter. The result is returned via result; errors via error.

Command

Description

ON <field-id> SET <value>

Set a field's value. Dispatches to the bound Control* plug-in or TCP location.

ON <field-id> GET

Read a field's current value.

ON <field-id> FOCUS

Move the GUI focus to the field's container (useful for interactive editing).

LIST / LIST_ALL

Return all field definitions in key:location:type:… format.

GET_MODEL

Return the full VDF XML data model (schema + scene data + directors + TL metadata).

SET_MODEL <xml>

Apply a VDF payload XML to set multiple fields at once.

HIT <x> <y>

Returns the field ID for the container at the given screen coordinates.

Chunked I/O
For payloads exceeding 64 KB, the protocol supports chunked transfer. Send commands with CHUNK_START, CHUNK, CHUNK_END prefixes. Results larger than 64 KB are split into chunks retrieved via the Get Next Result Chunk action, monitored through Pending Result Chunks.

Manual Entry Format

The Entries text field supports manually defined fields using this format:

key:location:type:min:max:maxchar:description:aux_field

Examples

# Text field bound to a geometry text node
votes:$top$label*GEOM*TEXT:integer:0:100:8:Percentage of votes
 
# Text field with no constraints
name:$bottom$name*GEOM*TEXT:::::Name of person
 
# Float field via direct TCP path
zoom:MAIN_SCENE*TREE*$Browser*FUNCTION*Browser*zoom:float:0.0:-10.0:10.0:Zoom level
 
# Using control channels (@-addressing)
zoom:MAIN_SCENE*TREE*@zoom:float:0.0:-10.0:10.0:Zoom level

Transition Logic Integration

Architecture

A Transition Logic broadcast setup involves two scene types:

  • Master scene (background scene): Contains Toggle containers and directors for each layer (for example, BannerLyr, TickerLyr, ClockLyr).

  • Object scenes (templates): Each has a ControlObject on its root that declares which layer and state it targets.

How the Take Works

  1. Newsroom app (Trio/Pilot) sends data via the in protocol.

  2. The object scene is merged into the master scene's Toggle layer.

  3. Toggle performs an A/B swap, animating the old graphic out and the new one in.

  4. The layer director executes GOTO_TRIO from the current stop-point to the state declared by the ControlObject's State identifier.

Critical Naming Rules

Names must match exactly

  • Layer identifiermust match both the Toggle container name and its director name on the master scene.

  • State identifiermust match a stop-point ($-prefixed) on that layer director.

  • Background sceneis the scene name only — not a full Graphic Hub path.

  • All names arecase-sensitive.

Stop-Point Preservation

When an object scene is merged into the object pool, director stop-points are discarded. Use Store Stop Points to serialise them into ControlObject before saving. On load, Restore Stop Points recreates them on the Toggle's object director (<LayerName>O).

Namespace Propagation

When the Namespace prefix is set (for example, Header), field IDs propagate upward through parent ControlObjects or ControlLists. A child field with ID 1 becomes accessible as Header.1 on the parent.

When namespace is empty, the ControlObject acts as a registration boundary. Field IDs do not propagate upward, and Toggle treats it as a self-contained template.

GFX Subscene Support

When Enable GFX subscene is on, ControlObject discovers ControlObjects in active GFX channels and forwards commands to them. Three merge modes control how subscene fields appear:

Mode

Behavior

Merge

Subscene fields are merged flat into the parent's field list.

Merged subfield

Fields are grouped under a single prefix (set by Subscene field id/prefix).

Subfields

Each GFX channel gets its own prefix (gfx1, gfx2, etc.).

See Also