Contact Support | System Status
Page Contents

    Overview: Cloud Playout APIs

    This topic provides and overview of the EPG API and the Channels API, which are used with Cloud Playout.

    Introduction

    There are two APIs related to Cloud Playout:

    • The EPG API allows you to retrieve an electronic programming guide for a Cloud Playout channel. Cloud Playout generates EPG adhering to XML TV standard as described in schema found at https://repository.data2type.de/XMLTV/v_1.47/html/index.html.
    • The Channels API allows you to retrieve information about your Cloud Playout channels which you can display in your UI or web page.

    Authentication

    The Cloud Playout APIs use the Brightcove OAuth system to authenticate requests through an access token that is passed in an authorization header with the request:

    Authorization: Bearer {access token}

    Access tokens are retrieved using the OAuth API - see Getting Access Tokens for details. You will also need client credentials to authenticate the requests for access tokens. These can be created in the Admin section of Studio - see Managing API Credentials. The permissions your credentials will need for the EPG API are:

    EPG API Permissions
    EPG API Permissions

    API URLs

    Get all Cloud Playout channels

    The following endpoint can be used to get a list of all Cloud Playout channels for an account:

    https://cm.cloudplayout.brightcove.com/accounts/{account_id}/cp_channels

    The account_id is the Video Cloud account id.

    Get an EPG

    The URL for the EPG API request is:

    https://sm.cloudplayout.brightcove.com/accounts/{account_id}/channels/{channel_id}/epg

    The account_id is the Video Cloud account id, and the channel_id is the id for the channel created in Studio.

    The Channel's ID can be found in the response to the request to get all Cloud Playout channels, or in the browser URL when you are in the Channel view of the Cloud Playout section of Studio:

    https://studio.brightcove.com/products/videocloud/cloudplayout/channel/2c73c2112f794e6eb80be1284a495674

    EPG request parameters

    The following optional query parameters can be added to the EPG request:

    EPG API Query Params
    Parameter Default Value Description
    start (14 days prior to now) The date-time from which the EPG responses can be queried and returned in ISO 8601 Date format
    end (now - the current date-time) The date-time until which the EPG responses can be queried and returned in ISO 8601 Date format
    limit (all programs) An integer value that controls the number of programmes returned in one request. Note that the limit value (default: 100) may prevent all programmes for the specified time period from being returned. See EPG API Best Practices for more information
    include_ads false Set this to true to include ads in the response

    Notes

    1. The start/end window cannot exceed 14 days. Start can be 14 days behind from current date-time to query historic EPG. You can also future EPG data for up to 14 days from the current date-time.
    2. If the difference between the end time and start time is greater than 14 days, then the API generates only 14 days from the time time requested to end time or 14 days, whichever is earlier.
    3. Both start and end can accept date-time values with and without timezone offsets - if no timezone offset is included, UTC is assumed.
    4. Both start and end must be URI-encoded:
      URI Encoding
      ISO 8601 Sample URI-Encoded
      2020-07-24 15:30:00 2020-07-24%2015%3A30%3A00
      2020-07-24 15:30:00 +0530 2020-07-24%2015%3A30%3A00%20%2B0530

    Sample EPG API response

    Below is a sample response from the API:

    <?xml version="1.0" encoding="utf-8"?>
        <tv source-info-name="Cloudplayout Schedules" source-info-url="http://www.cloudplayout.qa.brightcove.com">
            <channel id="9fb8032ff2fe4f55b388d8969c22ca58">
                <display-name>MyCloudChannel</display-name>
                <icon src="https://bc-cloudplayout-prod.s3.amazonaws.com/default_channel_image.png"/>
            </channel>
            <programme channel="9fb8032ff2fe4f55b388d8969c22ca58" start="20201120132000" stop="20201120132228">
                <title>Frozen</title>
                <desc>FrozenMultiLanguage</desc>
                <length units="seconds">147.605</length>
                <icon src="https://cf-images.us-east-1.qa.boltdns.net/v1/jit/6063799219001/43d57501-b98a-4708-bdd1-a09081f7a585/main/1280x720/1m13s802ms/match/image.jpg" width="1280" height="720"/>
                <category>video</category>
                <keyword>eyJ2aWRlb19pZCI6IjcwNzAwNDQxMDk2MjAyIiwib3JkZXIiOjEsInRhZ3MiOiJjaGlsZHJlbixjb21lZHkiLCJjdXN0b21fbWV0YWRhdGEiOnsicmVnaW9uIjoiYWZyaWNhIiwic29uZ3MiOjV9fQ==</keyword>
            </programme>
            <programme channel="9fb8032ff2fe4f55b388d8969c22ca58" start="20201120132228" stop="20201120133228">
                <title>LiveDemo</title>
                <desc>Live Demo</desc>
                <length units="seconds">600.0</length>
                <icon src="https://img.brightcove.com/cloudplayout/live-icon.jpg" width="1280" height="720"/>
                <category>live</category>
                <keyword>eyJ2aWRlb19pZCI6IjcwNzAxNDg0MjA3MjAyIiwib3JkZXIiOjIsInRhZ3MiOiJjcC1saXZlLXBsYWNlaG9sZGVyLGR1cmF0aW9uLTAwOjEwOjAwIiwiY3VzdG9tX21ldGFkYXRhIjp7InJlZ2lvbiI6Im5vcnRoIGFtZXJpY2EifX0=</keyword>
            </programme>
            <programme channel="9fb8032ff2fe4f55b388d8969c22ca58" start="20201120133228" stop="20201120133327">
                <title>ChildrenComedy</title>
                <desc>ChildrenComedy</desc>
                <length units="seconds">59.164</length>
                <icon src="https://cf-images.us-east-1.qa.boltdns.net/v1/jit/6063799219001/9430773f-76f5-476e-964d-a13b40cab90a/main/1280x720/29s582ms/match/image.jpg" width="1280" height="720"/>
                <category>video</category>
                <keyword>eyJ2aWRlb19pZCI6IjcwNzAxMjE2NDgyMjAyIiwib3JkZXIiOjMsInRhZ3MiOiJyb21hbmNlIiwiY3VzdG9tX21ldGFkYXRhIjp7InJlZ2lvbiI6ImFzaWEiLCJzb25ncyI6NX19</keyword>
            </programme>
            <programme>
                ...
            </programme>
        </tv>

    Notes

    1. The start and end timestamps are in UTC time.
    2. The category and keyword entries are for internal purposes.

    The EPG data contains multiple programme data where each programme represents details about the video or live asset:

    <programme channel="27963aa756294a7c98ca1c2c459d4ba2" start="20201118232206" stop="20201118232305">
    	<title>ChildrenComedy</title>
    	<desc>ChildrenComedy</desc>
    	<length> units="seconds">59.164</length>
    	<icon> src="https://cf-images.us-east-1.qa.boltdns.net/v1/jit/6063799219001/9430773f-76f5-476e-964d-a13b40cab90a/main/1280x720/29s582ms/match/image.jpg" width="1280" height="720" ></icon>
    	<category>video</category>
    	<keyword>eyJ2aWRlb19pZCI6IjcwNzAxMjE2NDgyMjAyIiwib3JkZXIiOjEsInRhZ3MiOiJjaGlsZHJlbixjb21lZHkiLCJjdXN0b21fbWV0YWRhdGEiOnsicmVnaW9uIjoiYWZyaWNhIiwic29uZ3MiOjV9fQ==</keyword>
    </programme>

    Here, the keyword contains base64 encoded json value. The decoded value of the keyword is shown below.

    • video_id: is the identifier for the video as in Video Cloud.
    • order: is the order of the asset in the Cloud Playout program list.
    • tags: comma separated (if any) - associated with the corresponding video in video cloud.
    • custom metadata: (if any, represented as name/value pairs) associated with the corresponding video in video cloud.
    {
      "video_id":"70701216482202",
      "order":1,
      "tags":"children,comedy",
      "custom_metadata":{
        "region":"africa",
        "songs":5
      }
    }

    Sample Channels API response

    {
            "items": [
              {
                "public_id": "f8eb5f9ccfb84f81b4fb506a663c5545",
                "name": "Channel-4",
                "description": "Test Channel",
                "account_id": "1752604059001",
                "state": "RUNNING",
                "status": "Channel started",
                "start_time": "2021-01-03 15:31:12 UTC",
                "stop_time": null,
                "input_groups": "slate:rtmp:playlist",
                "output_groups": "rtmp",
                "loop_playlist": true,
                "playlist_id": "1687789969630819284",
                "channel_class": "single-pipeline",
                "ssai_enabled": false,
                "aws_region": "us-east-1",
                "message": "",
                "created_at": "2021-01-02 15:39:05 UTC",
                "updated_at": "2021-01-03 15:31:12 UTC",
                "image_url": "https://bc-cloudplayout-prod.s3.amazonaws.com/default_channel_image.png",
                "output_destinations": [
                  "Brightcove Live"
                ],
                "channel_created_at": "2021-01-02 15:39:05 UTC",
                "channel_updated_at": "2021-01-02 15:39:05 UTC",
                "channel_created_by": "rcrooks@brightcove.com",
                "channel_updated_by": "rcrooks@brightcove.com"
              },
              {
                "public_id": "42ecb67a9a964662a4071b4fffff0012",
                "name": "Test-6",
                "description": "Test Channel",
                "account_id": "1752604059001",
                "state": "SCHEDULED",
                "status": "Scheduled for start",
                "start_time": "2021-01-09 05:00:00 UTC",
                "stop_time": "2021-01-09 23:00:00 UTC",
                "input_groups": "slate:rtmp:playlist",
                "output_groups": "rtmp",
                "loop_playlist": true,
                "playlist_id": "1688070644726417934",
                "channel_class": "single-pipeline",
                "ssai_enabled": false,
                "aws_region": "us-east-1",
                "message": "",
                "created_at": "2021-01-05 18:00:18 UTC",
                "updated_at": "2021-01-06 19:08:41 UTC",
                "image_url": "https://bc-cloudplayout-prod.s3.amazonaws.com/default_channel_image.png",
                "output_destinations": [
                  "Brightcove Live"
                ],
                "channel_created_at": "2021-01-05 18:00:18 UTC",
                "channel_updated_at": "2021-01-06 19:06:46 UTC",
                "channel_created_by": "rcrooks@brightcove.com",
                "channel_updated_by": "rcrooks@brightcove.com"
              }
            ]
          }

    The EPG and Bumpers

    How the EPG handles bumpers

    The EPG will not include the bumpers themselves. The durations of the bumpers will be reflected in the following way:

    • Pre-roll bumper durations are added the following video duration
    • Post-roll bumper durations are added to the previous video duration

    Potential problems

    There are two things you can do that will cause the EPG to be inaccurate:

    • Tagging videos to be both pre-roll (cp-preroll-bumper) AND post-roll (cp-postroll-bumper) will cause the EPG to be inaccurate because it depends on the tag to decide where to add the duration. If the video has both tags, the bumper duration will be added to both the previous and next video.
    • You can move bumpers in the Cloud Playout program list, but if you arrange them such that a pre-roll bumper is immediately followed by a post-roll bumper, both bumpers will play, but the EPG API will ignore them and the schedule for that time period will be empty.

    limitations

    1. The EPG is generated on best effort / close to accurate.
    2. When the EPG is initially constructed from the playlist, there may be a start time error as the Cloud Playout takes some time to initiate the switching.
    3. EPG may not be consistent for every retrieval when the playlist is modified, because it is constructed dynamically based on the current information it holds. Some actions that will alter the EPG include reordering the playlist or adding/deleting assets in the playlist.
    4. If any malfunction happens in the switching and the switch time is not accurate,there could be transit inaccuracy for the future EPG. Some examples of actions that could cause this would be a playlist switch or deleting the current active asset in playlist.
    5. Consumers of the EPG should be requesting it as close to realtime as possible to get the most accurate version.

    Page last updated on 12 Mar 2021