Dynamic Metadata

Analytics

Video Sessions (Analytics)

Normal

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

Tutorials

NodeJS

When I read a book, I fold a corner over the page I am reading to remember my place.  Sometimes I fall asleep while reading, and it takes a few minutes to figure out where I had finished the night before, and I wish to myself that I had folded over the corner.

Watching video online is the same way - if you're interrupted while watching a long video (Amazon delivery at the door, child is hungry, cat needs to be let out... you know) it would be nice to resume right where you left off.

## Resuming videos

YouTube recently remembered where I had left off on a knitting tutorial.. that I had watched 3 years ago.  I have small children, so we often have to pause movies for days before we finish them, and it is great that Netflix recalls that we turned off the TV at 42:11 into the feature.  No more scanning and seeing potential spoilers a scene or two ahead.

We can do the same with api.video's videos.  We've released a demo at [resume.a.video](https://resume.a.video) where you can test this feature out.



## Resuming Videos with api.video

### Identifying users

For each video that you'd like to resume, you should create a [dynamic metadata](https://api.video/blog/tutorials/dynamic-metadata/) attribute that you will use to identify each user. For the videos in the demo, I created a dynamic metadata with key "userName"

screenshot showing metadata setting for video

large_screenshot-2021-01-11-at-15-46-51.png

medium_screenshot-2021-01-11-at-15-46-51.png

small_screenshot-2021-01-11-at-15-46-51.png

thumbnail_screenshot-2021-01-11-at-15-46-51.png

screenshot-2021-01-11-at-15-46-51.png

>You can create a Dynamic metadata with the [Update video](https://docs.api.video/reference#patch-video) endpoint.  For the 'key' use the key.  For 'value' add two'_' before and after the term. The API will know that this value can have any potential value.

> You can also use the GUI at go.api.video to add the metadata.

We can use this to uniquely identify users who watch the video.  I would recommend using a unique non-identifiable string for each user, but for simplicity, I'll use first names in this demo. In this way, we can identify who is watching the video:

https://embed.api.video/vod/vi4fvaDG9nqfdMTqRnmZuvlJ?metadata[userName]=Doug

This video will record its session with the metadata userName: Doug.  

Awesome - assuming we know the user's name, we can insert this URL paramater and now identify all of their sessions with the video.


### Identifying user sessions

When you use the api.video player, each session has video analytics recorded (and each session is based on a cookie set in the browser). Using the [analytics video session](https://docs.api.video/reference#get_analytics-videos-videoid) endpoint, you can search each session for a video played.  You can limit this search with the metadata term. In NodeJS, this looks like:

```
var firstSessionQuery = {
			method: 'GET',
			url: 'https://ws.api.video/analytics/videos/'+videoId+'?currentPage=1&pageSize=1&metadata[userName]='+userName,
			headers: {
				accept: 'application/json',
				authorization: 'Bearer ' +authToken
			}
		}
		request(firstSessionQuery, function (error, response, body) {
			if (error) throw new Error(error);
			body = JSON.parse(body);
		}

```

The request url uses the videoId and userName to get just the sessions for the user.  The response can return from 1 to 100 results, with the most recent session appearing at the end. In this query, I only request the first session:

```
data {
  session: {
    sessionId: 'ps5qU6t436lzoDftbAfuJPzP',
    loadedAt: '2021-01-05T12:52:21+00:00',
    endedAt: '2021-01-05T12:52:53+00:00',
    metadata: [ [Object] ]
  },
  location: { country: 'United Kingdom', city: 'Watford' },
  referrer: {
    url: null,
    medium: 'unknown',
    source: 'unknown',
    searchTerm: 'unknown'
  },
  device: { type: 'computer', vendor: 'unknown', model: 'Other' },
  os: { name: 'Mac OS X', shortname: 'Mac OS X', version: '11.0.1' },
  client: { type: 'unknown', name: 'Chrome', version: '87.0.4280' }
}
pagination {
  currentPage: 1,
  currentPageItems: 1,
  pageSize: 1,
  pagesTotal: 23,
  itemsTotal: 23,
  links: [
    {
      rel: 'self',
      uri: '/analytics/videos/vi4fvaDG9nqfdMTqRnmZuvlJ?currentPage=1&pageSize=1&metadata%5BuserName%5D=Doug'
    },
    {
      rel: 'first',
      uri: '/analytics/videos/vi4fvaDG9nqfdMTqRnmZuvlJ?currentPage=1&pageSize=1&metadata%5BuserName%5D=Doug'
    },
    {
      rel: 'next',
      uri: '/analytics/videos/vi4fvaDG9nqfdMTqRnmZuvlJ?currentPage=2&pageSize=1&metadata%5BuserName%5D=Doug'
    },
    {
      rel: 'last',
      uri: '/analytics/videos/vi4fvaDG9nqfdMTqRnmZuvlJ?currentPage=23&pageSize=1&metadata%5BuserName%5D=Doug'
    }
  ]
}

```
 
Ok, so when I created this video in January 2021, I watched it, to ensure that it worked.  You can see my approximate location (it's really where my ISP exits to the internet), and I was on a Mac running Chrome.

So, why just one entry?  We want to get the last session that was viewed, and that is always the last session in the list.

```
var sessionCount = body.pagination.itemsTotal;
```

There are really only three possibilities to worry about here:

* sessionCount = 0.  This is a new viewer of the video, and there are no sessions saved.  If there are no sessions for the user - we can immediately serve the page, and start the video at the beginning:

```
				//no sessions for this user
				//return the video at time =0
				var videoUrl = 'https://embed.api.video/vod/'+videoId+'?metadata[userName]='+userName+'#autoplay';
				return res.render('video', {videoUrl});
```
This will load the page with the video autoplaying.

* sessionCount=1. The viewer has watched the video once.  If that is the case, the sessionId returned in the response will be the session we want.  You can now skip ahead to the "parsing session data" section.
* sessionCount >1.  There is more than one session for this user. In the example above, the itemsTotal parameter indicates that there are 23 sessions for userName=Doug.

The API has a limit of 100 sessions in the video analytics response. In general, one user is unlikely to have >100 sessions for a single video, so one query would probably be sufficient. However, this is a demo app with a default user - it is possible that we might exceed 100 sessions.  If I queried for 100 sessions, the demo would appear to fail - we'd only ever see the 100th session. So, we request one, and then to ensure that we always get the last session, we can now make a second query for the last session (conveniently in the pagination.links.last.uri).

```
var lastUri = decodeURI(body.pagination.links[linksLength-1].uri);
					console.log("number of sessions with this username:", lastSessionCounter);
					console.log("uri", lastUri);
					//request that last session
					var lastSessionQuery = {
						method: 'GET',
						url: 'https://ws.api.video' +lastUri,
						headers: {
							accept: 'application/json',
							authorization: 'Bearer ' +authToken
						}
					}
					request(lastSessionQuery, function (error, response, body) {
						if (error) throw new Error(error);
						body = JSON.parse(body);
						console.log("body", body);
						console.log(body.data[0]);
						var sessionId = body.data[0].session.sessionId;
						console.log(sessionId);
						//now we can access this sessionId, and get the last time in the session
						getSession(authToken, videoId, sessionId, userName);

```

This response now tells me the last session for Doug and this video:

```
 session: {
    sessionId: 'pshSgwO44hBbc0nYKz1OZsz',
    loadedAt: '2021-01-11T19:02:43+00:00',
    endedAt: '2021-01-12T11:35:49+00:00',
    metadata: [ [Object] ]
  },
  location: { country: 'United Kingdom', city: 'Slough' },
  referrer: {
    url: 'http://localhost:3006/',
    medium: 'unknown',
    source: 'unknown',
    searchTerm: 'unknown'
  },
  device: { type: 'computer', vendor: 'unknown', model: 'Other' },
  os: { name: 'Mac OS X', shortname: 'Mac OS X', version: '11.0.1' },
  client: { type: 'unknown', name: 'Chrome', version: '87.0.4280' }
}

```

Again - on my Mac - but this time, I am in Slough, UK (and I was testing this app locally on my computer).  The sessionId I want is 'pshSgwO44hBbc0nYKz1OZsz'

### Parsing session data

If there was a previous session for this user - we now have the last session (and more importantly the sessionId for that session). It may have just been one request - or it may have taken two.

I use the [session events](https://docs.api.video/reference#get_analytics-sessions-sessionid-events) endpoint to find out what happened in the session:

```
	function getSession (authToken, videoId, sessionId, userName) {
		//lets get 100 session activities - i doubt there will ever be that many - (or more than 100)
		var getSession = {
			method: 'GET',
			url: 'https://ws.api.video/analytics/sessions/'+sessionId+'/events?currentPage=1&pageSize=100',
			headers: {
				accept: 'application/json',
				authorization: 'Bearer ' +authToken
			}
		}
		request(getSession, function (error, response, body) {
			if (error) throw new Error(error);
			body = JSON.parse(body);
			console.log("sessions", body.data);
			var numberofEvents = body.data.length;
			console.log("num events", numberofEvents);
			var lastTimeRecorded = body.data[numberofEvents-1].at;
			console.log("last event time", lastTimeRecorded);
	
			var videoUrl = 'https://embed.api.video/vod/'+videoId+'?metadata[userName]='+userName+'#autoplay;t='+lastTimeRecorded;
					return res.render('video', {videoUrl});
	
		});
	
	}
	
	  
});

```

So the API calls the session endpoint with the sessionId we discovered in the last section.  We get a response (write to console log) and we extract how many events were in the last session, and find out what the last event was. 

>You'll note that in the comments I make an assumption that there will never be 100 events (play, pause, seek, etc.) in a single session. I think this is safe  to make :)

The session response looks like this:

```
sessions [
  { type: 'ready', emittedAt: '2021-01-12T11:59:42+00:00', at: 0 },
  { type: 'play', emittedAt: '2021-01-12T11:59:42+00:00', at: 0 },
  { type: 'pause', emittedAt: '2021-01-12T11:59:45+00:00', at: 2 },
  {
    type: 'seek.forward',
    emittedAt: '2021-01-12T11:59:46+00:00',
    from: 2,
    to: 163
  },
  { type: 'resume', emittedAt: '2021-01-12T11:59:47+00:00', at: 163 },
  { type: 'pause', emittedAt: '2021-01-12T11:59:49+00:00', at: 165 }
]
num events 6
last event time 165

```

So I started the video at time =0, and then at time t=2, I jumped ahead "seek.forward" to 163s.  Then I paused at 165s.

**So the last time viewed was at 165s.**

### Starting the video

We have now found all the sessions for the user.  We grabbed the last (most recent) session, and then found the last event in that session - to give us the last time that the user saw the video.

In HTML5, if you add #t=X, where X is an integer to the end of a video URL, the video playback will begin at that time. Simply returning the url with this parameter will start the video at the last time the user viewed the video.

## Summary

With Dynamic metadata, we are able to assign video watching sessions to specific customers.  We can then search a specific user's sessions for the most recent session, and inside that session, parse all the events that occured during playback. 

Using the last session, and the last event, we get the last time that the viewer interacted with the video.  We can now use this time as the "resume time" for the video, and stat the video at that time.

Don't forget to try it out: [resume.a.video](https://resume.a.video)

This is a nice feature that makes watching longer videos easier - your viewers know they can come back and quickly pick up where they left off.  

Are you thinking about using 'resume' in your videos?  The code is all up on [Github](https://github.com/dougsillars/resumeAVideo) Let us know - we'd love to see if it improves the engagement of your viewers! Leave us a comment in the [community](https://community.api.video) forum.

Resume a video

medium_screenshot-2021-01-11-at-13-29-09.jpg

small_screenshot-2021-01-11-at-13-29-09.jpg

thumbnail_screenshot-2021-01-11-at-13-29-09.jpg

screenshot-2021-01-11-at-13-29-09.jpg

You have created the perfect video, uploaded it to api.video, and embedded the player on your website.  Are you curious about how many people are looking at your video?  How about where they are in the world?

Maybe you want to get even more granular, and know how much of the video is being watched?  Are they rewinding and watching parts again?  Are they skipping ahead?  With api.video’s analytics, you can find out.

In this post, we’ll take a look at how to extract this information for one video, and in future posts, we will go into deeper depth into building analysis tools.


## My Video





I’ve used this video of Tuba players playing the Beatles in other tutorial posts.  So, we know it will have a lot of views. But, how many?  Using the [List Video sessions](https://api-video.doctave.dev/delivery-analytics/analytics) endpoint, we can get information about each time this video was played with the api.video player.

To use this API, you need 2 items:  a ```videoId``` of the video you want to measure, and an authentication token.  In order to [authenticate your session](https://docs.api.video/reference/basic-authentication), you need your api.video token.  Read the details in the [authentication tutorial](https://api.video/blog/tutorials/authentication-tutorial/), and then come back with your token (it will be valid for one hour).

In this example, we’ll use curl to access the video session endpoint.  The videoId is ```vi4blUQJFrYWbaG44NChkH27```.  The curl request looks like:

```
curl --request GET \
  --url 'https://ws.api.video/analytics/videos/vi4blUQJFrYWbaG44NChkH27?currentPage=5&pageSize=100' --header 'authorization: Bearer {token}'   --header 'accept: application/vnd.api.video+json'
```

I am requesting page 5 (currentPage in the url), with pageSize=100 (100 sessions per page, since I knew that this video had between 400 and 500 views.  For simplicity, I’ll show just the 2 most recent sessions:

```json
{
	"data": [
		{
			"session": {
				"sessionId": "ps4mPLq8bZzjXlxwJG4cg4vl",
				"loadedAt": "2020-10-12T11:21:09+00:00",
				"endedAt": "2020-10-12T11:27:20+00:00"
			},
			"location": {
				"country": "United Kingdom",
				"city": "Glasgow"
			},
			"referrer": {
				"url": null,
				"medium": "unknown",
				"source": "unknown",
				"searchTerm": "unknown"
			},
			"device": {
				"type": "computer",
				"vendor": "unknown",
				"model": "Other"
			},
			"os": {
				"name": "Mac OS X",
				"shortname": "Mac OS X",
				"version": "10.15.6"
			},
			"client": {
				"type": "unknown",
				"name": "Chrome",
				"version": "85.0.4183"
			}
		},
		{
			"session": {
				"sessionId": "ps42gcSLNv8hSQxKOWWgxeNj",
				"loadedAt": "2020-10-12T11:43:56+00:00",
				"endedAt": "2020-10-12T11:44:19+00:00"
			},
			"location": {
				"country": "Netherlands",
				"city": "Uithoorn"
			},
			"referrer": {
				"url": "https://t.co",
				"medium": "social",
				"source": "Twitter",
				"searchTerm": "unknown"
			},
			"device": {
				"type": "computer",
				"vendor": "unknown",
				"model": "Other"
			},
			"os": {
				"name": "Mac OS X",
				"shortname": "Mac OS X",
				"version": "10.15.7"
			},
			"client": {
				"type": "unknown",
				"name": "Safari",
				"version": "14.0"
			}
		}
	],
	"pagination": {
		"currentPage": 5,
		"currentPageItems": 22,
		"pageSize": 100,
		"pagesTotal": 5,
		"itemsTotal": 422,
		"links": [
			{
				"rel": "self",
				"uri": "/analytics/videos/vi4blUQJFrYWbaG44NChkH27?currentPage=5&pageSize=100"
			},
			{
				"rel": "first",
				"uri": "/analytics/videos/vi4blUQJFrYWbaG44NChkH27?currentPage=1&pageSize=100"
			},
			{
				"rel": "previous",
				"uri": "/analytics/videos/vi4blUQJFrYWbaG44NChkH27?currentPage=4&pageSize=100"
			},
			{
				"rel": "last",
				"uri": "/analytics/videos/vi4blUQJFrYWbaG44NChkH27?currentPage=5&pageSize=100"
			}
		]
	}
}
```
Let’s start with the information at the bottom.  We can get links for each page of sessions, and itemsTotal is 422 - meaning there have been 422 sessions watching this video.  

Let’s look at the 2 sessions in the logs.  The first session has sessionId = ps4mPLq8bZzjXlxwJG4cg4vl.  This user watched the video for about 6 minutes based on the session length:
				"loadedAt": "2020-10-12T11:21:09+00:00",
				"endedAt": "2020-10-12T11:27:20+00:00"

We also know that they are in Glasgow, UK, using Chrome 85 on a Mac..  It just so happens that my ISP enters the internet in Scotland (all my advertising is Scotland based) even though my physical location is England, so this session is from my computer.

The 2nd session is interesting:

	"location": {
				"country": "Netherlands",
				"city": "Uithoorn"
			},
			"referrer": {
				"url": "https://t.co",
				"medium": "social",
				"source": "Twitter",
				"searchTerm": "unknown"
			},
			
I accidentally tweeted the url to this video, and deleted the tweet within 30 seconds,  Yet, someone on Twitter in the Netherlands still got to see the video before the tweet disappeared.

> Did you know that the api.video player works in Twitter?  Now you do! Your analytics will show video plays from any share on Twitter!

### Applications

With this data - you could build a map of where the video is being watched by country, and in some cases by city (with the caeat that this is not 100% accurate - my ISP says I am in Scotland).  You can also understand the referring urls: Twitter, blogs, Linkedin, etc.  Finally, you can also monitor the traffic patterns by day of week, time of day, etc.


## Going even deeper 

It is great to know that there was a video view at 11:21 GMT - but we can learn even more about this video view.  Using the [session events](https://docs.api.video/reference/api/Analytics#get_analytics-sessions-sessionid-events) endpoint and the sessionId, we can actually describe the exact usage of that session.  Making a request using a sessionId (note this is a different - more interesting - session):

 ```
--request GET \
   --url 'https://ws.api.video/analytics/sessions/ps42gcSLNv8hSQxKOWWgxeNj/events?currentPage=1&pageSize=100' --header 'accept: application/vnd.api.video+json' --header 'authorization: Bearer {token}'  --header 'accept: application/vnd.api.video+json'
```

This request will return all of the video player events in that session: so we can see any play, pause or seek events that occurred in playback:

```json
{
	"data": [
		{
			"type": "ready",
			"emittedAt": "2020-10-11T20:43:32+00:00",
			"at": 0
		},
		{
			"type": "play",
			"emittedAt": "2020-10-11T20:43:32+00:00",
			"at": 0
		},
		{
			"type": "pause",
			"emittedAt": "2020-10-11T20:43:57+00:00",
			"at": 2
		},
		{
			"type": "resume",
			"emittedAt": "2020-10-11T20:44:00+00:00",
			"at": 18
		},
		{
			"type": "seek.forward",
			"emittedAt": "2020-10-11T20:44:00+00:00",
			"from": 2,
			"to": 18
		},
		{
			"type": "pause",
			"emittedAt": "2020-10-11T20:44:01+00:00",
			"at": 19
		},
		{
			"type": "resume",
			"emittedAt": "2020-10-11T20:44:04+00:00",
			"at": 2
		},
		{
			"type": "seek.backward",
			"emittedAt": "2020-10-11T20:44:04+00:00",
			"from": 19,
			"to": 2
		},
		{
			"type": "pause",
			"emittedAt": "2020-10-11T20:44:11+00:00",
			"at": 9
		}
	],
	"pagination": {
		"currentPage": 1,
		"currentPageItems": 9,
		"pageSize": 100,
		"pagesTotal": 1,
		"itemsTotal": 9,
		"links": [
			{
				"rel": "self",
				"uri": "/analytics/sessions/psyd0zH6RWUCxP7xnWqcnKm/events?currentPage=1&pageSize=100"
			},
			{
				"rel": "first",
				"uri": "/analytics/sessions/psyd0zH6RWUCxP7xnWqcnKm/events?currentPage=1&pageSize=100"
			},
			{
				"rel": "last",
				"uri": "/analytics/sessions/psyd0zH6RWUCxP7xnWqcnKm/events?currentPage=1&pageSize=100"
			}
		]
	}
}
```

The video was ready to play (entry 0) and started to play (entry 1) at ```2020-10-11T20:43:32+00:00```.  (That is expected, as the [player](https://api.video/blog/tutorials/tutorial-video-player-customisation/) associated with this video is set to autoplay as soon as it is ready). The video is also set to loop, which is evident in the next entry.

The third entry shows that the video was paused at ```2020-10-11T20:43:57+00:00```.  The video timestamp shows “2” meaning 2 seconds into the video.  About 25 seconds elapsed since the video started, so how does that work?  The video is about 20 seconds long, meaning that the video played to the end and started again before the pause occurred.  

The next entries show that there is a seek.forward event from 2->18s, and the video resumed for one second before rewinding back to 2 and then playing to 9 seconds into the video.

Aggregating these session stats across all sessions can give you an idea of when users rewind - perhaps when an important point is raised  - indicating that in future videos that data should be highlighted for your users.  You can also see if there is early abandonment, or jumps ahead - as users look for the content that they are interested in.

### Fast analytics

These results are available as soon as the session is completed.  To see how quickly, I recorded a video where I watched the video, and then retrieved the analytics immediately afterward.  




## Conclusion

When you use the api.video player, there are a number of interesting analytics collected. Beyond knowing the number of views, the geo-location of the views and the time that the videos were viewed, you can also dig into the analytics of each session to better understand how your videos are being played.  If you have questions, please reach out in the [community forum](https://community.api.video)


Video analytics: A primer

medium_abacus6.jpg

small_abacus6.jpg

thumbnail_abacus6.jpg

abacus6.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!).


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

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

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

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

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

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:


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

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

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

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

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:

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

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

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

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:


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

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

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

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

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

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:


Couchbase results in Google Sheets to create this chart.

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

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

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

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

### 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).


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

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

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

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

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

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

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

## 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

codec

video create

small_cedric.jpeg

thumbnail_cedric.jpeg

cedric.jpeg

Cédric Montet

Product updates

At api.video, our goal is for video to be easy and affordable for anyone to build, be it individuals or organizations. We understand that achieving this goal means reducing costs at some stage of the video streaming process. That’s why, we now offer adaptive bitrate encoding for your videos at zero cost. 

&nbsp;

Yes, you heard me right. 

&nbsp;

**Encoding videos will be absolutely free for all video qualities (1080p or 4K) at [api.video](https://api.video/) - no hidden calculations, footer notes or tricks.**

(Check out this [video](https://www.youtube.com/watch?v=ouosgLbW7Ts) for more details) 


## A step towards making video streaming affordable

Video encoding is crucial as it makes it possible for videos to be shared and played smoothly on the internet. It is why we are easily able to consume various types of video media, whether it’s a YouTube video, our favorite shows on Netflix, or even catching up with friends across the globe on Zoom. Video encoding basically makes the world go around in regards to anything related to video and video content.

&nbsp;

We at api.video recognize that. From [increasing the transcoding and playback speed ](https://api.video/blog/product-updates/2021-in-review/)to building [specialized hardware like ASICs](https://api.video/blog/video-trends/the-comeback-of-specialized-hardware/) cards to increase our transcoding capacities, we've been working to make video streaming easier for you every day. And after dedicating ample time to engaging with our customers and learning about their concerns, free encoding seemed to be the next step in this direction. 

&nbsp;

So, we worked tirelessly behind the scenes to give you what no one else will - free encoding for all video qualities, be it 360p or 4K. 

## How does free video encoding benefit you as a customer

The benefit is straightforward: you save a LOT of money!

&nbsp;

- With free video encoding, you will have one less thing to worry about. As you know, you pay for three things for streaming videos — encoding, hosting, and delivery – out of which encoding is the most expensive, especially if you have a lot of videos. Free video encoding will allow you to focus your attention and resources to what is most important.

&nbsp;

- As the video needs of your app users grow, you might need to scale up your encoding capacity. Free video encoding services will give you the power to scale without any additional costs, meaning your users can handle more videos without increasing your expenses.

&nbsp;

- You can [migrate from your previous provider to api.video](https://api.video/compare/azure-media-services/) without paying an ‘entry tax’ to us. With free video encoding, you no longer need to spend money on encoding videos with a new provider when you have already paid for encoding with an older one.

&nbsp;

Now with all the saved cost, you can allocate your resources and money to a place where it is actually important – building your product and delighting your users. 

## How to get started

To use the free video encoding benefit, getting started is easy. 

&nbsp;

- If you’re a new user, [sign-up](https://dashboard.api.video/register) for a free sandbox account and start uploading your videos
- If you are looking to migrate from another vendor, [import](https://import.api.video/) your videos from your current vendor
- If you have any questions, [talk to us](https://meetings.hubspot.com/diego398/cc-talk-to-us?__hstc=54467703.754940701eda85e3c99a902d8ab0b988.1687266643206.1694417789132.1694427271479.149&__hssc=54467703.3.1694427271479&__hsfp=3654297906) by booking a slot in our calendar

&nbsp;

To know more about our[ features](https://api.video/features/), [pricing](https://api.video/pricing/) or ask any other questions, [talk to our team ](https://meetings.hubspot.com/diego398/cc-talk-to-us?__hstc=54467703.754940701eda85e3c99a902d8ab0b988.1687266643206.1694162373815.1694167498585.144&__hssc=54467703.1.1694167498585&__hsfp=3654297906)and we will help you out. 

&nbsp;

Or, you can straightaway [sign-up](https://dashboard.api.video/register) for a free sandbox account and check our product out for yourself. 


Huge pricing update: Introducing video encoding at no cost

large_Blog_Zero Cost (2).png

medium_Blog_Zero Cost (2).png

small_Blog_Zero Cost (2).png

thumbnail_Blog_Zero Cost (2).png

Blog_Zero Cost (2).png

api.video team

Video trends

Modern technology has been helpful for an increasingly fast and simple method of consuming various types of video media, whether it’s a YouTube video, our favorite shows on Netflix, or even catching up with friends across the globe on Zoom. Despite the relative ease of doing anything related to video, a few complex processes take place behind the scenes, away from public view. One such process is video encoding.

Video encoding basically makes the world go around in regards to anything related to video and video content. Thanks to the technologies behind the video encoding process, it has become much easier for people and companies to share video content on the internet. But what exactly is video encoding, and what happens during the process? We’ll take a closer look at this and much more in this handy guide to video encoding.

## What is video encoding?

In a nutshell, video encoding occurs when you take raw video footage, either from a digital camera or an analog film camera, and digitally compress it to make it a more manageable file size. Video encoding happens daily in both professional and personal capacities, and many people don’t realize it.

But, without encoding, services like Netflix and YouTube would not exist – or, at least, not in the same way that it does today. Without it, we couldn’t send videos of our beloved pets to our friends and family as easily as we can today.

## Why is video encoding used?

There are a variety of reasons why video encoding is used, but all factors point to the single function of video encoding – **compression**.

This is done to ensure optimal performance and compatibility with a selected suite of software and hardware, be it for DVD/Blu-ray playback, mobile viewing, online video streaming, or general video editing. A file's video and audio information undergo transformation and compression during the encoding process, all in accordance with the requirements of the selected encoding standard.

On a professional level, the ability to compress raw video into more manageable sizes makes it easier to transmit video content such as training, promotion, presentation, and so on over the internet. 

On a personal level, video encoding makes it much easier to send videos taken from your phone directly to friends and family. Most modern-day personal devices have built-in video encoding capabilities to allow for this to happen without a second thought.

To put things in perspective, uncompressed or unencoded video can have a data rate that’s as low as 3,000 Mbps and as high as 12,000 Mbps, depending on the length and quality of the video recorded. 

**Without encoding, it would take up to days for anyone to not just transmit video, but to be able to consume it, too.**

## Differences between video encoding and video transcoding

You need to be familiar with two more [essential terms related to video encoding](https://api.video/what-is/) – transcoding and codecs.

Transcoding relates to the conversion from one digital encoding format to another. It takes the already encoded video file, decompresses it, and then alters it before re-encoding or compressing it into a different codec. Codecs are what allow encoding to occur in the first place. They are software or hardware that gives us the ability to compress video to make them more easily stored and delivered tightly.

While you may hear “encoding” and “transcoding” used interchangeably, the two terms actually mean different things. Putting it succinctly, encoding is the initial process of compressing a video from a source – such as a camera – into a codec, while transcoding takes an already encoded video file to convert it into a different codec.

## Examples of video codecs

In order to understand video encoding, you must first be familiar with two interrelated terms: [video codecs and video formats](https://api.video/blog/product-updates/every-video-format-codec-and-container-explained/). These also tend to be used interchangeably, but much like the terms encoding and transcoding, they refer to two different things.

Video formats are the type of files in which the compressed video/audio is stored. Also known as a “container”, you can tell what a video format is by looking at the file’s extension — the three to four characters that sit after a period in a file name. Here are some of the most common video formats used today:

* MP4
* FLV
* MOV
* MKV
* LXF
* MXF
* AVI
* WebM
* QT

On the other hand, **the codec is short for “Coder / Decoder” (compression / decompression)** and relates to the video compression algorithms that allow encoding to happen. Over the years, codecs have gone through multiple iterations as it coincides with the increasing sophistication and rise in the quality of filmmaking. 

If you’re a content creator, you might be aware of some of the video codecs that exist today:

- **H.264 – also known as AVC, this is the most widely-used video codec available on every platform and mobile device.**
- H.265 – also known as HEVC, stands for High-Efficiency Video Coding, and it’s slowly overtaking H.264 as the standard. This codec can compress video much more efficiently than its predecessor.
- **VP9 – is an open-source, royalty-free codec developed by Google and is considered the direct competitor of H.265. The video compression codec VP9 was created to reduce file sizes, making streaming videos simpler.**
- **AV1 – is another royalty-free, open-source codec released in 2019 by the non-profit Alliance for Open Media. It was developed to become the successor to Google’s VP9 and contend with HEVC more directly.**

## How do different technologies handle video encoding

As you may have suspected, there are a majority of ways that different technologies handle the video encoding process. Let’s take a look at the most common technologies that use video and how video encoding works on each of them:

### Video editing software

When it comes to video content creation, a majority of people will use one of two video editing software — Adobe Premiere Pro or Apple’s Final Cut Pro. Both of these video editing software handle video encoding in very similar ways: when exporting the finished video.

Depending on which device the video content is recorded on, it will already be encoded and formatted according to the settings of the device. For those using iPhones recording 1080p video at 25 frames per second (FPS), for example, the iPhone will automatically encode the video using H.264 and contain it in a .mov file format. The video editing software will “open up” the container to get to the encoded, compressed video file within so the editing process can begin.

After editing the footage is complete, it will need to be exported, which typically concerns video encoding. The edited raw media taken from a recording device such as a camera will be encoded via the codec of the person’s choosing before being put into a .mp4 container once they’ve hit “export”. As we’ve mentioned before, the most common codec used in video content creation is H.264 for HD videos, with 4K videos using H.265. 

### Websites

Different websites utilize different techniques to handle video encoding – with a majority of the major sites like YouTube, Netflix, and so on using their own technologies to handle the process. A majority of social media websites allow you to upload video files directly onto the site to share, although most of them require the files to be saved in specific containers. 

These websites will take your video file and transcode it before using their own systems and serves to re-encode it to match multiple display resolutions. This process will happen regardless of your video file's original codec and settings. Different websites have different processes, but companies that don’t have the capacity to build their own video encoding systems can use a third-party application programming interface (or API) to handle this process. These APIs act as [dedicated video encoder](https://api.video/encoding/) that allows companies to add on-demand videos to their websites more efficiently.

Using [api.video](http://api.video) as an example, all of the videos submitted to the platform will be transformed into H.264 codec in an MP4 container. This may be done using transmuxing and/or transcoding.

We expect the video bitrate to be lower than 16 Mbps for up to 1080p resolution and 50 Mbps for up to 4K resolution. We accept any bitrates, however, we will scale them down to the limits mentioned because anything above is usually challenging for most viewers’ connection to watch.

### API

The ability to generate, store, and distribute video is made possible via a video API. [api.video](http://api.video)’s solution can be tailored to suit any specific need. 

The backend process of video on demand (VOD) is exceptionally complex, even if you’re a software programmer specializing in video. It is necessary to encode, package, and typically transcode the data before sending it to any of several possible destinations. All of these things, and more, may be done with minimal fuss using api.video.

Our API basically keeps the complexities of streaming media hidden from view, so you can rapidly develop apps with as much control as you need. This saves time and effort so developers can concentrate on making the product.

## Conclusion

As you can see through this video encoding guide, a lot of work goes into making the video you watch and the video you share possible. Without video encoding compressing raw video footage, it could take days to upload and transmit video content over the internet and perhaps even longer to be able to download and enjoy them. 

The best part about encoding at api.video is that is offered at ZERO cost. You will only be charged for delivery and hosting of your videos, and the encoding will be free. Now integrate your videos in minutes with api.video or [contact us](https://api.video/contact) for more information.

A Guide to Video Encoding & Video Codecs

large_poster-3.png

medium_poster-3.png

small_poster-3.png

thumbnail_poster-3.png

poster-3.png

Erikka Innes

Encoding and transcoding are often used interchangeably but they have slightly different definitions. **Encoding is the initial process of converting raw video files into a specific digital format or codec.** It involves compressing and packaging the video data, often to reduce file size while maintaining acceptable quality. Encoding prepares the video for storage, transmission, or playback.

&nbsp;

**Transcoding, on the other hand, involves converting a video from one digital format or codec to another.** This is typically done to optimize the video for different devices or platforms, adapt to varying network conditions, or ensure compatibility with specific playback requirements. Transcoding occurs after encoding and often involves changing resolution, bitrates, or formats without altering the content itself.

## What goes on behind encoding a video?

It's easy to say that encoding is when you go from an _uncompressed source_ to a _compressed source_, but you may ask, what exactly do compressed and uncompressed sources mean?

&nbsp;

Uncompressed sources are video files that contain data that comes directly from a camera sensor vs. encoded video. In the digital space, it's SDI (Serial Digital Interface) or HDMI (High Definition Multimedia Interface). Both of them are popular standards. You'll find HDMI in places like your GoPro camera, or a mini camcorder. These days, you might also find HDMI in professional settings, but SDI is more common due to its reliability. Another example of an uncompressed source would be something analog, for instance, VHS tapes.

&nbsp;

A compressed sources, on the other hand, are video files that have undergone compression during the encoding process. Compression involves reducing the file size by removing unnecessary information or encoding the data in a more efficient format. This process results in a smaller file size, making it more manageable for storage, transmission, and playback.


## What are the types of transcoding methods?

There are three types of transcoding, depending on what you are trying to do to get a video to suit a particular browser, player, or platform:

* **Lossless-to-lossless** - This type of transcoding maintains the quality of your video across formats but allows you to take advantage of better hardware or compression algorithms. 
* **Lossless-to-lossy** - This type of transcoding will decrease your video in quality, but it will benefit you in ways such as – you will get a smaller and/or faster playing file, or a file that is compatible with the requirements of a particular platform, player, or browser.
* **Lossy-to-lossless** - Sometimes people think this means they are regaining quality. This isn't the case in this type of transcoding. If you transcode from a lossy format to a lossless format, all that it means is that you will not lose additional quality in the conversion process. You will not regain data you already lost through compression.

## Codecs for encoding and transcoding

For both encoding and transcoding, you will need to make use of codecs. A codec's job is to compress and decompress video files. It's right there in the name -  **co**mpress **dec**ompress or encode decode. So basically, codec is an algorithm that takes the video and shrinks it or changes it into a format that makes it compatible with the requirements of wherever you want the video to play. There are many codecs because there are many ways to compress a video or livestream for playback.



## What is transmuxing?

Now that you know the difference between encoding and transcoding, let's throw one more term in there - transmuxing. Transmuxing is when you change the container for a video instead of the format. It's a way of repackaging a video to make it compatible somewhere without changing what's in the file. 

&nbsp;

This process is faster than encoding or transcoding and takes less computing power because you only change the container, not the file. It's great when you need to quickly make something available, but the downside is that it doesn't handle things like making multiple video resolutions available. If you choose a container type that's incompatible with your video file, you may also cause compatibility issues, resulting in not being able to play the video.

## In closing

* **Encoding** - Encoding happens when you compress a raw data file from a video camera sensor or an analog source like a VHS tape. 
* **Transcoding** - Transcoding happens when you take an already compressed video file and change it to another format.
* **Transmuxing** - Transmuxing happens when you change the container of a video file but leave the video file untouched. 

We hope that explains the difference between encoding and transcoding clearly. 

_If you are looking for an affordable video API solution that does not burn a hole in your pocket for transcoding and encoding videos, check out our offerings on our [homepage](https://api.video/) or [sign-up for a free account here](https://dashboard.api.video/register)!_

Encoding and transcoding: what's the difference? 

Encoding and Transcoding - What's the Difference?

large_encoding-and-transcoding-whats-the-difference.jpg

medium_encoding-and-transcoding-whats-the-difference.jpg

small_encoding-and-transcoding-whats-the-difference.jpg

thumbnail_encoding-and-transcoding-whats-the-difference.jpg

encoding-and-transcoding-whats-the-difference.jpg

Once I upload my video, how quickly will it be ready to be viewed?

Our reply to this question has always been “it's really fast.”  And it is really fast. But, the dev team gave me access to the backend database, and pointed me to a few tables that might be helpful (thanks to Thomas Persohn for your patient help!)

Thus armed, I waded into a sea of data to better understand how fast our videos are encoded at api.video

## Encoding

When a video is uploaded to api.video, it is re-encoded to a HLS stream, with several different video dimensions and bitrates.  This allows api.video to deliver properly sized video to all users - no matter the device or network connection. (Read our post on [Responsive video delivery](https://api.video/blog/video-trends/responsive-video-delivery/) to learn more.)

> Summary:  All videos are encoded at 240p, 360p, 480p, 720p, 1080p and 2160p. However, the videos are only encoded up to the initial size of the video (so if the original video is 720p, there will not be 1080p or 2160p versions available). 

**FYI:** For our customers, encoding is absolutely free – we offer adaptive bitrate encoding at zero cost. 

How long does this step take? If a customer uploads a video to our service - they want to know how efficient api.video creates the content for viewing.

### Data in the study

We are constantly making adjustments to our infrastructure to speed the encoding step of our video (and that is one reason this post is dated 2H 2020 - we expect to be faster in early 2021). The last major adjustment was made in mid October, so the data presented in this study from every video uploaded to the api.video service between 15 October and 2 December 2020.

### Parameters that affect encoding

There are 2 major parameters that affect the speed of encoding a new video stream: the output dimensions and the length (duration) of the video.  

#### Dimensions

The output video dimensions have a huge impact on video creation - a 3840 × 2160 (or 4K or 2160p) video has millions more pixels than a 320x240 (240p) video, so it takes a lot longer to create.  In general, the videos exit the encoding process from smallest to largest.

#### Duration

If a video is 30 frames per second, and is 60 seconds long, there are 1800 frames to be created.  If a 30 frame per second video is an hour long 3600s), there are 108,000 frames to be created, so the longer the video - the more time for creation.

## Analysis

To better understand the encoding time, I divided the data by the size of the output video size, and looked at 2 lengths of video  - those under 5 minutes, and videos that are 45-75 minutes long (we are often asked how long a 1 hour video takes to encode).

I calculated encoding time for each bucket of video using percentiles.  

> Quick review - percentiles break the data into 100 evenly sized segments, so the 25th percentile is when 25% of the videos have been encoded. The median is the 50th percentile, and is when 50% of videos have been encoded.  We report here to the 95th percentile for video encoding.

### Short videos - under 5 minutes long

Many of the videos uploaded to api.video are short - under 5 minutes long.  These videos are generally ready to play in a few seconds:



The above chart has a lot of data, the 25, 50, 75, 90 and 95th percentile encoding times for all 6 variants of the video that api.video creates.

The median video is ready to play (at 240p) in 5.6 seconds, but a 720p version will be ready in 15s after encoding begins, and the 4K version will be ready in 37 seconds.

95% of all videos (under 5 minutes) will be playable in 32.6s, and will have 1080p versions ready in just over 2 minutes (140s).

### Long videos - 45 - 75 minutes long

Our most frequently asked question on encoding is "how long for a 1 hour video to be encoded and ready?"  Here are the numbers:


Observant viewers will see there are no 4K videos in this report. At this time, there are very few 4K streams that reach the 1 hour timeframe, and the data was quite noisy.  Hopefully, more of our 'long uploads' will add 4K support, so we can add this metric in our next update.

The median hour long video (red line) will be ready to play (at 240p) in just over 9 minutes (555s), and a 720p version will be ready about 18 minutes after encoding begins (1099s).

95% of hour long videos will have a 240p version ready in 33 minutes, and 720p in 54 (3230s).  the 1080p version will be available for 95% of videos in 108 minutes,

## Conclusion

Short videos will be ready to play - even at high resolution - in under a minute: the median 4K encoding for a short video is 37s. 

Hour long videos take longer to encode, and the median 720p video will be ready in 18 minutes.  95% of 720p videos will be ready to play in 54 minutes.

This is really fast! You can have responsive streaming video ready for your customers in just a few minutes with a simple upload!

That said, our team is working hard in the background to improve our infrastructure to make our encoding speeds even faster! 

We're really excited to have hard numbers to share with you on our encoding speeds, and we cannot wait to re-benchmark this data in 2021 to see how much faster your videos will be encoded as we improve our service.

Do you have questions about api.video or video encoding? Reach out on our [community page](https://community.api.video).


How fast does api.video encode video? 2H 2020 data

medium_gif.jpg

small_gif.jpg

thumbnail_gif.jpg

gif.jpg

Huge pricing update! Introducing video encoding at zero cost

Featured article

# api.video blog

Blog

Follow the api.video Blog to explore tutorials, video use cases, and learn about on-demand and live-streaming video updates.

Video on demand

Live streaming

Analytics

See all features

Online learning

Short-form videos

Marketplace & E-commerce

Video messaging and recording

Quick start guides

Documentation

Ecosystem catalog

Clients & SDKs

Community

Blog

Demos

Help center

Blog

Huge pricing update! Introducing video encoding at zero cost