DEV Community: Consuo Dev Blog

Lambda Function to Insert Ads with Consuo

Jonas Birmé — Fri, 05 Jun 2020 07:34:51 +0000

With Consuo you can create virtual linear TV channels from the video on demand files that you already have on your CDN and in this post we will describe how you can write a simple Lambda-function to insert ads between the programs in the channel.

A Lambda function in this case is a code snippet that is running in the cloud without you having to think about servers. Both Amazon Web Service, Azure and Heroku offers this functionality and in this blog post we will be using the service provided by AWS that is called AWS Lambda.

We will create a code snippet that will be given a URI to an HLS packaged video on demand file on the CDN and will rewrite the manifest of this HLS file and insert markers and ad segments. This modified manifest will then be scheduled in Consuo. Consuo preserves these ad markers in the virtual linear TV stream which means that by using a server-side ad replacer we can replace these ads with more targeted ads for a specific user.

How it works

We will create an endpoint that will respond with the modified HLS manifest and what will be served to a video player, or in our case, Consuo. As a query parameter you provide a base64 encoded payload with the location of the source VOD and the locations of the ads. Actually we will need two endpoints. One to handle the master manifest and another for each media manifest.

The process will be as follows:

Consuo (or a general video player) will be given an URI to the Lambda endpoint together with the base64 encoded JSON payload.
Consuo fetches the master manifest from the Lambda endpoint. The Lambda endpoint will return a master manifest where the media manifest are pointing to the Lambda endpoint together with the base64 encoded payload.
To start playing the media manifests are now fetched from this Lambda endpoint.
When a media manifest request is handled the Lambda function will retrieve the original media manifest from the VOD CDN and parse it. It will then manipulate this media manifest and insert the ad segments, adding ad markers and other necessary HLS tags.
It then returns this manipulated media manifest to Consuo or the video player. As it is only the manifest files that are manipulated the video segments will be still fetched directly from the CDN and not through this Lambda.

The Code

The code to handle a master manifest request is shown below. Full Source Code is available on GitHub.

const handleMasterManifestRequest = async (event) => {
  try {
    const encodedPayload = event.queryStringParameters.payload;
    console.log(`Received request /master.m3u8 (payload=${encodedPayload})`);
    const manifest = await getMasterManifest(encodedPayload);
    const rewrittenManifest = await rewriteMasterManifest(manifest, encodedPayload);
    return generateManifestResponse(rewrittenManifest);
  } catch (exc) {
    console.error(exc);
    return generateErrorResponse(500, "Failed to generate master manifest");
  }
};

And as previously mentioned it returns a rewritten master manifest where the media manifest locations from the original manifest has just been replaced to point to this Lambda endpoint instead.

To handle the media manifest request we will have these lines of code:

const handleMediaManifestRequest = async (event) => {
  try {
    const bw = event.queryStringParameters.bw;
    const encodedPayload = event.queryStringParameters.payload;
    console.log(`Received request /media.m3u8 (bw=${bw}, payload=${encodedPayload})`);
    const hlsVod = await createVodFromPayload(encodedPayload, { baseUrlFromSource: true, subdir: event.queryStringParameters.subdir });
    const mediaManifest = (await hlsVod).getMediaManifest(bw);
    return generateManifestResponse(mediaManifest);
  } catch (exc) {
    console.error(exc);
    return generateErrorResponse(500, "Failed to generate media manifest");
  }
};

And the interesting function here is the createVodFromPayload() which we can have a look into.

const createVodFromPayload = async (encodedPayload, opts) => {
  const payload = deserialize(encodedPayload);

  const uri = payload.uri;
  let vodOpts = {
    merge: true
  };
  if (opts && opts.baseUrlFromSource) {
    const m = uri.match('^(.*)/.*?');
    if (m) {
      vodOpts.baseUrl = m[1] + "/";
    }
    if (opts.subdir) {
      vodOpts.baseUrl += opts.subdir + "/";
    }
  }

  const hlsVod = new HLSSpliceVod(uri, vodOpts);
  await hlsVod.load();
  adpromises = [];
  for (let i = 0; i < payload.breaks.length; i++) {
    const b = payload.breaks[i];
    adpromises.push(() => hlsVod.insertAdAt(b.pos, b.url));
  }
  for (let promiseFn of adpromises.reverse()) {
    await promiseFn();
  }
  return hlsVod;
};

