Guide Channels

FieldStation42 has two types of guide channels.

The classic guide is built directly into the player. It renders a scrolling schedule grid using Python and Tkinter, supports rotating messages and images in the header, and plays background music. It is configured entirely through JSON and has no external dependencies beyond the base install.

The custom guide is a web-based guide that runs inside FieldStation42's web channel component. It comes with three decade-themed visual styles (80s, 90s, 00s), supports background music, video panels, and rotating text messages, and can be extended with your own CSS themes. It requires the web channel dependencies to be installed.

For quick copy-paste configs for both types, see Recipe 5 in the Channel Recipes guide.

Classic Guide Channel

The classic guide is the simplest option. Set network_type to "guide" and point it at your FieldStation42 server. The example config is the best starting point:

cp confs/examples/guide.json confs/

Basic Configuration

{
  "station_conf": {
    "network_name": "Guide",
    "network_type": "guide",
    "channel_number": 3,
    "play_sound": true,
    "sound_to_play": "runtime/guide_music/",
    "scroll_speed": 1.0,
    "messages": ["FieldStation42", "Cable Entertainment"],
    "images": ["runtime/guide/image0.png", "runtime/guide/image1.png"]
  }
}

sound_to_play accepts a single file, a directory (shuffles and loops), or a list of files. The upper section of the guide rotates between images on the left and messages on the right. If you use both, match the count so they stay in sync.

Messages and Images

Images appear in the upper left; messages appear in the upper right. Both rotate at message_rotation_rate seconds. To keep them in sync, use the same number of images and messages.

Messages support newlines (\n) for two-line display:

{
  "station_conf": {
    "network_name": "Guide",
    "network_type": "guide",
    "channel_number": 3,
    "content_dir": "catalog/guide_content/",
    "messages": [
      "FieldStation42\nCable Entertainment",
      "Cheers!\nFrom us to you!",
      "FieldStation42 Guide\nOn cable mode."
    ],
    "images": [
      "runtime/guide/image0.png",
      "runtime/guide/image1.png",
      "runtime/guide/image2.png"
    ]
  }
}

Make sure all image paths exist before starting. A missing file will prevent the guide from launching.

For a full list of layout, font, color, and sizing options, see the Classic Guide Appearance Reference at the bottom of this page.

Custom Guide Channel

The custom guide runs as a web channel pointed at the built-in guide endpoint. All configuration is in the URL.

{
  "station_conf": {
    "network_name": "Guide",
    "network_long_name": "Guide Channel",
    "channel_number": 3,
    "network_type": "web",
    "web_url": "http://localhost:4242/static/customguide/customguide.html?theme=90s&slots=3"
  }
}

This requires the web channel dependencies. See Recipe 7: Web Channel for setup instructions.

URL Parameters

All custom guide configuration is passed as URL parameters:

Decade Themes

80s

Vertical scrolling list. Channels are grouped under time-slot headings and scroll continuously from top to bottom, pause, then rebuild with fresh data.

Deep navy background, CGA-palette colors: cyan channel numbers, green channel names, yellow time headings, white titles. Monospace font. No video panel.

Background music loads automatically if a ?music= directory is provided, or falls back to a bundled music_playlist.json if present in the customguide static directory.

90s

Split-screen layout. The top section has a video player on the left cycling through clips and a rotating text carousel on the right. The bottom is a horizontal schedule grid.

Deep blue palette, yellow time headings and channel names, white titles. Boxy flat blocks with a faint raised-relief border. Matches the look of late-90s digital cable guide channels.

Expects 4:3 aspect ratio video clips. Music only plays if ?music= is passed.

00s

Same split-screen layout as 90s. Red rounded channel pills, pill-shaped time slot labels, rounded program blocks. Cleaner and more polished. Matches early-2000s digital cable guide aesthetics.

Expects 16:9 aspect ratio video clips. Music only plays if ?music= is passed.

Assets

Music

Put audio files in any directory under runtime/ and pass the path via ?music=:

runtime/
  guide_music/
    track1.mp3
    track2.ogg

...&music=runtime/guide_music/

Supported formats: .mp3, .ogg, .wav, .flac, .aac, .m4a, .opus

Videos (90s and 00s themes)

Put video files in runtime/guide_videos/. This directory is scanned automatically with no URL parameter needed. If the directory is empty the video panel hides itself.

runtime/
  guide_videos/
    promo1.webm
    bumper2.webm

The guide runs inside Qt WebEngine (Chromium-based), which on Linux does not support H.264 MP4 without additional GStreamer plugins. Convert your videos to WebM/VP9 first:

ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 33 -b:v 0 -c:a libvorbis output.webm

WebM/VP9 works reliably in Qt WebEngine on Raspberry Pi and desktop Linux.

Text Messages (90s and 00s themes)

The text carousel in the info panel loads from a JSON file. Pass the file path via ?messages=:

{
  "messages": [
    {
      "title": "Coming Up Next",
      "body": "Classic films all afternoon on Channel 7.",
      "duration": 10
    },
    {
      "title": "Did You Know?",
      "body": "FieldStation42 supports over 50 channels.",
      "duration": 8
    }
  ]
}

• title: displayed in the accent color. HTML is allowed.
• body: displayed in white. Plain text only.
• duration: seconds to show this message. Defaults to the theme's --text-carousel-speed (10 seconds).

If no messages file is provided, the panel shows "FieldStation42" as a static placeholder.

Creating a Custom Theme

A theme is a single CSS file placed in fs42/fs42_server/static/customguide/themes/. The filename is the theme name: mytheme.css is loaded with ?theme=mytheme.

The theme sets CSS custom properties on :root. The structural CSS uses these variables with sensible fallbacks, so you only need to define what you want to change.

Layout mode

--layout-mode: "list";   /* 80s-style scrolling list */
--layout-mode: "grid";   /* 90s/00s-style split-screen grid */

This is the most important variable. It controls which DOM layout the JS builds at startup.

Music autoload

--music-autoload: true;   /* fall back to bundled music_playlist.json if ?music= not passed */
--music-autoload: false;  /* only play music if ?music= URL param is set */

CSS Variables Reference

Layout and behavior

Colors

Typography and spacing

Scrolling (list mode)

Audio

Grid mode: top panel

Grid mode: channel column

Grid mode: header and time slots

Grid mode: program blocks

Classic Guide Appearance Reference

All of these can be overridden directly in your station config alongside network_type and the other standard fields.

Color values use Tkinter color names (e.g. "blue3", "white", "yellow") or hex strings (e.g. "#1a1a2e").