Generate virtual timeslots for unscheduled calendar areas

Parent: [EPIC] Display virtual timeslots / Music Fallba... (aura#176 - closed)

Currently the Scheduler of Engine is meant to create virtual timeslots for areas in the programme which neither have timeslots nor playlists assigned.

In such cases Engine should play the so called Station Fallback Playlist.

It is more practical to have such virtual timeslots created in Steering, because:

• All services which are digesting the Programme API have the same view on the Programme ("Single source of truth").
• No more need to replication of interpolation logic for "filling the gaps with virtual timeslots" on the API consuming site (Engine, Website, ...)
• Dashboard can easily display such timeslots too e.g. in a grayed out form. This is similar what LOHROthek is doing with their "Lückenfüller" concept.
• Configuration of the Station Fallback Show / Playlist could be done in a very flexible way. It could even change dynamically over the period of a day. If that's what is needed in the future.

Proposal

Three program endpoints

We introduce 3 distinct API endpoints for fetching program info.

All of them have a start [DEFAULT=now] and end [DEFAULT=+24h] query parameter.

1. Endpoint /program/playout (current playout endpoint)

Used for Engine and Studio clock. Returns timeslots. Structure:

[
  {
    "id": "start-datetime--end-datetime",
    "start": "iso8601-datetime",
    "end": "iso8601-datetime",
    "showId": int,
    "timeslotId": int | null,
    "episode": {
      "id": 2,
      "title": ""
    },
    "schedule": {
      "defaultPlaylistId": null,
      "id": 1
    },
    "show": {
      "defaultPlaylistId": null,
      "id": 2,
      "name": "EINS"
    },
    "timeslot": {
      "end": "2024-07-03T16:30:00",
      "id": 2,
      "isVirtual": false,
      "memo": "",
      "playlistId": null,
      "repetitionOfId": null,
      "start": "2024-07-03T14:00:00"
    }
  }
]

2. Endpoint /program/basic

Used by Dashboard

{
  "id": "start-datetime--end-datetime",
  "start": "iso8601-datetime",
  "end": "iso8601-datetime",
  "showId": int,
  "timeslotId": int | null
}

3. Endpoint /program/calendar

Includes all details required for website program overview pages.

Also includes all nested objects, but all referenced objects are listed in the beginning of the results. The results need to be queried client-site using the given resource ids.

Sub Tasks

• All necessary API endpoints providing timeslot-like results have a parameter to either include or exclude these virtual timeslots (includeVirtual=true URL parameter). API endpoints we agreed on are:
• In API results, virtual timeslots are marked with a property virtual: true.
• As soon a valid timeslot is created such virtual timeslots disappear, or shrink in their size, if there is still a gap left.
• Virtual timeslots are presented as if they were "real timeslots", holding all relevant meta information required for proper playout. Avoiding the need for any special case handling. Following fields are interpolated with configured values:
  • Episode title: default_pool = settings.program.fallback.defaultPool -> query pool description from episode_title = playout.pools[defaultPool] (compare config in #222 (closed))
  • Check and discuss on demand if there is any other field required.
• We decided not naming playout/program response fields show, episode, etc... but showPreview or partialShow (or any other prefix/suffix that communicates a non-standard object representation) in order to make a distinction between actual Show-objects and a stripped-down version for the playout endpoint.
• The separate ...Id fields are missing ({ "show": { "id": 1, ... }, "showId": 1 }) for all objects.
• Looking at the code for the virtual timeslot the show object is not null-ed in case no fallback show is specified. I’d prefer { "show": null } instead of the current { "show": { "id": null, "default_playlist_id": null, "name": "" }.
• I've noticed a bug: Today between 21:00 - 22:00 there is an empty slot. There should actually be some virtual timeslot, but the API doesn't return it. Instead the API fills it with some other timeslot, which is scheduled later at night ("Raumfest").

Dependency

• Valid schema for "/steering/api/v1/playout" end... (#154 - closed)