External stream configuration source (config_external)¶

Catena SE can obtain the list of TV channels (streams) from an external provisioning service instead of manual configuration. You implement this service yourself: Catena SE calls it over the config_external protocol and syncs its configuration to match.

The key method your service must provide is streams_list (GET /streams). Catena SE uses it to fetch the full stream list and force its configuration to match that list (add, update, and remove channels as needed).

What your service must implement¶

The external service must implement an HTTP API compatible with the description in the attached catena-se.yaml file (OpenAPI 3.1). First and foremost, it needs to expose:

• GET /streams (operationId: streams_list) — returns the stream list in streams_list format.

Response format:

• Response body — JSON object with a streams field: an array of items of type stream_config.
• Optionally, pagination fields from collection_response are supported: next, prev, estimated_count, timing. Catena SE may send query parameters limit and cursor for paginated retrieval.

Each entry in streams is one stream’s configuration: name, inputs, template, dvr, labels, timeouts, backup, on_play, and other fields described in the stream_config schema in catena-se.yaml. The stream name is unique and cannot be changed after creation.

How Catena SE uses the stream list¶

Sync behaviour on the Catena SE side:

• Catena SE requests the stream list from the external service (GET /streams, with cursor/limit if needed).
• All streams from the response are added or updated in Catena SE: if a channel already exists, its settings are fully overwritten by the response data. Existing labels on the channel are replaced by those from the external service.
• Channels that exist in Catena SE but are not in the external list are removed — except channels with the manual label.
• Channels with the manual label are not removed or overwritten by this mechanism.

To keep a channel out of external provisioning, give it the manual label (e.g. in labels.manual). If the external service later adds a stream with the same name, on the next sync the label will be overwritten and the channel will come under automatic management.

Episode list sync¶

Middleware can provide subscribers with the recording status of each programme for correct playback.

Recording status can be obtained from Catena SE by requesting episodes for a given time range via the episodes_get method. Catena SE will request episode lists from the server over the config_external protocol for missing time ranges, enrich them, and return the result.

The design assumes programme boundaries do not change, so caching is done once.

Example: single file and HTTP server¶

A minimal setup is a single static file streams containing JSON in central_streams_list format. This folder includes an example of such a file with one stream (demo source fake://fake).

Serving the file with Python’s built-in HTTP server:

python3 -m http.server 8000

After starting, the stream list is available at http://localhost:8000/streams. In Catena SE settings, set your server URL (e.g. http://HOST:8000) so that config_external requests http://HOST:8000/streams.

Example streams file content:

{
  "streams": [
    {
      "name": "channel1",
      "title": "Test channel",
      "comment": "Demo stream from external config",
      "inputs": [
        {
          "url": "fake://fake"
        }
      ]
    }
  ]
}

For production you need a service that returns the response with Content-Type: application/json and, if required, handles the cursor parameter.

How to enable config_external¶

Add a config_external section to the installation configuration file:

config_external:
  url: "https://auth@middleware.myservice.com"

config_external protocol technical details¶

The full API description is in OpenAPI 3.1 format in the catena-se.yaml file in this folder. It defines the streams_list, stream_config schemas, stream input types (stream_input_*), DVR parameters, labels, and all other fields your service can return in streams_list to provision streams in Catena SE.