Channel Service

Table of Contents

Overview
Data Model
Workflows
- Channel Management
- Playlist Management
Publishing
- Validation via Pre-Publishing Webhook
Interfaces
- GraphQL API
- Messaging
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 Encoding 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.

Note

A webhook is a synchronous request&response pattern used to send data to another service and/or query data from another service. In Mosaic, a webhook is an HTTP REST API implementation to which we send a JSON message (“application/json”) as a POST request that has to return a JSON message in the response body as “application/json”.

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"
}

Each request contains a message signature in the X-Mosaic-Signature HTTP header which was created by a hash-based message authentication code (HMAC) with SHA-256.

Service receiving pre-publishing requests would need to validate the signature. The @axinom/mosaic-service-common Mosaic library provides all functionality and data models required to verify the request signature and generate a valid webhook response.

Example of Pre-Publishing Webhook definition

import {
  Dict,
  generateWebhookResponse,
  handleWebhookErrorMiddleware,
  verifyWebhookRequestMiddleware,
  WebhookRequestMessage,
  WebhookResponse,
  WebhookValidationMessage,
} from '@axinom/mosaic-service-common';
import { Express, Request, Response } from 'express';
import { PrePublishingPayload } from './validation-webhook-model';

export const setupPrePublishingValidationWebhook = (app: Express): void => {
  app.post(
    '/pre-publishing',

    // Mosaic middleware to validate Request signature
    verifyWebhookRequestMiddleware({
      webhookSecret: 'WEBHOOK SECRET',
    }),

    // Mosaic middleware processes a webhook error and returns
    //a WebhookResponse with status code 401. Also logs the resulting error.
    handleWebhookErrorMiddleware,

    async (
      req: Request<
        Dict<string>,
        Dict<string>,
        WebhookRequestMessage<PrePublishingPayload>
      >,
      res: Response,
    ) => {
      const requestBody = req.body;
      let validationResponse: WebhookResponse<PrePublishingPayload> | null =
        null;
      try {
        const errors: WebhookValidationMessage[] = [];
        const warnings: WebhookValidationMessage[] = [];

        // Implement custom validation of Channel, or Playlist object

        validationResponse = generateWebhookResponse<PrePublishingPayload>({
          payload: requestBody.payload,
          errors,
          warnings,
        });
      } catch (error) {
        validationResponse = generateWebhookResponse<PrePublishingPayload>({
          payload: null,
          errors: [
            {
              message: `Unexpected error happened while validating message.`,
              code: `VALIDATION_FAILED`,
            },
          ],
          warnings: [],
        });
      }
      //returns status code 400, if validation result has any errors, otherwise return 200
      const statusCode = validationResponse.errors.length > 0 ? 400 : 200;
      res.status(statusCode).send(validationResponse);
    },
  );
};

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"
}

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.

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.