Versions Compared

Version Old Version 5 New Version 6
Changes made by

Phi Le

Thomas Langenskiold

Saved on

Key

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

Introduction

The channel Channel v4 APIs allow allows 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 

information about TV channels that are available in the service. The API reports metadata about the channels as well as configuration details. The API is public requiring no authentication. If configured, the API supports multi-tenancy through Operator Channels.

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 domainsis a representation of a Channel. It contains metadata information such as name and logo, information about enabled services for the channel and configuration options.

Endpoints overview

EndpointHTTP methodPurpose
/api/metadata/v1/channelsGETGet an index of a paginated list of all available 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 descriptionliveThe 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 toliveThis 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 
ID

Services

The Channel entity contains a list of enabled services. The entries in that list defines what services are available for the given channel, as well as service-specific attributes specifying how the service can be used.

Available Services for channels

Live

This service enables a user to watch the channel as a live stream.

Service attributeTypeDescription
startoverbooleanThe channel live stream can be watched starting from the scheduled start time of the currently airing program.
pausebooleanThe channel live stream can be paused and resumed later where it left off.
trickplaybooleanThe channel live stream can be skipped back and forth within the boundaries of the currently available live stream buffer.

nPVR

This service enables a user to create recordings of programs aired on the channel, allowing them to be streamed on-demand after the program has aired.

Service attributeTypeDescription
watch_ongoingbooleanRecordings from this channel can be watched while the program is still being aired.
trickplaybooleanStreams of recordings from this channel can be skipped back and forth.


Catchup

This service enables the user to watch programs that have aired on the channel on-demand for a limited time after they have aired, without having created a recording for the channel.

Service attributeTypeDescription
trickplaybooleanStreams of catchup items from this channel can be skipped back and forth.

Use cases

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)

...