Station Configuration Reference

This document describes the configuration format for FieldStation42 station/channel configurations.

Overview

Each station is configured via a JSON file in the confs/ directory. The configuration file must contain a top-level station_conf object with the station's settings.

Minimal Configuration

{
  "station_conf": {
    "network_name": "MyChannel",
    "channel_number": 5
  }
}

All other properties have sensible defaults applied by the system.

Default Values

If not specified, the following defaults are automatically applied:

Required Properties

Only two properties are strictly required:

Network Types

The network_type property determines how the station operates:

Top-Level Properties

General Properties

Scheduling Properties (Standard Networks)

Directory Paths

Media Files

Data Files

Clip Shows

Clip shows can be specified as: - Simple string: "show_tag" (defaults to 60-minute duration) - Object: {"tags": "show_tag", "duration": 30} (duration in minutes)

Example:

"clip_shows": [
  "quickstop",
  {"tags": "variety", "duration": 30}
]

The system automatically adjusts durations based on break_strategy to account for commercial time.

Active Rules

Active rules allow you to conditionally load a station configuration based on date ranges. If the active rules are not met, the configuration file will not be loaded on startup.

Supported Rules:

When date_range is specified, the configuration will only be loaded if the current date falls within the specified range (inclusive). The format uses full month names (capitalized) followed by the day of month, separated by a space-hyphen-space sequence.

Example:

"active_rules": {
  "date_range": "December 1 - January 2"
}

This would make the configuration active only during the holiday season from December 1st through January 2nd.

Note: If the date range does not parse correctly, a warning will be logged and the configuration will still be loaded.

Fallback Content

When the scheduler cannot find content matching the scheduled tags (e.g., due to filtering or empty catalog), it will attempt to use content from the fallback_tag directory instead. This is useful for generic content that should only play when all other scheduled content has been filtered out.

Example:

"fallback_tag": "generic-content"

If no fallback_tag is specified and content is not found, the scheduler will generate an error and stop.

Display Properties

Video Effects

Available video_scramble_fx values: - horizontal_line - Classic cable horizontal line scrambling - diagonal_lines - Deep scrambling with diagonal patterns - static_overlay - Static distortion overlay with rapid effects - pixel_block - Heavy pixelation with random blocks - color_inversion - Horizontal bars with inverted colors - severe_noise - Intense noise effect - wavy - Wavy distortion pattern - random_block - Random block replacement distortion - chunky_scramble - Complex realistic scramble effect - spicy - Spicy scrambling effect

On-Screen Display (Logo) Properties

Web Network Properties

Guide Network Properties

Guide Audio Examples

Single audio file:

{
  "network_type": "guide",
  "play_sound": true,
  "sound_to_play": "runtime/guide/background.mp3"
}

Directory of audio files (automatically finds all .mp3 files and shuffles):

{
  "network_type": "guide",
  "play_sound": true,
  "sound_to_play": "runtime/guide/music"
}

Note: Trailing slash is optional - any valid directory path will be auto-detected and expanded

Explicit shuffle playlist (plays files in random order, looping indefinitely):

{
  "network_type": "guide",
  "play_sound": true,
  "sound_to_play": [
    "runtime/guide/track1.mp3",
    "runtime/guide/track2.mp3",
    "runtime/guide/track3.mp3",
    "runtime/guide/track4.mp3"
  ]
}

Streaming Network Properties

Each stream object contains:

{
  "url": "https://example.com/stream.m3u8",
  "duration": 30,
  "title": "Stream Title"
}

Day Scheduling

