Content Engine Primer

Tip

Read this first to understand how to use the reference documentation effectively!

Examples

Each content engine has its own page, and they are structured similarly. We begin with a brief summary and a screenshot followed by YAML code that shows how to use the engine in a channel.

For instance, you might see something like this:

image: /content/images/my-image.jpg

To use it, put it in a channel:

channels:

- number: 123
  name: My channel
  abbr: EXAMPLE
  image: /content/image/my-image.jpg # <-- the content engine goes here

Or in a layout:

channels:

- number: 123
  name: My channel
  abbr: EXAMPLE
  loop:
  - image: /content/images/my-image.jpg # <-- here
    duration: 10
  - image: /content/images/my-image-2.jpg
    duration: 5

Or even in a reference:

refs:
  ad1:
    image: /content/images/my-image.jpg # <-- here

channels:

- number: 123
  name: My channel
  abbr: EXAMPLE
  ref: ad1

Properties

After the examples you’ll get an exhaustive list of unique properties for each content engine. These properties can be used to customize the behavior and appearance of the engine in your channels and layouts.

Properties that can apply to any engine won’t be displayed on every page but instead are available below:

_component section

Type: object

Since: TVS 5.11.0

Beginning in TVS 5.11.0, the _component property groups options that can apply to any content engine. Right now it contains the dimensions property, which lets you define a virtual video signal for the component.

This is useful when you need to render content for a specific target resolution while still letting the containing channel, layout, or parent component scale it to fit the available space.

generator:
  type: test-pattern
  _component:
    dimensions:
      width: 1280
      height: 720
      aspectRatioBehavior: contain

_component.dimensions

Type: object

Defines the size of the component’s internal work area in pixels. Think of this as a simulated video signal that the component renders into before it is scaled into its container.

width

Type: number

Width of the work area in pixels.

height

Type: number

Height of the work area in pixels.

aspectRatioBehavior

Type: 'stretch' | 'cover' | 'contain'

Default: contain

Controls how the virtual video signal is fitted into its container, which may be the root channel area, a layout region, or another component.

• stretch: Warps the signal to the exact size of the container. This can distort the aspect ratio.
• cover: Scales the signal until the entire container is covered. This can crop the image.
• contain: Scales the signal to fit entirely within the container. This can add letterboxing or pillarboxing.

_component.audio

Type: object

Since: TVS 6.0.0

The _component.audio section configures managed audio for a single rendered component.

When the component is mounted, TVS can start a managed audio source and apply routing rules to other active audio. When the component is unmounted, its managed audio and routing effects are removed.

If src is omitted, the component does not create a new player, but it can still participate in routing via group, priority, and interrupts.

image:
  src: /content/images/sponsor.png
  duration: 8
  _component:
    audio:
      src: /content/audio/vo-sponsor.mp3
      group: voice
      priority: 10
      interrupts:
      - behavior: duck
        duckTo: 0.2
        groups: [music]

src

Type: string

Audio file or stream URL for this component’s managed audio. If omitted, this entry only controls routing for other managed audio while the component is visible.

group

Type: string

Default: default

Named routing group for this source. Common values include music, voice, ambience, and sfx.

priority

Type: number

Default: 0

Priority used by managed audio routing. Higher-priority sources can affect lower-priority sources using interrupts.

loop

Type: boolean

Default: true

Whether this source repeats when playback ends.

interrupts

Type: IAudioInterruptRule[]

Routing rules this source applies to lower-priority sources while it is active.

Each rule supports:

• groups?: string[] - Which groups are affected. If omitted, all lower-priority groups are affected.
• behavior?: 'mute' | 'duck' - How matching groups are affected. Default is mute.
• duckTo?: number | false - Target gain multiplier when behavior is duck, from 0 to 1. Default is 0.25.

Base audio options

_component.audio also supports all standard background audio fields:

• volume?: number | false - Volume from 0 to 1. Default 1. 0 or false mutes.
• filterType?: 'lowpass' | 'highpass' | 'bandpass' | 'lowshelf' | 'highshelf' | 'notch' | 'allpass' - Optional filter type.
• filterFrequency?: number - Filter frequency in Hz. Default 0.
• noise?: number | false - Noise amount from 0 to 1. Default 0.
• corsMitigation?: boolean - Disables audio processing when CORS headers are missing. Filter options will not work when enabled.
• description?: string - Text shown in OSD metadata.
• nowPlayingUrl?: string - URL to fetch now playing information.
• nowPlayingProvider?: string - Provider for now playing fetch behavior.
• shufflePlaylist?: boolean - Whether playlist sources are shuffled. Default false.

For behavioral details of these base options, see Background Audio Options.

Shorthand Properties

shorthand properties are marked in blue and are properties that can be set using shorthand syntax; instead of saying:

image:
  src: /content/images/my-image.jpg

you can simply write:

image: /content/images/my-image.jpg

You can’t provide any other options with this shorthand syntax, but it is useful for simple cases such as when you just want to display an image or a video without any additional configuration.

Default Values

If there are multiple options for an optional property the default value will be labeled like this. Other available values will be in gray.