It utilizes the open source library @eyevinn/hls-splice to actually do the manifest manipulation.

Making it available

We now have the code for the Lambda function and once we have created a Lambda function in AWS we now need to make this available.

To do that we need to add an Application Load Balancer where HTTP requests on port 80 are forwarded to a target group of type Lambda.

Requests that are coming from the ALB are then handled in the main entry function of the Lambda.

exports.handler = async event => {
  let response;

  if (event.path === "/stitch/" && event.httpMethod === "POST") {
    response = await handleCreateRequest(event);
  } else if (event.path === "/stitch/master.m3u8") {
    response = await handleMasterManifestRequest(event);
  } else if (event.path === "/stitch/media.m3u8") {
    response = await handleMediaManifestRequest(event);
  } else {
    response = generateErrorResponse({ code: 404 });
  }

  return response;
};

Example

Here is an example with a pre-roll ad: http://lambda.eyevinn.technology/stitch/master.m3u8?payload=eyJ1cmkiOiJodHRwczovL21haXR2LXZvZC5sYWIuZXlldmlubi50ZWNobm9sb2d5L3N0c3dlMTctd2lsbGxhdy5tNHYvbWFzdGVyLm0zdTgiLCJicmVha3MiOlt7InBvcyI6MCwiZHVyYXRpb24iOjE2MDAwLCJ1cmwiOiJodHRwczovL21haXR2LXZvZC5sYWIuZXlldmlubi50ZWNobm9sb2d5L2Fkcy82Y2Q3ZDc2OC1lMjE0LTRlYmMtOWYxNC03ZWQ4OTcxMDExNWUubXA0L21hc3Rlci5tM3U4In1dfQ== and decoding the base64 show you the payload.

{"uri":"https://maitv-vod.lab.eyevinn.technology/stswe17-willlaw.m4v/master.m3u8","breaks":[{"pos":0,"duration":16000,"url":"https://maitv-vod.lab.eyevinn.technology/ads/6cd7d768-e214-4ebc-9f14-7ed89710115e.mp4/master.m3u8"}]}

Then we can use the example above and put it in a schedule in Consuo which could look like this.

[
...
 {
    "channelId": "eyevinn",
    "assetId": "urn:uuid:ee16c6bf-70b9-4246-9b70-b132b706beda",
    "eventId": "dd02e9ea-0ec4-4d26-9e6c-12a85e762c65",
    "id": "urn:uuid:ee16c6bf-70b9-4246-9b70-b132b706beda",
    "title": "STSWE17 Will Law",
    "start_time": 1591335742455,
    "end_time": 1591337431455,
    "start": "2020-06-05T05:42:22.455Z",
    "end": "2020-06-05T06:10:31.455Z",
    "uri": "http://lambda.eyevinn.technology/stitch/master.m3u8?payload=eyJ1cmkiOiJodHRwczovL21haXR2LXZvZC5sYWIuZXlldmlubi50ZWNobm9sb2d5L3N0c3dlMTctd2lsbGxhdy5tNHYvbWFzdGVyLm0zdTgiLCJicmVha3MiOlt7InBvcyI6MCwiZHVyYXRpb24iOjE2MDAwLCJ1cmwiOiJodHRwczovL21haXR2LXZvZC5sYWIuZXlldmlubi50ZWNobm9sb2d5L2Fkcy9iYzU1ZmZkYy1kMDcxLTQ4NTgtYTk3ZC1jMjI5M2YwNTlmMTkubXA0L21hc3Rlci5tM3U4In1dfQ==",
    "duration": 1689
  },
...
]

Summary

Adding this Lambda function you can generate virtual linear TV channels with ads and using this in combination with a server-side ad inserter you can have linear TV channels with individually targeted ads. If you want to know more about Consuo visit www.consuo.tv and request a free 30-days trial.

Launching Virtual Channels on AWS with Consuo

Jonas Birmé — Wed, 27 May 2020 20:37:33 +0000

