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 & 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.

    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.


    Page last updated on 29 Jun 2021