Character Generator

The Character Generator engine is loosely based on the Texscan MSI SpectraGen 3 character generator. It is a flexible way to show text and titles and relies on JSON-based configuration files to determine what text to show and how to show it. These config files do not need to be edited by hand however and can be generated using an editor.

Using the Bulletin Editor

Before you can begin using the Character Generator engine you must create a configuration file for it to use. TVS 5.10 and later include this editor in the package.

Opening the editor

Navigate to http://[your TVS instance]/bulletin-editor. There is a public version available on the demo site as well.

How the editor works

The editor window exposes two panes:

Preview pane: Shows a preview of what will be displayed in TVS. You can change the resolution of the preview by entering its width and height in the text inputs below the preview as well as scale the preview down to fit it on screen better. You can also drag from the lower right corner of the preview to zoom in / out. There are actions to Import / Export JSON configuration files as well as a button to save your current configuration to the browser so that you don’t lose it if the page reloads. You can only save one configuration at a time currently; there’s a button to create a new project which will reset your browser’s stored configuration to a default one.
Editor pane: This is where you can edit what’s shown in your configuration. There are tabs for Header, Footer, and Pages.

Project structure

A Project is defined as a complete configuration file, including header, footer and pages.

Headers and footers are optional and affixed to the top and bottom of the page. They can be edited in their respective tabs and turned off independently using the “Header / Footer enabled” checkboxes.

Projects contain one or more pages of data. The Character Generator engine will cycle between these pages, scrolling long pages with too much text to fit on screen automatically.

Pages are made up of Lines, and lines are made up of Chunks of text. Each of these components has their own settings.

Pages

Pages can be added and removed using the Add Page and Delete buttons, as well as reorganized using the Up and Down buttons. You can duplicate an existing page using the Duplicate button. You must have at least one page at all times.

