> For the complete documentation index, see [llms.txt](https://catchdocs.gitbook.io/catch-customer-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://catchdocs.gitbook.io/catch-customer-documentation/catch-control/media-player-integrations/generic-http-interface.md).

# Generic HTTP Interface

## Overview

Catch Control offers an HTTP interface that enables third-party media players to interact with features of the Catch platform, including mobile interactivity and real-time audience measurement.

Communication between the third-party media player and Catch Control is performed locally on the same host machine that the 3rd party media player runs on.

## Diagram

<figure><img src="https://3191043691-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdTGfthZOwExKcXtWjteP%2Fuploads%2FSrpQdK6L7wlI2J3Hv7Yo%2Fimage.png?alt=media&amp;token=3e023c1a-efc0-4360-8da6-cd4dc928a37d" alt=""><figcaption></figcaption></figure>

## Terminology

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`    | <p><img src="https://3191043691-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdTGfthZOwExKcXtWjteP%2Fuploads%2FAZIJq1q6tR914FOZZ7pY%2Fimage.png?alt=media&amp;token=5d6710b8-dba4-4485-8931-03fb143edac8" alt="" data-size="original"><br><br>A <code>source</code> is an area of the digital screen that displays <code>content</code>. This is typically the entire screen, as shown in the reference diagram, but is frequently a sub-division of a larger screen, as shown in the image above.</p><p></p><p>In both cases, a <code>source</code> has a single <code>playstate</code> at a given moment in time.</p><p></p><p><code>source</code> identifiers are unique strings containing only the characters <code>0-9</code>, <code>a-z</code>, <code>A-Z</code>, <code>\_</code>and <code>-</code>, and represent an integrator-defined identifier for the <code>source</code> (e.g. a Broadsign Frame ID).<br><br>The appropriate identifier to use will vary with each player integration. A manually-generated <code>source</code> identifier will be assigned on test players during development, which is then automated for deployment at scale.</p> |
| `playstate` | <p>The current state of a <code>source</code>, including its identifier, and its <code>playlist</code>. </p><p></p><p>One <code>playstate</code> must be sent to Catch Control each time the on-screen <code>content</code> changes.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `playlist`  | <p>The sequence of items associated with a <code>playstate</code>, in playback order, without gaps, and beginning with the <code>content</code> that is currently on-screen. </p><p></p><p>For correct operation of the Catch system, a <code>playlist</code> must have at least two items.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `content`   | <p>A single piece of media, identified by a unique string containing only the characters <code>0-9</code>, <code>a-z</code>, <code>A-Z</code>, <code>\_</code> and <code>-</code>. <br></p><p>This identifier can be allocated explicitly by the integrator, or it could be a surrogate  pointing to a third-party system. </p><p></p><p>For example, Broadsign integrations use the Broadsign "copy ID" as the Content identifier, and integrations backed by Hivestack (Perion) may use the content's Hivestack UUID.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `playback`  | <p>Whenever content finishes playing on-screen, a derived <code>playback</code> is created by Catch Control, sharing the UUID of the originating <code>playlist</code> entry. Along with the <code>source</code>/<code>content</code> information.</p><p></p><p>A <code>playback</code> is enriched with additional metadata from the Catch Platform, such as audience statistics, and a description of the attached Catchable/Catch Campaign.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

## HTTP Interface

Catch Control's Generic player implementation exposes an HTTP server at address `127.0.0.1:10000`

### Sending Playstates

Integrating players must submit one JSON `playstate` to Catch Control via HTTP POST request each time on-screen `content` changes.

To ensure the best user experience for Catch Interactivity, the `playlist` of the `playstate` must contain at least two items - one for the `content` currently on screen ("Current Content"), and one for the following piece of `content` ("Next Content").

{% hint style="info" %}
It is not necessary to synchronise `playstate` submission with on-screen playback transitions, however the `playstate` should be sent as early as possible after playback starts. \
\
For example, if the Next Content is not known when playback starts, sending the `playstate` may be delayed until the Next Content is known. Catch recommends that the `playstate` is sent no later than three seconds before the end of the Current Content.
{% endhint %}

One `playstate` must be provided each time the on-screen `content` changes within a `source`. The `playstate` must include a `playlist` of at least two entries, representing the current ad, and the one immediately following.

### Example Request

<mark style="color:green;">`POST`</mark> `127.0.0.1:10000/playstate/v1/`

**Post Body**

Example values below refers to the example in the diagram above

```json
{
   "playstate":{
      "source":"fullscreen_123456789",
      "playlist":[
         {
            "playback_instance":"03a6b35d-43be-4724-b4a6-996ed608e406",
            "end_time":"2025-06-04T12:20:23.923Z",
            "duration_ms":12000,
            "content":{
               "id":"12345",
               "media":{
                  "width":1920,
                  "height":1080,
                  "filename":"cocacola.mp4"
                  "local_path":"C:/MediaCache/cocacola.mp4",
               }
            }
         },
         {
            "playback_instance":"2d0fc162-320f-410f-925e-e4f34a154c6f",
            "duration_ms":12000,
            "content":{
               "id":"12346",
               "media":{
                  "width":1920,
                  "height":1080,
                  "filename":"tide.mp4"
                  "local_path":"C:/MediaCache/tide.mp4",
               }
            }
         }
      ]
   }
}
```

| Key                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`            | <p><code>string</code><br>The source ID associated with the playstate; each source represents a single content feed that is displayed on one or more physical screens. </p><p></p><p>Catch Control maps Source IDs to their corresponding Catch Stream IDs so that live content updates can be broadcast in real-time over Bluetooth. </p><p></p><p><strong>During development,</strong> <code>source</code> <strong>IDs are generated or allocated through co-operation between Catch and the integrator during setup and onboarding.</strong></p><p></p><p><strong>At scale, this process is automated.</strong></p> |
| `playlist`          | <p><code>array</code><br>The source's current sequence of media playbacks, represented as an array of entries, in playback order, starting the content that is currently on screen. The array must have no gaps.</p>                                                                                                                                                                                                                                                                                                                                                                                                   |
| `playback_instance` | <p><code>string</code><br>A UUID uniquely identifying the this playlist item; this UUID must be generated <strong>per-playback</strong></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `end_time`          | <p><code>string</code><br>the time at which this playback ends; only required/used for the first item in the array. Must be encoded in RFC3339 format to millisecond precision.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `content`           | <p><code>object</code><br>An object describing the media related to this playback instance</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `id`                | <p><code>string</code><br>content ID associated with this playlist entry; Catch Control will attempt to map this value to interactivity content defined in OOH Studio.<br><br>examples:<br>- Broadsign Copy ID<br>- Hivestack Content UUID</p>                                                                                                                                                                                                                                                                                                                                                                         |
| `duration_ms`       | <p><code>int</code><br>playlist entry duration in milliseconds</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `media`             | <p><code>object</code><br>All data in this object is optional, but recommended.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `local_path`        | <p><code>string</code><br>A complete path to the media resource of this <code>content</code> (e.g Image, Video) that will play on-screen,.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `metadata`          | <p><code>object</code><br>metadata associated with the playback; any values can be provided, with some common keys below</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `width`             | Width of the content in pixels                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `height`            | Height of the content in pixels                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `filename`          | File name of the conent, including the extension. If not provided, the `filename` will be inferred from any provided `local_path`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### **Response Codes**

{% tabs %}
{% tab title="200" %}

```json
OK
```

{% endtab %}

{% tab title="400" %}

```json
Failed to parse playstate: $ERROR_MESSAGE
```

{% endtab %}

{% tab title="422" %}

```json
Invalid playstate: $ERROR_MESSAGE
```

{% endtab %}
{% endtabs %}