Standard networks require all 7 days to be defined (even if they're empty {}). Days are specified using lowercase full names:

• monday
• tuesday
• wednesday
• thursday
• friday
• saturday
• sunday

Direct Scheduling

Define hour-by-hour slots directly:

"monday": {
  "0": {"tags": "late-night"},
  "1": {"tags": "late-night"},
  "6": {"tags": "morning"},
  "12": {"tags": "daytime"},
  "20": {"tags": "primetime"}
}

Note: Hours not specified are treated as off-air. Days can be empty objects {} if the entire day is off-air, but all 7 days must be present in the configuration.

Template References

Create reusable schedules using day_templates:

"day_templates": {
  "weekday": {
    "6": {"tags": "morning"},
    "12": {"tags": "daytime"},
    "20": {"tags": "primetime"}
  }
},
"monday": "weekday",
"tuesday": "weekday",
"wednesday": "weekday"

Processing: Template references are resolved during config preprocessing by ConfigProcessor._process_templates().

Time Slot Configuration

Each hour slot is an object that can contain:

Basic Properties

Tag Selection

Tags can be: - Single string: "tags": "sitcom" - Array (for half-hour splits): "tags": ["show1", "show2"] - First half-hour (0-29 minutes): uses first tag - Second half-hour (30-59 minutes): uses second tag - Array with random_tags: Randomly selects from the array

Bump/Commercial Overrides

Scheduling Overrides

Sequences

Sequences allow playing episodes in order from a specific range:

Example:

{
  "tags": "golden_girls",
  "sequence": "gg-season1",
  "sequence_start": 0.0,
  "sequence_end": 0.5
}

This plays the first half of the gg-season1 sequence in order.

Marathons

Trigger probabilistic multi-episode marathons:

Marathon object contains: - chance: Probability (0.0 to 1.0) of marathon occurring - count: Number of episodes to play consecutively

Example:

{
  "tags": "real_people",
  "marathon": {
    "chance": 0.5,
    "count": 6
  }
}

This has a 50% chance of playing 6 consecutive episodes.

Processing: Marathons are detected and executed by MarathonAgent during schedule building.

Slot Overrides

Define named override sets for reuse across multiple time slots:

"slot_overrides": {
  "prime_slots": {
    "start_bump": "caps/primetime_start.mp4",
    "end_bump": "caps/primetime_end.mp4",
    "break_strategy": "end",
    "schedule_increment": 60
  }
},
"monday": {
  "20": {"tags": "drama", "overrides": "prime_slots"},
  "21": {"tags": "sitcom", "overrides": "prime_slots"}
}

Processing: The overrides key is resolved by ConfigProcessor._process_strategy(), which inlines the properties and removes the overrides key.

Overridable Properties: - start_bump, end_bump - bump_dir, commercial_dir - break_strategy - sequence, sequence_start, sequence_end - schedule_increment - random_tags - video_scramble_fx - marathon

Tag Overrides

Define tag-based overrides that are automatically applied when content from a specific tag path is selected:

"tag_overrides": {
  "sitcoms/friends": {
    "start_bump": "extra/friends_start.mp4",
    "end_bump": "extra/friends_end.mp4",
    "bump_dir": "extra/friends_bumps",
    "commercial_dir": "extra/friends_commercials",
    "break_strategy": "end",
    "schedule_increment": 30
  },
  "movies/action": {
    "break_strategy": "center",
    "schedule_increment": 120
  }
}

How Tag Overrides Work:

Tag overrides work similarly to slot overrides, but are applied automatically based on the content tag of the selected episode/video. The system detects when selected content has a more specific tag than what was scheduled and applies the corresponding override.

Nested Tag Detection:

Tags can be hierarchical (e.g., sitcoms/friends). When a slot schedules content using tag "sitcoms" and an episode from "sitcoms/friends" is selected, the system detects the difference and applies the "sitcoms/friends" tag override if one is defined.

Example:

"tag_overrides": {
  "sitcoms/friends": {
    "start_bump": "friends_intro.mp4",
    "commercial_dir": "friends_commercials"
  }
},
"monday": {
  "20": {"tags": "sitcoms"}
}

If the scheduler picks an episode from catalog/content/sitcoms/friends/, the "sitcoms/friends" tag override will be applied automatically, using the Friends-specific bumps and commercials.

Overridable Properties: Same as slot overrides: - start_bump, end_bump - bump_dir, commercial_dir - break_strategy - sequence, sequence_start, sequence_end - schedule_increment - random_tags - video_scramble_fx - marathon

Random Tag Selection

{
  "tags": ["show1", "show2", "show3"],
  "random_tags": true
}

Randomly selects one tag from the array for each scheduling operation.

Continued Slots

Use "continued": true to inherit the previous hour's tags (applies tag smoothing):

"monday": {
  "20": {"tags": "movie"},
  "21": {"continued": true},
  "22": {"continued": true}
}

Processing: Tag smoothing is applied by SlotReader.smooth_tags() during station initialization.

Advanced Features

Autobump

Automatically generate bump videos with metadata:

"autobump": {
  "title": "NBC TV",
  "subtitle": "Classic Television",
  "variation": "retro",
  "detail1": "Line 1 of details",
  "detail2": "Line 2 of details",
  "detail3": "Line 3 of details",
  "bg_music": "logo1.mp3",
  "strategy": "both"
}

Configuration Processing Pipeline

1. Load JSON (StationManager.load_json_stations())
2. Preprocess (ConfigProcessor.preprocess())
3. Resolve template references
4. Inline slot overrides
5. Apply Defaults (from __overwatch)
6. Normalize Clip Shows (convert to duration objects)
7. Smooth Tags (for standard networks via SlotReader.smooth_tags())
8. Add Metadata (_has_catalog, _has_schedule)

Validation

A JSON Schema is provided at station_config_schema.json for validation. Use the included validate_configs.py script:

python3 validate_configs.py

Notes

• File paths in configuration are relative to the FieldStation42 root directory
• Hour keys in day schedules are strings ("0" through "23")
• Off-air hours are simply omitted from the schedule
• Template and override references are case-sensitive
• Network types without schedules: guide, streaming, web
• Network types without catalogs: guide, streaming, web

See Also

• confs/examples/ - Example configuration files
• station_config_schema.json - JSON Schema for validation
• fs42/config_processor.py - Configuration preprocessing logic
• fs42/slot_reader.py - Schedule slot reading logic
• fs42/station_manager.py - Station loading and initialization