Channel Service

Table of Contents

Overview
Data Model
Workflows
- Channel Management
- Playlist Management
Publishing
- Validation via Pre-Publishing Webhook
Interfaces
Administration
Pricing

Overview

The Channel Service is a Mosaic Managed Service for managing video content. It allows for creating, organizing, and managing Channels and Playlists made up of VOD assets. With its program scheduling feature, the media assets can be organized at the appropriate time and in the desired order. The service allows the planning of ad breaks as well as intro- and outro-videos into the video content. It provides the option for VOD-to-Live/FAST playback via streaming providers.

Figure 1. Channel Service container diagram

Data Model

Figure 2. Channel Service data model

The Channel metadata is used for describing the channel entity.

A Playlist defines a start date and the list of all Programs that are scheduled in that playlist. The scheduled items can be Media assets from the Axinom Media service, like Movies or TV Show Episodes (or other asset types implemented in that service), but it is also possible to integrate assets coming from any other service. The Channel Service automatically calculates the duration and end date of the playlist based on the length of associated programs and ad insertions. It is important to note that the playlist can only contain Media Assets with videos assigned.

A Program Cue Point describes a time point within a program, where it is possible plan an interruption of the content. The channel service will create a Program Cue Point for each AD_SPOT cue point the Program's video has. In addition to that it will allow a possible interruption also at the beginning and end of the program.

Each Program Cue Point can contain an individual Cue Point Schedules. Such a schedule can consist of the following options:

Ad Pod - defines a location and duration for the insertion of ads in the video playback via an SSAI service.
Video - allows inserting a video from the system to the defied cue point.

Workflows

Channel Service provides a Micro-Frontend for managing Channels. It plugs seamlessly into the Management System where it can be used together with the other Mosaic Services.

Channel Management

Channels workflows include:

Explorer station - overview of all channels in the system and option to create new ones.
Details station - allows managing each channel metadata.

Channel actions

Playlists - manage playlists associated with the Channel.
Manage Logo - assign logo image for the Channel.
Manage Placeholder Video - assign a placeholder video which will be used for example if a potential add insertion fails.
Publishing - validate and publish the Channel.
Delete - remove the Channel from the system.

Playlist Management

Playlist management has similar workflows as Channel management. The Explorer station provides an overview of all the playlists associated with the channel and schedules future playlists, with a default filter set to display upcoming playlists. The Details station allows setting the playlist start time and shows the calculated duration and end time of the playlist.

Playlist actions

Program - provides GUI that allows users to assign Media Assets and fill in video cue points with content (Ad Pods or Videos).
Publishing - validate and publish the Playlist.
Delete - removes the Playlist from the Channel. Only playlists in the state 'Not Published' can be deleted.

Figure 3. Playlist Program Management

Note

The program scheduling makes use of the VOD entities defined in e.g. your media service. To declare the available entity types the providing service needs to register a fast-provider, which provides the Channel service with enough information to make use of the entities in the scheduling. As a reference on how this is done, you can have a look at this PR which registers the media service as fast-provider for the 'Movie' and 'Episode' entities.

Cue Point Management

After adding an entity to the playlist, the workflow will offer various options to plan interruptions of the content.

The Channel Service will automatically create a Program Cue Point for each AD_SPOT cue point the Program's video has. In addition it allows to plan an interruption also at the beginning and end of each program.

To manage the cue points, please use the corresponding workflow on the video service.

Each Cue Point Schedule can consist of one or more of the following options: - A video from the video service (this can be used for bumper videos, intro videos, etc.) - An Ad Pod (this can be used for ad insertion via SSAI)

When the vod-to-live service encounters and ad pod it is expected to set a SCTE-35 marker in the stream to indicate the start and end of the ad break. This allows the server-side ad insertion (SSAI) service to insert ads into the stream. As a fallback the service usually schedules the placeholder video to be played during the ad break. This is will be used in cases where the SSAI fails, or when for specific users the ad break can only be partially filled with ads.
The precise behavior however is defined by the VOD-to-Live Service.

Publishing

Channels and Playlists share a common two-step publication process.

The first step is validation, where the system checks if everything is in order and there is no missing information. If there are any issues or errors found during validation notifications with issue severity and description will be shown.

Once the validation is successful, can proceed to the second step, which is publishing your channel or playlist.

Upon pressing "Publishing", validation rules are applied, and a list of errors and warnings is displayed. The validation page is always displayed even in the case that there are no issues so it is safe to click "Publishing" to see the current validation state even if you do not wish to publish at the time.

Errors prevent publication.
Warnings do not prevent publication.

