Product Updates | Contact Support | System Status
Page Contents

    Overview: Channels API

    With the Channel Manager endpoints, you can create a Cloud Playout channel, add assets & live events to the playlist, then activate, start, stop and delete the channel.

    Requirements

    • A registered application with Cloud Playout API authentication scopes enabled in video-cloud. (Studio UI -> Admin -> API Authentication)

    Creating a CloudPlayoutChannelManager workflow

    Below is the typical Cloud Playout channel management workflow:

    • Create channel
    • Add assets and Live events to the playlist
    • Activate the channel
    • Start the channel
    • Stop the channel
    • Delete the channel

    Apart from these, Get channel is helpful for checking the channel info & state of the channel.

    Create channel

    To create a channel we need mandatory attributes like, name of the channel, start time, input & output group, region and live_profile. DateTime values are preferred in ISO 8601 Date format (UTC or with time offset).

    Sample request

    Request

    Make a POST request to:

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

    Headers

    Content-Type: application/json
    Authorization: Bearer {token}

    Request body

    {
      "name": "channel name",
      "start_time": "2021-06-29T08:30:50.344Z",
      "input_group": [
        {
          "input_type": "playlist or rtmp or slate",
          "input_id": "dummy",
          "loop_on_completion": false
        }
      ],
      "live_profile": "your live profile",
      "output_group": [
        {
          "type": "rtmp or rtp",
          "ingest_locations": [
            {
              "pipeline_id": 1,
              "location": "bc_live or any live channel from your account"
            }
          ]
        },
        {
          "type": "s3",
          "ingest_locations": [
            {
              "pipeline_id": 1,
              "location": "s3 credential id"
            }
          ]
        }
      ],
      "region": "aws region"
    }
    Sample response
    {
      "public_id": "79f0e7503fd64af3b7d2b0f825100f28",
      "name": "channel name",
      "description": "",
      "account_id": "Your account id",
      "state": "DRAFT",
      "status": null,
      "start_time": "2021-06-29 08:30:50 UTC",
      "stop_time": null,
      "input_groups": "playlist",
      "output_groups": "rtmp:s3",
      "loop_playlist": false,
      "playlist_id": "1703814612527248093",
      "channel_class": "single-pipeline",
      "ssai_enabled": true,
      "aws_region": "aws region",
      "message": null,
      "created_at": "2021-06-28 12:43:55 UTC",
      "updated_at": "2021-06-28 12:43:55 UTC",
      "image_url": "https://bc-cloudplayout-prod.s3.amazonaws.com/default_channel_image.png",
      "output_destinations": [
        "Brightcove Live"
      ],
      "channel_created_at": "2021-06-28 12:43:55 UTC",
      "channel_updated_at": "2021-06-28 12:43:55 UTC",
      "channel_created_by": "username@brightcove.com",
      "channel_updated_by": "username@brightcove.com"
    }

    In addition to mandatory fields, there are fields which can be set like description, stop_time, ssai_enabled, image_id, mid_roll_import_enabled, mid_roll_slot_time, etc. Please refer the examples from the Channels API Reference for creating channels with different configurations.

    Add content to the playlist

    The next step is to add content to the channel content. For this you will use the CMS API (note that this is an abbreviated version of the whole CMS API Reference including just the operations relevant to Cloud Playout and with descriptions that are more appropriate to Cloud Playout).

    Get the playlist_id of the channel (from the response to the create channel request or from a get channel request). This is the playlist in which we manage our assets for our Cloud Playout channel.

    Sample request

    Request

    An update video request is used to add content. In the sample below, a collection of video ids are added to create a manual playlist, but note that you can also create smart playlists based on video tags, etc.

    Make a PATCH request to:

    https://cms.api.brightcove.com/v1/accounts/{account_id}/playlists/{playlist_id}

    Headers

    Content-Type: application/json
    Authorization: Bearer {token}

    Request body

    {
      "video_ids": [
        "70702887566202",
        "70702887586202",
        "70702260704202",
        "70702260706202"
      ]
    }
    Sample response
    {
      "id": "1701632459864392160",
      "account_id": "Your account id",
      "created_at": "2021-06-04T10:39:32.934Z",
      "updated_at": "2021-06-04T12:29:06.793Z",
      "description": "cloudplayout",
      "favorite": false,
      "name": "cloudplayout_dvfdb",
      "reference_id": null,
      "type": "EXPLICIT",
      "video_ids": [
        "70702887566202",
        "70702887586202",
        "70702260704202",
        "70702260706202"
      ],
      "state": "READY"
    }

    Add live event

    To add a live event to a channel, you make a create video request to the CMS API, taking care to include some special tags that will identify it as a Cloud Playout live event.

    Sample request

    Request

    Make a POST request to:

    https://cms.api.brightcove.com/v1/accounts/{account_id}/videos

    Headers

    Content-Type: application/json
    Authorization: Bearer {token}

    Request body

    {
      "name": "Name of the event",
      
        "tags": [
          "cp-live-placeholder",
          "duration-00:40:00"
        ]
      ,
      "description": "Description of the event"
    }
    Sample response
    {
      "id": "70702834583294",
      "account_id": "Your account id",
      "ad_keys": null,
      "clip_source_video_id": null,
      "complete": false,
      "created_at": "2021-06-04T11:00:48.551Z",
      "created_by": {
        "type": "user",
        "id": "76072843583",
        "email": "username@brightcove.com"
      },
      "cue_points": [
      ],
      "custom_fields": {
      },
      "delivery_type": "unknown",
      "description": "test description",
      "digital_master_id": null,
      "duration": null,
      "economics": "AD_SUPPORTED",
      "folder_id": null,
      "geo": null,
      "has_digital_master": false,
      "images": {
      },
      "link": null,
      "long_description": null,
      "name": "test live event",
      "original_filename": null,
      "projection": null,
      "published_at": "2021-06-04T11:00:48.565Z",
      "reference_id": null,
      "schedule": null,
      "sharing": null,
      "state": "ACTIVE",
      "tags": [
        "cp-live-placeholder",
        "duration-00:05:00"
      ],
      "text_tracks": [
      ],
      "updated_at": "2021-06-04T11:00:48.572Z",
      "updated_by": {
        "type": "user",
        "id": "76076294383",
        "email": "username@brightcove.com"
      },
      "playback_rights_id": "primary"
    }

    Please refer the CMS API Reference for Cloud Playout for more examples related to managing assets in Cloud Playout.

    Add/Manage Overlays

    Cloud Playout supports two kinds of overlays:

    For each type, the workflow is as follows:

    1. Create an overlay asset

      You will need to provide a public URL for the static or dynamic image. Be sure to include "type": "dynamic" if it is a dynamic overlay.

    2. Associate the overlay with a channel. Note that there are separate endpoints for associating static and dynamic overlays:

    Get Channel

    We can use this endpoint for checking the channel details and state of the channel.

    Sample request

    Request

    Make a GET request to:

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

    Headers

    Content-Type: application/json
    Authorization: Bearer {token}
    Sample response
    {
      "public_id": "channel id",
      "name": "channel name",
      "description": "Channel created for testing Cloud Playout",
      "account_id": "Your account id",
      "state": "DRAFT",
      "status": null,
      "start_time": "2020-12-17 06:00:00 UTC",
      "stop_time": "2020-12-17 07:00:00 UTC",
      "input_groups": "playlist",
      "output_groups": "rtmp",
      "loop_playlist": true,
      "playlist_id": "1686204667297382886",
      "channel_class": "single-pipeline",
      "ssai_enabled": false,
      "aws_region": "us-east-1",
      "message": null,
      "created_at": "2020-12-16 03:41:22 UTC",
      "updated_at": "2020-12-17 04:53:30 UTC",
      "image_url": "https://bc-cloudplayout-prod.s3.amazonaws.com/default_channel_image.png",
      "output_destinations": [
        "Brightcove Live"
      ],
      "channel_created_at": "2020-12-16 03:41:22 UTC",
      "channel_updated_at": "2020-12-17 04:53:30 UTC",
      "channel_created_by": "username@brightcove.com",
      "channel_updated_by": "username@brightcove.com",
      "live_profile": {
        "display_name": "Standard Live HD 720p - Tier 1",
        "name": "standard-live-hd-720p-tier-1",
        "date_created": "2018-06-04 18:16:44 UTC",
        "date_modified": "2018-06-04 18:16:44 UTC"
      },
      "channel_data": {
        "input_group": [
          {
            "input_type": "playlist",
            "value": "cloudplayout_testChannel",
            "description": "Playlist created for Cloud Playout",
            "public_id": "1686204667297382886"
          }
        ],
        "output_groups": [
          {
            "type": "rtmp",
            "location": "bc_live",
            "destination": "Brightcove Live"
          }
        ]
      }
    }

    Activate a channel

    Activate a channel by making the below request. No request body is required.

    Sample request

    Request

    Make a POST request to:

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

    Headers

    Content-Type: application/json
      Authorization: Bearer {token}
    Sample response
    {
      "message":"Channel activation initiated"
    }

    To check the state of the channel, see Get Channel section above.

    Start a channel

    Start a channel by making the below request. No request body is required.

    Sample request

    Request

    Make a POST request to:

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

    Headers

    Content-Type: application/json
      Authorization: Bearer {token}
    Sample response
    {
      "message":"Channel start initiated"
    }

    To check the state of the channel, see Get Channel section above.

    Stop a channel

    Stop a channel by making the below request. No request body is required.

    Sample request

    Request

    Make a POST request to:

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

    Headers

    Content-Type: application/json
      Authorization: Bearer {token}
    Sample response
    {
      "message":"Channel stop initiated"
    }

    To check the state of the channel, see Get Channel section above. Once stopped the channel will be in DRAFT state.

    Delete a channel

    Delete a channel by making the below request. No request body is required.

    Sample request

    Request

    Make a DELETE request to:

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

    Headers

    Content-Type: application/json
      Authorization: Bearer {token}
    Sample response
    {
      "message":"Delete initiated"
    }

    To check the state of the channel, see Get Channel section above. Once the channel has been deleted, you should no longer see the channel info from get channel by id request.

    Get an As-Run log

    An as-run log provides a record of what content (including ads and bumpers) was actually transmitted by a Cloud Playout Channel during the previous day. As-run logs are useful for auditing purposes and record-keeping.

    You can retrieve an as-run log for a channel in JSON, XML, or CSV format by sending a GET request to:

    https://cm.cloudplayout.brightcove.com/accounts/{account_id}/cp_channels/{channel_id}/as_run_logs?format={format}

    The value of format must be json (default), xml, or csv

    Notes

    • The log is constructed regardless of the current state of the channel.
    • The log provides previous day(24 hrs) record. Eg. If current date is 2021-09-22 05:30:00 UTC, then as-run logging provides playback data of the channel from 2021-09-21 00:00:00 UTC to 2021-09-22 00:00:00 UTC.
    • An asset in which a mid-roll is played is split and shown in the data as follows:
      1. VOD asset
      2. Mid-roll asset (played, for example, at 45 second)
      3. VOD asset with playhead_start_time = 00:00:45, the position from which it continues.
    Sample log: JSON
    {
      "account_id": "Account ID",
      "channel_id": "62713ed768434ffbac9ce2ff974c9cb9",
      "channel_name": "TestChannelName",
      "from": "Query start time (UTC)",
      "to": "Query end time (UTC)",
      "events": [
        {
          "name": "Video Cloud Asset name",
          "id": "Video cloud video ID",
          "type": "LIVE | AD | VIDEO | PRE_ROLL_BUMPER | POST_ROLL_BUMPER | MIDROLL",
          "start_time": "2021-07-30 00:00:00.0 UTC",
          "end_time": "2021-07-30 01:00:00.0 UTC"
        },
        {
          "name": "AD Placeholder",
          "id": "Video cloud video ID",
          "type": "AD",
          "start_time": "2021-07-30 01:00:00.0 UTC",
          "end_time": "2021-07-30 01:05:00.0 UTC"
        },
        {
          "name": "Asset with a Midroll AD",
          "id": "6246656690001",
          "type": "VIDEO",
          "start_time": "2021-07-30 01:05:00.0 UTC",
          "end_time": "2021-07-30 01:10:00.0 UTC"
        },
        {
          "name": "Asset with a Midroll AD",
          "id": "6246656690001",
          "type": "MIDROLL",
          "start_time": "2021-07-30 01:10:00.0 UTC",
          "end_time": "2021-07-30 01:10:30.0 UTC"
        },
        {
          "name": "Asset with a Midroll AD",
          "id": "6246656690001",
          "type": "VIDEO",
          "start_time": "2021-07-30 01:10:30.0 UTC",
          "end_time": "2021-07-30 01:20:00.0 UTC",
          "playhead_start_time": "00:05:00"
        }
      ]
    }
    Sample log: XML
    
       Account ID 
      62713ed768434ffbac9ce2ff974c9cb9
      TestChannelName
      Query start time (UTC)
      Query end time (UTC)
    
    
      Video Cloud Asset name
      Video cloud video ID
       LIVE | AD | VIDEO | PRE_ROLL_BUMPER | POST_ROLL_BUMPER | MIDROLL 
      2021-07-30 00:00:00.0 UTC
      2021-07-30 01:00:00.0 UTC
    
    
      AD Placeholder
      Video cloud video ID
      AD
      2021-07-30 01:00:00.0 UTC
      2021-07-30 01:05:00.0 UTC
    
    
      Asset with a Midroll AD
      6246656690001
      VIDEO
      2021-07-30 01:05:00.0 UTC
      2021-07-30 01:10:00.0 UTC
    
    
      Asset with a Midroll AD
      6246656690001
      MIDROLL
      2021-07-30 01:10:00.0 UTC
      2021-07-30 01:10:30.0 UTC
    
    
      Asset with a Midroll AD
      6246656690001
      VIDEO
      2021-07-30 01:10:30.0 UTC
      2021-07-30 01:20:00.0 UTC
      00:05:00
    
    
    
    Sample response: CSV
    account_id, channel_id, channel_name, from, to, event:name, event:id, event:type, event:start_time, event:end_time, event:playhead_start_time

    Page last updated on 02 Oct 2021