Memo: a note that’s only visible in the editor. This is used to identify the page in the editor.
Background / foreground colors: you can override the default colors per-page. For all color pickers you can choose from a palette of colors or specify any color manually.
Custom background image: you can use CSS background shorthand syntax to attach a background image or gradient. Use url(http://path-to/your-image.jpg) to use a background image or use a CSS gradient generator to create a background gradient.
Font: you can override the default font with a selection of pixel fonts as well as default browser fonts.
Vertical Alignment: by default pages are aligned to the top of the screen, but you can change this here. Perfect for centered title screens or ads.
Transitions: when the page is shown or hidden you can choose from a variety of fades, wipes and slide transitions and adjust their timing settings in milliseconds.
Text Reveal: the page’s lines can be shown sequentially using a number of effects and timings.

Lines

Lines of text can be added using the Add Line button and existing lines can be reordered using the *. You can remove

Line Type: there are currently two different types of lines:

Text: rich text which consists of chunks of text which can be formatted differently.
Clock: time and date display which updates automatically.

Depending on the line type, certain options may be unavailable.

Font: applies to all text chunks in this line unless overridden.
Alignment: whether to align text on this line to the left, right or center.
Font size: how big to make the fonts on this line, unless overridden per-chunk.
Line height: spacing between each line. Use to tighten up or loosen spacing within a paragraph.
Text width: stretches or compresses text on the line. Use to fit more text on a line or emphasize text.
Padding: CSS syntax padding for adding custom spacing between lines on the top, right, left and bottom of the line. Usually four values in the format top left right bottom. So for instance if you’d like some space on the bottom of a line you might say 0 0 0 1rem meaning nothing on the top, left, or right but 1rem on the bottom. For the format you can use px for pixels or rem for a relative unit based on font size, or any other valid CSS unit.
Colors: the default colors per line; can be overridden per chunk.
Character Styles: customizable shadow and outline effects which can be applied with custom colors. They can be used for style or to make text more visible.
Borders: top and bottom borders can be applied to lines with different colors and styles for each.
Crawls: you can apply a crawl / news ticker effect to a line with adjustable speed. Lower numbers indicate a lower speed and higher numbers will make the text scroll faster.

Chunks

Chunks of text will be displayed on the same line as each other.

Text area: this is where you enter the text that’s displayed on the screen. We’ll wrap lines automatically unless you’re using a Crawl effect on the line.
Colors: you can override background and foreground colors per chunk.
Font: you can specify a font override per chunk.
Font size: you can override font sizes per chunk.
Bold, Italic, Underline effects can be assigned per-chunk.
Blink: text can blink with custom timings in milliseconds (time visible and time hidden)
Color cycle: an animation that can be added to change text color per-letter with custom colors and timing.

Working with Dynamic Data

There are three types of dynamic data available for use in the Character Generator:

Variables: you can turn any chunk into a variable by assigning it a Variable Key. This will allow you to replace data at a later date using TVS YAML or an external JSON file.
Block Groups: you can turn a line or collection of adjacent lines into a Block Group by assigning it a Block Key. This allows you to repeat one or more consecutive lines as a group and any variables within will be replaced too.
Page Groups: Repeated pages of data which can contain Block Groups and Variables scoped to the page.

Using the editor, assign a page key (in the ribbon under Pages > General). Assign block keys or variable keys under the “Programmability” tabs for lines and chunks.

Visit the Data tab and you’ll see a list of all detected keys. You can add repeating pages and blocks of data here as well as assign local and global variables.

Preview in TVS will open up a draft of the current project including all its data.
Use the Export Channel button to generate YAML that you can paste into your TVS config file.
Use the Export Datafile button to export a JSON file which can be used as-is or as a reference for implementing custom server-side dynamic data.

Using the Character Generator Engine

Once you’ve exported your project from the Bulletin Editor as a JSON layout template, it’s time to put it to use!

character-generator:
    src: /content/bulletins/community-board.json

character-generator:
    src: /content/bulletins/community-board.json
    data: /content/bulletins/community-board-data.json
    refreshInterval: 300
    scrollSpeed: 24
    scrollDelay:
        before: 1
        after: 2

character-generator:
    src: /content/bulletins/weather-headlines.json
    variables:
        stationName: WGCW
        headline: Community Cleanup Saturday
    lines:
        closings:
        - schoolName: Lincoln High School
            status: Closed
        - schoolName: Washington Elementary
            status: Delayed 2 Hours
    weather:
        provider: weatherapi.com
        apiKey: ${WEATHERAPI_KEY}
        query: 94103

Description: Controls which page or page group to start on.

Use a number to select a zero-based page or page group index from the template.
Use random to start on a random page or page group.
Use previous to resume the last page or page group displayed on this channel for this component.
Use next to continue from the page or page group after the last one shown on this channel for this component.
Use first to always start from the first page or page group.

`showBlankBlockGroups`

Type: boolean

Default: false

Since: TVS 5.10.0

Description: If true, block groups with no matching dynamic line data are still shown and their placeholders remain visible.

`showBlankPageGroups`

Type: boolean

Default: false

Since: TVS 5.10.0

Description: If true, page groups with no matching dynamic page data are still shown and their placeholders remain visible.

`variables`

Type: Record<string, string> | string

Since: TVS 5.10.0

Description: Variable values used to replace bulletin chunks tagged with matching variable keys. You can provide them inline or point to a JSON URL that returns the same object shape.

`lines`

Type: Record<string, Record<string, string>[]> | string

Since: TVS 5.10.0

Description: Repeating line groups used to duplicate lines tagged with a matching repeat key in the template. Each top-level key is a block group name, and each array entry provides variable values for one repeated copy of that line group.

`pages`

Type: Record<string, ICharacterGeneratorRepeatingPageEntry[]> | string

Since: TVS 5.10.0

Description: Repeating page groups used to duplicate pages tagged with a matching repeat key in the template. Each top-level key is a page group name, and each array entry represents one generated page.

`variables` sub-property

Type: Record<string, string>

Description: Variable overrides applied to a single repeated page entry.

`lines` sub-property

Type: Record<string, Record<string, string>[]>

Description: Repeating line groups applied to a single repeated page entry.

`weather`

Type: IWeatherFramework

Since: TVS 5.10.0

Description: Optional weather data configuration for bulletin templates that request weather information.

`units` sub-property

Type: metric | imperial

Default: metric

Description: Units used for weather values.

`provider` sub-property

Type: usa | weatherapi.com | wttr.in

Default: usa

Description: Weather provider to use.

usa: Uses the built-in USA provider.
weatherapi.com: Uses the WeatherAPI.com provider.
wttr.in: Uses the wttr.in provider.

Since: weatherapi.com and wttr.in are available in TVS 5.10.0.

`apiKey` sub-property

Type: string

Since: TVS 5.10.0

Description: API key for the selected weather provider. This is not required for usa or wttr.in, but it is required for weatherapi.com.

`query` sub-property

Type: string

Since: TVS 5.10.0

Description: Query string for providers that support named or special location lookups. This is supported by wttr.in and weatherapi.com.

Examples include London, 94103, @github.com, and ~Eiffel Tower.

Character Generator

Using the Bulletin Editor

Opening the editor

How the editor works

Project structure

Pages

Lines

Chunks

Working with Dynamic Data

Using the Character Generator Engine

Properties

src required

data

refreshInterval

scrollSpeed

scrollDelay

before sub-property required

after sub-property required

limit

manualAdvance

startingPage

showBlankBlockGroups

showBlankPageGroups

variables

lines

pages

variables sub-property

lines sub-property

weather

units sub-property

provider sub-property

apiKey sub-property

query sub-property

`src` required

`data`

`refreshInterval`

`scrollSpeed`

`scrollDelay`

`before` sub-property required

`after` sub-property required

`limit`

`manualAdvance`

`startingPage`

`showBlankBlockGroups`

`showBlankPageGroups`

`variables`

`lines`

`pages`

`variables` sub-property

`lines` sub-property

`weather`

`units` sub-property

`provider` sub-property

`apiKey` sub-property

`query` sub-property