webhooks

Analytics

Normal

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

Tutorials

JavaScript

NodeJS

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://go.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

screenshot-2021-07-22-at-06-12-10.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://api-video.doctave.dev/delivery-analytics/analytics). 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

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://api-video.doctave.dev/delivery-analytics/analytics) 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/reference/get_analytics-sessions-sessionid-events) 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

Product updates

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.





a sample chyron from a new story (with a pun on underwear).

small_boxers.jpeg

thumbnail_boxers.jpeg

boxers.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

screenshot-2021-05-25-at-06-50-01.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

screenshot-2021-05-25-at-07-50-14.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_1024px-watermarksample.jpeg

medium_1024px-watermarksample.jpeg

small_1024px-watermarksample.jpeg

thumbnail_1024px-watermarksample.jpeg

1024px-watermarksample.jpeg

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!


Sample apps using api.video: a.video

large_screenshot-2021-04-14-at-22-23-49.png

medium_screenshot-2021-04-14-at-22-23-49.png

small_screenshot-2021-04-14-at-22-23-49.png

thumbnail_screenshot-2021-04-14-at-22-23-49.png

screenshot-2021-04-14-at-22-23-49.png

Video upload


With the explosive growth of remote working in the past year, we’ve all worked to find different ways of communicating. Slack and Zoom have become major tools for communication as we are all no longer in the same building or office.  

Apps like Clubhouse have become ‘places’ to go and hang out and chat with others.

One app that has featured explosive growth over the past year is Loom. Loom is an app that lets you record short video messages - sharing your screen or just using your camera. When you are done, the video is saved on a server, and you are given a link.  This link is easy to share: on social media, on Slack etc. It is a great way to communicate an idea, or to express your point - it’s everything that is great about video, packaged in an easy to use interface.  

It is no wonder that Loom is so successful.  My only issue is that I either have to use an installed app on my Mac (265 MB installed), or a Chrome extension (I did not go this approach, as Chrome eats too much memory already).

## Can I build a Loom-like app - in the browser?

I lead developer relations at api.video.  We offer a full service API for video transcoding, hosting and delivering video streams.  It is incredibly fast, and can be used to share videos in the same way Loom does.  So this raised 2 questions:

1. If I delegate the ‘hard’ bits of the video handling to api.video, can I build a recording app in the browser? 

2. Can I get this app running in all four major modern browsers?  Desktop & mobile?

TL;DR:  

Question 1: Yes - you can build a website to record and share video (screen sharing and camera video). It will even stream live video!

Question 2: Almost all browsers.  On the desktop, the full featured app works great in Chrome, Edge Firefox, and Safari 14.0.3 (there are some support issues that will fail below Safari 14).  

For Mobile: it works on Android (without screen sharing). Unfortunately, the APIs used are not yet in mobile Webkit, so no iOS support at this time.

