video create

Video upload

Normal

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

large_api-video-blog-tutorials.png

medium_api-video-blog-tutorials.png

small_api-video-blog-tutorials.png

thumbnail_api-video-blog-tutorials.png

api-video-blog-tutorials.png

Tutorials

NodeJS

User generated content (UGC) can be an incredible addition to your application or website. Your users generate videos, and upload them to share with other users, creating a cascading effect that increases the number of videos on your platform.

In the past, we've looked at [video moderation](https://api.video/blog/tutorials/automated-video-moderation/) to protect you from inappropriate UGC. In this post, we'll look at mitigation strategies to limit the NUMBER of videos one user might upload. (Go [here](https://docs.api.video/reference/api/Videos#create-a-video-object) to check out the API reference documentation for uploading videos.)

## Overwhelming video content

Your user might just be enthusiastic about our platform, or perhaps they have nefarious reasons - but they are just uploading too many videos! Perhaps you just want the videos to stop - so you could ban or cancel the user's account.  But perhaps the videos are still welcome, they just need to slow down a bit.

In this post, we'll add a rate limiting step to upload.a.video/JS.html. This page uses our [JS uploader](https://api.video/blog/tutorials/new-video-uploader-javascript-library/) to simplify video uploads.

## Defining the rate limit

On our Node backend, we add the "express-rate-limit" library, and initialize it to allow for 5 uploads an hour:

```
//rate limiting code
//rate limiting to protect the demos
const rateLimit = require("express-rate-limit");
app.use(
	rateLimit({
	  windowMs:  60 * 60 * 1000, // 1 hour duration in milliseconds
	  max: 5,
	  message: "You exceeded 5 requests in 1 hour.",
	  headers: true,
	})
  );

```

We set the window for the rate limit to be one hour, and the maximum number of calls to be 5.

Now, the upload code does not use the NodeJS backend, so I created a dummy endpoint on the nodeJS server called "/ratelimit"

```
//this applies the ratelimit to all uploads.  Limit to 5 per hour
app.get('/ratelimit',(req,res)=>{
	console.log("rate limiting test");
	res.sendStatus(200);
});
```

Now we can make dummy calls to upload.a.video/ratelimit to trigger the rate limit in our JavaScript code.

## Uploading in the browser

When the form changes, the EventListener fires.  Previously, the video would begin uploading.  Now, we make a call to the "/ratelimit" endpoint to see if we can commence the upload:

```
 input.addEventListener('change', () => {
		console.log("upload commencing");

		//adding in rate limiting to prevent abuse
		var qReq = new XMLHttpRequest();
		qReq.open("GET", "/ratelimit");
		qReq.onload = function (oEvent) {

			console.log(qReq.status);
				//once we create the video id do stuff
				if(qReq.status == 429){
					//rate limited
					document.getElementById("chunk-information").innerHTML = "Your uploads have been rate limited. We allow 5 uploads/hour with this demo app. Please try again in a bit."
				}
				else{
					//upload the first chunk to get the videoId
					//its ok to upload the video, we are not rate limited
					uploadFile(input.files[0]);
		
				}
		}
		qReq.send();

```

If the user has uploaded 5 videos in the last hour, the endpoint will return HTTP 429, and we update the website to tell the user that they have been rate limited.

small_429.jpeg

thumbnail_429.jpeg

429.jpeg

If the user is below the rate limit threshold, the rate limit endpoint will return HTTP 200.  Since we have passed the rate limit 'test' we call the uploadFile function that uploads the video.

small_200.jpeg

thumbnail_200.jpeg

200.jpeg

We genuinely hope that your UGC application will be successful, and one of the ways to ensure success is to allow UGC, but to lightly restrict how UGC can be added. Rate limiting is one of these light restrictions that you can implement to keep the content flowing, but to keep the pace of the content uploads a *bit* more manageable.

If you have any questions or suggestions, please share them on our [community forum](https://community.api.video/). If you don't have an api.video account yet, you can create one in just a few seconds [here](https://dashboard.api.video/register). Thanks for reading! 



Adding rate limits to your video uploader

large_stop-jpeg.jpeg

medium_stop-jpeg.jpeg

small_stop-jpeg.jpeg

thumbnail_stop-jpeg.jpeg

stop-jpeg.jpeg

webhooks

Analytics

JavaScript

One of the most satisfying features of livestreaming is seeing a live counter of how many people are watching your live stream.  In this demo, we’ll build a counter that gives a real time count of the number of viewers watching a live stream.

## api.video livestreams

Each livestream at api.video can be used over and over. It is a conduit for your livestreams.  There is a RTMP url that you use to send your livestream to api.video, and a playback url that you can embed in your website.  When you look at a livestream on your [api.video dashboard](https://dashboard.api.video/), you’ll see all the connection details (some are obfuscated in the screenshot) to connect your livestream. 

large_screenshot-2021-07-22-at-06-12-10.png

medium_screenshot-2021-07-22-at-06-12-10.png

small_screenshot-2021-07-22-at-06-12-10.png

thumbnail_screenshot-2021-07-22-at-06-12-10.png

viewer-count-video.png

Right underneath the thumbnail of the livestream, you can see a viewer count.  In the screenshot above it is at 632. That is the count of historical views for this livestream - a sum of all the views for every livestream that has been run. While this is an interesting stat, this is not exactly what we want to see during a livestream.

This NodeJS function takes your liveStreamId, and calls the analytics endpoint to get the total number of sessions that have occurred for that live stream:

```
function getLiveSessionCount(liveStreamId){
 
   return new Promise(function(resolve, reject){
       console.log(liveStreamId);
       var pageSize=1;
       var currentPage = 1;
       params = {
           "liveStreamId": liveStreamId,
           "pageSize":pageSize,
           "currentPage":currentPage
       }
       //get all sessions for livestream
       var sessionList = client.rawStatistics.listLiveStreamSessions(params);
       sessionList.then(function(liveSessionList){
           //get total sessoin
           var sessionCount = liveSessionList.pagination.itemsTotal;
           console.log("live sessions" , sessionCount);
           resolve(sessionCount);
       }).catch((error) =>{
           reject(error);
       });
   });
}

```

## Counting the views

To get an accurate count of viewing sessions during a livestream, we need to grab the livestream count when the stream starts (all of the views PRIOR to the current stream).  As the stream progresses, the number will increase, but a simple difference ```currentCount - startCount``` will provide the number of sessions that occurred during the current stream.

### Live stream webhooks

In July 2021, we launched 2 new webhooks: ```live-stream.broadcast.started``` and ```live-stream.broadcast.ended```.  These webhooks announce whenever one of your live streams begin/end broadcasting. 

When the ```live-stream.broadcast.started``` webhook fires, our webhook listener identifies that a live stream has started.  Then it calls the getLiveSessionCount function to get the starting count of sessions.

```
app.post("/receive_webhook", function (request, response) {
   console.log("new video event from api.video");
    let event = request.body;
   let body =request.body;
   let type = body.type;
   let emittedAt = body.emittedAt;
   webhookResponse = "";
   if(type =="live-stream.broadcast.started"){
       liveStreamId = body.liveStreamId;
       liveStreamStatus = true;
       webhookResponse = "event: " +type+ " at: "+ emittedAt+ " LiveStream,Id: "+liveStreamId+ "  has started.";
      
       //change the broadcasting status in the JSON pbject
       broadcastingStatus[liveStreamId]=liveStreamStatus;
       //TODO - get the number of views at start
       startViews = getLiveSessionCount(liveStreamId);
       startViews.then(function(startcounter){
           console.log("number of views when broadcast starts", startcounter);
           viewersAtStartOfStream[liveStreamId] = startcounter;
           webhookResponse = "event: " +type+ " at: "+ emittedAt+ " LiveStreamId: "+liveStreamId+ "  has started. There have been "+startcounter+" at the beginnig";
 
       });
      
    } else if (type =="live-stream.broadcast.ended"){
       liveStreamId = body.liveStreamId;
       liveStreamStatus = false;
       broadcastingStatus[piLiveId]=liveStreamStatus;
       webhookResponse = "event: " +type+ " at: "+ emittedAt+ " LiveStreamId: "+liveStreamId+ "  has stopped.";
    }
  
   //console.log(headers);
   console.log("response",webhookResponse);
 
  
   response.sendStatus(200); 
 });


```

Now, as the streaming progresses, the website polls /getLivecount every three seconds:

```
// Send list of the new count of viewers every x seconds
app.get("/getLivecount", function (request, response) {
 
 
   var LiveId = request.query.live;
   console.log("LiveId", LiveId);
   console.log(viewersAtStartOfStream);
   startCount = viewersAtStartOfStream[LiveId];
   console.log("startCount", startCount);
   //we have liveid get new user count
   var currentCount = getLiveSessionCount(LiveId);
           currentCount.then(function(currentWatchCount){
 
               console.log(startCount + " " + currentWatchCount);
               numberOfWatchers = currentWatchCount - startCount;
               console.log("numberOfWatchers", numberOfWatchers);
               response.send("There are " +numberOfWatchers + " watching this stream!");
           }).catch((err) => {
               console.log(err);
           });
 });

```

And this returns the difference from the start of stream (stored in an array on the server), and the current count.  Voila, a simple view counter!

##  Conclusion

In this demo, when the live stream begins broadcasting, we utilize the [live stream started webhook](https://docs.api.video/reference/api/Webhooks#create-webhook), which broadcasts that the stream has started. We determine the ‘seed’ number of sessions using the [Live stream session analytics](https://docs.api.video/analytics/overview). Now we know the “0” for this live streaming session.

We can call the same endpoint every 3 seconds and report the growth in the number of sessions.  Each one of these is a new loading of the live stream video player - counting as a new viewer of the stream. This is then added to the page to indicate how many viewers are watching the live stream.

This demo is live at [watch.a.video/broadcast](​​https://watch.a.video/broadcast?streamId=li400mYKSgQ6xs7taUeSaEKr). To begin the stream, head over to [livestream.a.video](https://livestream.a.video) and begin the stream. To grow the number of viewers, you must open [watch.a.video/broadcast](​​https://watch.a.video/broadcast?streamId=li400mYKSgQ6xs7taUeSaEKr) in multiple incognito/private browser tabs (since the session is browser window based).

Try it out, and tell us what you think! If you’d like to look at the code to modify for your app, it is live on [Github](https://github.com/dougsillars/watchLivestream).


Count your live stream viewers with api.video

thumbnail_counter.jpeg

counter.jpeg

api-video-blog-product-updates.png

Product updates

In today's fast-paced digital landscape, the explosive growth of videos has revolutionized the way we consume information, connect with others, and engage with brands. Whether it's on social media, streaming platforms, or corporate websites, videos have become an integral part of our online experience.

&nbsp;

And behind the captivating visuals, lies a treasure trove of data waiting to be unraveled. Today, we recognize the importance of data-driven insights in shaping strategies, enhancing user experiences, and achieving desired outcomes. By meticulously examining viewer behavior, engagement patterns, and demographic insights, we can uncover actionable intelligence that allows us to personalize experiences and unlock untapped potential.

&nbsp;

For this very reason, **api.video has recently launched real-time video Analytics which allow you to dive deeper into the numbers behind your videos**. Let's learn a little more about it below. 

## How does Analytics help you?

Analytics help you get in depth insights for your videos and live streams. It will help you answer questions like: 

&nbsp;

- Which videos are being viewed the most today or this week or this month?
- Where in the world is my content being viewed?
- Which devices, browsers, and operating systems are viewers using the most?
- What time of the day is my content most engaging?

## What do you get with Analytics?

Analytics provide you engagement data related to your videos and live streams. For instance, you can:

&nbsp;

- get the number of plays for a specific video for a period like the current day, current week or the last 30 days
- get the number of plays by country
- get the number of plays for specific devices, browser agents, and operating systems.


## How does it work?

Api.video's solution uses playback data to analyze and segment your viewers. 

&nbsp;

- Numbers are automatically collected for every video or live stream if played with the built-in api.video player
- Each interaction with the video content generates a play event
- Play events are reported in real time and can be instantly viewed on the api.video dashboard or retrieved through the API
- Third-party players are also supported through the provided analytics plug-ins (any HTML5 player that supports event-based reporting)
- The data is retained for 30 days

&nbsp;


![pexels-lukas-590020.jpg](https://datocms-bucket.s3.eu-central-1.amazonaws.com/pexels_lukas_590020_4c03e9015f.jpg)

## The best part - it is all real-time data!

Yes, you read that right! All the data you see under the Analytics section is collected and computed in real-time. We all know time and speed = money, which is why this data will be available immediately for your usage and analysis. This real-time data can be especially useful if you are using it to keep track of live stream engagement or manage a lot of user-generated content.

## How do you start using Analytics?

To start viewing data, you can use the dedicated API endpoint or check the dedicated page on the api.video dashboard if you are looking for convenient access and viewing.

&nbsp;

Check out the detailed guide in our [analytics documentation](https://docs.api.video/analytics/overview) for more details on this, and our [FAQ section](https://help.api.video/en/articles/7983849-analytics) for some common questions you may have. In production, you can activate Analytics from your Dashboard. You will need to be the owner of the workspace account to do so.

&nbsp;

__[Sign-up on api.video](https://dashboard.api.video/register) now and get the complete toolkit for your videos at one place!__

Introducing Analytics at api.video for better video insights

Analytics at api.video for better video insights

large_video_meets_data_not_rounded.jpg

medium_video_meets_data_not_rounded.jpg

small_video_meets_data_not_rounded.jpg

thumbnail_video_meets_data_not_rounded.jpg

video_meets_data_not_rounded.jpg

Understanding your audience is key to successful video and live stream content delivery. Whether you deliver your own content, or develop a mobile app which enables creatives to deliver their own, leveraging data and analytics can help you. With api.video's [Analytics solution](https://docs.api.video/analytics/overview), you gain vital insights into the viewers’ preferences and behaviors, enabling you or your users to make data-informed decisions in content creation, and engage better with the audience.

&nbsp;
 

**In this tutorial, we’ll go through two methods that you can use to retrieve analytics data for your videos and live streams.**

## What data?

The mainspring of api.video’s Analytics solution is **play event data**. Play events determine the number of times your video or live stream had viewer engagement. 
&nbsp;
 
api.video’s solution analyzes and groups play event data by these dimensions:

&nbsp;
 

- the date and time of the play event,
- the ID of a specific video or live stream that generated play events
- the countries where your viewers are based,
- the device type your viewers are using, like `phone` or `computer`
- the browser your viewers are using, like `Chrome` or `Firefox`
- the operating system that your users are running, like `iOS` or `Windows`
&nbsp;
 
api.video helps you read and filter this data, enabling you to segment and understand your audience better.

## Requirements

Before we discuss the two methods, let’s talk about some requirements. api.video can only generate analytics data when you meet these simple requirements:

&nbsp;

1. You have already uploaded videos or broadcasted live streams.
2. These videos or live streams already had viewers that create play events.
3. You used the api.video player to deliver your content. You will meet this requirement when you integrate one of [api.video’s Player SDKs](https://docs.api.video/sdks/player), or embed the video or the live stream into a website, or simply share the video or live stream URL with your viewers.


You can also use a different player solution, however, you will need to integrate api.video’s [analytics plug-ins](https://docs.api.video/sdks/player#player-analytics-sdks), which are available for [hls.js](https://github.com/apivideo/api.video-hlsjs-analytics), [video.js,](https://github.com/apivideo/api.video-videojs-analytics) [Android](https://github.com/apivideo/api.video-android-player-analytics), and [iOS](https://github.com/apivideo/api.video-swift-player-analytics).

&nbsp;
    

Once you fulfill these requirements, you’ll immediately be able to retrieve analytics using both methods discussed in this tutorial.

&nbsp;

*Note that when using api.video’s **Sandbox environment**, the extent of data that you can retrieve is limited to the last 24 hours.*

## The no-code way

By far the easiest method to get analytics for your videos and live streams is through the [Analytics page in the api.video dashboard](https://dashboard.api.video/analytics). The dashboard shows the number of play events grouped by some of the most useful dimensions that can help you answer questions like:

&nbsp;

- Which videos or live streams are the most popular this week?
- What time of the day is your content most engaging?
- Which country are most of your viewers based in?
- Which devices, browsers, and operating systems are viewers using the most?

## The integrated way

For those that prefer a more hands-on approach, we’ll dive into how you can leverage our API to retrieve analytics data and build out some typical Analytics use cases.

### 1. Set up the **api.video client**

Let's initialize the [api.video client SDK](https://docs.api.video/sdks/api-clients) in your environment, using an example **in Node.js**:

### 2. Create a request

The client SDK will require your API key, which you can find [in the dashboard](https://dashboard.api.video/project-settings/api-keys). Check out the [Authentication guide](https://docs.api.video/reference/authentication-guide) if you want to understand the different authentication methods you can use with api.video.

&nbsp;
 

Let’s say you want to know **which one of your videos performed the best in the last week**:

Notice that we’re passing in `from` and `to`, which determine the time interval that you want to analyze. We’re also adding `videoID` as the dimension, which will give you result for every `videoID` available in your project.
&nbsp;
 

Here’s an example response payload for this request:

In the response, `value` shows values for the `dimension` we set in our request. In this case, since we requested `dimension=videoId`, each `value` field in the response returns a video ID.
&nbsp;
 
`plays` returns the number of play events.
&nbsp;
 

Now let’s try a different dimension: let’s see **how a specific video performs across different countries** where your viewers are based.

Notice that we’re passing `from`, which determines the starting time of the data analysis. We’re adding `country` as the dimension, which will give you results for every country where you had viewer engagement. We’re also adding a video’s ID value as the `filter`, which will filter results in the response payload and only shows analytics for the specific video that the ID belongs to.
&nbsp;
 

Here’s an example response payload for this request:

Check out the **complete list of dimensions** and **example response payloads** for both success and error cases in [the API reference](https://docs.api.video/reference/api/Analytics).

### 3. How to use this data?

When building an application or website where you serve videos or live streams, you can find some creative ways to leverage analytics data:
&nbsp;
 

- Create **data visualizations** for your users. This could include graphs and charts showing views over time, peak viewing periods, or geographic distribution of the audience.
-  **Localize Content.** Use geographic data from play events to tailor content to specific regions, accommodating regional preferences or languages.
- **Create recommendations**. Find the most popular, or even the least popular videos and show them as recommended videos for your viewers.

## Conclusion

With api.video’s Analytics solution, you're not only delivering content; you're unlocking a world of data that helps you connect more meaningfully with your audience. Whether you're aiming to expand your reach, tailor content to specific regions, or simply understand your audience better, api.video’s Analytics is your gateway to smarter content strategy.


&nbsp;


To start using api.video and see how this works, [sign-up](https://dashboard.api.video/register) for a free sandbox account now.

How api.video’s Analytics can help you enhance your content strategy

api.video Analytics helps you enhance your content strategy

Blog_Analytics.png

Use api.video Analytics to mark viewer density with Observable

Api.video Analytics: Add markers representing viewer density per city to a map with Observable

 Build a Choropleth Map with api.video Analytics

Api.video Analytics: Build a Choropleth Map (and find out what one is)

Using analytics to analyze where to edit a video

Leverage api.video’s Analytics to enhance your content strategy

How many people have watched my video?

How much of my video are people watching?

Is there a common abandonment time?

Are my users skipping ahead in the video?

These are questions that can be solved with api.video's [analytics](https://docs.api.video/reference/api/Analytics).  

## Now available with external players

api.video offers video encoding, hosting, delivery and analytics.  If you do not want to use our player (or already have an integration with another player), you can use your [3rd party player to deliver the video](https://api.video/blog/tutorials/using-api-video-with-external-video-players/). 

Until now, when you used an external player, you lost the opportunity to gain any insights from our analytics engine. We have now launched libraries for [videojs](https://github.com/apivideo/videojs-player-analytics), [hlsjs](https://github.com/apivideo/hlsjs-player-analytics), and a general [analytics package](https://github.com/apivideo/player-analytics), allowing you to integrate api.video analytics into your customized 3rd party video player!

## How does it work?

Let's look at an integration with videoJS. Here's a simple page that loads a video from api.video into videoJS, (and has added in analytics):


```
<head>
  <link href="https://vjs.zencdn.net/7.10.2/video-js.css" rel="stylesheet" />
  <script src="https://vjs.zencdn.net/7.10.2/video.min.js"></script>
  <script src="https://unpkg.com/@api.video/videojs-player-analytics"></script>

  
  
</head>

<body>
  <video
    id="my-video"
    class="video-js"
    controls
    preload="auto"
    width="1280"
    height="720"
    poster="https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/thumbnail.jpg"
    data-setup="{}"
  >
    <source src="https://cdn.api.video/vod/vi4blUQJFrYWbaG44NChkH27/hls/manifest.m3u8" type="application/x-mpegURL" />
    
      To view this video please enable JavaScript, and consider upgrading to a
      web browser that
      <a href="https://videojs.com/html5-video-support/" target="_blank"
        >supports HTML5 video</a
      >
    </p>
  </video>

  <script>
             videojs.registerPlugin('apiVideoAnalytics', VideoJsApiVideoAnalytics);
            
             var player = videojs('my-video');
	         player.apiVideoAnalytics();
			 
         </script>
</body>
```

To add analytics, we add the script in the head of the document:

```
 <script src="https://unpkg.com/@api.video/videojs-player-analytics"></script>
```

and then to add the analytics engine, we add the JavaScript at the end of the page:
* registering the api.video analytics plugin
```
 videojs.registerPlugin('apiVideoAnalytics', VideoJsApiVideoAnalytics);
```
* assigning a variable to the player
```
 var player = videojs('my-video');
```
* connecting the player to the analytics plugin
```
player.apiVideoAnalytics();
```

and that's all there is to it!

## Can I add metadata to the analytics?

Yes! If you replace: 

```
player.apiVideoAnalytics();
```

with:

```
      player.apiVideoAnalytics({
        metadata: {
          player: "videojs"
        }
      });
```

you can collect [dynamic metadata](https://api.video/blog/tutorials/dynamic-metadata/).  In this case, I am assigning the value videojs to the player variable.  Now, whenever anyone watches a video using this videoJS player, it will be recorded in the dynamic metadata as such (so I can break down the playback across different devices).

Querying the analytics, we can see this in action:


```
		{
			"session": {
				"sessionId": "ps4ZrdWqAR8mevHi4IwHoACf",
				"loadedAt": "2021-04-01T11:07:25+00:00",
				"endedAt": "2021-04-01T11:07:25+00:00",
		*		"metadata": [
					{
						"key": "player",
						"value": "videojs"
					}
				]*
			},
			"location": {
				"country": "United Kingdom",
				"city": "Chesham"
			},
			"referrer": {
				"url": "https://jsfiddle.net/",
				"medium": "unknown",
				"source": "unknown",
				"searchTerm": "unknown"
			},
			"device": {
				"type": "computer",
				"vendor": "unknown",
				"model": "Other"
			},
			"os": {
				"name": "Mac OS X",
				"shortname": "Mac OS X",
				"version": "11.2.3"
			},
			"client": {
				"type": "unknown",
				"name": "Chrome",
				"version": "89.0.4389"
			}
		}
```

## Conclusion

We are working to make api.video integrate easily into your infrastructure.  If you use a 3rd party player, you are no longer prevented from using our analytics to study the playback of your videos.

Grab the appropriate library, and try it today!

[videojs](https://github.com/apivideo/videojs-player-analytics)

[hlsjs](https://github.com/apivideo/hlsjs-player-analytics)

[General analyitics package](https://github.com/apivideo/player-analytics)

New feature: Analytics libraries for 3rd party video players!

43160471697fbafef276c.jpg

In the classic movie *Field of Dreams*, a mysterious voice whispers to Kevin Costner “if you build it, they will come.”  


<video autoplay muted loop>
		<source src="https://media.giphy.com/media/gZuxOq7zSL5DO/giphy.mp4">
</video><br/><br/>


His belief of this statement completely transformed his life and drove him to build a baseball stadium in the middle of a cornfield in Iowa… and they came…<br/>


<video autoplay muted loop>
		<source src="https://media.giphy.com/media/z3WMjg3hu3ce4/giphy.mp4">
</video><br/><br/>


## If you Stream it...

You've created some awesome videos, and uploaded them to api.video.  Great work - it looks awesome.  

Here is a video that we posted in our blog post announcing our new video player:

<iframe src="https://embed.api.video/vod/viTLpKB231ATWOWjkHgi9bf#autoplay#loop" frameborder="0" scrolling="no" allowfullscreen=""></iframe>
<br/><br/>

## ...Who will come?

Eventually you want to know, how many people came to see my video?  What can I learn about them? Enter api.video’s powerful [video analytics](https://docs.api.video/reference/api/Analytics) API. Using the API, we can transfer all of the view data form our videos into our favourite database, and learn about the viewers of our videos.

Let’s start with grabbing the viewing details for a video. In this case, I’ll use this Planets video that my daughter recorded for her class on astronomy:

<iframe src="https://embed.api.video/vod/vi16NDdXmGxk5QSggW54qw0v#autoplay#loop"  frameborder="0" scrolling="no" allowfullscreen=""></iframe>

The url for this video is: https://embed.api.video/vod/vi16NDdXmGxk5QSggW54qw0v

First I must [authenticate](https://api.video/blog/tutorials/authentication-tutorial/) myself at API.video, and I receive an access token that is good for an hour.

With the token, I can use the videoId to request all of the view information about my video with the [analytics API](https://docs.api.video/reference/api/Analytics).  The videoId for the video is the value at the end of the url (vi16NDdXmGxk5QSggW54qw0v):




In this case, I am requesting 25 results per page, and page one of the data.  That’s actually fine, since I know there are only 19 views on this video.  

The JSON result is pretty long, but here is what one entry looks like:


To me, this is super cool.  A person in Vietnam, using Firefox on Ubuntu, watched this video in June!  And there are 18 more of these to look at and to parse.

### Demo

We have created a demo that takes a videoId and counts the country, device and browser for each view, and places the results on a page. You can try it out at [whoswatched.a.video](https://whoswatched.a.video).

In order to look at the data, I am going to suck the JSON file into Couchbase - a database that uses JSON to create a "table" format similar to SQL. This will allow me to run queries on the JSON much like one would run a database query.

### Creating a database in Couchbase:

Download and install [Couchbase](https://www.couchbase.com/) on your computer.  When the install is complete, you’ll have an admin dashboard open in your browser (on my Mac it is running on localhost:8901).  We’d like to add in our api.video JSON file into a data bucket.  To create the bucket - navigate to the Bucket section and click the "ADD BUCKET" button. I have the memory set at the minimum 100 MB (there are all of 19 entries after all!).


Great - now we have our data bucket added.  Now we’ll want to import the JSON from api.video, so we can do our analysis.  This is done in the terminal using the ```cbimport``` command:

My username is Administrator with password 123456 (Google Chrome is mighty peeved about my use of an insecure password on localhost), adding a json file into the videoStats bucket.  Each video view has a sessionId, so I use that as a unique key.

I get a success message in my terminal, and looking back at the Couchbase admin panel under Documents, I can see each entry from the JSON has been added:


Now we must index the data. In the Query Editor, enter:

Now we can do data analysis of our video views. For example, to understand the number of views per country:

That’s pretty cool!  


## Live Stream Analytics

We can do exactly the same thing with live stream analytics. Note: these only show “views” of a live stream.  If you run a live stream and no one watches - there will be no analytics reported.  Further - if your live streams are saved as video on demand (VOD) for later use - any VOD analytics are saved with the newly created VOD video, and will have no connection to the original live stream.

Let’s look at a live stream that has a number of views.  On the [api.video](https://api.video) homepage, we have a demo that allows you to livestream right from the homepage.  The live streamer then “watches” their stream in the browser at the same time that they are broadcasting - guaranteeing that every live stream gets at least one viewer (in the same location as the live streamer!)

The API call is similar to that of the VOD request, I just use the 'live-streams' endpoint as opposed to the 'videos' endpoint I used above.

### GeoLocation  


The live stream demo is hosted in North America and in Europe, and we use geolocation to direct our users to the correct server. Let’s see how well our load balancers are doing. Traffic directed to North America is on the left, and European traffic is on the right:


It looks like our load balancing is doing a bang up job. :)


Combining the two sets of data (I just created a new bucket with all the data added) allows us to see that api.video’s home page has been live streaming all around the world:


### Devices & browsers

Most of the streams are from desktop machines. All 28 phone instances correspond directly to 28 Android devices.(This is due to a limitation in Safari that prevents the demo from working on any iOS device.)  Of our Android users, we see 25 using Chrome, 1 Samsung Internet, 1 Opera (and one hidden variant.)

Desktop users are mostly Windows and Mac (and pretty evenly distributed), but also a good number on Linux/Ubuntu).


## Conclusion


The video analytics offered by api.video allow you to better understand who is consuming your content. In this post, we've walked through the steps to extract the data using the Analytics API in JSON format, and then ingested the data into a database for fast and easy queries.  

We used this data to see how the live stream demo on the api.video home page was used in July 2020.

How are you using api.video's analytics? Drop us a note in the [community forum](https://community.api.video) with your use cases!

Analytics with api.video

When video meets data: Introducing Analytics at api.video for better video insights

Blog_illustration_analytics.png

small_Blog_Analytics.png

thumbnail_Blog_Analytics.png

If you want to advertise on a budget, it's easier when you know where your content is already succeeding. With api.video's analytics, you can see what cities and countries viewers are visiting your site from. This kind of information can give you a general sense of where you might want to spend (or not spend) your advertising dollars. 

You could view your data in a list, but it might be faster if you represented the data visually with something like a map that shows viewer density per city. Today, we're going to use OpenLayers, Observable, and api.video's data analytics for a demo account to retrieve what we need to plot all the cities viewers watch live streams from on a map. We'll represent how many sessions (viewers) there are per city with a circle that has a bigger circumference if there's more viewers, and a smaller one if there's less viewers. We won't fill in the circles so we can see markers for all overlapping cities. 

Let's start mapping! 

## Prerequisites 
For this tutorial, you'll need: 

* api.video account - [Sign up for api.video here](https://api.video).
* Observable account
* OpenCage Geocoding API account 
* requests, csv, pycountry, opencage, and pandas libraries for Python 

If you don't know JavaScript, or the version of it that Observable's using, you don't have to. This tutorial will explain how to configure your map in a way where you don't have to know the JavaScript. If there's interest in having the JavaScript content explained more, let us know in our [community forum](https://community.api.video)! We can explain everything in a future post. 

## Build Your Data File 
In this section, we'll create the data file we want to use with our map. The code sample will: 

* Authenticate with the api.video API.
* Retrieve a list of all our live streams.
* Retrieve all sessions for each live stream and for each session, create a dictionary containing the live stream title, the session ID for the session, the city, the country, and we'll also add the latitude and longitude coordinates using the OpenCage Geocoding API.
* Write each dictionary to a line in a csv file that we can then use in a pandas dataframe. 

Here's the code:

In the code we choose to use 'open with' to open the csv file we'll write to, because this method will close the file for us when it's done writing everything. We also use the dictionary writing feature of the csv module for Python. This allows us to create a header row listing all the columns we want. We can then create a dictionary where every key matches a column title. Whatever we set as the value will be written to the csv file as a row. 

We add latitude and longitude for every city in our file, and then we output to the file ls_session_data.csv. The next step is to add our CSV file to a pandas dataframe. 

## Create a Dataframe With Your CSV File 
We convert our brand new CSV file to pandas so we can manipulate the data. There are other ways you can do this, but once you have the hang of pandas, you can do a lot with it. 

Here's the code for moving our csv file to pandas, grouping everything and then outputting it back to a csv file we call 'country_lat_lon.csv:

Now we're ready to build our map. 

## Configure Observable 
In this section, we walk through how to get your map set up on Observable. If you haven't done so, sign up for an Observable account. Then do the following: 

1. Navigate to our Observable notebook [Where api.video Live Streams Are Watched](https://observablehq.com/@erikkai/where-api-video-live-streams-are-watched). 
2. Click the three dots in the upper right corner. A menu opens. 
3. From the menu, choose **Fork**. Now you have your own copy of the map to edit and play around with. 
4. Click the three dots in the upper right corner again and choose **File attachments**. 
5. Delete the existing copy of **country_lat_lon.csv** and upload your copy. Don't try to upload expecting an overwrite - it will add a 1 at the end of your file. Then you will have to tweak the file name in the code. (Where you do that is explained in the Observable notebook if you decide to go that route instead.) 
6. Make sure your data is loaded. You can check if anything needs an update by looking for a solid blue triangle in the upper right corner of the cells on this page. Click any you see. 
7. Your map should display, showing viewer density by city through the size of the circle used as a marker.

## Tweaking Observable and OpenLayers
You can tweak this map lots of different ways, or go back to the one it's forked from and tweak that instead. Some suggestions for areas to try changing things: 

1. Go to the Set the Center section. The array listed shows a pair of coordinates that are longitude, then latitude. If you change these, you can change the center the map starts out with. 
2. Go to the Define vectorSource, Programmatically Add Markers section. In the block of code that starts **data.forEach** you can change how big or small the circles are by changing what you multiply Count by. This creates the radius of your circle. 
3. Go to the Add Your Data section. If you click the three dots to the left of **data = Array(45)** you'll be able to see the import code. If you want you can use a different file name, or change the code to upload a different kind of file for use in the project (though that might have more effects on the rest of the code). 
4. You can see different types of markers you can add by looking at another user's post about using OpenLayers - [Fork of Openlayers to put some markers/features on](https://observablehq.com/@chonghorizons/fork-of-openlayers-to-put-some-markers-features-on). 

If you try a map, be sure to share it with us in our community forum! We'd love to see what you do with your data. 

A map showing viewer density per city using api.video data, Observable, Geocoding, and Open Layers

apivideomapmarkerslivestream.jpg

A great way to see at a glance how many viewers you have per country is with a choropleth map. It probably sounds like I'm talking about some weird kind of plant you've never heard of, but chances are you've looked at lots of choropleths before. It's a map that's used to represent statistical data by shading different geographical areas with different colors that represent a certain number of people, items, or whatever else. If you're still a little confused by that explanation, a picture is worth a thousand words, so here's an example of a choropleth map: 

The map we're displaying here shows you population density per square mile in the U.S. The value of a choropleth map, is you can quickly understand data. If you had to look at a list of density numbers by state, you might take extra time to scan and find the biggest numbers. With this example map you can see that the darker colors represent higher densities and the lighter colors represent lower densities. Armed with that knowledge you can easily see which states have the highest population densities by color. 

We can create the same kind of map for api.video! In this tutorial, we'll talk about grabbing the data you'll need, and then how to use it with Observable to turn it into a map. 

## Prerequisites
For this tutorial, you'll need:
* api.video - [Sign up here](https://api.video).
* Observable account - [Sign up here](https://observablehq.com).
* requests, csv, pycountry, and pandas libraries for Python 

Let's start coding! 

## Retrieving Analytics Data
There are lots of ways to retrieve analytics data, so while we'll post a code sample here, you may want to change it for your data. Some tips to keep in mind are: 

* Take a look at a JSON response for analytics before building anything to grab the data. You can see responses here - [Tips for Working with api.video Analytics Data](https://api.video/blog/tutorials/tips-for-working-with-api-video-analytics-data/). You can also figure out how you want to design everything. 
* For Python samples, if you know you have a lot of videos, livestreams, and/or sessions, you will need to handle pagination yourself. 
* If you know what you want to do to start with, you can retrieve just that data. We added a few extra things for reference, but otherwise pared down the available data.
* Decide how often you want to update your data. 

To keep things simple, this time we're just pulling the data and writing it to a CSV file. In future tutorials, we'll learn how to create a database that periodically updates itself with your analytics data. 

Here's the code we used to: 

* Get all the analytics data and flatten the JSON. Flattening JSON means taking it out of its nested structure, so each set of information about a video, livestream or a session fits into one row of data. 
* Add the three letter country code for every country. If one can't be retrieved because the country is unknown, add '---.' 
* If the city or country isn't known, put 'unknown.'
* Add the title to a video or live stream for our reference when reviewing the csv
* Add the assetID and sessionID for our reference when reviewing the csv
* Write a row to a csv file for each session

If you don't like what we choose to extract, you can add or remove by tweaking the code. 

We will be using the file we generate to create the choropleth.

After you run the code sample, you should have a csv file that contains details about all of your video and live stream sessions. It takes awhile to run if you have a lot of data, so if it seems like it's stuck, it's not. It can take upwards of 15 minutes if you have lots of data to crunch through. Take a break or work on something else while everything is retrieved. 

## Add Your CSV to a Pandas DataFrame
The next step is to take your CSV file and convert it into a pandas dataframe. Pandas is a software library used for data science activities. It makes it easier to do a lot of time consuming, repetitive tasks you need to do with data like cleansing, performing mathematical operations on columns, filling information in, removing data, inspecting it, and lots more. It also has a steep learning curve, but don't worry if you've never used it, we're providing a code snippet for working with it. 

In this code snippet, we create a dataframe in pandas. Then we drop everything and grooup information so we get a table in CSV format with two columns: ISO_A3 and Count. That's all we need for our map! If you need to get the data back, it's still in your CSV file and you can use it in pandas to group information however you want. 

We're going to use this new csv file- 'choro.csv'- to build our choropleth. 

## Configure Your Choropleth in Observable
Here's where we walk through using Observable. We're going to switch over to using something similar to JavaScript. Most of it's set up for you, and the sample map we've created will show you where your data goes. 

1. Navigate to Observable and log in (or sign up if you didn't already). 
2. Navigate to my [sample choropleth](https://observablehq.com/@erikkai/viewers-of-my-videos-and-live-streams-around-the-world) (built from Mike Bostock's cool [Hospital Beds](https://observablehq.com/@mbostock/hospital-beds) choropleth).



3. Get the final CSV file generated with the instructions (for Python) - 'choro.csv'
4. Click the three dots in the upper right corner. Click **Fork**. You want to do it this way, so you get this version of the file and not the original hospital beds map. We've tweaked a couple of things, and if you don't want to do tweaks yourself and instead see everything work as described, you want to fork this project.
5. Click the three dots again. Click **File attachments**. You'll open an upload panel.
6. Click **Upload**.
7. Browse for your copy of '**choro.csv**' and upload it.
8. Run everything, it should work and show you a map. Based on how many viewers you have, this implementation will automatically divide everything into colors on the scale displayed at the top.

You can make your own version of the map and then publish a notebook that you can share anywhere, showing off a beautiful map of where you have the most viewers! 

choropleth, apivide, api.video, data analytics

choroplethapivideo.jpg

Video analytics can tell you a lot about how people are watching your video, especially if you decide to dig into player sessions. With api.video's [analytics endpoint](https://docs.api.video/reference/api/Analytics) you can figure out details like where people fast forward, or rewind your video. This information can be used to help you determine things like:
* Whether something is confusing or boring
* Whether something is interesting or entertaining

...and more! 

For this article, I decided to pull analytics for a popular api.video demo called [Upload a video to Discord](https://a.video/works/upload-a-video-to-discord). 

## Pull Analytics Data for a Video
If you know what video you want to pull analytics for, it's pretty easy to grab this information: 

1. Open your dashboard by clicking **Login** on the [api.video](https://api.video) homepage and logging in if you are not logged in to api.video. 
2. Navigate to [your dashboard](https://dashboard.api.video/).
3. Click on the video you want analytics data for. 
4. On the video's page, there's a copy link section that will contain a video link. It will look something like: `https://embed.api.video/vod/vi5PBib80QrC8q73AekJqNDH`. Get the videoId, which is the part that comes after **vod/**. 

NOTE: You could also collect this information programmatically. To do that, you'd send a request to the [videos](https://docs.api.video/reference/api/Videos#list-all-video-objects) endpoint. You'd look through the list returned, pull the videoId for the one you wanted, and continue on. 

5. After you have your videoId, you're going to want to retrieve an exhaustive list of player sessions for your video. The code for that is: 

For our data file, for each row we list the sessionID, what type of action was taken, when the session with the video first started (emitted at), and then three columns - at, from, and to. Some of the action types don't use some of these last three columns.

## Get Familiar with Your Data
Now that you have your csv file containing all the sessions for the video you selected, it's time to start thinking about how to analyze it. You can see a lot of interesting information: 
* pause - when someone pauses a video 
* resume - when someone resumes a video
* ready - when the video is at the start position
* play - when someone starts the video
* end - when someone watches to the end of the video
* seek.backward - when the video winds backward
* seek.forward - when the video winds forward

In our table, a sample row for each will look like: 

pause
`-sessionID-, pause, 2021-02-25T09:57:14+00:00, 45, not, not` 

What we can see from this sample row, is that someone paused their video 45 seconds in. If the row right after pause isn't resume, we can check if the sessionID is different. If it is, we can be sure that whoever was watching the video, stopped watching at 45 seconds. Who would do such a thing? There's an extra 5 seconds of video after that! As it turns out, if you watch the video here: [https://a.video/works/upload-a-video-to-discord](https://a.video/works/upload-a-video-to-discord) you can see that by 45 seconds, Doug successfully completed the task he's teaching with the demo. The video runs on Discord. If you were satisfied with the demo, you might pause the video and then leave, or close the tab (which would count as a pause to api.video's analytics). 

resume
`-sessionID-, resume, 2021-02-25T18:10:28+00:00, 25, not, not` 

The resume action will usually occur right after pause, or after a seek.forward or seek.backward action. This action is anytime the video is stopped, and you press play. If your video is at the very start, clicking play doesn't register as a resume. 

ready
`-sessionID-, ready, 2021-02-25T14:48:49+00:00, 0, not, not` 

Ready appears when you open the video and you haven't started playing it yet. If you see ready and then you see a different sessionID, you know the user reached the video, then decided for some reason not to play it. You will need other contextual data to guess why that might be.

play
`-sessionID-, play, 2021-02-25T18:10:20+00:00, 0, not, not`

The play action occurs at the start of the video, when the user presses play. This can be a useful event to check for since if you don't find it in a session, you can be sure the user didn't start the video. 

end 
`-sessionID-, end, 2021-02-27T17:30:18+00:00, 50, not, not`

The end action indicates that the user watched the video to the very end. This can be useful if you want to filter through sessions to see what percentage of sessions reach the very end of the video. 

seek.backward
`-sessionID-, seek.backward, 2021-02-27T14:53:02+00:00, not, 35, 29`

Something to watch for is where users wind back. If you're teaching them something, they might be winding back because they don't understand a concept, or they can't clearly see something in the video. They could also wind something back because it's interesting, or they weren't paying attention and need to rewatch it. 

seek.forward
`-sessionID-, seek.forward, 2021-02-26T09:52:56+00:00, not, 29, 38`

Seeking forward can mean a lot of things. If you've made an instructional video, a user could seek forward to surf through the video and see if they can find the information they need more quickly. They could seek forward because a concept was well explained, and they're ready for the next concept or step. It could also be because they feel bored. It will depend on the video and your analysis of the content vs. the behavior. 

## Grooming the Data
To do find patterns in your data, you can start trying to filter it to see if you find something. Here's a few ideas I started with: 

* See if there's anything repetitive that stands out when I scroll through the csv that gives me ideas. 
* See if there's anything weird that stands out. 

NOTE: Obviously looking at a table of data when there's tons of entries isn't the best way to review your information. It's a starting point that acquaints you with what it looks like and what you have. You should always make sure to come up with questions to investigate where you can filter content to answer them or visualize your content. 

* Come up with ways to filter things that might display a pattern. This would be where you ask questions like, how often do people seek backwards or forwards? What do they seek backwards and forwards across the most? 
* Come up with ways to count things that might yield interesting information. For example, how many sessions are there where people watch the video all the way to the end? 

### Browsing the Data
As luck would have it, when I started browsing the data I did notice something I thought was odd. There were a lot of instances where it looked like a user wound the video back from the very end to the very beginning. The lines of data looked something like this: 

`-sessionID-, seek.backward, 2021-02-28T15:49:44+00:00, not, 50, 0`

Why, I wondered, would a user want to rewind all the way to the beginning? Examining the data, I noticed something else- the seek.backward like this happened after the end event in the same session.

`-sessionID-, end, 2021-02-28T15:48:42+00:00, 50, not, not`

I checked and discovered the player for this project is set on loop. I didn't know before, but now know that if your player is looping, the loop is shown as two events - first, end. Second, seek.backward to 0. Instances where I found this in the data were spots where someone left the video running and it just looped around again. 

### Filtering the Data
To filter the data, I decided to start with an easy question. Out of the total number of sessions I pulled, how many sessions did a user watch the video all the way to the end? 

NOTE: You need to have pandas installed in your Python environment.

From this data, we get answers to questions I have not asked yet! Starting with the first question, what percentage of users watch all the way to the end? To answer this, we must figure out how many sessions we have total. That's easy - we know that 'ready' only occurs once per session, and indicates that a video is ready to be played. From our chart, we can see we have 725 instances of ready. So that means 

Answer: 25.5% of users! That's great. Especially because in an instructional video, people often learn the concept, and leave immediately. The end of this video is an interesting shot of bells chiming in a church, which 25% of viewers liked enough to stay for, even though it could be argued that you learn everything you need about this demo by about the 42 second mark - where you see the video successfully play on Discord. I would interpret this statistic as an indication that the content is educational and entertaining. 

We also learn something that might seem a little strange, we have 725 sessions, but of those 725 sessions, people only played the video 582 times. That means about 80.28% of users watch the video, but about 19.72% don't. That might seem weird - who goes to a page to see a demo then says nope nevermind? A possible answer lies in the page the video is shown on. Here's an image for you: 


So we can see the video here, but check out the choices we offer below the video - Blog Post and Github. As you may know, some developers don't want to read blog posts or watch videos. They just want a code sample. So a possibility is they come here for the demo, then they see we offer the code, decide that's what they prefer, and away they go! 

What I could maybe be looking at here is the answer to the question 'What percentage of developers prefer a code sample to a written tutorial or demo?' (specifically for our company, don't quote me on this one). I could pull more of api.video's demo analytics and see if the percentage stays consistent across the demos. With a tool like HotJar, I could figure out if we have a lot of users that immediately click on that GitHub link or not, and start building a case for my hypothesis, or disproving it.

Because we're creating educational content, I could maybe use the ~20% statistic to make a case for always including code samples for our demos on github. You could use this information other ways too. If your video was a movie or a short film for example, you might want more people to watch the video than 80%. Maybe it would lead you to test other page designs, or changing the thumbnail for your video to make it more interesting to everyone. 

Okay well this was fun. Let's try some more filtering and a little bit of visualizing. 

### Visualizing the Data
There are lots of ways to visualize your data. For this post, I decided to keep it simple, and use a graph you can create with plotly. But before we get to the tools, how about the question? I decided to plot all instances where somebody is seeking forward or backward. 

For my first try, I thought, why not use the index to plot each instance of winding forward and backward, and I'll use colors. I narrowed my data down to just rows that contained seek.forward or seek.backward. Here was my code:

In the sample, I take all the master file with all my sessions for this video, and then I choose only rows that contain seek in the type. I output this into a new file 'discord_seek_sessions.csv'. 

Now it's time to try making some kind of chart. I went with something simple. I thought maybe I can use the index to represent separate events. Each event gets its own index marker. It came out like this: 

There's a lot going on. There's so many entries, they scroll off the top and bottom right side of the page. If it's not clear, the legend on the right represents the time interval in seconds someone used seek.forward or seek.backward. The line represents the color that will be displayed in the graph. On the graph, across the bottom you can see the time in seconds. Up the left side, is the index that went with the event displayed. 

Let's make this better. The first thing I tried, was regrouping everything. I gave a unique index to anything with the same session ID and seek direction. That way each session would have two bands where you could see the lines. It didn't improve the chart's clarity, but the code for it is neat and will help us later, so I'm going to share that for you here: 

If you ever need to assign an index value based on a group, this code will help you! But it didn't help with our situation. That led me to the next idea, what if I split the sessions into separate dataframes? or csv files, depending on how you prefer to do things? 

This yielded a bit more clarity. Also I chose to put the data into separate csv files, this is the code for that:

Checking out the different files in my chart, I used the groupby trick I just told you about. Because there is only one type of action per chart, it places every instance of a particular seeking action on one line. A little less busy, but not a big improvement. 

The next thing I thought of was going back and counting how popular it was to wind either forward or backward at any point in the video. The code for that is pretty simple, and I decided to use it for winding forward: 

Now it's getting interesting. What if I make a chart of the most popular place to forward.seek from? It looks like it's about 33 seconds into the video. (See?) 

Let's make the chart now! We can reuse some code from earlier, and filter for instances when from = 33. 

Why is seeking forward so popular here? If you watch the video, you'll note that this is the part where Doug walks through using Discord. If you are using the tutorial because you like Discord, it's possible some users are really familiar with Discord already. So during this section, they seek forward to find out what comes next. When it gets to where the video plays, 25% watch the video, everyone else says aha! I've learned how to do this now I will go implement what I've learned etc. 

You can repeat this process with other areas in your video. For example, in this video, there's high seek forward rates from around 15 seconds through to 22 seconds. In the video, this is the part where you wait for an upload to complete. If you were trying to optimize the video or edit it, you might make a case that part of this section could be edited out. 

While we're applying this to an educational demo, you could easily apply this kind of simple research to short films and movies. Find out where people fast forward to learn if a section of the film isn't working the way you planned. If someone keeps winding a section back to rewatch it, maybe it's because it's an incredible scene, and you can make sure to do more things a similar way in the future. 

Hope this was a fun start to analyzing your content! See you next time.

bekindrewindapivideo.png

screenshot-2020-08-13-at-13-01-16.png

screenshot-2020-08-13-at-13-12-54.jpg

screenshot-2020-08-13-at-13-14-20.png

screenshot-2020-08-13-at-13-16-21.png

Couchbase results in Google Sheets to create this chart.

screenshot-2020-08-13-at-13-17-03.jpg

screenshot-2020-08-13-at-13-33-04.png

screenshot-2020-08-13-at-13-33-10.png

screenshot-2020-08-13-at-13-33-15.png

Dynamic Metadata

Online video training is huge. There are many companies that offer video training courses where the course follows one video after another. The only way to continue in the course is to finish a video, and when the video is completed, the next video is unlocked. This ensures that the video course is taken in the order designed by the instructor, and that the students are not 'skipping' ahead through the coursework.


Other use cases for this might be a corporate training, where it is required that every employee watches each video in a series to be compliant with the policies of an organization (as a veteran of AT&T, I have taken months of this sort of training)

In this post, we'll walk through how you can build a video training app with api.video. 

## Connecting a session to a user

The first step in any training course will be to login your user. In the case of training a video, we'll skip a secure login form (it is just a demo!) and simply ask you to enter your name:

large_screenshot-2021-06-28-at-18-14-33.png

medium_screenshot-2021-06-28-at-18-14-33.png

small_screenshot-2021-06-28-at-18-14-33.png

thumbnail_screenshot-2021-06-28-at-18-14-33.png

screenshot-2021-06-28-at-18-14-33.png

When you submit this form, we'll search through the videos connected to the course (in this case, they are hardcoded in the app as an array:

```
var videolist = ['vi47Q8KHXLYyaOoX2Yoznxqh','vi6QvU9dhYCzW3BpPvPsZUa8','vi1DrBc0VkPfedcfTc21U1TP'];
var videoDurations= [91,321,333];
```

Note, we also hardcode the duration of the 3 videos (but in a more dynamic app, you can get the video duration from the [video status](https://docs.api.video/reference/api/Videos#retrieve-video-status-and-details) endpoint.

Now for each of these videos, I have created  dynamic metadata entry:


```
	"metadata": [
		{
			"key": "classUserName",
			"value": "__classUserName__"
		}
	],
```

when the value of a metadata entry has two underscores on either side of the value, any value can be applied to the metadata entry.  In this case, we'll apply the username as the value.  We can search for any video sessions that have the classUserName "Doug" for each of the videos in the training session. (in the code below, I am using the NodeJS client:

```
			currentPage = '1';
      pageSize = '25';
      var metadata = {'classUserName': userName};
      var params = { videoId, metadata, currentPage, pageSize};
      console.log("params",params);
      const result = client.rawStatistics.listVideoSessions(params);

```

This will result in the first 25 sessions where the variable userName (Doug) is saved as the classUsername metadata. (Of course, if you believe that your users might have more than 25 sessions per video, you can expand that number up to 100 - but for a training course, 25 viewing sessions per video per user is probably more than adequate).

The response from this will be every session that the user has had for the video.  For each of these sessions, we want to know if the video was watched all the way through.  We've [written up this analysis](https://api.video/blog/tutorials/video-event-analysis-using-api-video-sessions/) of session events. As soon as we discover a session that has watched the video, we stop looking through the sessions.  

## How many videos to unlock?

This approach will then be completed for each video in the series, until we reach a video that has not been watched.  This is done through the recursive function iterateVideos:

```

function iterateVideos(videolist, videoDurations, userName, videoCounter){
  return new Promise(function(resolve, reject){
      //soo take list of videos, and iterate until we know which video can be watched.
      console.log("testing video "+videoCounter);
      var videowatched  = videoWatched(videolist[videoCounter], videoDurations[videoCounter], userName);
      videowatched
      .then(function(passfail){
    
        console.log("video "+videoCounter+ " "+ passfail);
        if(passfail){
          //video was watched, so lets check the next one
          videoCounter++;
          if (videoCounter < videolist.length){
            var nextVideo = iterateVideos(videolist, videoDurations, userName, videoCounter);
            resolve(nextVideo);
          }else{
            //the last video was watched so, stop and show all the videos...
            resolve(videoCounter -1);
          }
        }else{
          //video was NOT watched start wit this video
          console.log("resolve the counter of the first video not watched", videoCounter);
          resolve(videoCounter);
        }
      }).catch((error) =>{
        reject(error);
    });



  });
```

The videoWatched function checks each session to see if the video has been completed.  

If the video has been completed, it returns true.  Then we check the next video to see if it has been watched. (If we reach the end of the video list - we show all of the videos.).

If the video has not been watched - we know where to stop displaying playable videos, and we can display the page.

### What the user sees

For this simple example with three videos, there are just three potential views:

* If no videos have been watched - the first video will have no sessions, and the session analysis will stop immediately. The page will show the first video as playable, and the subsequent videos as locked.

* If the first video has been completed, but not the second: the page will show the first two videos as playable, but the third video will still be locked.

* If videos 1-2 are completed (or if all 3 videos are completed), all three videos appear as watchable.


### Looking at the HTML

```
<iframe type="text/html" src="https://embed.api.video/vod/vi6QvU9dhYCzW3BpPvPsZUa8?metadata[classUserName]=Doug" width="960" height="320" frameborder="0" scrollling="no"></iframe>

```

See how each video adds the ```metadata[classUserName]=Doug```  this will ensure that any video session that is started on this page will be assigned to the user Doug. Once a video is watched, the user can refresh the page, and all the session data will be recalculated, and the next video will be unlocked.


## Build your own video training app

With api.video, you can easily upload your videos for playback. Using our analytics and dynamic metadata, we can build a training application that unlocks each video as content is viewed. Build your own based on our code on [Github](https://github.com/apivideo/trainingavideo). If you have question, feel free to reach [our community](https://community.api.video/) or [test it now](https://dashboard.api.video/register) in our free Sandbox environment.

Build a self guided training course with api.video

large_build-a-self-guided-training-course-with-api-video.png

medium_build-a-self-guided-training-course-with-api-video.png

small_build-a-self-guided-training-course-with-api-video.png

thumbnail_build-a-self-guided-training-course-with-api-video.png

build-a-self-guided-training-course-with-api-video.png

Video Sessions (Analytics)

How much of your video is being watched?  With api.video analytics, we can tell you exactly how much of the video was watched.  In this post, we'll walk through how to parse video session data in order to add up how much of the video was watched in a session.

## A video Session

A video session occurs when an api.video player is opened in a browser.  As long as the same window is used, each viewing of the video will be added to that one session.

You can get a list of your video sessions by using the [analytics endpoint](https://docs.api.video/analytics/overview) for a given videoId. In my code (using NodeJS), it looks something like this:

```
var params = { videoId, metadata, currentPage, pageSize};
  
const result = client.rawStatistics.listVideoSessions(params);
  result.then(function(videos) {
        var sessionList = videos.data;
        console.log("Number of sessions to test " , sessionList.length);

          for(i=0;i<sessionList.length;i++){
            //get each session ID, and figure out how long each session watched the video
            var sessionId = sessionList[i].session.sessionId;
            pageSize = '100';
            console.log(sessionId);

```


The Node endpoint takes my parameters (including the videoId I wish to analyze) and sends it to the ```client.rawStatistics.listVideoSessions``` endpoint.  This returns an array of the sessions that can be analyzed. 

The log will list a count of sessionIds, and then list each sessionId. Here is an example output from this code snippet:

```
Number of sessions to test  8
ps5orCkYsuaMw08btQmsW8vp
ps24iGEi011m9xKPqdTnIOvZ
ps7ODtZR04dfRBQCcarOIhv7
ps19mQmv5CTQwdeb75n8lLWr
ps1UdYeHbp6tQ21vrGUI8gXw
ps6xqBySKoSQfmG4zjcyZtWU
ps3cLLchT0Os75lzXovlCqTe
ps3MpNgw5Ax5EQ4GSAVyODRh
```

## get Session Events

In each session, the video player records each event, and sends it back to api.video.  Using the [Session event](https://docs.api.video/analytics/overview) API endpoint, we can retrieve each of these events.

```
 var sessionParams = {sessionId, currentPage, pageSize}; const sessionData = client.rawStatistics.listSessionEvents(sessionParams);
    sessionData.then( function(lastSessionData) {
      //this is the session data
      console.log("session events", lastSessionData);

```


The response of this endpoint looks something like this:

```
session events RawStatisticsListPlayerSessionEventsResponse {
  data: [
    PlayerSessionEvent {
      type: 'ready',
      emittedAt: 2021-06-17T19:00:54.000Z,
      at: 0,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'play',
      emittedAt: 2021-06-17T19:00:55.000Z,
      at: 0,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'end',
      emittedAt: 2021-06-17T19:02:27.000Z,
      at: 91,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'pause',
      emittedAt: 2021-06-18T10:59:03.000Z,
      at: 91,
      from: undefined,
      to: undefined
    }
  ],

```

In this case, the video is ready at time =0, begins playing, and then reaches the end at 91s.  The window is closed a day later, sending a pause event.  (this is just evidence that your author has a browser tab problem).

Using this data (and with the knowledge that the video is 91 seconds long), it's pretty easy to determine that the entire video was watched in this session.  from ready to the first pause is 91s, so the video must have been completed. But what about more complicated viewing patterns?  Let's look at an example:


```
  data: [
    PlayerSessionEvent {
      type: 'ready',
      emittedAt: 2021-06-21T12:33:06.000Z,
      at: 0,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'play',
      emittedAt: 2021-06-21T12:36:13.000Z,
      at: 0,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'pause',
      emittedAt: 2021-06-21T12:36:18.000Z,
      at: 81,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'resume',
      emittedAt: 2021-06-21T12:36:19.000Z,
      at: 81,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'seek.forward',
      emittedAt: 2021-06-21T12:36:19.000Z,
      at: undefined,
      from: 5,
      to: 81
    },
    PlayerSessionEvent {
      type: 'end',
      emittedAt: 2021-06-21T12:37:19.000Z,
      at: 91,
      from: undefined,
      to: undefined
    },
    PlayerSessionEvent {
      type: 'pause',
      emittedAt: 2021-06-21T13:10:18.000Z,
      at: 91,
      from: undefined,
      to: undefined
    }
  ],
```


In this session, we again start playing at time = 0, but the next set of events occur at 81s (pause/resume). So the video stopped and restarted at t=81. The next event tells us how we got to t-81 - the view skipped ahead (noted as a 'seek.forward' event) at t=5, to t=81. The video paused because the video had to load, and then from t=81, it played until the end at t=91.  

In this case, even though the playback started at t=0, and ended at t-91, no one would consider this video fully watched, as the viewer skipped 76s of the video.

## Calculating the time watched

To calculate the time watched, we'll add up the time between every play/resume event and every pause/end event.  Then we'll subtract any time in a 'seek.forward' event.

```
 for(j=0; j< numberOfEvents; j++){
        if(lastSessionData.data[j].type == "play" || lastSessionData.data[j].type == "resume"){
          //start time measure
          starttime = lastSessionData.data[j].at;
          counting = true;
          console.log ("start" , starttime);
        }else if(lastSessionData.data[j].type == "pause" || lastSessionData.data[j].type == "end"){
          if(counting){
            endtime = lastSessionData.data[j].at;
            counting=false;
            console.log ("stop" , endtime);
            console.log ("added time" , endtime-starttime);
            summedtime += endtime-starttime;
            
          }
        }else if(lastSessionData.data[j].type == "seek.forward"){
          console.log("seeked forward", (lastSessionData.data[j].to - lastSessionData.data[j].from));
          summedtime -= (lastSessionData.data[j].to - lastSessionData.data[j].from);
          //if there was a seekforward, the max time previously calculated previously is no longer valid and needs to be recalculated.
          maxWatchedTime = 0;
        }
        console.log("summedtime: ", summedtime);
				
				
}

```

We can log the math that happens as we iterate through the events:

```
summedtime:  0
start 0
summedtime:  0
stop 81
added time 81
summedtime:  81
start 81
summedtime:  81
seeked forward 76
summedtime:  5
stop 91
added time 10
summedtime:  15

```

Comparing these events - we can see that from the first start to the first pause is 81seconds, but then we encounter the seeked forward of 76 seconds - leading to a summed time of 5 seconds.  After the last 10 seconds are watched, we have a total of 15 seconds of the 91 second video watched.


## Playback totals

When watching required training videos, it is often mandatory that the time watched is logged and and recorded. With the api.video session data, we can track each user's viewing to know if they have completed a video, or if they must re-watch the video.

In a future post, we will combine this video watching algorithm with code to 'unlock' subsequent videos in a training series.

Video event analysis using api.video sessions

large_screenshot-2021-06-21-at-13-06-24.png

medium_screenshot-2021-06-21-at-13-06-24.png

small_screenshot-2021-06-21-at-13-06-24.png

thumbnail_screenshot-2021-06-21-at-13-06-24.png

screenshot-2021-06-21-at-13-06-24.png

We recently launched a new [TypeScript NodeJS API client](https://docs.api.video/sdks/api-clients/apivideo-nodejs-client) that replaces the NodeJS SDK.  The NodeJS SDK is not going anywhere - so you can keep using it - but no new features will be added to the SDK.  All new features will now be added to the Client API.

Now, as we add new features, you might want to reduce the number of dependencies in your codebase and remove the NodeJS SDK - migrating to the new API Client.  We've prepared a [migration guide](https://github.com/apivideo/nodejs-api-client/blob/main/doc/MIGRATE.md) to help you along the path.

## Share a video migration

The changes are quite simple.  Let's walk through how I migrated the share.a.video application to the apiclient:

The [share.a.video](https://share.a.video) application uses a livestream to share a recorded video. This lets all the viewers watch the video at the same time.

In this application, the Node backend does a search of the livestreams in my account. First I added the SDK, and then I did a search for all livestreams:

```
//apivideo
const apiVideo = require('@api.video/nodejs-sdk');

<snip>

	//get data on both movies:
	const client = new apiVideo.Client({ apiKey: apiVideoKey });
	let allLiveStreams = client.lives.search();

```

To migrate this to the new API client, I only have to change these three lines:

 * Update the library I am going to use
 * change the apiVideo.Client to apiVideoClient, and place the parameters in brackets
 * lives to liveStreams
 * search() to list()


```
const apiVideoClient = require('@api.video/nodejs-client');

<snip>

	//get data on both movies:
	const client = new apiVideoClient({ apiKey: apiVideoKey });
	let allLiveStreams = client.liveStreams.list();

```

That's it. The code now runs on the new API client!


## resume a video

[resume.a.video](https://resume.a.video) finds a user's last session with a video, and then begins playback at the last second viewed by that user.  (just like when you restart a Netflix or YouTube video, it knows where you left off).

In resume.a.video the Node SDK was not querying analytics or sessions properly, so I used raw API calls:

* Authenticate my apiToken
* Receive all sessions for the user
* get the latest session data for the user for the most recent time,

With the Node API Client, this is now all possible with the client, and no more raw API calls.

When the user submits their username and the video they'd like to watch, we provide the Node server with the videoId and userName.  We make a request to the rawStatistics.listVideoSessions endpoint, asking for just one session.

If there are sessions, we grab the number of sessions, but if there are no sessions for that user, we know we can commence the video playback at time=0.


```
//first we'll get the session data for the video and the metadata userName
	var params = { videoId, metadata, currentPage, pageSize};
	console.log("params",params)
	const client = new apiVideoClient({apiKey: apiVideoKey});
	const result = client.rawStatistics.listVideoSessions(params);
	
	result.then(function(videos) {
	//	console.log("Allsessions that match", videos);
		const numberSessions = videos.pagination.itemsTotal;
		console.log("number of results: ", numberSessions);

		if(numberSessions >0){
			<we'll get the last session>
		}else{
			var videoUrl = 'https://embed.api.video/vod/'+videoId+'?metadata[userName]='+userName+'#autoplay';
						return res.render('video', {videoUrl});

		}	

```

### The user has sessions with the video

In the case that the user *has* watched this video, we'll be in the ```if(numberSessions >0)``` conditional.  We want to know how many sessions the user has had and collect the last one (which will have the last watched moment of the video).  

So, we make a second request to the same endpoint to get the most recent session for this user and this video and collect the sessionId.

```
if(numberSessions >0){
			currentPage = numberSessions;
			const lastSessionParams = { videoId, metadata, currentPage, pageSize};
			console.log("lastSessionParams", lastSessionParams);
			const lastSessionResult = client.rawStatistics.listVideoSessions(lastSessionParams);
			lastSessionResult.then(function(lastSession) {
				console.log("lastSesson: ", lastSession);
				//this is the last session
				var sessionId =  lastSession.data[0].session.sessionId;

```


With the sessionId, we can then call the  ```client.rawStatistics.listSessionEvents(sessionParams)```. Each event has the time recorded in the video when the event happened.  We retrieve this time value (in seconds) and append that to the video url with the ```#t``` url attribute.


```
				sessionData.then( function(lastSessionData) {
					//this is the session data
					console.log("session events", lastSessionData);
					var numberOfEvents = lastSessionData.pagination.itemsTotal;
					console.log("sessionevents", numberOfEvents);
					var lastTimeRecorded  = lastSessionData.data[numberOfEvents -1].at;
					console.log("lastTimeRecorded", lastTimeRecorded);

					var videoUrl = 'https://embed.api.video/vod/'+videoId+'?metadata[userName]='+userName+'#autoplay;t='+lastTimeRecorded;
						return res.render('video', {videoUrl});


				});
```

This tells the player to begin video playback at the time the last session ended, completing the task that resume.a.video was built to do. With many fewer lines of code, the new NODE api client has simplified the application, and it runs faster.

## Migrate your app

Our new Node API client is where all new api.video features will appear, as we have deprecated the Node SDK.  As this post shows, the migration from the older SDK to the API client is easy and relatively painless, so you can keep your application on our latest code base with minimal refactoring.

Migrate your Node app to our new API client

large_birds.jpeg

medium_birds.jpeg

small_birds.jpeg

thumbnail_birds.jpeg

birds.jpeg

large_api-video-blog-product-updates.png

medium_api-video-blog-product-updates.png

small_api-video-blog-product-updates.png

thumbnail_api-video-blog-product-updates.png

The SDKs for api.video make it easier to get started building with our tools.  Abstracting all the authentication and taking care of a lot of the connections for you, our SDKs help you plug and play api.video into your codebase quickly.  Historically, our most popular SDK has been our NodeJS SDK. 

That said, we had some limitations in our Node SDK: 

* search results included EVERY result without pagination.  This is great if you expect only a few results, but for our power users, this meant thousands of results, slowing the response time, and making parsing difficult.  We wanted to upgrade our SDK to allow for better search results.
* The analytics endpoint was not easy to use (mainly due to above, and a lack of filtering options).

We also had many requests for a TypeScript SDK using the api.video APIs.

When we took all of this feedback to the ecosystem team, they created a new [API Client for NodeJS and Typescript](https://github.com/apivideo/nodejs-api-client).  Our old SDK is still here and not going anywhere, but it is also no longer going to be updated, and all future features will be incorporated into the API client.  There are not that many changes between the two, so a migration will not be that hard (and we've created a [migration guide](https://github.com/apivideo/nodejs-api-client/blob/main/doc/MIGRATE.md) to make it even easier for you!)


New NodeJS/Typescript API Client

small_screenshot-2021-06-03-at-08-23-46.png

thumbnail_screenshot-2021-06-03-at-08-23-46.png

screenshot-2021-06-03-at-08-23-46.png

A chyron is the text that appears at the bottom of the TV on news channels telling viewers the topic being discussed.  You might want to add a chyron to your live stream or to your video on demand (VOD).  In this post, we'll walk through the steps to add a chyron to your video.





small_boxers.jpeg

thumbnail_boxers.jpeg

chyron-example.jpeg

## Chyron a video

The application (which will soon be published at chyron.a.video) extends https://record.a.video. You can read about how we built record.a.video in a [series of blog posts](https://api.video/blog/tutorials/grabbing-camera-streams-with-mediadevices-getusermedia/).  This application allows you to share your camera and your desktop, and creates a live stream or VOD recording of what you have shared.

We'll extend this by adding an icon to the left of the chyron (in the same approach as [watermark.a.video](https://api.video/blog/tutorials/watermarking-your-videos/). We'll then add a stripe over the video that the text will appear on.

## The code

The HTML adds 2 fields to the form: one for the logo url, and the 2nd for the text to be placed in the chyron. Along with some CSS, we style the form:

```
    <div class="settingHeadings">
                Chyron<br/>
            </div>
            <div id="watermark">
                <label for="watermark-url">image for chyron</label> 
                <input type="text" id="watermark-url" value="http://localhost:3037/API.PNG"><br/>
                <label for="chyron-text">text for chyron</label> 
                <input type="text" id="chyron-text" value="Your text here.">
            </div>
```

medium_screenshot-2021-06-01-at-14-14-23.png

small_screenshot-2021-06-01-at-14-14-23.png

thumbnail_screenshot-2021-06-01-at-14-14-23.png

screenshot-2021-06-01-at-14-14-23.png

### Starting the playback

When the stream is started, we add a few features to the canvas:

```
//chyron
        canvas.drawImage(watermarkImg, watermark_x, watermark_y);
        canvas.fillStyle='#fa4b2a'; 
        canvas.fillRect(chyron_x,chyron_y, chyron_length, chyron_height);
        canvas.fillStyle='#ffffff'; 
        canvas.font = "60px Arial";
        ctx.fillText(document.getElementById("chyron-text").value, chyronText_x, chyronText_y);
```

First we draw the icon (with variable name watermark) with the x,y positions hardcoded inthe JS.  We assume the size of the icon is 100x100.

Next we add a rectangle with fill color #fa4b2a (orange) that appears across the bottom of the screen.  

Then we change the fill color to white (#ffffff), and add the text from the form field.

These canvas events are all within a loop that fires every 20ms, or about 50 frames per second.  Since our video is capturing at a lower framerate than that, it will appear to update instantaneously.

## See it in action


In the video above, as the text on the browser window changes, so does the text in the chyron.  With 2 displays, you can now produce a live stream or VOD video with a chyron bar at the bottom of the screen.

## Try it yourself

The code for chyron a video is on [Github](https://github.com/dougsillars/chyronavideo). It's super easy to launch locally with NodeJS, and by changing the variables for the canvas colour and fill, you can easily adjust the font and look of the chyron to fit your requirements.

In this post, we've gone through the steps taken to convert record.a.video into a video with a chyron. You may have even learned what a chyron is :).

Let us know what you think, and how you've changed the app to customize your chyron in you VOD or livestream in our [developer community](https://community.api.video)

Adding a chyron to your video: Look like the news!

live - create

Videos - Upload a Thumbnail

When publishing a video on the web, sometimes it is desirable to add a defining mark on the video, often called a watermark.

When you use api.video in the sandbox, we add a watermark to show that the videos are being played back in our test environment:


medium_screenshot-2021-05-25-at-06-50-01.png

small_screenshot-2021-05-25-at-06-50-01.png

thumbnail_screenshot-2021-05-25-at-06-50-01.png

watermarked-video.png

Perhaps you want to add your corporate logo in the corner of the video.  Or perhaps the class name.  There are a number of different reasons you might want to add a watermark to your video, and in this post, I'll walk through two approaches to add a watermark to your videos. 

NOTE: We now have watermarking available as part of the API. Check out the new way to update content here: [https://docs.api.video/reference/api/Watermarks#upload-a-watermark](https://docs.api.video/reference/api/Watermarks#upload-a-watermark)
 
## The watermark

In this study, we'll be adding the api.video logo as our watermark.  I (randomly) chose to insert the logo in the top right corner of the video.



logoorange100.png

Your watermark should be appropriately sized for the space in the video.  In this case 100x100 pixels to fit inside a 1920x1080 video (~5%x10% of the screen). 

I have adapted the [record.a.video](https://record.a.video) app to add a watermark and you can test it at [watermark.a.video](https://watermark.a.video), and in this app, I have provided 2 ways to add the watermark: the frontend and the backend.  

medium_screenshot-2021-05-25-at-07-50-14.png

small_screenshot-2021-05-25-at-07-50-14.png

thumbnail_screenshot-2021-05-25-at-07-50-14.png

input-box.png

If the box is checked, the watermark is inserted on the frontend. If unchecked, the watermark is added on the backend.  The field allows you to change the image being added as a watermark.  

## Frontend Watermark

In the watermark.a.video application, the screen (screenCaptureAPI) and the camera (MediaRecorded API) are drawn to a canvas.  I've [described this process in detail](https://api.video/blog/tutorials/building-record-a-video-the-screencapture-api/) with code samples. The canvas is refreshed every 20ms, giving 50 FPS video on the canvas.  

To add a watermark, I simply load the image into the app, and instead of only drawing the screen (videoElem) and the camera (cameraElem), I add the watermarkImg:

```
        console.log("FE watermark", canvasWatermark);
        //load watermark image
        var watermarkImg = new Image;
        watermarkImg.src = canvasWatermark;
            //draw the 2 streams to the canvas
            drawCanvas(videoElem, cameraElem,watermarkImg,ctx);

```

Inside the drawCanvas function, I draw the watermakrImg on top of the other 2 elements (by placing it last in the list of things drawn):

```
    function drawCanvas(screenIn, cameraIn,watermarkImg, canvas){
        var textLength = 60;
        canvas.drawImage(screenIn, screenX0,screenY0, screenX1, screenY1);
        canvas.drawImage(cameraIn, cameraX0, cameraY0, cameraX1, cameraY1);
        canvas.drawImage(watermarkImg, watermark_x, watermark_y);
```

For this demo, I have hardcoded the watermark to be in the upper right corner, so watermark_x = watermark_y = 25.


## Backend Watermark

Perhaps the watermarking for your videos needs to be hardcoded into your process, or you do not want your users to be able to modify the watermark. Adding a processing step in the backend to insert a watermark makes this easy.

> Note that this approach oly works on a live stream, and not with the video on demand.  The VOD recording is done completely on the front end.

In the [record.a.video](https://record.a.video) app, livestreams are sent to a NodeJS server, where the WebRTC video recorded by the browser is converted to RTMP for ingestion into the api.video livestream server.  This conversion is done with FFMPEG.  We can simply modify the FFMPEG command insert the watermark on top of the video while it is being transcoded.  

```
			var ops = [
				'-i', socket._watermarkUrl,
				'-i','-',		
         '-preset', 'ultrafast', '-tune', 'zerolatency', 
			       '-r', framerate, '-g', framerate*2, '-keyint_min',keyint_min, 
				'-filter_complex', '[1:v][0:v] overlay=25:25',
     				'-c:a', 'aac', '-b:a','44k', '-ar', 44100, 
			        '-f', 'flv', socket._rtmpDestination		
		
		];

```

The FFMPEG options for watermarking has 2 lines added to the code from record.a.video.

```
				'-i', socket._watermarkUrl,
```

We have to give the URL of the image to add as the watermark.

```
	'-filter_complex', '[1:v][0:v] overlay=25:25',
```

The filter complex tells FFMPEG the order of the overlay.  Since I add the watermark first (index 0), and then the video stream(index 1) - we place the video stream first, and then the watermark on top, with an offset of 25x25.

FFMPEG reads the image file and just inserts it on each frame encoded to the api.video server.

### Watermark addition

In both cases, the live video that is sent to api.video has the watermark added. In the first case it is added in the browser as the video is being recorded, and in the second case, it is inserted by FFMPEG during a transcoding step.

Here's what the resulting video looks like:




In either case, you can see that we have successfully added the api.video logo as a watermark in the upper right corner.  Try out the demo: [watermark.a.video](https://watermark.a.video).  If you want to add watermarks to your videos - try out [api.video](https://dashboard.api.video/register). Feel free to fork the repo on [Github](https://github.com/dougsillars/watermarkavideo) and try it out yourself! And you can check out all the API reference documentation here: [api.video API Reference documentation](https://docs.api.video/reference). If you have any questions or suggestions, please let us know on our [communtiy forum](https://community.api.video/). 



Watermarking your video or live stream

large_Watermarking.png

medium_Watermarking.png

small_Watermarking.png

thumbnail_Watermarking.png

Watermarking.png

large_api-video-blog-video-trends.png

medium_api-video-blog-video-trends.png

small_api-video-blog-video-trends.png

thumbnail_api-video-blog-video-trends.png

api-video-blog-video-trends.png

Video trends

Building sample apps with api.video: a.video


Here at api.video we want to make it easy for people to share and distribute video, 
ensuring video is the **way** to communicate.  But we are often asked - “what can I do with your API?”

In order to answer some of your questions, we’ve begun creating demo applications that show off some of the power of api.video, and hosting them at [a.video](https://a.video).  We chose a.video so that we could have fun with the addresses hosting the demo applications.

In the last three months we’ve launched a number of applications that showcase some of the techniques you can use with api.video.  

## Uploading videos

There are 2 demos that focus on uploading video only:

[Upload.a video](https://upload.a.video) is a basic video uploader.  It uses a delegated token (a public API token that can only be used to upload videos.  It also breaks up large videos in the browser using file.slice() so that there are no file size issues during the upload (links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/upload-a-video).

[privatelyupload.a.video/](https://privatelyupload.a.video/) is a riff on the upload theme, but it uses an expiring delegated token.  What this means is that the token is only valid for a few seconds - allowing the upload to start, and then it expires.  It also allows you to rename the video, add a description, add/remove the mp4 version, and make the video public/private in the form. Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/private-delegated-upload).


## Upload a video, and then do something with the video

Once a video is uploaded, we can do more with the video.  Here are some apps we’ve built to upload, then do *something* with the video:

[upload.a.video/toDiscord](https://upload.a.video/toDiscord) uses nearly exactly the same code as upload a video, but it also posts the video in the Discord channel selected.  Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/upload-a-video-to-discord).

[moderate.a.video](https://moderate.a.video/)  takes your uploaded video, and adds tagging - initially tagging the video as “needsModeration.”  Then the video is sent to the hive.ai for moderation -looking for content like guns, smoking and nudity. Once the video has been processed, we analyze the results, and retag the video based on the results.  I was not surprised that the “Baywatch” theme song had swimsuits, or that the James Bond trailer had guns, but this app allows automatic sorting of videos without any human intervention.  Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/video-moderation).

[caption.a.video/](https://caption.a.video/)  Once the video is uploaded, the mp4 is sent to Authot, which does an audio analysis of the video, and creates a webVTT caption file.  Once this is created, the caption file is added to the video automatically.  Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/caption-a-video).

## Live Stream

[livestream.a.video](https://livestream.a.video/)  uses your webcam, and creates a livestream video -right from your browser!  Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/livestream-a-video).

[record.a.video](https://record.a.video) Livestream a video with screen and camera - in several different overlays.  You can also record a video and upload without streaming if you only want to playback the video. Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/record-a-video).

[share.a.video](https://share.a.video) plays a pre-recorded video on a livestream  This means that you can stream a movie and everyone will be watching the recorded video at approximately the same time, creating a virtual watch party!  Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/share-a-video).

## Video playback

Of course, watching the video is a major part of the experience for your customers.  Here are a few demos that leverage api.video’s playback tools to maximize the experience

[watch.a.video/playlist/](https://watch.a.video/playlist/) Create a playlist of videos and have them play one after the other. Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/a-video-playlist).

[storyify.a.video/](https://storyify.a.video/) This application only shows videos created in the last 24 hours.  Like many social media apps that “destroy” the video after 24 hours - this places a sense of urgency to users, so they keep coming back.  Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/storyify-a-video).

[resume.a.video](https://resume.a.video) uses our analytics along with your usernames (assuming a logged in user) to remember where the viewer left off.  Did they watch the first 36 minutes? On return, the video starts at 30:01, instead of back at the beginning. Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/resume-a-video).


[watch.a.video/broadcast](https://watch.a.video/broadcast) shows a livestream at the top, and then lists the 5 most recent recorded streams.  Perfect for a class setting - where the live and most recent lectures/classes are all located on the same page. Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/watch-a-video-broadcast)

## Video deletion

[delete.a.video/](https://delete.a.video/) It is sad, but sometimes, a video just needs to be deleted.  This demo only deletes videos with one file name in my account, but can easily be modified to search and delete videos by name or tag. Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/delete-a-video).

## Video analytics

[ffprobe.a.video](https://ffprobe.a.video) uses a feature of FFMPEG - ffprobe to give you details about the video.  This one does not leverage our APIs per se, but it's a cool way to learn about your video’s features. Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/ffprobe-a-video)

[whoswatched.a.video/](http://whoswatched.a.video/) uses our analytics to break down each user session by country, device type and more.  Links to the blog post, and to the GitHub repository in the [a.video description page](https://a.video/works/who-s-watched-a-video)

## Conclusion

These are the demos we’ve come up with in the last few months - if you have an idea, feel free to post it on the [community](https://community.api.video) page.  If you have a demo that we could feature - let us know!  We’d love to feature your cool api.video implementation as well!


Video on demand

Live streaming

Analytics

Video infrastructure

Video player

AI features

See all features

Online learning & Corporate training

Social & Entertainment

Marketplace & E-commerce

Communication & UGC

Generative AI

Quickstart guides

Documentation

Ecosystem catalog

Clients & SDKs

Community

Blog

Demos

Customer success stories

Help center

NodeJS