Media Server Integration

Since: TVS 6.7.0

Television Simulator can browse and play media from one or more Jellyfin or Plex servers. Media servers are configured once at the top level of the config file and exposed to menu themes through a shared provider interface.

The hypercom1998 theme’s menu is currently the first to use this system. It adds Movies, TV, and Music to the main menu whenever at least one media server is configured. With one server, TVS opens that library directly. With multiple servers, it asks which server to use first, then shows results only from that server.

Under construction!

You must use the hypercom1998 menu theme to access media server features at this time; more themes will be updated in future releases.

Configuration

Add servers to the top-level mediaServers array. They are displayed in the order in which they are defined.

mediaServers:
  - name: Upstairs Office
    src: http://192.168.1.20:8096
    key: jellyfin-api-key
    type: jellyfin

  - name: Game Room
    src: http://192.168.1.21:32400
    type: plex

name

Required. Type: string

The name shown in server-selection and setup screens.

src

Required. Type: URL

The base URL of the Jellyfin or Plex server. It must be reachable from the browser running TVS. A trailing slash is optional.

type

Required. Type: jellyfin or plex

Selects the provider client used for the server.

key

Optional. Type: string

A Jellyfin API key or Plex access token. This can provide a shared default, but it does not need to be committed to the config file; a user can save a browser-local key instead.

userId

Optional. Jellyfin only. Type: string

The Jellyfin user whose libraries TVS should browse. When omitted, TVS first asks Jellyfin for the current authenticated user and falls back to the first enabled user visible to the API key. Set userId explicitly when the server has multiple users and the selected library matters.

Browser-stored credentials

Open the TVS graphical setup page and use Media Server Keys to enter, test, or replace a credential for each configured server. A saved browser key takes precedence over key in the config file. Use Default removes that override and returns to the config value.

This is especially useful for Plex because access tokens are tied to Plex accounts, and for installations where each TVS browser should use a different Jellyfin user.

Browser storage is not a secret vault

Media server keys are saved in local storage for the current TVS origin. They are not encrypted. For Plex specifically remember that your token grants access to your Plex account so outside of a LAN-only environment it shouldn’t be publicly exposed.

Changing a server’s type, src, or name gives it a new internal identity, so an existing browser-stored key will no longer apply. Save the key again for the changed server.

Supported libraries

Both current providers use the same TVS menus and built-in Audio Player and Video Player.

Section	Current behavior
Movies	Browse poster artwork and start the selected movie
TV	Play shuffled episodes; browse shows, show information, seasons, and episodes; play in order or shuffled; search shows and episodes
Music	Play a shuffled library queue; browse artists, albums, songs, and genres; search tracks; start an instant mix from a selected track

Jellyfin and Plex both support these sections, search, instant mixes, and negotiated video transcoding. TVS first attempts the preferred stream and can ask the provider for a compatible fallback when direct playback does not start. Long libraries are loaded in pages so browsing and playback can begin before the complete collection has been downloaded.

When a media-server application is suspended or the page reloads, TVS stores stable provider item IDs with the queue and refreshes the playable URLs before restoring it. Only one application queue is retained at a time.

Media support still depends on the browser, server configuration, available transcoders, and permissions of the account represented by the key.

Network requirements

TVS communicates directly from the browser to each media server. If a server works in its own web app but not in TVS, check that:

• src is reachable from the TVS device and uses the correct protocol and port.
• The server permits browser requests from the TVS origin.
• The access key can read the intended movie, television, and music libraries.
• The server can direct-play or transcode the selected media into formats supported by the browser.
• HTTPS pages are not trying to load media over blocked HTTP connections.

Use the Test button under Media Server Keys to verify the URL and credential before troubleshooting an individual media item.

If an individual file still fails, try it in the provider’s web player and check whether the server can transcode it to H.264 video with AAC audio or to browser-compatible audio. TVS reports a playback error and, for an audio queue, continues to the next playable item instead of remaining on an endless loading screen.