Consuo is a cloud-agnostic software component to generate virtual linear TV channels, and in this blog post we will describe how you can deploy this component to AWS and not having to manage any server instances.

Elastic Container Service and Fargate

Amazon ECS (Elastic Container Service) is a container management and orchestrator of Docker containers running on a cluster. With the Fargate launch type you run your cluster on a serverless infrastructure, and this is what we will use in the example.

Task Definitions

Before we create the ECS cluster we will start by defining two task definitions. One task definition for the Consuo Schedule container, and another for the Consuo Engine container.

Let us begin with the task definition for the Consuo Schedule task. Some parts are left out to highlight the Consuo specifics.

{
  ...
  "containerDefinitions": [
    {
      ...
      "entryPoint": null,
      "portMappings": [
        {
          "hostPort": 8001,
          "protocol": "tcp",
          "containerPort": 8001
        }
      ],
      ...
      "environment": [
        {
          "name": "CORS_WHITELIST",
          "value": "https://example.com,https://www.example.com"
        },
        {
          "name": "KEY",
          "value": <LICENSEKEY>
        }
      ],
      ...
      "image": "eyevinntechnology/consuo-schedule:v1.1.0",
      "name": "consuo-schedule",
      ...
    }
  ],
  "requiresCompatibilities": [
    "FARGATE"
  ],
  ...
}

We define the port mappings for the default port that is 8001 for Consuo Schedule and provide the environment variables CORS_WHITELIST and the license key. For a full list of available environment variables and their purpose read the Consuo documentation.

We then define a similar task definition for the Consuo Engine.

{
  ...
  "containerDefinitions": [
    {
      ...
      "entryPoint": null,
      "portMappings": [
        {
          "hostPort": 8000,
          "protocol": "tcp",
          "containerPort": 8000
        }
      ],
      ...
      "environment": [
        {
          "name": "CHANNELMGRAPI",
          "value": "http://<CONSUO_SCHEDULE_IP>:8001"
        },
        {
          "name": "KEY",
          "value": <LICENSEKEY>
        }
      ],
      ...
      "image": "eyevinntechnology/consuo-engine:v1.1.0",
      "name": "consuo-schedule",
      ...
    }
  ],
  "requiresCompatibilities": [
    "FARGATE"
  ],
  ...
}

At the moment we have a placeholder for the CHANNELMGRAPI variable and we will later replace it with the URI that the Consuo Schedule API will be accessible on. In both task definitions we define that we want to use Fargate as the launch type for these tasks.

Cluster and Services

Then we will create the cluster for Consuo services in ECS. Once the cluster is created we will then create two services. One for the Consuo Schedule service and another for the Consuo Engine service.

When creating the services we will use each of the task definitions defined above and service type REPLICA and launch type FARGATE. For the Schedule service you need to ensure that the security group allows TCP traffic on port 8001 and for the Engine service open up port 8000, as this is what we specified in the task definitions. Number of replicas we set initially to 1.

Load Balancing

To be able to access these services we need to setup a load balancer. We will use the AWS Application Load Balancer so we can reuse the same instance for both services. We will have one target group for each of the services. The ALB we configure with two listeners: HTTP 8000 and HTTP 8001 where port 8000 forwards to the Consuo engine target group and port 8001 forwards traffic to the Consuo schedule target group.

Once everything is setup you will then be able to access the Consuo schedule service on for example: http://alb-consuo-486438318.eu-north-1.elb.amazonaws.com:8001/api/docs/

And now you can update the CHANNELMGRAPI variable to point to for example http://alb-consuo-486438318.eu-north-1.elb.amazonaws.com:8001.

If you don't intend to have the schedule accessible outside of the cluster we could use the service discovery functionality and have the Consuo schedule container only accessible by the Consuo engine container. That is left as an exercise for the reader.

CDN

To off-load the traffic to the Consuo engine service it is recommended to place a CDN in front of it. With AWS we can use their CDN service Cloudfront to do this. This also gives a possibility to have SSL termination which is today needed to be able to play the stream in a browser. You create a distribution where you specify the ALB as the origin and origin port 8000. Important to configure the distribution to Use Origin Cache Headers and query string whitelist channel. You might also want to override the caching TTLs for error codes such as 404 and 500, to avoid getting 404s stuck in the caches.

