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.

See also: To override the schedule on a single calendar date without swapping the entire config, use date_overrides.

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 and Audio 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 - special_sauce - Authentic scrambled cable TV emulation (pairs with the matching audio effect) - glitchtastic - Glitchy digital look

Available audio_scramble_fx values: - special_sauce - Audio companion to the special_sauce video effect

Both fields accept the same kind of value: a preset name applied as an mpv filter at playback time. They can be set independently or paired. New presets are defined in fs42/station_player.py and then referenced by name from a station config.

Example pairing both effects on a scrambled premium channel:

{
  "video_scramble_fx": "special_sauce",
  "audio_scramble_fx": "special_sauce"
}

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"
  ]
}

Loop Network Properties

Example:

{
  "network_type": "loop",
  "content_dir": "catalog/loop",
  "shuffle_loop": true
}

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().

Date-Specific Overrides

Use date_overrides to replace the normal weekday schedule on specific calendar dates. This is useful for holiday marathons, one-off events, and full-day takeovers.

Each key is a date written as "Month Day" (full month name, capitalized, followed by the day of the month). Each value is either:

• A string referencing a day_templates entry, or
• An object using the same hour-slot structure as a normal weekday.

Reference an existing template:

"day_templates": {
  "christmas_day": {
    "0": {"tags": "christmas_movie"},
    "1": {"tags": "christmas_movie"}
  }
},
"date_overrides": {
  "December 25": "christmas_day"
}

Define the override inline:

"date_overrides": {
  "December 25": {
    "0": {"tags": "christmas_movie"},
    "1": {"tags": "christmas_movie"},
    "2": {"tags": "christmas_movie"},
    "3": {"event": "signoff"}
  }
}

Partial overrides are supported. Hours not specified in the override fall back to the normal weekday schedule for that hour:

"date_overrides": {
  "April 23": {
    "20": {"tags": "wwf"},
    "21": {"tags": "wcw"}
  }
}

On April 23, only 8 PM and 9 PM are overridden; every other hour uses the regular weekday schedule.

Resolution order: When building a schedule, the system first checks date_overrides for the current date. If a match exists and the current hour is defined in it, that slot is used. If the hour is not defined in the override, the normal weekday schedule is used as a fallback. If no date matches, the weekday schedule is used as before.

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 - audio_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 - audio_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