Versions Compared

Version Old Version 3 New Version 4
Changes made by

Phi Le

Phi Le

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

The channel v4 APIs allow clients to get list of channels with paginations by operator if operator config is enabled. Besides, client can get channel by ID to look at information of specific channel. They are cacheable and do not requite authentication. 

Entities 

EntityPurpose
ChannelThis stores information of channels. It also stores flags indicate services of channels such as npvr/live/catchup.
ChannelConfigThis stores configs of channels which describe specific availabilities of channels such as startover, recording window, catchup horizon, etc.
ChannelDomainsDomains belongs to channels. A channel can have multi domains.

Endpoints overview

EndpointHTTP methodPurpose
/api/metadata/v1/channelsGETGet an index of channels.
/api/metadata/v1/channels/{channel_id}GETGet information of a specific channel by channel_id

The APIs accept request parameter language to return channel's name and description by language. The request parameter "show_hidden" in the index of  channels API indicate whether hidden channels should be displayed or not.

Explanation of services

Table of services that are available to users

Value in APIService description
liveThe user may watch this channel as a live stream. User can pause live stream if the channel supports that service.
npvrThe user is allowed to record this channel to their cloud storage account. User can watch an ongoing program if the channel support that service.
catchupThe user is permitted to watch programs that aired previously and are still within the defined catchup window (typically 2 weeks)

Trickplay Service Config

From Wikipedia

Trick mode, sometimes called trick play, is a feature of digital video systems including Digital Video Recorders and Video on Demand systems that mimics the visual feedback given during fast-forward and rewind operations that were provided by analogue systems such as VCRs. Trick play manipulates the video stream to include only a subset of frames.

The AminoTV platform allows trickplay to be enabled on three services.  The following table outlines what enabling trickplay on each service enables the user to do.

Value in APITrickplay features allow the user to
liveThis refers to the ability to fast-forward or rewind through live television.
catchupThis refers to the ability to fast-forward or rewind through television that is being watched in catchup.
npvrFast-forward and rewind.

Explanation of features

Hidden channels

Channels are mainly hidden from the channels' list. They are not disabled. We can still get the channel's info if we know the channel_id. Besides, recordings, epgs, streams and related things are still available for hidden channels. The purpose of hidden channels are for being prepared before official release or they are in maintenance.

Use cases 

First use case 

Step nameStep descriptionAPI endpoint

Info

Possible info text for the use case and how it is linked to other use cases

Second use case

Third use case

Migration guide

Known issues and limitations

Info

Info level limitation example

WarningWarning level limitation example

Get list of visible channels

Client can make a call to GetIndexChannels to list all visible channels and their necessary information. The response will look like this

Code Block
languagephp
themeDJango
firstline1
titleGetIndexChannels
linenumberstrue
collapsetrue
{
  "data": [
    {
      "id": "42",
      "type": "Channel",
      "attributes": {
        "name": "Yle",
        "description": "Lozente",
        "images": [
          {
            "image_type": "Thumbnail",
            "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
            "width_pixels": 320,
            "height_pixels": 200,
            "iso_639-2_lang": "fin",
            "url": "https://www.demo.com/assets/img/thumbnails/movies/diehard.png"
          }
        ],
        "channel_number": {
          "default": 1
        },
        "media_type": "video|audio",
        "enabled_services": [
          {
            "type": "Live",
            "startover": false,
            "pause": false,
            "trickplay": false
          },
          {
            "type": "nPVR",
            "watch_ongoing": true,
            "trickplay": true
          },
          {
            "type": "CatchUp",
            "trickplay": false
          }
        ],
        "channel_domains": [
          "foo",
          "bar"
        ],
        "dvb_info": [
          {
            "type": "C|T|T2",
            "onid": 123,
            "tsid": 123,
            "sid": 4324,
            "quality": "SD|HD|UHD"
          }
        ],
        "metadata_provider_information": [
          {
            "provider": "ERICSSON",
            "external_id": "724693092"
          }
        ]
      },
      "relationships": {
        "stream": {
          "data": {
            "id": "24",
            "type": "LiveStream"
          }
        }
      }
    }
  ]
}

The request accepts parameter language to describe channel name and description by the corresponding language. The other param is page[number] so client can get list of channels by page.


Info

The list of channels are paginated and it is configured.


Get list of channels including hidden channels

Client can make a call to GetIndexChannels to list all channels and their necessary information. The hidden channel are responded if client requests with parameter "show_hidden=true" . If the param is not requested or "show_hidden=false", the endpoint returns all visible channels.

Get information of channel by id

Client can make a call to GetChannelById to get a specific channel's information. The information of hidden channel is also returned if client knows the channel id. The response looks like this:

Code Block
languagephp
themeDJango
firstline1
titleGetChannelById
linenumberstrue
collapsetrue
{
  "data": {
    "id": "42",
    "type": "Channel",
    "attributes": {
      "name": "Yle",
      "description": "Lozente",
      "images": [
        {
          "image_type": "Thumbnail",
          "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
          "width_pixels": 320,
          "height_pixels": 200,
          "iso_639-2_lang": "fin",
          "url": "https://www.demo.com/assets/img/thumbnails/movies/diehard.png"
        }
      ],
      "channel_number": {
        "default": 1
      },
      "media_type": "video|audio",
      "enabled_services": [
        {
          "type": "Live",
          "startover": false,
          "pause": false,
          "trickplay": false
        },
        {
          "type": "nPVR",
          "watch_ongoing": true,
          "trickplay": true
        },
        {
          "type": "CatchUp",
          "trickplay": false
        }
      ],
      "channel_domains": [
        "foo",
        "bar"
      ],
      "dvb_info": [
        {
          "type": "C|T|T2",
          "onid": 123,
          "tsid": 123,
          "sid": 4324,
          "quality": "SD|HD|UHD"
        }
      ],
      "metadata_provider_information": [
        {
          "provider": "ERICSSON",
          "external_id": "724693092"
        }
      ]
    },
    "relationships": {
      "stream": {
        "data": {
          "id": "24",
          "type": "LiveStream"
        }
      }
    }
  }
}

The endpoint accepts parameter language to return channel name and description by language.

Migration guide

The legacy endpoint /api/user/<email>/channel is replaced by GetIndexChannels to list all channels

The legacy endpoint /api/user/<email>/channel/<channel_id> is replaced by GetChannelById to list the specific channel.

Postman collection

Table of Contents

Table of Contents

Child Pages

Child pages (Children Display)

...