# Program Associated Data

## Overview

Rivendell includes full support for the origination and transmission of program associated data (PAD) in realtime, including a Python module (PyPAD) that can be used to create scripts for interfacing Rivendell's PAD feed to most any arbitrary external system.

### The JSON Interface

All Rivendell PAD updates are emitted as JSON documents of type `padUpdate` via TCP port 34289. A typical update looks like:

    {
        "padUpdate": {
            "dateTime": "2019-03-28T15:09:01-04:00",
            "hostName": "elastigirl",
            "shortHostName": "elastigirl",
            "machine": 1,
            "onairFlag": false,
            "mode": "Automatic",
            "service": {
                "name": "Production",
                "description": "Production Log"
                "programCode": ""
            },
            "log": {
               "name": "Example"
            },
            "now": {
                "startDateTime": "2019-03-28T15:09:01-04:00",
                "lineNumber": 0,
                "lineId": 0,
                "cartNumber": 10477,
                "cartType": "Audio",
                "cutNumber": 1,
                "length": 225500,
                "year": null,
                "groupName": "MUSIC",
                "title": "Allentown",
                "artist": "Billy Joel",
                "publisher": "",
                "composer": "",
                "album": "The Complete Hits Collection 1973-1997",
                "label": "",
                "client": "",
                "agency": "",
                "conductor": "",
                "userDefined": "",
                "songId": "",
                "outcue": "",
                "description": "Cut 001",
                "isrc": "",
                "isci": "",
                "externalEventId": "",
                "externalData": "",
                "externalAnncType": ""
            },
            "next": {
                "startDateTime": "2019-03-28T15:12:46-04:00",
                "lineNumber": 1,
                "lineId": 1,
                "cartNumber": 10153,
                "cartType": "Audio",
                "cutNumber": 1,
                "length": 168700,
                "year": null,
                "groupName": "MUSIC",
                "title": "Me & You & A Dog Named Boo",
                "artist": "Lobo",
                "publisher": "",
                "composer": "",
                "album": "'70s Radio Hits",
                "label": "",
                "client": "",
                "agency": "",
                "conductor": "",
                "userDefined": "",
                "songId": "",
                "outcue": "",
                "description": "Cut 001",
                "isrc": "",
                "isci": "",
                "externalEventId": "",
                "externalData": "",
                "externalAnncType": ""
            }
        }
    }

### PyPAD

Rivendell ships with a Python 3 module called "pypad" that automates away most of the work involved in reading, parsing and processing the raw JSON data feed described above. A copiously commented example script can be found in the Rivendell source tree at `apis/pypad/tests/now_and_next.py`.

#### Starting Scripts Automatically with the "rivendell" Service

Rivendell can be configured to start one or more PyPAD scripts automatically whenever the "rivendell" systemd service is (re)started. In order to support this, a PyPAD script must meet the following requirements:

- Accept exactly three command-line arguments as follows:

  `script host-name port-num config`

  The config value should be passed to the `pypad.Receiver.setConfigFile()` method, and host-name and port-num values should be passed to the `pypad.Receiver().start()` method. See any of the production PyPAD scripts in the Rivendell sources in `apis/pypad/scripts/` for an example.

- If the script is configurable via a configuration file, provide a sample copy of the configuration file, using wherever possible sane default values along with comments documenting what the various parameters do. The file should have the the same base name as that of the script, but have an `.exemplar` extension.

  For example, if the script is called `myscript.py`, the sample configuration file would be called `myscript.exemplar`.

- Install a copy of the script, along with a copy of the sample configuration file (if needed) in the Rivendell PyPAD script directory `$(libdir)/rivendell/pypad/`.

  In the RHEL/CentOS reference installation, this directory is `/usr/lib64/rivendell/pypad/`.

  The `$(libdir)` path component evaluates to the value used for the `--libdir` switch that was passed to the "configure" script when Rivendell was built [default value: `/usr/local/lib`].

All PyPAD scripts started in this manner will be run under the user/group specified by the `PypadOwner=` and `PypadGroup=` directives in the `[Identity]` section of the `rd.conf` 5 configuration file.

See for instructions on enabling a script that has been prepared in this manner.