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
- Control Object without Transition Logic
- Control Object with Transition Logic Enabled
- Control Object Properties
Overview
ControlObject is the backbone of Vizrt's template-based broadcast workflow. It serves four primary roles:
Field collection: Discovers child Control* plug-ins (ControlText, ControlImage, ControlNum, etc.) and registers their editable fields into a unified field map.
Command protocol: Exposes an
inparameter that external applications (Viz Trio, Viz Pilot, Viz Multichannel, automation) use to read, write, list, and focus fields.VDF data model: Generates an XML schema describing all fields, types, defaults, and metadata consumed by newsroom systems for template editing.
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
TAKEcommand. 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 toOff, only directors withAuto Startenabled in the Director Editor start when the scene is taken in. This parameter is only used when Transition Logic is set toOff.
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
Create an object scene with a root container named
object.Add ControlObject to the root container.
Set Description to a human-readable name (for example, "Lower Third – Breaking News").
Enable Transition Logic.
Set Layer identifier to match a Toggle container on your master scene (for example,
BannerLyr).Set State identifier to a stop-point on the layer director (for example,
LOWERTHIRD).Set Background scene to the master scene name (for example,
default).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, |
Background scene | empty | Master scene name (name only, not a full path). Must not contain |
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, |
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 |
Script (deprecated) | empty | Trio client script name. Deprecated, use Logicmaker instead. |
Entries (manual) | template | Manually defined field entries in |
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 |
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 |
|---|---|
| Set a field's value. Dispatches to the bound Control* plug-in or TCP location. |
| Read a field's current value. |
| Move the GUI focus to the field's container (useful for interactive editing). |
| Return all field definitions in |
| Return the full VDF XML data model (schema + scene data + directors + TL metadata). |
| Apply a VDF payload XML to set multiple fields at once. |
| 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_fieldExamples
# Text field bound to a geometry text nodevotes:$top$label*GEOM*TEXT:integer:0:100:8:Percentage of votes# Text field with no constraintsname:$bottom$name*GEOM*TEXT:::::Name of person# Float field via direct TCP pathzoom: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 levelTransition 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
Newsroom app (Trio/Pilot) sends data via the
inprotocol.The object scene is merged into the master scene's Toggle layer.
Toggle performs an A/B swap, animating the old graphic out and the new one in.
The layer director executes
GOTO_TRIOfrom 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 ( |
See Also
