Analytics

Normal

medium_screen-shot-2021-01-26-at-11-48-47-am.jpg

small_screen-shot-2021-01-26-at-11-48-47-am.jpg

thumbnail_screen-shot-2021-01-26-at-11-48-47-am.jpg

screen-shot-2021-01-26-at-11-48-47-am.jpg

Erikka Innes

Tutorials

Python

JavaScript

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

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

Let's start mapping! 

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

medium_apivideomapmarkerslivestream.jpg

small_apivideomapmarkerslivestream.jpg

thumbnail_apivideomapmarkerslivestream.jpg

apivideomapmarkerslivestream.jpg

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

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

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

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

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

Here's the code:

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

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

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

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

Now we're ready to build our map. 

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

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

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

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

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

Use api.video Analytics to mark viewer density with Observable

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

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

medium_examplechoroplethapivideo.jpg

small_examplechoroplethapivideo.jpg

thumbnail_examplechoroplethapivideo.jpg

examplechoroplethapivideo.jpg

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

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

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

Let's start coding! 

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

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

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

Here's the code we used to: 

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

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

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

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

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

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

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

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

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



choropleth, apivide, api.video, data analytics

medium_choroplethapivideo.jpg

small_choroplethapivideo.jpg

thumbnail_choroplethapivideo.jpg

choroplethapivideo.jpg

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

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

 Build a Choropleth Map with api.video Analytics

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

analytics data, apivideo, api.video, video and live stream analysis

small_analyticsdataapivideo.jpg

thumbnail_analyticsdataapivideo.jpg

analyticsdataapivideo.jpg

You may want to grab analytics data from api.video and then visualize it different ways. Today we'll take a look at the data you can use, what that data looks like, and the code snippets for data retrieval. api.video has three sets of analytics you can collect: 
* Video on Demand Session Analytics
* Live Stream Session Analytics
* Player Session Analytics 

Everything is set up so you can pull details at a granular level - so for each request to the API, you would choose the video, live stream, or player you want details about, and send an individual request for information about that that asset. If you want to pull data for an individual asset, or multiple assets, the first thing you need to do is get a list of those assets. 