When everything is up and running you will now have a system setup that looks similar to this drawing.

To build the Consuo component ecosystem

Erik Hoffman — Tue, 26 May 2020 04:54:46 +0000

At Eyevinn we’ve always valued platform and product independence as well as taking a neutral stand when it comes to languages and frameworks. Therefore, when building components for Consuo, our vod-to-live stitching product, it was a quite obvious choice for us to not only build a React component, which may have been the simplest decision, but also a web component for vanilla JavaScript projects with no framework being used.

A lot of JavaScript developers these days thinks that you need a framework such as React or Vue to be able to create encapsulated components to be shareable. Though over the last few years standards as been moving quite fast and the web component standard as such give us all the features that we expects and wants out of modern JavaScript solution for building a component to act isolated as well as being shared in a simple way, both internally as well as externally (e.g. webcomponents.org).

Since before we already had an Up Next component for Consuo, built and shared as a React component. As soon as it had been shared internally I took the challenge to create an exact replica as an web component, as I as a developer loves standard vanilla, no framework, solutions.

Why do we need an ecosystem for Consuo?

Consuo as a product, or rather as a base platform together with its open source engine, is the core of a wider end user experience. We want to bring the laid back experience of classic linear tv into the new era of streaming, as well as bringing the unused potential back to the streaming companies backlog of clips and vod videos in terms of consumption and monetization.

Consuo as a core handles the scheduling as well as the stitching of the channel, creating the core experience. Though we want to help you evolve that experience by bringing more functionality to the table by building a base plate of open source components to be used. This starts with our schedule related components to show what’s currently on air and what’s next up.

Framework decisions and framework neutrality?

We started to build this component as a React component, as this is currently the framework of choice for our product web as well as demo solutions. But as mentioned earlier, we have a history and pride of being language and framework agnostic at Eyevinn. And we do really want this experience and these components to be available for everyone to implement and to use.

With the evolvement of the quite recent web component standard it was a simple decision to take, to develop such alternative as well. As this can be used in all frameworks, not isolated to a single one.

The state of web components

As mentioned earlier The state of web components in style JavaScript standard is quite exciting these days. The api as such might not be as simplified and fine tuned as in React or Polymer, but all the functionality as expected is there, and to avoid the overhead of an framework as well as creating a shareable component not dependent on the framework being used by the implementing part, is a quite exciting thing.

So what can we do?

Choose to be reachable by outer JavaScript or to entirely encapsulate the functionality.
Choose to be reachable by outer styling or to entirely encapsulate our styles.
Act on being attached, as well as detached, from a document. (See Life Cycle Callbacks)
Act on the attributes of the element being changed during runtime.

This means that we can choose whether we want to build an ecosystem by contributed functionality only, or by encapsulated visually designed components that matches our product’s graphical profile.

For this specific component we just wanted to deliver the functionality of a simple schedule visualizer and do not encapsulate any specified styling.

So let’s go to the functionality of the Up Next component as such and to compare a React component to what we can build in native JavaScript.

The feature set

The component as such solves a rather basic scenario which can be seen as a base plate functionality in any linear channel experience - Showing what’s currently playing and what’s Up Next.

This is implemented by pulling the schedule from which the linear experience is created out of the video files that already exists in the archive.

An example of such schedule json

