Station JSON Reference

Station JSON Reference

CSL Music Mod Revisited reads station files with the exact lowercase extension .json from the root of each active CSLMusicMod_Music directory.

Schema

name string  

Sets the station's internal identifier. Give each custom station a unique name.

If you omit collections, the loader looks for a collection with the same name.

{
  "name": "string"
}

collections string[]  

Selects the content collections available to the station.

The loader compares collection names by letter case. It treats night, Night, and NIGHT as separate collections. See Collection name resolution for names derived from folders and game content.

{
  "collections": ["string"]
}

thumbnail string  

Names an image relative to the station JSON file. The mod uses its built-in station thumbnail when you omit this field or the loader cannot find the file.

{
  "thumbnail": "string"
}

schedule object[]  

Defines the radio state chain. Each state requires three fields:

Field	Type	Required	Behavior
type	string	Yes	Content type. Parsing ignores letter case.
min	integer	Yes	Minimum number of items for the state.
max	integer	Yes	Maximum number of items for the state.

Supported type names are Music, Blurb, Talk, Commercial, and Broadcast.

Use a non-negative min, set max to at least min, and include content for each required type. The loader creates the station without validating those relationships.

{
  "schedule": [
    { "type": "Music", "min": 0, "max": 1 }
  ]
}

If you omit schedule or leave it empty, the mod generates one from the content types in the selected collections. Generated ranges use 1 to 5 for music, 0 to 3 for commercials, and 0 to 1 for the other content types.

filters object  

Maps case-sensitive names to reusable context conditions.

Supported condition types are time, weather, mood, and disaster. Type names are case-sensitive. See Context-Sensitive Radio for their fields and evaluation rules.

contexts object[]  

Selects collections and songs through named or inline conditions.

Field	Type	Required	Behavior
conditions	array of arrays	Yes	Outer entries are OR branches. Terms inside one branch use AND.
collections	string[]	Yes	Selects collections when the context applies. The loader adds these names to the station's full collection set.
songs	string[]	No	Restricts the context to exact display names. An absent or empty array selects each song in the context collections.

{
  "contexts": [
    {
      "conditions": [["filterName"]],
      "collections": ["string"],
      "songs": ["string"]
    }
  ]
}

A condition term can reference filters by name or contain an inline condition object. The loader logs an unknown filter name and adds no condition to that branch.

The loader checks contexts in array order and uses the first match. With no match, it permits all content assigned to the station.

See Context-Sensitive Radio for their fields and evaluation rules.

The current loader ignores top-level description, context name, and unknown metadata. These fields cannot control playback.

The loader rejects the whole station if a required field has the wrong JSON type, a schedule type is unknown, or another parse operation throws an exception.

Collection name resolution

The loader derives collection names from file locations:

• Local root files use Userdefined.
• An immediate child directory uses its directory name.
• A music pack's root files use MusicPack followed by the pack mod's displayed name.
• A music pack's immediate child directory uses its directory name.
• Vanilla radio content uses names such as Music: <station internal name> and equivalent prefixes for other content types.

Examples

The examples below use JSONC-style // comments for explanation. Remove the comments before saving a strict JSON file.

Example (from schema)

{
  "name": "string", // Required station identifier.
  "collections": ["string"], // Optional base collections; defaults to the station name.
  "thumbnail": "string", // Optional image path relative to this JSON file.
  "schedule": [
    { "type": "Music", "min": 0, "max": 1 } // Optional state chain entry.
  ],
  "filters": {
    "filterName": {
      "type": "time", // Supported types: time, weather, mood, or disaster.
      "from": 0,
      "to": 24,
      "not": false
    }
  },
  "contexts": [
    {
      "conditions": [["filterName"]], // Every term in a branch uses AND; branches use OR.
      "collections": ["string"], // Collections used when this context matches.
      "songs": ["string"] // Optional exact display-name filter.
    }
  ]
}

Example

{
  "name": "City Hours", // Also used as the station's internal identifier.
  "collections": ["Day", "Night", "Ident"], // Base collections available to this station.
  "thumbnail": "City Hours.png", // Resolved relative to this JSON file.
  "schedule": [
    { "type": "blurb", "min": 0, "max": 1 }, // Optional station ID before music.
    { "type": "music", "min": 2, "max": 4 } // Play two to four music entries.
  ],
  "filters": {
    "night": { "type": "time", "from": 20, "to": 6 }, // Crosses midnight: 20:00 through 06:00.
    "day": { "type": "time", "from": 6, "to": 20 } // The daytime range.
  },
  "contexts": [
    {
      "conditions": [["night"]], // Contexts are checked from top to bottom.
      "collections": ["Night", "Ident"] // Night music plus station IDs.
    },
    {
      "conditions": [["day"]], // Used when the day filter matches.
      "collections": ["Day", "Ident"] // Day music plus station IDs.
    }
  ]
}

Next step

Read Context-Sensitive Radio for the full field reference and evaluation rules for filters and contexts conditions.