Video upload

Normal

large_logo_avatar.webp

medium_logo_avatar.webp

small_logo_avatar.webp

thumbnail_logo_avatar.webp

logo_avatar.webp

api.video

large_api-video-blog-tutorials.png

medium_api-video-blog-tutorials.png

small_api-video-blog-tutorials.png

thumbnail_api-video-blog-tutorials.png

api-video-blog-tutorials.png

Tutorials

This tutorial showcases the API endpoints and operations that you can use to add video functionalities to a service similar to Airbnb. The tutorial only focuses on the API itself - you can use our recent tutorial about [creating a video uploader in PHP](https://api.video/blog/tutorials/upload-video-with-PHP/) to learn more about creating the backend and frontend for a similar web-based solution.

## Why videos?

When you create a platform where you want to enable users to sell or rent, adding video functionality can be a game changer. In case of a solution that’s similar to Airbnb, showing videos can help hosts earn the trust of their guests, which can lead to more bookings, and increased traffic on your platform.

&nbsp;

api.video’s API can give you a simple solution to provide these functionalities for your users:

- creating and uploading a video
- managing videos: listing, editing, or updating uploaded videos
- deleting a video

&nbsp;

Let’s go through these endpoints!

## Create and upload a video

Creating and uploading videos is a simple concept in the api.video ecosystem:

&nbsp;

1. First, you **[create a video object](https://docs.api.video/reference/api/Videos#create-a-video-object).** Think of it as a container for the video file. Creating a video object generates the video’s `videoID`, and amongst other things, creates the assets URLs that you can embed into your website. You can use the `metadata` attribute to add unique key-value pairs to each video object, for example to differentiate between users who upload the video.

&nbsp;

2. Then, you **[upload a video](https://docs.api.video/reference/api/Videos#upload-a-video)** into that video container object. The uploaded video file is hosted by api.video. Uploading a video file starts the encoding process. Depending on your stream quality, your videos are encoded into HLS in different resolutions, from 240p to 2160p.

Flowchart of the video object creation and file upload for api.video.

create-a-video-light.svg

## Manage videos

Giving your users the ability to manage their videos is straightforward through api.video’s endpoints:

- [**list all videos**](https://docs.api.video/reference/api/Videos#list-all-video-objects) to retrieve and display a list of videos for your users. You can use the `metadata` attribute you provided to filter specific content for different users.
- [**upload**](https://docs.api.video/reference/api/Videos#upload-a-thumbnail) or [**set thumbnails**](https://docs.api.video/reference/api/Videos#set-a-thumbnail) for videos. Setting thumbnails uses content from the video based on a set time interval.
- [**update a video**](https://docs.api.video/reference/api/Videos#update-a-video-object) to modify attributes like titles, descriptions, whether the video is published or hidden. Check out the [API reference](https://docs.api.video/reference/api/Videos#update-a-video-object) for a full list of attributes that you can update.
- [**retrieve video status**](https://docs.api.video/reference/api/Videos#retrieve-video-status-and-details) to show real-time information on encoding status, and to determine when a video is uploaded, and ready for playback. Once the encoding is completed, the API response also lists the available stream qualities. You can make your solution more robust by subscribing to the `video.encoding.quality.completed` webhook. This webhook triggers whenever you upload a video and the API finishes encoding the video in a set quality. Read more about webhooks in the [API reference](https://docs.api.video/reference/create-and-manage-webhooks).


## Demo

We have put together a simple demo for you to see how the video upload and playback in the “Airbnb” workflow could look like - head over to the [Airbnb mockup page](https://apivideo-airbnb-demo.netlify.app/) to try it out yourself.

## What’s next?

Now that you understand the different API functionalities behind creating, uploading, and managing videos, you can also start thinking about video delivery. 

&nbsp;

Check out our [Delivery & Analytics quickstart](https://docs.api.video/delivery-analytics/delivery-analytics-quickstart) to learn how to implement the api.video Player, and the different ways you can provide play analytics data to your users. Analytics enables you to create useful visualizations and data-driven enhancements for your users in your platform.

&nbsp;

Read more about [Analytics and how it can help content strategy in our recent blog post](https://api.video/blog/tutorials/api-video-analytics-content-strategy/).

## Further reading

Check out the documentation to learn more about:

- [video management basics](https://docs.api.video/vod/video-management-basics)
- [video statuses and details](https://docs.api.video/vod/show-video-upload-status)

&nbsp;

If you prefer a more hands-on approach, try going through the [VOD quickstart](https://docs.api.video/vod/get-started-in-5-minutes), where we guide you through the process of creating a sample video implementation in a few easy steps.

&nbsp;

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

API showcase - build a service like Airbnb with api.video

Header image for a blog post about creating an Airbnb-like service using api.video

large_AV Blog_AirbnbClone.jpg

medium_AV Blog_AirbnbClone.jpg

small_AV Blog_AirbnbClone.jpg

thumbnail_AV Blog_AirbnbClone.jpg

AV Blog_AirbnbClone.jpg

t02cw29ka-u04jtt0jcg3-549047173ac2-512.jpeg

Artem Matinian

When considering building your project or website, you went through several languages and eventually settled for PHP. It’s a great language, easy to pick up and it can help you build your own project within minutes. 

&nbsp;
 

However, with all the great things that come with PHP, there are also some challenges. For example, how do you upload videos with PHP, while also making sure that users have a good experience while uploading and streaming these videos?

&nbsp;
 

You are probably already aware of some of these challenges, otherwise, you wouldn’t be reading this article. 😄

## How to upload a video: A step-by-step guide

For the sake of this example, let’s stick to the basics and build a very simple video uploader on an existing PHP server. The workflow is quite simple:

&nbsp;
 
1. Your PHP server shows the user a file selector.
2. The file selector lets the user pick a file from their device.
3. The selected file is delivered in a multi-part form to the PHP server.
4. The PHP server then uploads the video to [api.video](https://api.video/) for transcoding, hosting, and delivery.

&nbsp;
 
Now, let’s start with creating a simple PHP server. You can skip the Preparation if you already have PHP implementation set up.

## Preparation

### 1. Sign up to api.video for free

[Let’s create a free account with api.video.](https://dashboard.api.video/register) We’ll handle the video transcoding, hosting, and delivery for your viewers.

### 2. Install PHP

You can skip this step if you have PHP already installed. If not, you can find instructions in the [PHP official installation guide](https://www.php.net/manual/en/install.php).
&nbsp;
 
Alternatively, you can use MAMP to create a local server environment. Visit the [official MAMP website](https://www.mamp.info/en/windows/) for more information.

### 3. Install Composer

In order to get all the respective libraries for the use case we are building here, you’ll need a package manager. Let’s install Composer, a simple package manager for PHP. Check out the instructions on how to download and install Composer [here](https://getcomposer.org/doc/00-intro.md).

### 4. Create a PHP server folder

1. Let’s a new folder for the app. Choose any name for the project.
2. Create a new file called `server.php` inside that folder.

&nbsp;
 

Now that you’re all set, let’s begin with the process.

## Create the video uploader frontend

We’ll start by setting up the PHP server and the multipart form.

&nbsp;
 

1. The server will receive a request: we will check that the request type is [GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET).
2. We will also check that and that the URL that the user is hitting is `/`. This means that the user landed on the main page.
3. The multipart type form is necessary if the user uploads a file through the form. Give the form a `name` and an `id`. We’ll use it later on.


&nbsp;
 
Copy this script into your `server.php` file:

Now let’s do a quick test run! 

&nbsp;
 

1. Open your `cmd` or `terminal` 
2. Navigate to the PHP folder you've stored the project in

3. Run the PHP server (this command will run the file server.php on your local machine on port 8000)

4. Navigate to localhost:8000 on your browser

localhost.png

video-uploader.png

If this is the first time you are working with PHP, then congratulations - you’ve just created your first PHP website!

## Create the backend

Now that the frontend part is done, let’s set up the backend. The backend’s job is to:

&nbsp;
 

1. Receive the videos from the frontend
2. Send the videos over to [api.video](https://api.video) in order to make sure your users have the best experience while uploading and streaming.

### Configure file uploads in PHP

Let’s enable file uploading, and configure the size of the files your users can upload. To configure this, we need to find the `php.ini` in your implementation.

&nbsp;
 

1. In your terminal, type:

This should give you the following output:

Navigate to the php.ini file, and change or add these following values:

You can choose smaller or larger values than 150M. Now let’s save it.

### Receive the video files

Before the file is sent to [api.video](https://api.video), it has to be stored locally. This is only temporary and you can delete the file after your server uploads it to api.video.

This is the workflow we’ll follow:

&nbsp;
 

1. First, we create a new “endpoint” that accepts `POST` requests to an `/upload` endpoint. Remember our multipart form? It is actually already set up to submit the file to `/upload`. Multipart form are set to `POST` by default. So, we will create an `if` statement to handle that.
2. Once a `POST` request will hit this endpoint, it will pass in the file. We pick it up and save it in a `/uploads/` directory in the PHP server folder. Let’s create the `/uploads` folder inside the PHP project folder:

Now edit the server.php file and add this code we just described:

With this code, we take the file name and store it in the `/uploads` folder with the [move_uploaded_file](https://www.php.net/manual/en/function.move-uploaded-file.php) function.

&nbsp;
 

Awesome! Now we have a cool server that can ask the user for a file. Let’s run the server again to test it. Start the PHP server again:

Navigate to localhost:8000 and this time, select a file to upload and click on Upload Video. After the file is uploaded, you should see it in the /uploads folder in your PHP server project.

upload-folder-server.png

## Upload the videos to api.video

You’re more than half-way done, great job! 

&nbsp;
 

Now, you only need to add a small thing to all the mix. After uploading the video to your PHP server, you can just give your users public access to this file, and let them play it, right? 

&nbsp;
 

Not quite. There’s a lot of science behind delivering a video. While it can be delivered directly from your PHP server, your users may see issues with the playback: long loading times, and even issues with loading the video at all. It comes down to transcoding the video to different qualities, hosting the video on a scalable environment and having a good enough CDN that will deliver the video fast. You also need a capable player that will have all the options that your users need, without having to pour vast amount of money and resources into expensive services.

&nbsp;
 

With around ten simple lines of code, you can make sure your users have the best experience while watching and uploading their videos.

### Add api.video to your code

Now that you have an api.video account, grab your [API key from the dashboard](https://dashboard.api.video/project-settings/api-keys) and paste it in as the value of `$apiKey` in the `server.php`:

Notice that we are also initializing the api.video client library. So, we need to run the Composer in order to get these libraries inside the server’s main folder.

&nbsp;
 

1. Let’s make sure that Composer is installed.
2. Open the terminal again and run these commands:

3. After the packages are installed, run the PHP server again:

## Deliver the videos

Let’s try upload a new video in your `localhost` environment. 

&nbsp;
 

Since we implemented api.video in the code, uploading a video will give you a response with different parameters, including the assets. The assets are actually the video you just uploaded in different streaming formats (HLS and mp4). You’ll notice that you also have an `iframe` parameter, which is your video embedded in an `iframe`. Let’s display the video as soon as it is ready. We’ll add a bit more code to retrieve the status of the video, so once it’s ready, we can display it in the `iframe`.

&nbsp;
 

Let’s add a status request to our code:

We’ve added a `while` loop that checks the video status. If the video is playable (which means that api.video finished transcoding it), we can take the `iframe` asset, embed it, and display it to the users. This part is handled in echo `$response->getAssets()->getIframe()`.

&nbsp;
 

Now save your code, upload a new video via `localhost`, and enjoy the show! 😊

&nbsp;


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

How to upload a video file in PHP

large_Upload with PHP.jpg

medium_Upload with PHP.jpg

small_Upload with PHP.jpg

thumbnail_Upload with PHP.jpg

upload-with-php.jpg

Erikka Innes

Product updates

api.video is proud to announce a brand new PHP client for our video API. Our old PHP SDK will be deprecated. You can continue to use it, but it will no longer be updated. Instead, the new PHP client will stay up-to-date with all our new feature releases. 

Like our other clients, it's autogenerated and handles authentication for you, including refreshing your access token when needed. It also handles paginated responses and chunked uploads for large files. A unique aspect of this client is that it is also [PSR-18](https://www.php-fig.org/psr/psr-18/) compliant. This makes it more reusable as it reduces the number of dependencies and lowers the likelihood of version conflicts.

You can install our new client with:
```composer require api-video/php-api-client```

And the entire client is available in the GitHub repository here: 
[https://github.com/apivideo/php-api-client](https://github.com/apivideo/php-api-client)

In addition to the documentation we have at docs.api.video, you can find client-specific documentation in the GitHub repository. If you are looking up parameters, we recommend that you refer to the content provided in the client respository first. Some information may be tweaked to make it easier to create and use the client. There's a docs page for each part of the API here: [https://github.com/apivideo/php-api-client/tree/main/docs/Api](https://github.com/apivideo/php-api-client/tree/main/docs/Api) 

PHP is fast, flexible and widely used in web applications. We hope you'll enjoy using our new client to code your video projects! 



api.video announces a new PHP client

php.png

Delegated Upload

Python

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

uploadbar.jpg

Android

Thibault Beyou

Kotlin

This article is about how to easily add an upload mechanism from [api.video](https://api.video) to your Android application with a specific component from the Android API client and the Android video uploader called the UploadService.

In your Android application, if you use the `upload` API with the [Android API client](https://github.com/apivideo/api.video-android-client) or the [Android video uploader](https://github.com/apivideo/api.video-android-uploader), you might have noticed that it is not a piece of cake. Here are the main reasons why:

- **NetworkOnMainThreadException**: on the modern Android version, you must not perform network calls on the main thread; otherwise your application will crash with an `android.os.NetworkOnMainThreadException` . As `upload` is a synchronous API, you must call it from a Thread.
- **Background**: performing long-running tasks in your Activity is forbidden, so if the user sends your application to the background while an upload is in progress, the system might kill the process at some point and the file will never be uploaded
- **Upload management**: with the `upload` API you can't just cancel a running upload, you can't efficiently perform multiple uploads unless you have implemented it in a separate Thread.

At some point, you will have to implement the `upload` API in a dedicated Thread or an [Executor](https://developer.android.com/reference/java/util/concurrent/Executor) or, even better with [Kotlin coroutines](https://kotlinlang.org/docs/coroutines-overview.html). It might be a lengthy task if you are not familiar with these components. A Thread won't be able to handle uploads when the application is in the background. If you are already familiar with Android Services, you know that implementing a Service is a good solution for this kind of issue. Let's have a deeper look at this component.

## 1. Android Service

According to Android [documentation](https://developer.android.com/guide/components/services):

"A [Service](https://developer.android.com/reference/android/app/Service) is an [application component](https://developer.android.com/guide/components/fundamentals#Components) that can **perform long-running operations in the background**. It does not provide a user interface. Once started, a **service might continue running for some time, even after the user switches to another application**. Additionally, a component can bind to a service to interact with it and perform interprocess communication (IPC). For example, **a service can handle network transactions**, play music, perform file I/O, or interact with a content provider from the background."

Nice!

There is another interesting part about the service:

"When a service is running, it can notify the user of events using [snack bar notifications](https://developer.android.com/develop/ui/views/notifications/snackbar)
 or [status bar notifications](https://developer.android.com/develop/ui/views/notifications/build-notification)."

For a type of service called Foreground Service, your service must display a notification. The notification can look like a text, but it can also be an audio player.

When you start looking for Service notifications, they are everywhere.

Why am I talking about notifications? Because it would be nice to have a notification showing the upload's progress. Right? Like this:

So, if your application requires uploading files to [api.video](https://api.video/), the solution would be to call the `upload` API from an Android Service.

I have an excellent news for you: **the [Android API client](https://github.com/apivideo/api.video-android-client) and the [Android video uploader](https://github.com/apivideo/api.video-android-uploader) comes with a fully customizable Service whose purpose is to upload files, called UploadService.**

## 2. api.video UploadService

The UploadService is the easiest way to upload video files to [api.video](https://api.video) on Android.
It supports:

- upload with video id
- upload with upload token
- progressive upload
- progress notification of the upload of the current file
- success notification
- error notification
- multiple uploads: it uploads files from an internal queue
- cancel the upload of a specific file or all files

Here is a small video to show how it’s used in the [‣ example](https://github.com/apivideo/api.video-android-uploader/tree/main/examples/service):

### UploadService notification customization

The UploadService comes with many levels of notification customization:

- Notification color and icon
- Notification messages
- Notification itself. You can choose not to display progress or to display the name of the file currently being uploaded. For example, notifications could have a Stop button.

To customize the UploadService, the first step is to extend the UploadService:

If you have a closer look at the UploadService constructor, you will notice that you can change the notification icon and color with:

To have more controls over the notification, you can override `onUploadProgressNotification`, `onUploadErrorNotification`, `onUploadStartedNotification`, `onUploadCancelledNotification`, `onUploadSuccessNotification`, `onLastUploadNotification`.

There is a solution for each of your requirements!

### Implementation

As with every service, you have to declare it in the `AndroidManifest.xml`

As the UploadService is a Foreground Service (a special type of service), you also have to add:

Nice. We are almost done. You have to start it and bind it. Fortunately, there is a static API to simplify its usage:

As startService binds your application to the UploadService, you must call UploadService.unbindService when your application is put to background.

Once you have access to the service, you can call upload API for a video id

## Conclusion

With the UploadService, uploading a video to [api.video](https://api.video) has never been this easy! For a complete example with the UploadService, check out the [‣ example](https://github.com/apivideo/api.video-android-uploader/tree/main/examples/service).

And we're done! To start building right now, check out our **[docs](https://docs.api.video/)**
and **[sign up for a free account](https://dashboard.api.video/register)**

Upload videos on your Android app with an Android Service

Upload-video-in-your-android-app.png

How to easily upload videos on your Android app with an Android Service?

Analytics

JavaScript

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

&nbsp;
 

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

## What data?

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

&nbsp;
 

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

## Requirements

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

&nbsp;

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


Blog_illustration_analytics.png

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

&nbsp;
    

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

&nbsp;

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

## The no-code way

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

&nbsp;

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

## The integrated way

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

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

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

### 2. Create a request

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

&nbsp;
 

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

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

Here’s an example response payload for this request:

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

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

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

Here’s an example response payload for this request:

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

### 3. How to use this data?

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

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

## Conclusion

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


&nbsp;


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

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

small_Blog_Analytics.png

thumbnail_Blog_Analytics.png

Blog_Analytics.png

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

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

Let's start mapping! 

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

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

If you don't know JavaScript, or the version of it that Observable's using, you don't have to. This tutorial will explain how to configure your map in a way where you don't have to know the JavaScript. If there's interest in having the JavaScript content explained more, let us know in our [community forum](https://community.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

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

apivideomapmarkerslivestream.jpg

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: 

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

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

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

Let's start coding! 

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

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

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

Here's the code we used to: 

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

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

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

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

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

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

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

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

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



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

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

 Build a Choropleth Map with api.video Analytics

choropleth, apivide, api.video, data analytics

choroplethapivideo.jpg

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

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

...and more! 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Using analytics to analyze where to edit a video

bekindrewindapivideo.png

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

Player SDK

video create

Video list

Player

Mobile

mathieu_round-1.png

Github Mathieu Thiry

LinkedIn Mathieu Thiry

Mathieu Thiry

React

Typescript

Next.js

This tutorial will show how quick and straightforward it is to build a TikTok clone as a progressive web app (PWA) with [api.video](https://api.video/use-cases/short-form/) and Next.js. A PWA is a website that looks and behaves like a mobile app. It can have all the capabilities of a native mobile app, like design and functionality, and you can even install it on your phone!

TikTok’s core functionality is to create and share short-form content. So today, we will focus on these crucial features:
- **Get** videos with [@api.video-node.js-client](https://github.com/apivideo/api.video-nodejs-client) package
- **Display** videos with [@api.video/react-player](https://github.com/apivideo/api.video-react-player) package
- **Upload** videos with [@api.video-typescript-uploader](https://github.com/apivideo/api.video-typescript-uploader) package
    
Thanks to these 3 easy-to-use api.video tools, you will have everything you need to build a **smooth scrolling** TikTok feed. Let's start 🎬
    

*NB: You can see the demo [here](https://api-video-tiktok-demo.vercel.app) and the complete code [here](https://github.com/apivideo/tiktok_clone). We invite you to clone the project, insert your free-to-use API key from our Sandbox environment and start testing it with your videos!*

Screenshot TikTok demo on desktop screen size

cover_image_tiktok_clone.png

## Quick Setup

As in this tutorial, we will focus on the core features. We provide two links on how to start the project easily: 

We created a dedicated [tutorial](https://github.com/apivideo/Next.js_Starters-) on building a **new Next.js application** using Create Next App and Typescript. Please follow these [instructions](https://github.com/apivideo/Next.js_Starters-) to get an up-to-date Next.js app.

1. Transform the Next.js app into a PWA with [next-pwa](https://www.npmjs.com/package/next-pwa). Complete all steps with this article [here](https://blog.avneesh.tech/how-to-create-a-pwa-with-nextjs).
2. Once inside our project, install api.video’s [Node.js client](https://github.com/apivideo/api.video-nodejs-client), [typescript video uploader](https://www.npmjs.com/package/@api.video/video-uploader), [react’s player SDK](https://www.npmjs.com/package/@api.video/react-player), and [swr](https://www.npmjs.com/package/swr) for data fetching.

## Get videos

## Back-end: **Create API routes with api.video/nodejs-client**

You can declare the API under the `pages/api` directory. When you declare a file or folder inside `pages/api`, it will generate an URL endpoint that matches `/api/<folder>/<file>`. We set our API key in an environment variable in the `.env.local` file for security.

Now create a `pages/api/videos/index.ts` file. Inside this file, add the following code:

We can get videos in just a few lines of code by applying the method `list`. Check more methods you can use with our *nodejs* client [here](https://github.com/apivideo/api.video-nodejs-client/blob/main/doc/api/VideosApi.md#list).

### Front-end: Client-side data fetching

**Initialize swr**

[useSWR](https://swr.vercel.app/docs/getting-started) is a React Hook library made by Vercel. It fetches data from an API or other external source, then saves that data in a cache and renders the data. We configure swr in `_app.tsx`.

The useSWR hook takes two parameters and returns data. It accepts the following:

- A `Key`: API URL we are calling.
- A `fetcher`: a function that returns the fetched data.

We call `useSWR` hook. Once we get the result, we store data in the state `videos`. Then, we  `map` videos around  `VideoComponent`, whose role is to display videos.

### How to create smooth scrolling

tiktok-demo-screenshot-mobile.png

The app has a `height: 100vh`. It has 2 sections. The first one, the div `app__video`, is scrollable with a `height: calc(100%-50px)`, and the second one, the upload section, has a fixed `height: 50px`.

**CSS scroll snap**

As written above, the class `app__videos` has the property `scroll-snap-type: y mandatory;` and  `overflow-y: scroll;` making the scroll vertical. This property allows for the creation of well-controlled scroll experiences by declaring a scroll snapping position, in our case, at the `start` of the video. To obtain this perfect result, we just need to add the property `scroll-snap-align: start` to the child component, here the `ApiVideoPlayer` *(see code in the section below.)*

## Display videos

We are going to use [api.video react player component](https://github.com/apivideo/api.video-react-player), which allows us to display our videos in just a few lines of code. The only requirement is to pass the `videoId`. Create a `ref` to manipulate methods like `pause` or `play` easily. We set the `object-fit` CSS property in `cover` to ensure that even a landscape video will take the full size.

## Upload a video

[api.video](https://api.video) provides a [typescript library](https://www.npmjs.com/package/@api.video/video-uploader) to upload videos to api.video using delegated upload token. The easiest way to create an upload token is to open your api.video’s dashboard, go to the upload tokens section from the sidebar, then click on the “*Create upload token*” button. Find the full guide [here](https://docs.api.video/vod/delegated-upload-tokens).

**Upload using delegated upload token**

We create a hidden input with a type `file` that we activate programmatically. Create a new object `VideoUploader`, and add two options, the `upload token` set as an environment variable for security purposes and the current `file` to upload.

That’s it. You are done 🎉. Now you can safely and efficiently upload videos.

## Conclusion

We recreated TikTok thanks to [api.video’s features](https://api.video/use-cases/short-form/) in just a few steps. We did not cover every topic, but the entire code is available [here](https://github.com/apivideo/tiktok_clone).

And we're done! To start building right now, check out our **[docs](https://docs.api.video/)** and **[sign up for a free account](https://dashboard.api.video/register)**.

***BONUS***

In this part, I will explain how **to send** 💟’s

Each video object has a `metadata` property containing an array of key-value objects. So we can add a ‘*likes*’ metadata with a numeric value and increase this value when the user has pressed on the 🤍 icon!

To record the new data, we need to update the video by making an API call 

Note: Find a full description of the upload method [here](https://github.com/apivideo/api.video-nodejs-client/blob/main/doc/api/VideosApi.md#update).

Ready to build your own TikTok-like project? Get started by [signing up](https://dashboard.api.video/register) with api.video!

Build your own TikTok with PWA and api.video

large_cover-tiktok-s-clone.png

medium_cover-tiktok-s-clone.png

small_cover-tiktok-s-clone.png

thumbnail_cover-tiktok-s-clone.png

cover-tiktok-s-clone.png

SDKs and libraries

olivier.png

Olivier Lando

In this tutorial, we'll see how to build a Loom-like web application using the JS library we've just released: [@api.video/media-stream-composer](https://github.com/apivideo/api.video-typescript-media-stream-composer).

## **Presentation**

### **The Loom tool**

For those who do not know the Loom tool, here is the description that can be found on their site:

> Loom is a video messaging tool that helps you get your message across through instantly shareable videos.
> 
> 
> With Loom, you can record your camera, microphone, and desktop simultaneously. Your video is then instantly available to share through Loom's patented technology.
> 

Here we will create a simplified version of Loom, which will incorporate its main functionality, namely uploading videos from a screencast with the user's webcam overlaid as a rounded thumbnail.

### **The @api.video/media-stream-composer JS library**

The [@api.video/media-stream-composer](https://github.com/apivideo/api.video-typescript-media-stream-composer) aims to simplify handling video streams in browsers.

Here are its main features:

- generated a video stream composed of several video streams available in browsers (webcams, screen recording)
- easily generate & upload this video stream to [api.video](https://api.video/) using api.video's progressive upload feature
- let the user interact with the stream composition on the fly (by moving/resizing each base stream or drawing in the result stream)

The library can be easily included in any web page or added as a dependency to a project, for example, in a React.js application. For more information, feel free to check out the [readme](https://github.com/apivideo/api.video-typescript-media-stream-composer) on GitHub.

### **What it will look like**

What we will build will take the form of a simple web page where the user will have to choose the screen window he wants to save.

Then this window will be displayed on the web page with the webcam in superposition. It will be possible to move and resize the webcam view.

A button will allow you to start and stop the recording. Once the recording is finished, a link to the uploaded video will be displayed.

loom-like-app-screenshot.jpg

## Prerequisites

The only things you’ll need are:

- a text editor
- an [api.video](https://api.video) account - you can easily create a free sandbox account by going here: [https://dashboard.api.video/register](https://dashboard.api.video/register).

## **Let’s do it!**

### **Page layout**

The first step will be to write the HTML code of the web page. It will be very straightforward since it will contain only the following elements:

- a div container that will contain the preview of the recording
- 2 buttons to start and stop the recording
- a select input to choose the mouse tool: move/resize or drawing
- a text holder for the video link

This is what it looks like:

### **The @api.video/media-stream-composer library**

### **Initialization**

Let's get serious! The first step here is to include the script of the library. To do this, we'll add the following in the `<head>` tag of the page:

Fine, the script is now included; we can now add some JS code to initialize the library. To keep it simple for this tutorial, all the JS code will be directly included in the HTML page.

Let's add the following before the closing `</body>` tag:

In this snippet, we create the `MediaStreamComposer` instance. The `MediaStreamComposer` is a class that will allow us to compose a video stream from several video streams available in browsers.

Then, we append the canvas created by the `MediaStreamComposer` to the `#canvas-container` div. By doing so, the video stream will be displayed on the web page, and the user will be able to interact with it.

We can add our video streams now that we have initialized our library.

### **Adding video streams**

We will add two streams to our composition:

- a screencast of the user's screen in the background
- a webcam stream in a rounded thumbnail in the bottom left corner

Adding a stream is done with the `addStream()` method. It takes 2 parameters: the MediaStream, and the settings object specifying how the stream should be displayed.

First, we have to request the browser to give us the streams. This is done with the `navigator.mediaDevices.getUserMedia()` & `navigator.mediaDevices.getDisplayMedia()` methods.

Now that we have the streams, we can add them to the composer.

Done! The streams are now added to the composer, and the video stream is displayed on the web page. We can now configure the drawing tool.

### **Drawing tool**

The drawing tool is a simple pen that will allow the user to draw on the video stream. It can be configured using the `setDrawingSettings()` method as follow:

Nice! We're almost done. The last step is to add some buttons & inputs to the web page so the user can interact with it.

### **User interactions**

To simplify the task, we will first create constants containing references to the buttons & inputs.

We can now bind the events to the buttons & inputs.

*The `start` button*

When the user clicks on the `start` button, we can call the `MediaStreamComposer` to start recording. We will use the `startRecording()` method. This method takes an `uploadToken` as a parameter. An upload token is a unique identifier that will be used to upload the video to api.video. You can create a new upload token using the API or directly from the api.video dashboard.

*The `stop` button*

When the user clicks on the `stop` button, we will call the `stopRecording()` method. This method returns a Promise that will be resolved when the recording is stopped. The Promise's value is an object containing the details about the uploaded video. We will retrieve the video URL from the object and display it in the `video-link` element.

*The `tool-select` select*

This select box will allow the user to select the action performed when the user clicks on the video stream. It can be either "drawing" or "moving / resizing a stream". Choosing a tool is done by calling the `setMouseTool()` method.

## **To go further...**

The media stream composer library allows you to do many other things, like selecting a different audio source from the video streams, or adding static images to your composition (to display a logo for example). For more information, feel free to check the readme on the github repo.

## **Conclusion**

You have seen how easy and fast it is to create this application using the @api.video/media-stream-composer library.

The full code is available in the repo of the library on GitHub here: [examples/screencast-webcam.html](https://github.com/apivideo/api.video-typescript-media-stream-composer/blob/main/examples/screencast-webcam.html).

You can see the demo live at [https://record.a.video/screencast-webcam.html](https://record.a.video/screencast-webcam.html).

To see a more complex example, in action, look at [https://record.a.video](https://record.a.video/). You'll be able to test almost all the features of the library in action.

Ready to build your own Loom-like App? Get started by [signing up](https://dashboard.api.video/) with api.video!

Video on demand

Live streaming

Analytics

Video infrastructure

Video player

See all features

Online learning

Short-form videos

Marketplace & E-commerce

Video messaging and recording

Quickstart guides

Documentation

Ecosystem catalog

Clients & SDKs

Community

Blog

Demos

Help center

Video upload