[
  {
    "channelId": "eyevinn",
    "assetId": "urn:uuid:da80b21b-2e6e-42ae-82b8-3b1b5581b59a",
    "eventId": "735fecc8-cade-410d-993f-9860e4de9efe",
    "id": "urn:uuid:da80b21b-2e6e-42ae-82b8-3b1b5581b59a",
    "title": "TV Plus Joachim",
    "start_time": 1590226668810,
    "end_time": 1590226741810,
    "start": "2020-05-23T09:37:48.810Z",
    "end": "2020-05-23T09:39:01.810Z",
    "uri": "http://lambda.eyevinn.technology/stitch/master.m3u8?payload=eyJ1cmkiOiJodHRwczovL21haXR2LXZvZC5sYWIuZXlldmlubi50ZWNobm9sb2d5L3R2cGx1cy1hZC1qb2FjaGltLm1vdi9tYXN0ZXIubTN1OCIsImJyZWFrcyI6W3sicG9zIjowLCJkdXJhdGlvbiI6MTYwMDAsInVybCI6Imh0dHBzOi8vbWFpdHYtdm9kLmxhYi5leWV2aW5uLnRlY2hub2xvZ3kvYWRzL3NmZi0xNXMubXA0L21hc3Rlci5tM3U4In1dfQ==",
    "duration": 73
  },
  {
    "channelId": "eyevinn",
    "assetId": "urn:uuid:b8ff551a-6da3-485a-8a53-b11c5d28753f",
    "eventId": "c25f531a-3bf5-4645-b3f0-cbaf4c7f459d",
    "id": "urn:uuid:b8ff551a-6da3-485a-8a53-b11c5d28753f",
    "title": "TV Plus Johanna",
    "start_time": 1590226741810,
    "end_time": 1590226816810,
    "start": "2020-05-23T09:39:01.810Z",
    "end": "2020-05-23T09:40:16.810Z",
    "uri": "http://lambda.eyevinn.technology/stitch/master.m3u8?payload=eyJ1cmkiOiJodHRwczovL21haXR2LXZvZC5sYWIuZXlldmlubi50ZWNobm9sb2d5L3R2cGx1cy1hZC1qb2hhbm5hLm1vdi9tYXN0ZXIubTN1OCIsImJyZWFrcyI6W3sicG9zIjowLCJkdXJhdGlvbiI6MTYwMDAsInVybCI6Imh0dHBzOi8vbWFpdHYtdm9kLmxhYi5leWV2aW5uLnRlY2hub2xvZ3kvYWRzLzZjZDdkNzY4LWUyMTQtNGViYy05ZjE0LTdlZDg5NzEwMTE1ZS5tcDQvbWFzdGVyLm0zdTgifV19",
    "duration": 75
  }
]

React component vs Web Component

Both these components are built in quite a similar way as the feature set is quite similar, as mentioned earlier on in this post. So the things that really differs is the markup as such, the state handling and the rendering language implementation.

Life cycle handling

Life cycles in React and Web Components exposes the same possibilities, though with different terminology and minor limitations.

A simple table of the most common life cycle events can be shown as this

Event	React Component	Web Component
Added to DOM	componentDidMount	connectedCallback
Rendering	render	-
Attributes being changed	-	attributeChangedCallback
Removed from DOM	componentWillUnmount	disconnectedCallback

As seen the main structure is the same between the solutions, though the missing part doesn't mean that the functionality is missed as such.

React handles the changed attributes by simply changing the values on the props of the component, and re-render the component with those values in mind. In the web component you will have to trigger the render function yourself, both when added to DOM (the connectedCallback event) as well when you get the event for changed attribute values.

Rendering

The other major difference is how the rendering is handled. In React you render your inner html with a markup language called JSX. This gives us the ability to get great autocompletion in your code editor as well as evaluating expressions and values of properties to take visualisation decision based on those. For Web Components on the other hand, we will rather create the inner html elements in JavaScript and append them as childs or, as I prefer to do, write the html as such in a template literal. Even though this doesn't bring the excellent editor functionality as JSX might give us, we will have the same ability to handle expressions and property values in the rendition.

React Example

Web Component Example

Conclusion

To take the extra step and deliver a cross framework component is, as seen, quite a small job - bringing not only a value to the ecosystem that we want to build, but also letting the customer utilise our knowledge and development undependent on their framework choices.

The components can be downloaded through npm (React component and web component) and the source code can be found on our Github (React component and web component). Please feel free to contribute, either to the libraries and components that already exists or to the ecosystem around the Channel engine and Consuo by building open source functionality around them.

Using the in-built Auto Scheduler

Jonas Birmé — Sat, 23 May 2020 11:22:07 +0000

The quickest way to get started and creating a virtual channel is to use the in-built auto-scheduler. In this blog post we will walk you through how this is done.

In the Consuo Schedule micro service, an automatic scheduler is included that can automatically add events to a channel's schedule. The assets for the events are randomly chosen and four events at the time are added back-to-back in the schedule. This can be used to create numerous virtual channel based on a search query in the VOD library. For example a virtual channel for all news clips about a news event that is unfolding.

