Hacking Cinegy ‒ Cinegy Type

Reading time ~5 minutes

This post provides details on how Cinegy Type templates can be updated from the external data source like Excel file or RSS using built-in Windows OS PowerShell scripting. Source codes are also available for the reference.

Introduction

The idea behind Hacking Cinegy presentations during TechCon 2017 is to demonstrate tips and tricks that can be used to extend functionality of your products using open Cinegy architecture and APIs. The latest demo showed the following features:

Type Templates Data From Excel or RSS

The existing Type API allows operator to update CG templates data dynamically from external sources. This post provides details on how template data can be updated from the external Excel file or RSS feed.

All sources are available for download on Cinegy GitHub.

General Concept

The main idea behind the demo is the following:

  • Prepare a sample news template with exported variables to be filled in dynamically;

  • Set up the template to update visual content when new data is available;

  • Create an external "controller" that will push data to template using API;

  • Read data from the external source (Excel file or RSS) and provide it to the controller.

Preparing the News Template

The news template contains the following objects:

  • news title (background plate and static text);

  • news text (background plate and static text).

The default duration for the template is set to about 7 seconds. Small text IN and OUT animations are added to make visual experience more attractive.

Type Editor

In order to be accessible for the external data providers, the corresponding text is linked to the variable.

Dynamic Updates

In order to apply the new data only when the scene is restarted (to avoid glitches on the screen when the text is updated in the middle of the previous news item), each variable is also marked with the "Restart" or "Autorestart" trigger. Also, to allow pushing and display of several news items at ones, the "Queue" parameter should be checked:

Variables in Type Editor

When all the steps described above are done, the template is ready to be put on-air and updated dynamically with new data.

Pushing Data On-air

Each Cinegy Playout engine exposes WEB API that can be used to send Type data updates dynamically. To access the API, the following URL should be used:

http://<host>:<port>/postbox

The format of the URL is the following:

  • <host> – defines the IP address or host name of the machine running Cinegy Playout;

  • <port> – defines the Cinegy Playout instance number to send updates to.

    Note
    		 The port number equals 5521 + InstanceNumber (zero-based).

The Playout WEB API expects the update to be sent via the HTTP POST call as an XML segment describing one or several variables updates:

<PostRequest>
    <SetValue Name="Name1" Type="text" Value="Val1"/>
    <SetValue Name="Name2" Type="text" Value="Val2"/>
    <SetValue Name="Name3" Type="text" Value="Val3"/>
</PostRequest>

The name of the variable to update should correspond to the name of the exported Type template variable.

Reading Data from Excel

There are several ways of reading the data from Excel files depending on the availability of Microsoft Office on the machine, required performance, etc. The selected approach is based on the PowerShell Data Basics: File-Based Data article.

In a nutshell – it is better to transform an Excel file to a CSV file via a single command and then use native PowerShell functionality to read data than read data directly from Excel workbook cells as it results in better performance and flexibility.

All the helper functions are moved to a separate Helpers-Excel.ps1 file in order to keep the script readability.

The PowerShell script reads data from the Excel file using the provided helper function Excel-ImportData.

Once the data is available, the required Type template is activated on the corresponding Cinegy Playout instance via the WEB API command. This ensures that the template is loaded into the required CG layer and is visible.

After the initialization step, the variables update command is sent to the Cinegy Playout instance using the provided helper function Type-UpdateVariable.

Web API

As variables are configured on queuing and their update results in automatic scene restart, running of the script will lead to the creation of a whole news list. The items in this list will be displayed on playout automatically one by one.

Reading Data from RSS

The update from RSS samples follows the same approach that is described in the previous section with the only difference that data is read from several RSS sources instead of a single Excel file.

The PowerShell script uses a complimentary simple XML file that defines the RSS sources to be scanned for the news items:

<rssfeeds>
    <feed name="World" url="http://rss.cnn.com/rss/edition_world.rss"/>
    <feed name="U.S." url="http://rss.cnn.com/rss/edition_us.rss"/>
    <feed name="Travel" url="http://rss.cnn.com/rss/edition_travel.rss"/>
    <feed name="Video" url="http://rss.cnn.com/rss/cnn_freevideo.rss"/>
</rssfeeds>

The name of the feed is used as a news item category and the actual news item text is taken from the corresponding RSS item using the provided helper function RSS-GetItems. In order to limit the number of news items display per category, the script variable $newsToDispaly is initialized with the corresponding value.