Refs (Referenced Content)

Content can be defined as a reference and reused in multiple places throughout your Television Simulator config file. You can override top-level properties of referenced content at the time that you use it.

refs section

In the TVS configuration file you can define reusable content by adding a refs section at the top level of the file.

Keys in the refs section are arbitrary names that you can use to reference the content later in the file.

refs:
  movie: # The reference "key". You can name this anything, but it must be unique, start with a letter, and only use letters, numbers, hyphens, and underscores.
    video: my-movie.mp4

  network-logo:
    image: images/logo.png

In the example above we’ve defined two pieces of reusable content: movie and network-logo. To use them, you’ll use the ref engine in a channel. So instead of:

channels:
- number: 1
  abbr: MOV
  video: my-movie.mp4

You would do:

channels:
- number: 1
  abbr: MOV
  ref: movie

And TVS will replace the ref: movie line with the content defined in the refs section.

Overriding properties

Properties in references can be overridden when you use them.

Caution

To override properties, you can’t use shorthand syntax when defining the reference.

refs:
  non-overridable-reference:
    video: my-video.mp4 # Cannot be overridden because shorthand syntax is used.

  overridable-reference:
    video:
      src: my-video.mp4 # Can be overridden because full syntax is used.

To override properties, you’ll use the ref engine in a slightly different way:

refs:
  movie:
    video:
      src: my-movie.mp4

channels:
- number: 1
  abbr: MOV
  ref:
    name: movie
    overrides:
      volume: 0

You’ll specify a name for the reference key you want to use, then define overrides with the properties you want to change.

The example above will render like this:

video:
  src: my-movie.mp4
  volume: 0

Nested references

You can nest references within other references for more complex reuse scenarios.

refs:
  ad1:
    image:
      src: placeholders/example-ad.webp

  ad2:
    mix:
      a:
        ref: ad1
        mixMode: difference
      b:
        ref: intro
        mixMode: exclusion

In the example above, the ad2 reference uses the ad1 reference within a mix layout.

Danger

Beware of circular references! If a reference points to another reference that eventually points back to the original reference, it will create an infinite loop and likely crash TVS.

TVS does not currently detect circular references, so it’s up to you to avoid them.

# **Do not do this, and do not do anything like this!**
refs:
  ref-a:
    ref: ref-b

  ref-b:
    ref: ref-a