When creating a new channel you define that this channel should use the automatic scheduler and you provide an URI to an Atom RSS feed containing the assets the automatic scheduler can choose from. Between your video asset search you build an adapter that translates the response into an Atom RSS xml. The mandatory fields are <id> and <link> but a title is recommended to also be provided.

<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Content from Eyevinn</title>
  <id>urn:uuid:883e6f00-783e-46d0-bb6c-0e15e6ac4e33</id>
  <updated>2020-05-22T08:48:00Z</updated>
  <entry>
    <id>urn:uuid:23d1d228-2305-4bc8-a937-1280a0d7e33a</id>
    <title>Tears of Steel</title>
    <link>https://maitv-vod.lab.eyevinn.technology/tearsofsteel_4k.mov/master.m3u8</link>
  </entry>
  <entry>
    <id>urn:uuid:1555b26b-ecdd-4658-b527-e35b6429ef58</id>
    <title>VINN</title>
    <link>https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8</link>
  </entry>
</feed>

To create a channel with automatic scheduling enabled you issue an HTTP POST with the following JSON to the /channels endpoint.

{
  "id": "mychannel",
  "name": "My Automatic Channel",
  "config": {
    "auto_populate": true,
    "auto_populate_content": <RSS_URI>,   
    "auto_cleanup": true
  }
}

The config parameter auto_populate when set to true enables the automatic scheduler and the auto_populate_content parameter points to the RSS feed.

To verify that the automatic scheduler is working you can fetch the schedule for this channel with an HTTP GET of /channels/mychannel/schedule and you would get something similar to this:

[
  {
    "channelId": "eyevinn",
    "assetId": "urn:uuid:da80b21b-2e6e-42ae-82b8-3b1b5581b59a",
    "eventId": "735fecc8-cade-410d-993f-9860e4de9efe",
    "id": "urn:uuid:da80b21b-2e6e-42ae-82b8-3b1b5581b59a",
    "title": "TV Plus Joachim",
    "start_time": 1590226668810,
    "end_time": 1590226741810,
    "start": "2020-05-23T09:37:48.810Z",
    "end": "2020-05-23T09:39:01.810Z",
    "uri": "http://lambda.eyevinn.technology/stitch/master.m3u8?payload=eyJ1cmkiOiJodHRwczovL21haXR2LXZvZC5sYWIuZXlldmlubi50ZWNobm9sb2d5L3R2cGx1cy1hZC1qb2FjaGltLm1vdi9tYXN0ZXIubTN1OCIsImJyZWFrcyI6W3sicG9zIjowLCJkdXJhdGlvbiI6MTYwMDAsInVybCI6Imh0dHBzOi8vbWFpdHYtdm9kLmxhYi5leWV2aW5uLnRlY2hub2xvZ3kvYWRzL3NmZi0xNXMubXA0L21hc3Rlci5tM3U4In1dfQ==",
    "duration": 73
  },
  {
    "channelId": "eyevinn",
    "assetId": "urn:uuid:b8ff551a-6da3-485a-8a53-b11c5d28753f",
    "eventId": "c25f531a-3bf5-4645-b3f0-cbaf4c7f459d",
    "id": "urn:uuid:b8ff551a-6da3-485a-8a53-b11c5d28753f",
    "title": "TV Plus Johanna",
    "start_time": 1590226741810,
    "end_time": 1590226816810,
    "start": "2020-05-23T09:39:01.810Z",
    "end": "2020-05-23T09:40:16.810Z",
    "uri": "http://lambda.eyevinn.technology/stitch/master.m3u8?payload=eyJ1cmkiOiJodHRwczovL21haXR2LXZvZC5sYWIuZXlldmlubi50ZWNobm9sb2d5L3R2cGx1cy1hZC1qb2hhbm5hLm1vdi9tYXN0ZXIubTN1OCIsImJyZWFrcyI6W3sicG9zIjowLCJkdXJhdGlvbiI6MTYwMDAsInVybCI6Imh0dHBzOi8vbWFpdHYtdm9kLmxhYi5leWV2aW5uLnRlY2hub2xvZ3kvYWRzLzZjZDdkNzY4LWUyMTQtNGViYy05ZjE0LTdlZDg5NzEwMTE1ZS5tcDQvbWFzdGVyLm0zdTgifV19",
    "duration": 75
  }
]