Table 1. Channel validation rules
Severity	Message	Description
`WARNING`	No image assigned.	Logo image is not assigned to the Channel.
`WARNING`	Image with id '{unique_id}' no longer exists.	Logo image unique identifier was not found in the Image Service.
`WARNING`	No video assigned.	Placeholder video was not assigned to the Channel.
`ERROR`	Details for video '{unique_id}' were not found.	Placeholder video assigned to the Channel was not found in the Video Service.

Table 2. Playlist validation rules
Severity	Message	Description
`ERROR`	Channel associated with the playlist is not published.	Playlist cannot be published independently from the Channel.
`WARNING`	No images assigned.	Playlist programs have no covers assigned.
`WARNING`	Image with id '{unique_id}' no longer exists.	Image associated with the program was not found.
`WARNING`	No video assigned.	Playlist programs have no videos assigned.
`ERROR`	Details for video '{unique_id}' were not found.	Video associated with the playlist program was not found.

Validation via Pre-Publishing Webhook

The optional functionality of validation via Pre-Publishing Webhook allows extending the validation rules applied to entities before publication. The webhook handler can be part of any external service (usually VOD-to-Live Service) that would be the consumer of published events.

If the Pre-Publishing webhook is set (read below how to configure) alongside basic validation, the Channel Service will send a REST request to the Webhook API as part of the entity validation process. The request will contain a JSON document, that will contain the Channel/Playlist object required to validate. This allows a customizable service to perform any form of additional business rule validation before the entities are published.

Pre-Publishing Webhook request format

{
   "payload":{
     // JSON object for published channel, or playlist
   },
   "message_id":"41409546-df67-42b6-b5c4-c006b26b6bad",
   "timestamp":"2022-09-22T09:26:10.498Z",
   "message_type":"PublishEntityType",
   "message_version":"1.0"
}

The Webhook response should be in a pre-defined format containing the lists of validation errors and warnings.

Pre-Publishing Webhook response format

{
   "payload":{
      // JSON object for published channel, or playlist
   },
   "errors": [{
     "message": "The error message",
     "code": "ERROR_CODE_1"
   }],
   "warnings": [{
     "message": "The warning message",
     "code": "WARNING_CODE_1"
   }],
   "message_version": "1.0"
}

Please refer to the Webhooks article on how to implement a webhook securely.

Interfaces

GraphQL API

The GraphQL API is available to read and manage all data stored in the service. Interactions with the service API require a JWT token from the Admin Service. See more: How to authenticate a service account.

Messaging

The Channel Service implements the Mosaic Messaging concept. The service supports several commands and events, with the most prominent being the Channel and Playlist published event messages.

Workflows

Route Resolvers

Channel pilet registers following route resolvers, that can be used to link to the Channel stations:

channel-details - resolvers the route to the Channel Details station.
program-details - resolvers the route to the Program Management Components station

To link to these stations consuming workflows need to use PiletApi method resolveRoute and provide resolver name and dynamic route parameters. The method will return a string containing the route that can be used for linking to the station.

Channel Details Station Route Resolver

Channel details route resolver can be called in two different ways:

providing a channelId as a string

const channelRoute = app.resolveRoute('channel-details', '123');

providing an object where object key represents the name of the dynamic route segment channelId
```
const channelRoute = app.resolveRoute('channel-details', {
  channelId: '123',
});
```

Program Management Components Station Route Resolver

Program details route resolver can be called in two following ways:

providing a programId as a string. Though the route doesn’t contain programId in it, it will be used to request the missing dynamic segments channelId and playlistId from the service and replace route with values returned from the service.
```
const programRoute = app.resolveRoute('program-details', '789');
```
providing an object where object key represents the name of the dynamic route segments. There are several options what dynamic route segments to provide with the object:
- providing programId. The channelId and playlistId will be requested from the service and route will be replace using the resolved values.
  const programRoute = app.resolveRoute('program-details', { programId: '789', });
- providing channelId and playlistId, where channelId is optional and playlistId is required. In case channelId is not provided, it will be requested from the service and route will be replace using the resolved values.
  const programRoute = app.resolveRoute('program-details', { channelId: '123', // optional playlistId: '456', });

Administration

The Pre-Publishing Webhook settings can be configured in the Mosaic Admin Portal. The webhook configuration has a corresponding secret which will be used for signing the requests to the webhook. The secret generated by Admin Portal for the webhook should be used by the receiving service (usually VOD-to-Live Service) to validate the requests.

Figure 4. Admin Portal - Channel Service Configuration

channel admin gui configuration new webhook

Figure 5. Admin Portal - Define a Webhook URL

channel admin gui configuration webhook secret

Figure 6. Admin Portal - Webhook Secret

Pricing

The service fee is depending on the number of channels managed by the service. See Mosaic Pricing for more details.