Open Source CAP Broadcaster

Development Guide

2024 CAP Implementation Workshop

 

 

Prepared by:

Vincent Maggard

---

Executive Summary

This white paper is aimed at software developers interested in integrating additional alerting system support into OBPlayer and potentially other broadcast automation systems using Common Alerting Protocol (CAP) covering the following elements:

• Understanding the Common Alerting Protocol

• Overview of open source alert systems using CAP

• CAP code examples for implementation

The primary goal of this project is to use bare metal computers including the low cost Raspberry PI and virtual environments to automate the process of receiving and broadcasting a CAP message with open source software. This unattended alerting process for radio and TV is standardized in Canada, the United States and many other countries presently using CAP.

What is CAP?

Common Alerting Protocol (CAP) is a worldwide open standard for alert creation and transmission via IP networks. CAP is used by many systems to ingest and distribute alerts for broadcast. Some of the common systems included IPAWS in the US managing Wireless Emergency Alert (WEA) on cell phones, sirens, and more.¹ IPAWS CAP Technology Guide

Figure : Example of CAP formatted message:

Pull Vs Push Methods

Alerts can be pulled or pushed from the CAP alert server(s) to the clients. CAP alerts can be life critical, favouring to publish/subscribe (RSS and ATOM). Otherwise, a CAP alert might be missed

Pull uses HTTP(s) for alerts fetching. This fetching is normally done via an ATOM or RSS feed. Each alert is given a feed entry with a link to the full cap XML. The client polls the server every x number of seconds, with common poll rates of every 30-40 seconds. The client must keep track of alerts it’s already used in the feed, so as to not keep repeating it over and over. When a new message is found the clients logs and downloads it. At that point it can treat it much the same as Push.

Push on the other hand sends the alert or pushes it to the client. This allows for near-real time activation. With push alerts they are still logged but since messages are normally sent once so the receiving system can be sure it’s new. If an internet outage or system reboot happens when an alert is sent, the client would miss it. Some cap servers handle this with alert repeats via heartbeat messages, however if used it adds more processing and code to do so to the system.

Profiles

Profiles are used with CAP to add needed requirements for special systems like the US’s EAS, or Canada’s Alert Ready system. CA-CP handles unique French language accent characters ² Canada Alert Ready Specifications

Common profile for the United States is IPAWS. ³  IPAWS Profile

All alerts have the CAP v.1.2 elements.

There are profiles for other countries as well such as CAP-AU.

Project Breakdown

Alert Processing & Validation

Alerts received require parsing of the XML and alert validation (simple pre-air checks).

The order of handling an alert is as follows:

1. Parse the XML into an object.

2. Run through checks listed in the example table using the object.

3. If the alert passes all checks, download the attached audio, or create text to speech. For video create a crawl via concatenating the description & instructions elements values.

4. Place audio & crawl live on air.

Pre-Air Checklist

Check Name	Needed Actions
Is the alert active?	Current time > Issue time but < expire time.
Is the alert for the broadcasting area?	Check for one or more locations is included
Check if event code is set for broadcast?	Run though list of allowed event codes.
Check for the language code for the broadcaster viewer/listener?	Use the info block’s language tag to find the right version of the message.

Code Examples

Below is group of code examples using Python 3.x This code is open source and can be found on GitHub ⁴ CAP Examples

Expired / Active Alert Check

To check for a given alerts status expired, or not, is quite simple. To get the difference from the sent time and expire time examine if the difference is > 0 then the alert is active.

Figure : Example using Python date objects handling it with two steps.

CAP Pull Download

Example using an Open source CAP server.

Figure : Example downloading the xml file

Step by Step Guide

1. HTTP get request (download xml) CAP feed of alerts.

2. Parse xml

3. Compare with alerts already processed while handling multiple alerts.

4. Validate CAP alert and pass along to the broadcast chain.*

* OBPlayer presently logs the CAP alerts including off air audio logs as required by regulators.