As you see in the example above the schedule events are all back-to-back and that is taken care of by the automatic scheduler.

The config parameter auto_cleanup specifies whether old events should be automatically removed.

This automatic scheduler is at the moment very basic and does not prevent that same assets in a row are scheduled and if you intend more sophisticated logic you can build your own automatic scheduler using the APIs provided.

And how to do that, we leave room for in another blog post. Stay tune!

Schedule events for your first virtual channel

Jonas Birmé — Sat, 16 May 2020 12:00:10 +0000

In this blog we will walk you through how you by using the Consuo Schedule API can create a virtual channel and add events to the schedule.

Pre-requisities

You have already an instance of Consuo up and running and you replace <CHANNELMGR_IP> in this post with the IP-address to where your Consuo Schedule manager is running. For instructions on how to setup and install Consuo you can read the Quick Start guide.

Create channel

We will use the Consuo Schedule API to create a channel. You find the API documentation at http://<CHANNELMGR_IP>:8001/api/docs/. In the examples in this post we will use Node JS but other programming languages can be used as the API is HTTP based. What we will do first is to create a channel.

In this example we use fetch as HTTP client and to create a channel we do an HTTP POST with the following body to the endpoint /channels.

{
  id: "one",
  name: "Channel One"
}

Example code:

const fetch = require('node-fetch');
const API = "http://<CHANNELMGR_IP>:8001";

async function run() {
  const res = await fetch(API + '/channels', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      id: "one",
      name: "Channel One"
    })
  });
  const json = await res.json();
  console.log(json);
}

run();

Now you have a channel created that has the ID one and the name Channel One.

Add an event

Next, let us schedule an event. An event has a start, end and a URI to the video file to be played out. The format of the video file must be HLS as that is what Consuo supports today. The start time of the event is provided as a Unix Timestamp in milliseconds and all timestamps are in UTC timezone.

As an example, we want to create an event that starts on May 16 at 14:00 CET (UTC+02:00).

const start_time = Date.parse("16 May 2020 14:00:00+02:00");

In this example start_time is then 1589630400000. To calculate the end_time we need to add the duration of the video file that we want to schedule. The video file we want to schedule is https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8 and it has a duration of 106 seconds. To calculate the end_time we need to multiply the duration with 1000 as the timestamps are in milliseconds and then we add this to the start_time.

const end_time = start_time + (106 * 1000);

The event we want to schedule then looks as follows:

const event = {
  assetId: "VINN",
  title: "VINN",
  start_time: Date.parse("16 May 2020 14:00:00+02:00"),
  end_time: start_time + (106 * 1000),
  uri: "https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8",
  duration: 106
};

Then we make an HTTP POST with the above JSON to /channels/one/schedule. The schedule for this channel will now include this:

[
  {
    "assetId": "VINN",
    "eventId": "4c605714-a3db-48e5-a5af-d0ece30246de",
    "id": "VINN",
    "title": "VINN",
    "start_time": 1589630400000,
    "end_time": 1589630506000,
    "start": "2020-05-16T12:00:00.000Z",
    "end": "2020-05-16T12:01:46.000Z",
    "uri": "https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8",
    "duration": 106
  }
]

The code example for the above can then look like this:

  const uri = "https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8";
  const start_time = Date.parse("16 May 2020 14:00:00+02:00");
  const end_time = start_time + (106 * 1000);
  const event = {
    assetId: 'VINN',
    title: 'VINN',
    start_time: start_time,
    end_time: end_time,
    uri: uri,
    duration: 106
  };
  const res = await fetch(API + '/channels/one/schedule', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(event)
  });

Playing the channel

To start playing the channel that you just created and added events to you need an HLS capable video player. If you just want to test you can use the HTML player at http://player.eyevinn.technology/ and enter the URI http://<ENGINE_IP>:8000/live/master.m3u8?channel=one. The <ENGINE_IP> is the IP to the Consuo Engine service.