Try it out! The application is live at [record.a.video](https://record.a.video). You can also check out our [live stream API reference documentation](https://docs.api.video/reference/api/Live-Streams#list-all-live-streams).

## How does it work?


large_screenshot-2021-03-26-at-11-13-30.png

medium_screenshot-2021-03-26-at-11-13-30.png

small_screenshot-2021-03-26-at-11-13-30.png

thumbnail_screenshot-2021-03-26-at-11-13-30.png

screenshot-2021-03-26-at-11-13-30.png

When you open [record.a.video](https://record.a.video), you'll get a menu as above. (You may not get the available cameras and microphones - press "start capture" and allow camera/microphone permissions, then reload the page).

* The top bar allows you to switch between Live streaming and recording a video.
* Choose your camera and mic (if you have more than one).
* Select the screen layout - do you want to show just the camera or screen, or do you want to overlay the camera on the screen?
* Live captions:  If you are using Chrome, we can add live captions to the video being created.  Pick top or bottom for the captions.
* "Show recording" if you leave this checked, you'll see the video being recorded in the browser.  Our CEO dislikes the "vortex effect" you see when sharing the screen, so we added this button for him to disable the view. (👋 Hi Cedric!)

Now that you've chosen all your options, you're ready to start capture!

### Recording

Once you've started recording, you'll see 3 new views appear:

* The screen being shared
* The camera
* The recording (showing screen, camera or both). (Unless you hid the recording).


small_screenshot-2021-03-26-at-11-22-05.png

thumbnail_screenshot-2021-03-26-at-11-22-05.png

screenshot-2021-03-26-at-11-22-05.png



## Record and stream right from your browser!

So it works!  Recording your screen and camera in the browser with live streaming or recording and uploading for asynchronous viewing.  

What completely blows my mind about this application is that leveraging web APIs, this site weighs in at just under 300KB.  There is a NodeJS backend to handle the streaming (we have to convert the format to RTMP for ingestion into api.video), but if you remove the live streaming component, this app runs with just JavaScript (you can even run it locally on your computer!)

## See it in action

##  Curious about the details

I'm really glad you asked!  We've written a series of posts describing the APIs used to collect video streams, how they were cpmbined, and how they are streamed:

* In [post 1](https://api.video/blog/tutorials/grabbing-camera-streams-with-mediadevices-getusermedia/), I talked about the getUserMedia API to record the user's camera and microphone.

* In [post 2](https://api.video/blog/tutorials/building-record-a-video-the-screencapture-api/), I discussed recording the screen, using the Screen Capture API. Using the video streams created in posts 1 & 2, I draw the combined video on a canvas.

* In [post 3](https://api.video/blog/tutorials/building-record-a-video-the-mediarecorder-api/), I'll discuss the MediaRecorder API, where I create a video stream from the canvas to create the output video.  This output stream feeds into the video upload (for video on demand playback) or the live stream (for immediate and live playback).

* In [post 4](https://api.video/blog/tutorials/building-record-a-video-using-the-webspeech-api-for-live-captioning/), I'll discuss the Web Speech API. This API converts audio into text in near real time, allowing to create 'instant' captions for any video being created in the app. This is an experimental API that only works in Chrome, but was so neat, I included it in record.a.video anyway. 



## Conclusion

Record.a.video lets you easily record and share video - live or asynchronously! 


Go give it a shot [record.a.video](https://record.a.video), and if you want to build your own - the code is on [Github](https://github.com/apivideo/recordavideo). In the coming days, we’ll add some technical posts describing how we built it.

If you have any comments or suggestions, please leave us a note in our [community forum](https://community.api.video). 


Building "Loom" in the browser: record a video with api.video

large_loom-app.png

medium_loom-app.png

small_loom-app.png

thumbnail_loom-app.png

loom-app.png

## Webhooks

We're super excited to begin rolling out webhooks as a part of api.video. Today we have released our video on demand (VOD) encoding webhook. 

## What are webhooks

Webhooks are callbacks that announce when something has occured (pushing data to you), rather than having to ask whether an event has occurred (polling data from the server).


small_2247608175268b5d4f7o.jpg

thumbnail_2247608175268b5d4f7o.jpg

2247608175268b5d4f7o.jpg

The classic polling interface is children asking "are we there yet?" every few minutes from the backseat of the car.

The classic "pushing" of notifications is your phone telling you when you have a new email message. Your phone is not asking every minute, but the server tells your phone that an email has arrived.

Polling takes more energy - as both sides have to keep asking for data, and depending on the polling interval, can add delays to the process. Pushing data delivers the needed data as soon as it is available - using fewer resources to deliver more timely data.


## Polling for video encoding complete

Before webhooks were launched, you had to poll the [video status](https://docs.api.video/reference/api/Videos#retrieve-video-status-and-details) endpoint to know when a video was ready for playback. The ```encoding.playable``` result tells us if one version of the video is ready (typically a low quality version), but if you wanted to wait until a higher quality, like 720p video was encoded, you could look at that size to see when the encoding was completed.

## Webhook encoding events

Our first webhook is the ```video.encoding.quality.completed``` which pushes a message for each quality of each video has been encoded.

For example, when a recently uploaded video was encoded, the webhook received several webhooks: one for each version.  Here is an example:

```
{ type: 'video.encoding.quality.completed',
  emittedAt: '2021-03-23T17:03:39.908Z',
  videoId: 'vi7DWgHCu29smlHThpzEajfs',
  encoding: 'hls',
  quality: '720p' }
```

This tells us that this videoId was encoded as HLS at 720p.  


### Usages

* **Track uploads**: If you allow users to upload videos, you can track every videoId uploaded every day.
* **Display in your app**: Perhaps you only want to display a video when the 720p (or 1080p) video is ready (240p is great, but can be really fuzzy).  You can now use these webhooks to decide when a video can be pushed live.
* **Send your mp4 for analysis**.  Perhaps you would like to do further processing with the mp4 (to add captions, or to performa video moderation). Now, when the webhook alerts you that it is ready, you can begin that secondary processing.

## API calls

[Create webhook](https://docs.api.video/reference/api/Webhooks#create-webhook)
[List webhooks](https://docs.api.video/reference/api/Webhooks#list-all-webhooks)
[Get webhook](https://docs.api.video/reference/api/Webhooks#retrieve-webhook-details)
[Delete webhook](https://docs.api.video/reference/api/Webhooks#delete-a-webhook)

## Limitations

* Today, we allow you to have 3 webhook endpoints.  We may allow for more endpoints in the future.
* Each webhook event is sent 3 times. If it fails 3 times, no further attempts are made to deliver the message.
* There is no tracking or history of webhook notifications.
* There is no authentication or certificate validation at this time.

## Live demo

[Webhook a video](https://webhook.a.video) displays encoding events when a video is uploaded. It is connected to the [upload a video](https://upload.a.video) application, so if you upload a video there, you'll see the encoding events in the webhook application.

small_screenshot-2021-03-23-at-17-59-28.png

thumbnail_screenshot-2021-03-23-at-17-59-28.png

screenshot-2021-03-23-at-17-59-28.png

In the screenshot above, you can see multiple encoding events have occurred: for several different videos.  It shows the webhook event, the date & time, the videoId, and the format and size of the encoding.

Rather than display these results, your application can base it's internal logic on these events.

## Conclusion

We're excited to begin launching webhooks, with the first being VOD encoding events. We'll next be working on live stream webhooks, so look for that coming in the near future.

If you have any comments about our webhooks (or any other feature you'd like to see, please leave a post at out [community forum](https://community.api.video).


New feature: Webhooks

codec

video create

small_cedric.jpeg

thumbnail_cedric.jpeg

cedric.jpeg

Cédric Montet

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

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