You can also see a fun project using api.video analytics data over at Observable. We made a [notebook that shows where all our live stream viewers watch from](https://observablehq.com/@erikkai/where-api-video-live-streams-are-watched).

## Get All Videos, Live Streams, or Players 
The first step in using your analytics data, is to find out what you have available to analyze. You're going to want to know what videos, live streams, and players you have. 

1. Authenticate with your API key and get a token. 
2. Use the token with the [List all videos](https://docs.api.video/reference/api/Videos#list-all-video-objects), [List all live streams](https://docs.api.video/reference/api/Live-Streams#list-all-live-streams), or [List all players](https://docs.api.video/reference/api/Player-Themes#list-all-player-themes) endpoint to get all listings for everything in that category. 

The code for this part looks like this: 

In this sample, we went through every endpoint and got a complete list of assets. Then, so we don't have to keep going back to the API for this information, we output each set of details to a .json file. You probably won't want to necessarily save this, but for learning or browsing, it's great to be able to open the file and see this data you'll be working with. If you want to experiment with retrieving data from these files and converting to different formats, these can be helpful. 

### Data Structure for a Live Stream 

If you were to retrieve a single live stream, it would contain the data shown here, and a pagination section in case you have so many entries you need to retrieve multiple pages of asset listings.

### Data Structure for a Video 
As with live streams, if you were to retrieve a single video, it would contain the data shown here. Notice there's a ton of videos - 608 to be exact, and the pagination section provides details for grabbing additional pages of data so you can get an exhaustive list of all assets if you need it.  


Test create video

### Data Structure for a Player 
For players you get details about how each one is customized. It has the same pagination feature as the other data structures. Because you don't use this information to retrieve session details, it's more for informational purposes only if you wanted to know about the players you have.

## Retrieve Sessions 
The next part of retrieving your data is to grab session information. Because the analytics endpoints are set up to be granular, you need the unique live stream, video, or player ID to use with the associated endpoint. Then you can retrieve details about all sessions for that endpoint. Live stream and video sessions come back using the same structure. Players are different (as you'll see). 

The code to retrieve details about one asset for video or live stream would be: 

### Data Structure for Live Stream and Video 
Live streams and videos bring back information with the same format. Something to remember is when the information comes back, it will not include the title of your live stream or video, or its type. If you were to get back one single session for a live stream or video, it would come back like this: 

Chrome

Mac OS X

### Data Structure for Player
Because you are reviewing session details on a player for a particular video or live stream, you may want to note this in your data at some point. The returned data for a session doesn't include details about what video or live stream it's for beyond repeating the session ID in the pagination URLs.

## Tips for Handling Data 
This section includes some tips for handling your analytics data. 

* It will be easier if you know what you want to do at the start so you can retrieve appropriate information for your project. 
* When creating a file to work with, remember that flattening the JSON makes your project easier. Flattening the JSON means that you undo the nesting for each entry, so that everything for each is in a single row. 
* You may want to add extra details when you retrieve informat for an asset, like a column for the title. If you mix your live stream and video data to get big picture analytics data, you may want to have another column that lists whether something is a live stream or video. Otherwise, you don't have a way to retrieve that information later.
* If you don't know what you want to do, you may want to design a way to gather all the data together. One way is to put live stream and video data into a table, and then join that table to a player table based on session ID. This would be a way to build a master file of your data. 

Tips for working with api.video analytics data

Live - Upload a Thumbnail

A beautiful and engaging video thumbnail can help describe what your video  or live stream is about and attract viewer interest. If you have ideas for a thumbnail for your live stream, but you aren't sure how to add it, the api.video API provides an easy way to include one. Let's get coding!

## Prerequisites:

* Python
* Account with [api.video](https://api.video)
* Live stream equipment like a camera, phone camera, web cam or similar (this tutorial uses the Mac's built in web camera) 
* Thumbnail you want to use - thumbnail must be .jpg or .jpeg and 8MB or smaller

## What you'll be doing
This tutorial walks you through everything you'll need to add a thumbnail, including setting up a live stream if you didn't already do that using [another tutorial](https://api.video/blog/tutorials/live-stream-to-the-browser-with-ffmpeg-cli-and-python/) or our [API reference documentation](https://docs.api.video). The steps are: 

1. Set up a live stream if you don't have one.
2. Retrieve the Live Stream ID so you can make changes to the thumbnail.
3. Add your thumbnail. 

## Add a live stream
To add a live stream to api.video, you create a container for the live stream, and then send your stream to it to be played. In this tutorial, we're focused on making updates to the container. If you want to actually stream, see one of the other tutorials on the topic. 

The code sample for setting up the live stream container is: 

You might recognize this code sample from the tutorial ["Live Stream to the Browser with FFMPEG CLI and Python"](https://api.video/blog/tutorials/live-stream-to-the-browser-with-ffmpeg-cli-and-python/). 

## Retrieve live stream ID 
There are two ways to retrieve the live stream ID from your live stream:

* Look in the dashboard
* Send a request to api.video for a list of live streams 

### Look in the dashboard
This is a no-code way to get the live stream ID: 

**No-Code Method for Getting the Live Stream ID**

1. Open the api.video dashboard. 
2. Click **My videos**. 
3. Click **Live**. 
4. Click the live stream you want to add a thumbnail to. 
5. On the live stream's details page, under **Copy code**, grab the live stream ID from the end of the link there. It should be whatever comes after **live/**. 

**Get the Live Stream ID with Python**
You can retrieve all live stream IDs with Python and then sort through them for the live stream you wanted. If you have some information to start with, you can tweak this script to bring back live streams with attributes that match what you want. Here's the code sample for retrieving all live streams:

In our code sample, we authenticate with our API credentials, then retrieve an access token. The token is good for one hour. Next, we send a request to the live streams endpoint asking to retrieve all live streams, and print them out in the console. 

You can look through what's returned to find your live stream or write additional code to retrieve and handle a specific live stream. The sample is to help get you started. 

When you locate the live stream you want to add a thumbnail to, save it for the next step. 

## Upload a thumbnail 
We're going to use the thumbnail endpoint for live streams. Place your thumbnail image in the same folder as your script. Here's the code:  

Notice the code sample continues from after the first sample listed - so we assume you have your token for use authenticating with the live stream thumbnail endpoint. To make the code sample easy to follow, we also assume that you've retrieved the live stream ID you want and it's listed as the variable **live**. 

To access a specific live stream and upload a thumbnail to it, you have to include the live stream ID in the endpoint. We build the endpoint with the line: 
```url = 'https://ws.api.video/live-streams/' + live + '/thumbnail'```

To add the image, you need to append it with this code: 
``` files = { 
    'file': ("image1.jpg", open("image1.jpg", "rb"))
} 

```

You open the file using a dictionary that contains a tuple and then add it to your request. 

If you successfully make the upload, you'll get back something that looks like this: 

```{
	"liveStreamId":"yourliveStreamId",
	"createdAt":"2021-03-05T09:25:10+00:00",
	"updatedAt":"2021-03-18T05:49:54+00:00",
	"streamKey":"7337t9e0-82d3-4258-b497-489648e10444",
	"name":"Live Stream Title",
	"public":true,
	"record":false,
	"broadcasting":false,
	"assets":{
		"iframe":"\u003Ciframe src=\u0022https://embed.api.video/live/yourliveStreamId\u0022 width=\u0022100%\u0022 height=\u0022100%\u0022 frameborder=\u00220\u0022 scrolling=\u0022no\u0022 allowfullscreen=\u0022true\u0022\u003E\u003C/iframe\u003E","player":"https://embed.api.video/live/li1rVQ9RmyvQ2R4ae57KeEm5",
		"hls":"https://live.api.video/yourliveStreamId.m3u8",				   "thumbnail":"https://live.api.video/yourliveStreamId/thumbnail.jpg"
	}
} 
```

## Check the thumbnail
To check if your thumbnail is there, go into the live streams section of your dashboard, and see if your live stream displays it. 

## You may also like... 

* [Upload a Big Video File Using Python](https://api.video/blog/tutorials/upload-a-big-video-file-using-python/) - Upload a file over 128MB using Python.
* [Start and Record a Live Stream of Your Zoom Meeting](https://api.video/blog/no-code/start-and-record-a-live-stream-of-your-zoom-meeting/) - Add a live stream to your Zoom meeting to broadcast to more people and save a high quality HLS recording for playback later.
* [Live Stream to the Browser with FFMPEG and Python](https://api.video/blog/tutorials/live-stream-to-the-browser-with-ffmpeg-cli-and-python/) - Set up a live stream using api.video, Python, and the magic of FFMPEG. 

How to add a thumbnail to your live stream

live stream, captivating thumbnail, upload a thumbnail

medium_jean-paul-balech-c0s288tt79w-unsplash.jpg

small_jean-paul-balech-c0s288tt79w-unsplash.jpg

thumbnail_jean-paul-balech-c0s288tt79w-unsplash.jpg

jean-paul-balech-c0s288tt79w-unsplash.jpg

live - create

Let's learn how to live stream using the FFMPEG command-line interface for Mac and Python, then write a program that will do everything for us in Python. For the camera and audio, we'll use what's built-in to your Mac. You can attach another camera if you want, this tutorial should help with figuring out how to do that too. We recommend trying this tutorial as-is first. And then...

<center><iframe src="https://giphy.com/embed/26BRrxbIBrDJ3jq5G" width="480" height="360" frameBorder="0" class="giphy-embed" allowFullScreen></iframe><p><a href="https://giphy.com/gifs/producthunt-live-stream-livestreaming-opeah-26BRrxbIBrDJ3jq5G"></a></p><br></center>

## Requirements

* Mac (as always, you can tweak the instructions for Linux or PC but it's a Mac focused tutorial) 
* Homebrew - if you don't have it we'll include a little about installing it
* Xcode - you can add this as part of a homebrew installation 
* api.video account - you can get one for FREE right here - [SIGN UP](https://dashboard.api.video/)
* Python
* requests module for Python
* ffmpeg-python 
* OSX10.7 or higher

You can also check out our live stream API reference documentation here: [Live stream](https://docs.api.video/reference/api/Live-Streams#list-all-live-streams)

## Install FFMPEG

Sometimes an FFMPEG install can get complicated. You'll see a lot of people online asking why their installation doesn't work. If you have a Mac, there is an easy answer to this problem...hopefully. Let's go over one simple way you can install FFMPEG so it starts working at the command line for you right away. We're going to use the homebrew method, because it makes installation simple if you already have homebrew installed. 

### For users who already have Homebrew
If you've got homebrew installed, all you need to do is this: 

```brew install ffmpeg```

That's it. It should install without issue. (Famous last words right?) Test that it works with this: 

```ffmpeg -version```

If it's installed, you will get back a bunch of information about your configuration. If not you will get an error of some type. Troubleshooting installation is beyond the scope of this tutorial, but you can post questions in the [community forum](https://community.api.video/) and we'll help you figure it out.

### For users who don't have Homebrew
If you fall into this category, you may be wondering what homebrew is. It's a free, open-source software package manager. It simplifies installation of software on macOS and Linux. 

To install homebrew, you'll need to run this command: 

```/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"```

If you don't have Xcode, or the appropriate Xcode components installed, you'll have to install those. Fortunately, you'll be told what's missing so you can install it. Follow the instructions to install and if you run into problems, there is a lot of documentation online to help you through. We can't be more specific for Xcode, because there's a lot of ways your installation can differ from another one. However, if you need help, feel free to contact us in the [community forum](https://community.api.video/). 

## Let's use FFMPEG CLI and Python to live stream
Now that we have FFMPEG installed, let's try using it to set up a live stream.   

1. Let's set up the container for our live stream. With api.video, you create a container for your live stream, then you send your stream to it to be played. The code for this is: 

2. Now that we have our container, open the api.video [dashboard](https://dashboard.api.video) and click **My Videos**.
3. Click **Live**. You should see your livestream (mine's named Bob) here. But it's not working yet. That's okay, we're going to change that. Click on the picture representing your livestream.
4. You'll see some information about your livestream. The information we're interested in, is the RTMP Stream Url. Go ahead and make a note of that and leave the dashboard open - we're going to add that url into our script.
5. Open a Terminal window. 
6. Let's list the available video and audio devices on your Mac using FFMPEG. At the CLI prompt, type: 
```ffmpeg -f avfoundation -list_devices true -i "" ```
This will list all the devices available to you. You should see something similar to this: 

``` 
[AVFoundation indev @ 0x7fed75d21fc0] AVFoundation video devices:
[AVFoundation indev @ 0x7fed75d21fc0] [0] FaceTime HD Camera (Built-in)
[AVFoundation indev @ 0x7fed75d21fc0] [1] Capture screen 0
[AVFoundation indev @ 0x7fed75d21fc0] AVFoundation audio devices:
[AVFoundation indev @ 0x7fed75d21fc0] [0] Built-in Microphone 
```

So you might be asking what's going on here? Let's go over the command. First, you're telling the system that you're using the ffmpeg CLI by saying 'ffmpeg.' Then your script says for our input file format (-f) use the framework avfoundation and list available devices. We know it's for the input file because of the -i flag. There's more to this explanation, but it's a little outside the scope of this tutorial. Without getting too into the details here, the device is your input instead of a file. When you run the script a list comes back and it shows you two arrays. One array is for video choices, and one is for audio. Note the number for each item you want to use. For this tutorial we're going to use 0 and 0.    

7. And now for the script. Type: 
```ffmpeg -f avfoundation -framerate 25 -i "0:0" -f flv rtmp://broadcast.api.video/s/streamKey``` 

We have a few things going on in this script. We start by telling the system we want to use the ffmpeg command line, then we provide information about our input "file" (camera and audio in this case). We say for the input file format -f we want to use the AVFoundation framework (avfoundation) at framerate (-framerate) 25. And we mention it's for input here too (-i) and what kind of input with "0:0." If you're like what the heck is "0:0" you're in good company. This is basically a key value pair for the video and audio. Think of it like "video:audio." And what you did, is you said for video use what's in slot 0 of the video choices array. For audio use what's in slot 0 of the audio choices array. You can also use just the first word of each item in the array, typed exactly the same way. That would look like "FaceTime:Built-in." Finally you say for your output file format (-f) you want to send the format of flv (flv) to the RTMP server with your stream key. That's where it will be turned into beautiful HLS and streamed for you. 

If you've seen FFMPEG before, you might wonder where the codecs are. You can add them in to your script, but for the sake of simplicity they're excluded here. By excluding them, your system will choose what it thinks are the best codecs. You can see what was selected, and then manually include them in your script if you feel like it. This can be a good way to test that you understand where to put the codec flags in your script. After that works, if you don't like a codec you can trade it out for something else and see if it runs better (or in some cases at all, codecs are finnicky). 

At this point, if your script is running, you have a bunch of choices available to you: 

* You can grab the embed iframe information and add the live stream to a web page.
* You can grab the embed link and add it to a page, or just put it in the browser search bar and open it to play there. 
* You can associate it with a player. 

8. It won't stop running! That's okay, you have two choices here. You can click on the Terminal window and press **q** or you can use **CTRL-C**. 

If you want to try running this entire process programmatically, read on! 

## Run ffmpeg CLI with ffmpeg-Python
This is a pretty cool Python module. It's a wrapper for your CLI commands, meaning you can run everything using a Python file. We're going to need it for this next code snippet. 

1. Install ffmpeg-python. It's a little confusing because the install command looks different than the module title. On the command line, install with: 
```pip install ffmpeg-python```

NOTE: Don't mess up and try installing ffmpeg. It will install something, but in our case, not something useful.

2. In your code sample, make sure you add import ffmpeg. 

3. And now the code sample: 

The code sample will authenticate, grab a token, set up the container for your livestream, fetch the livestream key and build your server URL, then start up your live stream. It prints out the iframe embed code and the live stream link. You can take the iframe code and paste it into an HTML page for viewing or you can use the live stream (player) link and put it in your web browser. Press play and you're streaming! 

## Clean up on Aisle 9 - Delete Your Live Streams
After trying the code sample a few times, you may have a bunch of live streams when you only wanted one or two. 

You can remove the live streams one at a time with this code: 

Note that the liveStreamId is not the stream key. It's the value that shows at the end of the player link. This is an example player link: 
```https://embed.api.video/live/li6pLlinklOtQ6aK6u7Ktc6N```

Add the part that comes after 'live/' after 'live-streams/' in the code sample and send your request. The live stream will be deleted for you.

Thanks for reading today! If you have any questions, suggestions or trouble setting this up, please contact us in the [community forum](https://community.api.video/). We can include troubleshooting content based on issues you run into. 

Live stream to the browser with FFMPEG CLI and Python

large_live-stream-ffmpeg-cli-and-python-1.png

medium_live-stream-ffmpeg-cli-and-python-1.png

small_live-stream-ffmpeg-cli-and-python-1.png

thumbnail_live-stream-ffmpeg-cli-and-python-1.png

live-stream-ffmpeg-cli-and-python-1.png

Live stream to the browser with FFMPEG CLI and Python 

Player

No-code

Today we'll use OBS (Open Broadcaster Software), the api.video API, and Python to set up a live stream! A common interest people have right away is being able to live stream straight from the browser. If this is something you need, you'll want to check out this demo - [livestream.a.video](https://livestream.a.video/) - instead of this tutorial. There are various reasons that live streaming from the browser isn't common, but explaining why is beyond the scope of this tutorial. So if you're ready, onwards! Let's set up our own live stream!

A quick note before we get started - you can create and view your live stream without doing any coding. However, at the very end, if you want to add your live stream to your own custom web page, you do use a tiny bit of code. It's an extra step you can take if you want. Otherwise stick with the other sections for a no-code experience!

If you are interested in the coding aspects, you can check out our [live stream API reference documentation](https://docs.api.video/reference/api/Live-Streams#list-all-live-streams).

## Prerequisites
For this project you'll need:
- OBS - we will install as part of the walk through, so don't worry if you don't have it yet
- api.video [account](https://dashboard.api.video/register) and API key (for this tutorial, we're using the production key, which requires a paid account - but everything will work with your sandbox key if you prefer)
- Mac - you can also use a PC, but this tutorial is geared towards a Mac so you'll need to make adjustments as needed
- Video camera - if you have a Mac, we'll use the built-in camera. If you don't have something built in, you'll need to have something else available and it will probably require a bit more set up than what's described here. Ask our [community forum](https://community.api.video/) for help.
If you've got your prerequisites in order, let's get started!

## Create a player and a live stream
We'll want a player for our live stream, and you'll also want to associate your player with your live stream when we create the live stream. You don't have to use an api.video player if you don't want to, but for the purposes of the walk through, we will.

16. Log in to your api.video account.
17. At the top of the dashboard, click My videos. You're taken to go.api.video.
18. At the top of the screen, click Players. You're taken to the Players screen.
19. Click the +Add Player button. You're taken to the Add a player screen.
20. You can choose how you want to configure your player here, from choosing colors for the different parts of the player, to details about whether the player is accessible via API and more. For our walk through, leave the settings to their default arrangement. Click Save player.
21. Make a note of the player ID or leave this screen open while we work on other parts of the project.
22. Go back to the dashboard, which is the screen you first see when you log into your api.video account.
23. At the top of the dashboard, click My videos. A screen offering tabs for Videos, Live and Players opens.
24. Click Live.
25. Click Create a live stream. The Edit a live stream screen opens.
26. In the Name field, put a name for your live stream. I'm going to call mine 'Bob.'
27. Leave Player id blank.
28. Click Save livestream. What we've done, is set up our live stream. We can't use it just yet, but we're almost there.
29. Click on the live stream you just created. You'll be able to see all kinds of details about the live stream. We're going to need a few pieces of information from this screen, so leave it open. Of particular importance is the Stream key and the RTMP Server Url. Leave this page open, and let's get OBS ready.

## Install and configure Open Broadcast Studio
Now we need to set up OBS so we can get our live stream.

34. Navigate to obsproject.com.
35. Choose the product appropriate for your operating system. This tutorial will focus on the mac version. Click macOS 10.13+.
36. Install the dmg file, drag the icon over to applications, and open OBS.
37. When you open OBS for the first time after installation, it offers a configuration wizard. This wizard doesn't reappear on its own again, but it can be accessed by clicking Tools at the top of the screen and choosing Auto-Configuration Wizard. (We are going to use the wizard, because it does some configuration for you that's useful if it's your first time using OBS.)

large_obs.png

medium_obs.png

small_obs.png

thumbnail_obs.png

obs.png

5. Whether you opened automatically on the wizard, or you clicked **Tools** and chose the wizard, the next step is to choose how you want your OBS set-up optimized. Because we're going to do live streaming, choose **Optimize for streaming, recording is secondary**.
6. Click **Next**.
7. The wizard shows you some settings it's selected for you. Leave them as-is and click **Next**.
8. Now it's time to add your stream information. We left the api.video dashboard open on the page where you set up your live stream. Go back and grab the server information **rtmp://broadcast.api.video/s**. Enter that in the **Server** field in the OBS wizard.
9. Retrieve the stream key from the api.video dashboard and enter that in the **Stream Key** field in the OBS wizard. Leave the dashboard open, we'll be coming back again.
10. Click **Next**. You'll be notified that a bandwidth test is about to start. Running the test is a good way to optimize your configuration, and make sure you can contact the api.video rtmp server. 
11. Click **Yes**. A screen that looks like static will appear behind the wizard. You'll see information presented as OBS completes different test results. The final output will tell you the settings you should use for your system. For this walk through, accept the suggested settings. You can manually set them later if you want something different.
12. Click **Apply Settings**.
13. Before we move on, you may have had the experience where you couldn't connect to the api.video server. If this happens, often the problem is that OBS is being blocked by a firewall, or similar issue. Some things to check are your VPN settings, any firewall settings that are directly on your computer or network, and any firewall settings that might be on your router. We can't specifically list steps to take to solve this because all set ups are different. If your issue happens to be on your router, you need to log in and figure out how to change security to allow OBS through.

## Create a Source
Now we need to configure what we'll be streaming from. For simplicity's sake, we're going to use the built-in camera that comes with your Mac. If you have a PC or another reason that you want to use a different camera, you'll have to connect it and tweak these steps as needed to continue. 

1. Under Sources, click the **+** button. 
2. Choose **Video Capture Device**. You'll get a pop up asking if you want to create a new device.
3. Choose **Create new** and name your device. 
4. Click **OK**. 
5. Choose your device from the Device drop-down. For this walk through, it will be **FaceTime HD Camera (Built-in)**. If it's working, you should immediately see what the device sees. If you are using a different camera, make sure it's on, and you are able to see what it sees through OBS. 

## Start Streaming
It's time to start streaming! 

1. Click **Start Streaming**. If it's working, it'll switch to saying 'Stop Streaming.' You'll see streaming health at the bottom of the screen - how many kb per second, and a square that's either green, yellow, or red. Green is healthy and means things are going well. Yellow means things have slowed a bit, and Red means things have slowed a lot. 
2. To check out your live stream, go to the api.video dashboard and press the **Play** icon on your live stream. If all goes well it should start up! 
3. If you like, you can now add the embed link or iframe to a web page and watch your stream that way. You can also open the stream as a link in the browser and watch it there! 

## Stream in Your Own Web Page with a Player
If you want to generate your own web page to stream in, we'll use a tiny bit of Python code and HTML. 

Here's the code sample:

To run this, we've used a sample web page from [here](https://http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/webtemplates.html).

What the code is doing, is building a web page from a string. You pass a string that consists of the HTML code you need for a simple web page to the function browseLocal. In browseLocal, you write the string to a new html file, import what you'll need to present a web page, then open the web page by opening your new html file. The strToFile function is used to write the string to the html file you open. Cool huh? 

This is it for live streaming today. If you want to do more with your live stream (for example if you want to delete it), you'll need to work with the API. We'll live stream using python in a [future post](https://api.video/blog/tutorials/live-stream-to-the-browser-with-ffmpeg-cli-and-python)! 

If you have any questions or suggestions, please join our [community forum](https://community.api.video/).

## You May Also Like...

* [Live Stream to the Browser with FFMPEG CLI and Python](https://api.video/blog/tutorials/live-stream-to-the-browser-with-ffmpeg-cli-and-python/) - Quickly create sample code that lets you start a livestream and display it in your browser. 
* [Live Stream From Your Android Phone](https://api.video/blog/tutorials/livestream-from-your-android-phone/) - Use a free app from Google Play to live stream from your Android phone. 
* [Secure Live Streams with a Unique Overlay](https://api.video/blog/tutorials/secure-live-streams-with-unique-overlay/) - Learn how to secure your live streams with a watermark that's unique to each viewer.

Live stream with OBS and api.video

large_nathan-anderson-yqesar7snli-unsplash.jpg

medium_nathan-anderson-yqesar7snli-unsplash.jpg

small_nathan-anderson-yqesar7snli-unsplash.jpg

thumbnail_nathan-anderson-yqesar7snli-unsplash.jpg

nathan-anderson-yqesar7snli-unsplash.jpg

Delegated Upload

api.video offers delegated uploads! For uploading video, this means you can create an authorization token, and choose how long your authorization token lasts, anywhere from a few seconds (this might be a bit extreme) to forever. The value in using a delegated upload token is that you don't expose your api key, authorization token, or refresh token. All you need is the delegated token you create. You can create tokens for users if you want them to be able to do uploads and you can delete tokens at any time if they are compromised, or no longer needed.

## How does a delegated video upload differ from a regular video upload?
Glad you asked! There are a few differences. If you use the regular upload endpoint, you must: 
* Use the authorization token you retrieve with your API key.
* Create a video container with any details you want to provide about your video.
* Upload your video into the video container you created. 

If you use the delegated video upload endpoint, you must:
* Create a delegated token for use with the delegated upload endpoint.
* Upload your video - api.video creates the container for you. You don't provide more detail than the file title. 

You can use the delegated token for as many uploads as you like, or delete the token if you don't need it any longer. You can add details about your video later using the update a video endpoint. 

## The Authorization Flow for Delegated Uploads 
You use your api key to authenticate and get a token. Then, you use your token to request a delegated token. The delegated token may be used for uploads through the delegated upload endpoint only. What's great about it, is if you want you can create and give this token to someone else to make uploads with. You can give the delegated token an expiry time, or let it last forever. Don't worry, you can also delete tokens if one of then is compromised, or if you don't need it any longer. 

## What's in this tutorial
We'll go over a code sample for: 

* Uploading a Video Under 200 MiB with a Delegated Token
* Uploading a Video 200 MiB or greater with a Delegated Token 

## Delegated upload for video under 200 MiB
<a title="RRZEicons, CC BY-SA 3.0 https://creativecommons.org/licenses/by-sa/, via Wikimedia Commons" href="https://commons.wikimedia.org/wiki/File:Upload.svg"><img width="256" alt="Upload" src="https://upload.wikimedia.org/wikipedia/commons/thumb/e/e6/Upload.svg/256px-Upload.svg.png"></a><br>
If you have a video under 200 MiB, upload is fairly straightforward. Here's the code sample: 

### Walkthrough - Delegated Upload for a Video Under 200 MiB

The start of this you're probably familiar with by now if you've tried the other tutorials. You're going to add the requests library, grab your API key (you can use sandbox or production, the difference being that for sandbox all video will be watermarked), and authenticate so you can get a token. 

### Retrieve a delegated token for video upload

Use your access token to set up the bearer auth header you'll need to retrieve a delegated token. For the body of your request, you need to add a value for the **ttl** field. TTL stands for time-to-live. In this walkthrough, we are setting ttl equal to 0, which means the token will last forever. You can set the token to other lengths of time in seconds. 

After you've set the payload, send your request, then retrieve the delegated token from the response. Armed with your shiny new token, you're ready to upload your video! 

### Upload your video that's under 200 MiB

To upload with the token, you need to send with the application/vnd.api.video+json header. Then the token is sent as a query field. The payload will be your video file, opened in binary. The title of your uploaded file will be the same name as the title of the file you send. 

## Delegated upload for video 200 MiB and bigger

This section shows you how to complete a chunked video upload. Because some of the code is the same as what was in the walkthrough directly preceding this one, we'll post the code sample, then focus in on what's different. 

After you get your delegated token, there are a few differences in the code to be aware of. Our read_in_chunks function stays the same, but for the upload function, notice that we set a videoId variable. This is because we are going to need to retrieve the videoId. 

Because api.video creates the video container for you on a delegated upload, you don't know what videoId you're uploading to. This is fine if you're uploading a complete video, but if you're sending your video in chunks, you need to tell the server what video container you want to send the chunks to. When you send your first upload request for a chunked video, include the Content-Range header (the only header you'll need) and then retrieve the response from your request. 

Get the videoId from the response, and in subsequent requests, you include the videoId. Like so: 

As you can see here, we use a few different tools from the requests library to make the subsequent requests. Your token for authenticating is a query parameter. The videoId goes in the body of your request. And you attach your file chunk as a file. 

If you change the name of the file in your requests (the spot where it says "file name here") then your file will be named to match that. Use the same title in both places for "file name here" in the code. The file you open for upload won't be referenced, because in a chunked upload, the request doesn't get the name of the file, it just has a chunk of the file attached each time. So it's a little different than a regular upload. 

There's only one step left for your chunked upload, and that's to use the function: 

Ta-da! You've done it! You've uploaded a video or a chunked video... or at least read all about it. In future posts, we'll go over how to manage your tokens. 

## Posts you may also like...
* [Upload a Video with the api.video API Using a Public URL (Python)](https://api.video/blog/tutorials/upload-a-video-with-the-api-video-api-using-a-public-url-python/)
* [Upload a Video From Your Computer with the api.video API (Python)](https://api.video/blog/tutorials/upload-a-video-from-your-computer-with-the-api-video-api-python/)
* [Upload a Big Video File Using Python](https://api.video/blog/tutorials/upload-a-big-video-file-using-python/)

Delegated uploads for videos large and small

medium_uploadbar.jpg

small_uploadbar.jpg

thumbnail_uploadbar.jpg

uploadbar.jpg

Authenticate

video create

If you have a large video you need to upload, sometimes the server you're uploading to will not accept it in one request. Different servers have different limits. For api.video, you can upload a video file up to a size of 199 MiB before your file is considered too big. Once your video crosses this limit, to upload it you'll need to break it into chunks and send it that way. You send each chunk and the server reassembles it for you. 

In this tutorial, we'll walk through a simple example of how to do a large video upload.

<center><iframe src="https://giphy.com/embed/jVeI3SzbxKGKQ" width="480" height="480" frameBorder="0" class="giphy-embed" allowFullScreen></iframe><p><a href="https://giphy.com/gifs/vhs-vcr-jVeI3SzbxKGKQ">This looks like it would turn into a really big video file.</a></p><br></center>

## Prerequisites
* [Account](https://dashboard.api.video) with api.video 
* api.video API key 
* You'll need access to Python and you'll need to install the requests library if you don't already have it added

And if you'd rather watch this tutorial than read it, check out our video tutorial here: 
                        <iframe src="https://embed.api.video/vod/vi3oTmhrZdwpAdJiEjeIQ7Fz" width="100%" height="100%" frameborder="0" scrolling="no" allowfullscreen="true"></iframe>
                    

## What You'll Be Doing 
This is a quick summary of what you're going to do to upload your large video. 

1. You'll authenticate with api.video using your API key and retrieve a token that lasts one hour that you can use to access all of api.video's other endpoints.
2. You'll create a video container for your video and retrieve the videoId. 
3. You'll use the videoId to create the endpoint you'll send your video to.
4. You'll break up your video file into chunks, then upload each chunk of the video file.

## Troubleshooting / What to Watch Out For 
If you decide to build your own uploader, a few things will help you out: 

* Remember that you must open the file as binary and work with it as binary. It's easy to forget and open it without adding 'rb' or depending on what you're doing, 'wb'.
* Headers are very important. The wrong header will prevent you from sending your content. 
* When using the Content-Range header, you must make sure you are listing the correct set of bytes being sent. If you are off by even one byte, it won't work. You will get weird errors like: 
```UnicodeDecodeError: 'utf-8' codec can't decode byte 0xd1 in position 52: invalid continuation byte``` And the solution is often a simple fix - correct how you're listing your bytes in the header.
* When you send bytes in the Content-Range header, it's inclusive. If you want to send the first 100 bytes, you write it as 0-99. This can get confusing when you're breaking your file into chunks because you can say 'grab the first 100 bytes' and the computer knows to grab 0-99. When you say 'grab the next 100 bytes,' the computer would grab 100-199. However, it's easy to write a dynamic header where you make mistakes like listing 0-100 instead of 0-99, or starting over on the same byte, for example 0-100, then 100-200. All these kinds of mistakes will cause a decode or encoding error. If you choose to build your own uploader instead of using this sample, keep this in mind. 
* If you label what type of file you're sending, you may cause unexpected issues. This sample works by opening, reading, and sending your video file as chunks of binary data. When it arrives, it's encoded into HLS for you, no matter what kind of video it started out as. 

## Code Sample 

```
## How to upload a large video that is over 199 MiB to api.video. (Though this script will also work for videos under 200 MiB if you want to test it out.)

import requests
import os 

## Set up variables for endpoints (we will create the third URL programmatically later)
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"

## Set up headers and payload for first authentication request
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "your API key here"
}

## Send the first authentication request to get a token. The token can be used for one hour with the rest of the API endpoints.
response = requests.request("POST", auth_url, json=payload, headers=headers)
response = response.json()
token = response.get("access_token")

## Set up headers for authentication - the rest of the endpoints use Bearer authentication.

auth_string = "Bearer " + token

headers2 = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}

## Create the video container payload, you can add more parameters if you like, check out the docs at https://docs.api.video
payload2 = {
    "title": "Demo Vid from my Computer",
    "description": "Video upload test."
}

## Send the request to create the container, and retrieve the videoId from the response.
response = requests.request("POST", create_url, json=payload2, headers=headers2)
response = response.json()
videoId = response["videoId"]

## Create endpoint to upload video to - you have to add the videoId into the URL
upload_url = create_url + "/" + videoId + "/source"

## Set up the chunk size. This is how much you want to read from the file every time you grab a new chunk of your file to read.
## If you're doing a big upload, the recommendation is 50 - 80 MB (50000000-80000000 bytes). It's listed at 6MB (6000000 bytes) because 
## then you can try this sample code with a small file just to see how it will work.  The minimum size for a chunk is 5 MB.

CHUNK_SIZE = 6000000

## This is our chunk reader. This is what gets the next chunk of data ready to send.
def read_in_chunks(file_object, CHUNK_SIZE):
    while True:
        data = file_object.read(CHUNK_SIZE)
        if not data:
            break
        yield data

## Upload your file by breaking it into chunks and sending each piece 
def upload(file, url):
    content_name = str(file)
    content_path = os.path.abspath(file)
    content_size = os.stat(content_path).st_size

    print(content_name, content_path, content_size)

    f = open(content_path, "rb")

    index = 0
    offset = 0
    headers = {}

    for chunk in read_in_chunks(f, CHUNK_SIZE):
        offset = index + len(chunk)
        headers['Content-Range'] = 'bytes %s-%s/%s' % (index, offset -1, content_size)
        headers['Authorization'] = auth_string
        index = offset
        try:

            file = {"file": chunk}
            r = requests.post(url, files=file, headers=headers)
            print(r.json())
            print("r: %s, Content-Range: %s" % (r, headers['Content-Range']))
        except Exception as e:
            print(e)

## Add a path to the file you want to upload, and away we go! 
upload('your-giant-file-here.mp4', upload_url)
```

## Code Walkthrough

Wanna know how it works in a little more detail? Great, here we go! The first couple of sections might look like some of the other blog posts, scroll down for a discussion about the new stuff if that's the case. 

You'll start by adding the requests and os libraries, so you can easily make HTTP requests.

```
import requests
import os
```

Next, let's assign a variable to each endpoint we'll use, they'll be a little easier to work with. We're going to assign two of them here, and we'll use the second one later to build the third one: 
* [Authentication](https://docs.api.video/reference/basic-authentication) endpoint - This is where we send our API key to exchange it for a token. It's **auth_url** in the code sample.
* [Videos](https://docs.api.video/reference/api/Videos#create-a-video-object) endpoint - Specifically we'll use the feature on this endpoint that's for creating a video. It's **create_url** in the code sample.
* [Video Upload](https://docs.api.video/reference/api/Videos#upload-a-video) endpoint - It looks a lot like the other endpoint. It's create_url + "/videoId" + "/source". We'll construct this after we get a videoId to work with. 

```
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"
```

### Authentication - Get Your Token
We'll prepare our headers and payload for authentication, then send a POST request to api.video. With the api.video API you start authentication by sending a request using your API key to retrieve a token. You can use your sandbox or your production key, the backend will figure out which you are using and handle it accordingly. If you choose to use your sandbox credentials for this walkthrough, your video will be uploaded with the watermark 'FOR DEVELOPMENT PURPOSES ONLY.': 

```
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "your API key here"
}
response = requests.request("POST", auth_url, json=payload, headers=headers)
```

Now we need to get the token from our response, so we can authenticate with the rest of api.video's endpoints when we want to do something. To get the token, we'll convert the response to JSON, then retrieve the token out of the JSON dictionary. 

```
response = response.json()
token = response["access_token"]
```

### Set up a Video Container 
Using the token, we'll get the headers and payload ready for our next request, which will be to ask api.video to create a video container for us.

```
## Set up headers for authentication
headers_bearer = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}

## Create a video container
payload2 = {
    "title": "Demo Vid from my Computer",
    "description": "Video upload of Big Buck Bunny to demo how to do an upload from a folder on your computer."
}
```

api.video endpoints use bearer authentication. Add the authorization header for bearer authentication to your list of headers, and then for the payload we keep it simple, just a title and description. But what about the path to your file? Don't worry we're just creating a container right now. When you upload from your computer, you create a container first, and do your upload second. 

### Send Your Request and Grab the VideoId
For the next part of our walkthrough, we'll send our request, convert the response to JSON, and retrieve the videoId. We need the videoId so we can tell api.video what container we want to upload our video to. 

```
response = requests.request("POST", create_url, json=payload2, headers=headers_bearer)
response = response.json()
videoId = response["videoId"]
```

### Create the Endpoint for Uploading Your Video
Set up the endpoint you'll upload your video to, which is composed of "https://ws.api.video/videos" + "/" + videoId + "/source". 

### Build a Data Chunk Reader
To break your data into chunks, you're going to want to decide how big each chunk should be, and then from an open file keep grabbing the next chunk of data to read. We'll set the chunk size at 1000000 bytes. This is fairly small, in case you wanted to try the sample with a smaller video file to see how it works. If you plan to start using this data chunk reader, make the chunk size larger. A good size is about 50-80 MB or about 50000000-80000000 bytes. 

This function assumes you've already opened your file elsewhere, and it's using **yield**. What this does, is return a generator. Every time you use this function as part of a for loop, it will run until it hits yield, then return the value. Yield 'remembers' where you left off, so each time you loop through, it will return a new chunk of data. 

```
CHUNK_SIZE = 1000000

def read_in_chunks(file_object, CHUNK_SIZE):
    while True:
        data = file_object.read(CHUNK_SIZE)
        if not data:
            break
        yield data
```

### Start Your Large Video Upload 
<center><iframe src="https://giphy.com/embed/TI3IErToEDAERYK7LL" width="480" height="480" frameBorder="0" class="giphy-embed" allowFullScreen></iframe><p><a href="https://giphy.com/gifs/TalentSmiths-loading-talentsmiths-janetsmiths-TI3IErToEDAERYK7LL"></a></p><br></center>
Here's our next function. This one is the upload function, and it contains our chunk reader. What we do here, is use the os library to grab some file details, so we know how big the file we're going to send is, the path to get to it, and the name of the file. 

We open our file, and NOTE...we are opening our file in binary. This is important to remember, since opening a video file in other formats will probably not work. 

Next we set up our index, that's going to represent what point we're at in the file. We also set up the offset, which represents how far forward to move the index after we send each chunk. 

Then we start reading chunks of data. For each chunk of data, we prepare the Content-Range header so we are correctly listing what part of the file we are sending in bytes. To send our data chunk, we need to put it into a one item file dictionary. We do that, and then for readability assign it to a variable. Then we send our request! This will loop through until we're out of data chunks (the last chunk will probably be smaller than the others). 

```
def upload(file, url):
    content_name = str(file)
    content_path = os.path.abspath(file)
    content_size = os.stat(content_path).st_size

    print(content_name, content_path, content_size)

    f = open(content_path, "rb")

    index = 0
    offset = 0
    headers = {}

    for chunk in read_in_chunks(f, CHUNK_SIZE):
        offset = index + len(chunk)
        headers['Content-Range'] = 'bytes %s-%s/%s' % (index, offset -1, content_size)
        headers['Authorization'] = auth_string
        index = offset
        try:

            file = {"file": chunk}
            r = requests.post(url, files=file, headers=headers)
            print(r.json())
            print("r: %s, Content-Range: %s" % (r, headers['Content-Range']))
        except Exception as e:
            print(e)
```

You don't need any other headers. 

You will know you are successful after you send the last chunk. It's possible to receive a -200- response for each chunk, then have it not work out at the very end, so make sure to watch your video upload the first time through. Success is denoted by the response to the last chunk, where you will receive something that looks like this: 

```
{
 'videoId': 'viyourvideoIdz', 
 'title': 'Demo Vid from my Computer', 
 'description': 'Video upload test.', 
 'public': True, 
 'panoramic': False, 
 'mp4Support': True, 
 'publishedAt': '2021-02-08T06:14:53+00:00', 
 'createdAt': '2021-02-08T06:14:53+00:00', 
 'updatedAt': '2021-02-08T06:14:53+00:00', 
 'tags': [], 
 'metadata': [], 
 'source': {
	 'type': 'upload', 
	 'uri': '/videos/vviyourvideoIdz/source'
	 }, 
 'assets': {
	 'iframe': '<iframe src="https://embed.api.video/vod/viyourvideoIdz" width="100%" height="100%" frameborder="0" scrolling="no" allowfullscreen="true"></iframe>', 
	 'player': 'https://embed.api.video/vod/viyourvideoIdz', 
	 'hls': 'https://cdn.api.video/vod/viyourvideoIdz/hls/manifest.m3u8',    
	 'thumbnail': 'https://cdn.api.video/vod/viyourvideoIdz/thumbnail.jpg'
	 }
}
r: <Response [201]>, Content-Range: bytes 4000000-4824145/4824146
```

Check your video's status in [your dashboard](https://dashboard.api.video/). If you have a very large video file, wait a few minutes while api.video finishes processing it. When processing is finished, you'll be able to see a thumbnail for your video and play it from the dashboard. 

If your video upload is unsuccessful, you won't receive the detailed message listed above. You might receive an additional 200 response, or a 400 response for each chunk, depending on how much went wrong with your upload. 
In the dashboard, you may see your video uploaded, but it stays stuck on processing. If this happens, review your code, or contact us with your issue in the [community forum](https://community.api.video/). 



Upload a big video file using Python

large_upload-a-big-video-file-using-python.png

medium_upload-a-big-video-file-using-python.png

small_upload-a-big-video-file-using-python.png

thumbnail_upload-a-big-video-file-using-python.png

upload-a-big-video-file-using-python.png

Video upload

If you have some videos on your computer that you need to upload to api.video, you're in luck - today's tutorial will show you how to do just that using Python. Your video must be under 200 MiB to use this method. The code sample is available on github in the [api.video python-examples repository](https://github.com/apivideo/python-examples). Let's get started! 

medium_pexels-designecologist-1779487.jpg

small_pexels-designecologist-1779487.jpg

thumbnail_pexels-designecologist-1779487.jpg

pexels-designecologist-1779487.jpg

## Prerequisites
* An [api.video account](https://dashboard.api.video/register) 
* api.video API key 
* You'll need access to Python and you'll need to install the requests library if you don't already have it added

## What You'll Be Doing
This is a quick summary of what you're going to do to upload your video. 

1. You'll authenticate with api.video using your API key and retrieve a token that lasts one hour that you can use to access all of api.video's other endpoints.
2. You'll create a video container for your video and retrieve the videoId. 
3. You'll use the videoId to upload your video from your computer to api.video. You can only upload a video to the videoId once. If you decide you wanted to upload a different video, you'll have to go through the create container and upload video steps again. You don't need to repeat the part where you get a new token unless your token expires (so if you take an hour long break and come back, you'll need to redo that step then). 

## Code Sample 

```
## How to upload a video under 200 MiB using the api.video API

import requests

## Set up variables for endpoints
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "your API key here"
}

response = requests.request("POST", auth_url, json=payload, headers=headers)
response = response.json()
token = response.get("access_token")

auth_string = "Bearer " + token


## Set up headers for authentication
headers_bearer = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}

## Create a video container
payload2 = {
    "title": "Demo Vid from my Computer",
    "description": "Video upload of Big Buck Bunny to demo how to do an upload from a folder on your computer."
}

response = requests.request("POST", create_url, json=payload2, headers=headers_bearer)
response = response.json()
videoId = response["videoId"]

## Create endpoint to upload video to
upload_url = upload_url + "/" + videoId + "/source"

## Create upload video headers 
headers_upload = {
    "Accept": "application/vnd.api.video+json",
    "Authorization": auth_string
}

file = {"file": open("local/path/to/myvideo.flv", "rb")}
response = requests.request("POST", upload_url, files=file, headers=headers_upload)
json_response = response.json()
print(json_response)
```

## Code Walkthrough

You'll start by adding the requests library, so you can easily make HTTP requests.

<center><iframe src="https://giphy.com/embed/YGlRW1Am9q7e0" width="320" height="480" frameBorder="0" class="giphy-embed" allowFullScreen></iframe><p><a href="https://giphy.com/gifs/books-libraries-shelves-YGlRW1Am9q7e0">How people added libraries before computers did it for you.</a></p><br></center>

```
import requests
```

Next, let's assign a variable to each endpoint we'll use, they'll be a little easier to work with. We're going to assign two of them here, and we'll use the second one later to build the third one: 
* [Authentication](https://docs.api.video/reference/basic-authentication) endpoint - This is where we send our API key to exchange it for a token. It's **auth_url** in the code sample.
* [Videos](https://docs.api.video/reference/api/Videos#create-a-video-object) endpoint - Specifically we'll use the feature on this endpoint that's for creating a video. It's **create_url** in the code sample.
* [Video Upload](https://docs.api.video/reference/api/Videos#upload-a-video) endpoint - It looks a lot like the other endpoint. It's create_url + "/videoId" + "/source". We'll construct this after we get a videoId to work with. 

```
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"
```

### Authentication - Get Your Token
We'll prepare our headers and payload for authentication, then send a POST request to api.video. With the api.video API you start authentication by sending a request using your API key to retrieve a token. You can use your sandbox or your production key, the backend will figure out which you are using and handle it accordingly. If you choose to use your sandbox credentials for this walkthrough, your video will be uploaded with the watermark 'FOR DEVELOPMENT PURPOSES ONLY.': 

```
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "your API key here"
}
response = requests.request("POST", auth_url, json=payload, headers=headers)
```

Now we need to get the token from our response, so we can authenticate with the rest of api.video's endpoints when we want to do something. To get the token, we'll convert the response to JSON, then retrieve the token out of the JSON dictionary. 

```
response = response.json()
token = response.get("access_token")
```

### Set up a Video Container 
Using the token, we'll get the headers and payload ready for our next request, which will be to ask api.video to create a video container for us.

```
## Set up headers for authentication
headers_bearer = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}

## Create a video container
payload2 = {
    "title": "Demo Vid from my Computer",
    "description": "Video upload of Big Buck Bunny to demo how to do an upload from a folder on your computer."
}
```

api.video endpoints use bearer authentication. Add the authorization header for bearer authentication to your list of headers, and then for the payload we keep it simple, just a title and description. But what about the path to your file? Don't worry we're just creating a container right now. When you upload from your computer, you create a container first, and do your upload second. 

### Send Your Request and Grab the VideoId
For the next part of our walkthrough, we'll send our request, convert the response to JSON, and retrieve the videoId. We need the videoId so we can tell api.video what container we want to upload our video to. 

```
response = requests.request("POST", create_url, json=payload2, headers=headers_bearer)
response = response.json()
videoId = response["videoId"]
```

### Create the Endpoint for Uploading Your Video
Set up the endpoint you'll upload your video to, which is composed of "https://ws.api.video/videos" + "/" + videoId + "/source". You also need to add the headers. For Python, you don't want to use the "Content-Type": "multipart/form-data" header you see listed if you try the API explorer. Because you are doing an upload with only one part, it won't work. Omit this in your headers. Set things up like this: 

```
headers_upload = {
    "Accept": "application/vnd.api.video+json",
    "Authorization": auth_string
}
```

For the payload, you're sending a video file, so you'll have to open the file, attach it to a dictionary, and for readability, we assign the dictionary to a variable. We use "rb" because we want to open the file as read-only binary format. Check it out: 

```
file = {"file": open("sample-flv-file.flv", "rb")}
```

We can assign our variable in our request to upload our video, and then process and print the request response:

```
response = requests.request("POST", upload_url, files=file, headers=headers_upload)
json_response = response.json()
print(json_response)
```

The response provides a lot of detail about your video:

```
{
	'videoId': 'video ID here', 
	'title': 'Demo Vid from my Computer', 
	'description': 'Video Upload From My Computer', 
	'public': True, 
	'panoramic': False, 
	'mp4Support': True, 
	'publishedAt': '2021-02-05T04:25:02+00:00', 
	'createdAt': '2021-02-05T04:25:02+00:00', 
	'updatedAt': '2021-02-05T04:25:02+00:00', 
	'tags': [], 
	'metadata': [], 
	'source': {
		'type': 'upload', 
		'uri': '/videos/video_ID_here/source'
	 }, 
	'assets': {
		'iframe': '<iframe src="https://embed.api.video/vod/video_ID_here" width="100%" height="100%" frameborder="0" scrolling="no" allowfullscreen="true"></iframe>', 
		'player': 'https://embed.api.video/vod/video_ID_here', 
		'hls': 'https://cdn.api.video/vod/video_ID_here/hls/manifest.m3u8',
		'thumbnail': 'https://cdn.api.video/vod/video_ID_here/thumbnail.jpg'
 }
}
```

* **videoId** - the unique identifier for your new video. Before it was just referencing a container, now it's referencing a container that holds your video!
* **title** - the title you provided for your video when you made the container
* **description** - a description of what the video contains
* **public** - by default, your video is public 
* **panoramic** - by default, your video isn't listed as being a 360° (panoramic is the term api.video uses for 360° or immersive video)
* **mp4Support** - whether you have an mp4 version of your video available or not. By default you do. If you turn this off, your video will not be downloadable from a player and there won't be a link to an mp4 version of your file.
* **publishedAt** - the time your video was published, in ISO-8601 format.
* **createdAt** - the time your video was created, in ISO-8601 format.
* **updatedAt** - the time your video was updated in ISO-8601 format.
* **tags** - you can add individual key words to categorize your videos and make them easier to search if you have a lot of them.
* **metadata** - you can add a dictionary of key value pairs that categorize your videos for searches.
* **source** - this lists the video type, which is upload, and the link you add to the api endpoint to get to your video. 
* **assets** - this is a list of links you can use to set up different services with your video. You can embed an iframe using the iframe code, use the player link to add the file to a player, get the manifest file if you need the source for live streaming, and api.video selects a thumbnail for you automatically. 

You can update all of this information should you choose to. That's it for uploading a video from your computer using Python! 

If you have any questions or suggestions, please share them on our [community forum](https://community.api.video/) and if you still haven't created your api.video account, you can do that [here](https://dashboard.api.video/overview). Happy building! 

Upload a video with api.video’s API (Python)

Photo by <a href="https://www.pexels.com/photo/silver-imac-displaying-collage-photos-1779487/">Designecologist</a> from Pexels

Upload a video from your computer with the api.video API (Python)

If Python is your programming language of choice, and you want to quickly upload a video to api.video using a public URL, you've come to the right place. The code sample is available on github in the [api.video python-examples repository](https://github.com/apivideo/python-examples). Let's get started! 

<center><iframe src="https://giphy.com/embed/l0IyjiXOXTX6Yemsg" width="480" height="270" frameBorder="0" class="giphy-embed" allowFullScreen></iframe><p><a href="https://giphy.com/gifs/l0IyjiXOXTX6Yemsg"></a></p><br></center>

## Prerequisites

If you would prefer to watch a video that explains the same information as this tutorial, you can watch this:

* [An api.video account](https://dashboard.api.video/register)
* api.video API key 
* URL for a public video you want to try uploading (we'll be using this link here: [https://www.learningcontainer.com/mp4-sample-video-files-download/#Sample_AVI_File](https://www.learningcontainer.com/mp4-sample-video-files-download/#Sample_AVI_File))
* You'll need access to Python and you'll need to install the requests library if you don't already have it added

You can also review the API reference documentation for uploading videos here: [Upload a video](https://docs.api.video/reference/api/Videos#upload-a-video)

## Code Sample

```
import requests

## Set up variables for endpoints
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"

## Set up header for first authentication request
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "sandbox or production key here"
}

response = requests.request("POST", auth_url, json=payload, headers=headers)
response = response.json()
token = response.get("access_token")

auth_string = "Bearer " + token


## Set up headers for bearer authentication
headers2 = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}

## Upload the video
payload = {
    "title": "My Demo Video",
    "source": "https://www.learningcontainer.com/mp4-sample-video-files-download/#Sample_AVI_File"
}
response = requests.request("POST", create_url, json=payload, headers=headers2)

## Check out the response
print(response.json())

```

## Code Walkthrough
This section walks through the code to give you an idea of what you'll be doing.

### Set up Authentication with Your API Key
You'll start by adding the requests library, so you can easily make HTTP requests.

```
import requests
```

Next, let's assign a variable to each endpoint we'll use, they'll be a little easier to work with. We're going to use two endpoints today: 
* [Authentication](https://docs.api.video/reference/basic-authentication) endpoint - This is where we send our API key to exchange it for a token. It's **auth_url** in the code sample.
* [Videos](https://docs.api.video/reference/api/Videos#create-a-video-object) endpoint - Specifically we'll use the feature on this endpoint that's for creating a video. It's **create_url** in the code sample.

```
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"
```

Create the payload for your headers and the payload for your payload. These are for your authentication request. The api.video API requires that you authenticate with your API key to obtain a token. Your token is good for one hour and can be used to authenticate with all other endpoints. 

NOTE: You can use your sandbox or your production key. The backend for api.video will figure out which you selected and route your request appropriately. If you didn't pay for a full account, all of your videos will be watermarked 'FOR DEVELOPMENT PURPOSES ONLY'.

```
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "your API key here"
}

```

Send a request with your header and payload information, convert the response to json so you can retrieve information from it, and then grab **access_token**.

```
response = requests.request("POST", auth_url, json=payload, headers=headers)
response = response.json()
token = response.get("access_token")
```

Now you have your token, you need to set new headers that are for Bearer authentication. Create a string with your token for the new Authorization header, and a new header payload. 

```
auth_string = "Bearer " + token

headers2 = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}
```

### Send Your Video Upload Request

And the part you've been waiting for, the code for video upload! By default, your video is public and includes mp4 support, which is a link to a 1080p mp4 of your file. If you want to change these settings so your video is private or mp4 support is turned off (this will make it so no one can download your video from a player) you can [check our docs](https://docs.api.video/reference/api/Videos#create-a-video-object) for details about all the parameters your payload can include. For now, we'll keep the payload simple: 

```
payload = {
    "title": "My Demo Video",
    "source": "https://www.learningcontainer.com/mp4-sample-video-files-download/#Sample_AVI_File"
}
response = requests.request("POST", create_url, json=payload, headers=headers2)
print(response.json())
```

You can use this payload to see the sample run. For your own upload, you may want to use a different title and a different source link.

### Review Video Details in the Response

When you print the response here, you get back a lot of interesting information about your video: 

```
{'videoId': 'vi8PXlHuWN25wPOVtGfBSQkJ', 
'title': 'My Demo Video', 
'description': '', 
'public': True, 
'panoramic': False, 
'mp4Support': True, 
'publishedAt': '2021-02-04T01:50:23+00:00', 
'createdAt': '2021-02-04T01:50:23+00:00', 
'updatedAt': '2021-02-04T01:50:23+00:00', 
'tags': [], 
'metadata': [], 
'source': {
	'type': 'upload', 
	'uri': '/videos/vi8PXlHuWN25wPOVtGfBSQkJ/source'
	}, 
'assets': {
	'iframe': '<iframe src="https://embed.api.video/vod/vi7EVlHuWN05wPOVtGfBSQkJ" width="100%" height="100%" frameborder="0" scrolling="no" allowfullscreen="true"></iframe>', 
	'player': 'https://embed.api.video/vod/vi8PXlHuWN25wPOVtGfBSQkJ', 
	'hls':'https://cdn.api.video/vod/vi8PXlHuWN25wPOVtGfBSQkJ/hls/manifest.m3u8',   'thumbnail': 'https://cdn.api.video/vod/vi8PXlHuWN25wPOVtGfBSQkJ/thumbnail.jpg'
  }
}
```

* **videoId** - a unique ID that identifies your uploaded video
* **title** - the title of your video
* **description** - if you put a description of your video it appears here
* **public** - whether your video is public or not
* **panoramic** - whether your video is 360° or not
* **mp4Support** - whether your video has an mp4 version of it available or not (turn this off if you don't want people to be able to download your video from a player)
* **publishedAt** - when you first published your uploaded video
* **createdAt** - when your uploaded video was created
* **updatedAt** - when you last updated your video
* **tags** - if you added individual tags to categorize your video with, they appear here
* **metadata** - if you added key value pairs to categorize your videos with, they appear here
* **source** - details about your video source 
* **assets** - different ways you can upload or work with your new video, there's a link you can use with a player, the source file for the hls versio of your video, and a thumbnail that's selected for you (you can change it if you like, but that's a different tutorial)

And that's how you do a simple video upload to api.video! Let us know if you have any questions in [our Community](https://community.api.video/)! Happy building!

Upload a video to api.video using a public URL

large_upload-a-video-to-api-video-using-a-public-url.png

medium_upload-a-video-to-api-video-using-a-public-url.png

small_upload-a-video-to-api-video-using-a-public-url.png

thumbnail_upload-a-video-to-api-video-using-a-public-url.png

upload-a-video-to-api-video-using-a-public-url.png

codec

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

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

Doug Sillars

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