Interactive Applications

Since: TVS 6.7.0

Applications are interactive, full-screen experiences that run on a special APP “channel” (it isn’t really a channel, but you can think of it as one) which is only available while an app is running. Television Simulator includes built-in Audio and Video Player applications and can load your own web applications in an IFrame.

Applications use special remote input. Navigation, media transport, colored, and numeric controls can be delivered to the active application. Channel Up and Channel Down are always reserved however: press either button once to display an exit warning, then press them again within three seconds to suspend the application and change channels.

Under construction!

Both the default and Hypercom 1998 menus can launch configured applications, but currently only the Hypercom theme supports media server integration.

When you leave an application with Back, TVS suspends it and restores the menu page and selection that launched it. Opening the menu with Menu starts again at the main menu.

The APP input and saved state

Only one application can run at a time. While it is active, tuner and information OSDs display the application’s own name, title, summary, artwork, and audio information instead of metadata from the previous channel.

Launching another application replaces the saved one. Upon a Factory Reset the app is closed.

Built-in applications

The built-in applications are used by media server integration and can also be configured globally under applications.

Video Player

The Video Player plays one video or a queue using the same media support as the Video engine. It supports Play, Pause, Stop, Fast Forward, Rewind, and Select. The default player theme seeks in ten-second steps. The vcr theme provides stepped fast-forward and reverse-scan effects. When a preferred source cannot start, provider-backed videos can negotiate a browser-compatible fallback stream.

Audio Player

The Audio Player plays individual tracks and playlists, advances through queues, and exposes playback information to compatible OSDs. Play, Pause, Stop, Fast Forward, Rewind, and Select control playback. Its colored controls are:

Control	Action
Red / Green	Previous or next visualizer
Yellow	Show or hide the visualizer
Blue	Show or hide song and time information

Using the numeric buttons on the remote will activate audio effects. One can be active at a time and to disable effects you can press 0. There are currently 7 effects available, so check ‘em out!

Speed effects require a finite audio file and are unavailable for live streams. Other effects also depend on the browser allowing TVS to process the source through the Web Audio API.

Built-in application settings

Use the reserved _videoPlayer and _audioPlayer entries to change the built-in players. IDs beginning with an underscore are reserved by TVS and are not shown as custom applications.

applications:
  _videoPlayer:
    theme: vcr
    combinePlayAndPause: true

  _audioPlayer:
    theme: default
    combinePlayAndPause: true
    themeOptions:
      showSongInfo: true
      showTime: true
      showVisualizer: true

theme

Selects the player’s OSD theme. The Audio Player currently supports default. The Video Player supports default and vcr. An unknown value falls back to default.

combinePlayAndPause

Default: false

When true, either Play or Pause toggles between playing and paused. This is useful with remotes that provide only one combined play/pause control.

themeOptions

Audio Player theme options. The default theme accepts showSongInfo, showTime, and showVisualizer booleans.

Adding web applications

Categories

You must define at least one category in applicationCategories before adding applications.

applicationCategories:
  games: # the ID used by applications to refer to this category
    name: Games # name displayed in the menu
    icon: /placeholders/default-app-categories/games.png # optional icon for the category; only used by themes that support it (like the default theme)
    background: /placeholders/default-app-categories/games-bg.png # optional background image for the category; only used by themes that support it (like the hypercom1998 theme)

applications:
  blackjack: # the ID of the application; must not begin with an underscore
    category: games # refers to the ID above in applicationCategories
    title: Blackjack
    src: https://gcpw.art/tvs/games/blackjack/ # URL of the web application
    options: # options specific to this application
      startingBankroll: 300
      minimumBet: 5

Custom applications are loaded with scripts, same-origin access, and autoplay permission. The application URL must therefore be reachable by the browser running TVS and must permit iframe embedding.

Application IFrames do not accept mouse or touch input. TVS disables pointer events on them so clicking the picture cannot steal keyboard focus and leave the user unable to exit the app.

Data Persistence

TVS remembers which IFrame application was running and relaunches it with the same arguments after a refresh, but 3rd party apps need to take care of data persistence by themselves (for the application’s private internal state). An IFrame application that needs to restore a game or document should save that state itself.

To receive remote commands, audio state, launch options, and application lifecycle events, implement the Application IFrame API. The application API is separate from the standard TVS IFrame API.