Delegated Upload

API client

Video upload

Normal

large_img_8063-min-1.jpg

medium_img_8063-min-1.jpg

small_img_8063-min-1.jpg

thumbnail_img_8063-min-1.jpg

img_8063-min-1.jpg

github-brands.svg

GitHub Yohann

5a22d420c9a5a7-416105621512231968826.png

LinkedIn Yohann

Yohann Martzolff

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

JavaScript

React

NodeJS

Next.js

Uploading a video to [api.video](https://api.video) can be done in several ways: 

- **API:** make calls to get the mandatory information such as access token, create your fully customized video container, and finally upload your video file 🧑‍💻.
It’s the most secure way to upload, but it requires a backend to hide sensitive data and several API calls. Even though it’s easy, customizable, and reliable, you may need a faster way to do this.
- **TypeScript uploader:** [api.video](https://api.video) provides a [TypeScript uploader](https://www.npmjs.com/package/@api.video/video-uploader) that allows you to upload video directly to your workspace without calling the API. You can even choose between three upload methods 🤩!
Don’t forget you still have to implement a UI for your uploader if it’s not already done!
- **React upload button:** a few weeks ago, we quietly released the first version of our [React upload button on NPM.js](https://www.npmjs.com/package/@api.video/react-upload-button).
This new package allows you to display a fully customizable button in your application in less than a minute!
Today, we will see together how to get mandatory information from a Node backend to use this React component without exposing any sensitive data 🔒.

## **Prerequisites**

- [React](https://reactjs.org/docs/getting-started.html) and [NodeJS](https://nodejs.org/en/) knowledge
- For the simplicity of this example, we’ll use [Next.js](https://nextjs.org/), a React framework that provides an already implemented Node server. Basic knowledge of it can help you go through this tutorial.

Remember that any Node backend will work to get information, as seen in this article.

## Get started

You need an [api.video](https://api.video) account to work with our API and our packages.

[**Create a free one or log into yours just here.**](https://dashboard.api.video/login)

## 1. Create a new Next.js application

From your command line, run one of the below commands:

Once completed, open your new Next.js application in your favorite IDE and run it:

large_screenshot-2022-05-23-at-10-30-25.png

medium_screenshot-2022-05-23-at-10-30-25.png

small_screenshot-2022-05-23-at-10-30-25.png

thumbnail_screenshot-2022-05-23-at-10-30-25.png

next-js-new-application.png

## 2. Get the required packages

To complete this tutorial, we’ll need two [api.video](https://api.video) packages 🛠️

- **NodeJS client package:** to access the API with ease
- **React upload button:** to upload our videos

From your application root, run this command:

## 3. Create a .env.development file

Create a `.env.development` file at the root of your application and store two environment variables in it:

- The **Next.js public API host:** to access the implemented Node.js API from Next
- Your **API key value:** to instantiate the Node.js client from api.video

You can find your API key on the right hand column of your dashboard 'Overview' page. 

large_Screenshot 2024-02-21 at 4.55.04 PM.png

medium_Screenshot 2024-02-21 at 4.55.04 PM.png

small_Screenshot 2024-02-21 at 4.55.04 PM.png

thumbnail_Screenshot 2024-02-21 at 4.55.04 PM.png

copy-api-key-through-dashboard.png

⚠️ You need to **restart your application** each time you’ve made changes in your .env.development. Otherwise, you cannot access new environment values.

## 4. Create your API endpoint

In this part, we want to create **one API endpoint** that allows us to make **two actions**:

- **Retrieve** our upload tokens list
- **Create** one if needed

To do this, we will differentiate the calls to this endpoint by HTTP methods:

- **GET** to retrieve our upload tokens list
- **POST** to create one upload token

Create a new file under the `/pages/api` directory in your application and name it `uploadTokens.ts`

thumbnail_screenshot-2022-05-23-at-11-26-11.png

application-project-tree.png

### Retrieve your upload tokens list

In your brand new `uploadTokens.ts` file, create your endpoint and the method to retrieve your upload tokens list. Copy and paste the code below:

*[Find the official documentation for the upload tokens list method here.](https://github.com/apivideo/api.video-nodejs-client/blob/main/doc/api/UploadTokensApi.md#list---list-all-active-upload-tokens)*

### Create a new upload token

We may need to generate a new upload token if we don’t have any available.
Add the creation method in your `uploadTokens.ts` file:

*[Find the official documentation for the upload token createToken method here.](https://github.com/apivideo/api.video-nodejs-client/blob/main/doc/api/UploadTokensApi.md#createtoken---generate-an-upload-token)*

## 5. Call your API

Now we can **retrieve our upload tokens list** and **generate a new one** on demand. We’ll see how to make it happens from the **front end.**

Let’s clean our Home component 🧹
Go to your `pages/index.tsx` file and modify it:

Now our app is nice and clean, let’s implement our logic in 2 steps:

- We want to check if we have any available upload tokens from our upload tokens list.
- If we do not have any upload token, we want to create one.

### Set your upload token

Create a new method that calls your API endpoint `uploadTokens` to retrieve your list, and create one if the list is empty. You should call it in a useEffect inside your Home component:

Call the method in a useEffect inside your Home component:

## 6. Click. It’s magic! 🧚

Already? 😱

Everything should work well now. Click on the displayed button in your application and choose a file to upload to your [api.video](https://api.video) workspace.

large_screenshot-2022-05-23-at-16-04-10.png

medium_screenshot-2022-05-23-at-16-04-10.png

small_screenshot-2022-05-23-at-16-04-10.png

thumbnail_screenshot-2022-05-23-at-16-04-10.png

upload-application-screen.png

## 7. Customize your upload button 💅

You can customize multiple things to make your upload button unique:

- CSS: make it looks the way you want
- Progress event: trigger a callback on upload progress
- Success event: trigger a callback on upload success
- Error event: trigger a callback on upload error

**[Check our complete list of examples for inspiration](https://codesandbox.io/s/great-shtern-0ck5eo?file=/src/App.tsx)** 🧘

How to upload a video with React and NodeJS

small_UploadReactNodeJs.png

thumbnail_UploadReactNodeJs.png

Upload-React-NodeJs.png

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

Video sharing apps like TikTok offer 'duets', where you record a video next to a video playing back, add a commentary, or sing along. In this demo, we'll build a duet app in the browser!



## Creating a duet

For a duet, you need to have a camera, a mic and a video that you want to duet with. Since the video you are singing along with plays out loud, using headphones is recommended for best results. Due to varying support of media APIs, this demo will work in Chrome, Edge and Firefox, but will not run in Safari. :(

The default sing-along video is Nathan Evans singing "The Wellerman," a sea shanty that has been a viral duet hit on TikTok this year, but you can change this with the video URL input box on the left side of the screen. 

When you access the site, it will ask you for access to the camera and mic for camera and mic access - this is clearly required for your duet. Once you've approved usage, choose which mic/camera combo you'd like to use, and start recording.  Both you and Nathan will appear next to each other. Sing to your heart's content, and when you are done with the duet, press "stop."  The video playback will stop and your video will be uploaded to api.video.  In a few seconds the video will be ready for playback at the link provided.

(If you notice that your video/audio is a bit delayed from the singer in the video, you can move the video delay slider and it will shift your video/audio by 50ms to help you sync them up.  We'll discuss why this is needed in the implementation section.)

## How it all works

Much of this code was restructured from our [record.a.video](https://record.a.video) app - rather than sharing a screen - we share a video. 

### Routing the video

The video from the camera and the video are both drawn to a canvas. The canvas is then sent to a MediaRecorder. When the recording is completed, we use the videoUploader to upload the video to api.video.

large_screenshot-2021-09-17-at-12-00-44.png

medium_screenshot-2021-09-17-at-12-00-44.png

small_screenshot-2021-09-17-at-12-00-44.png

thumbnail_screenshot-2021-09-17-at-12-00-44.png

screenshot-2021-09-17-at-12-00-44.png

Interesting features:

When grabbing the video from the camera, you can specify the aspect ratio:

```
 var videoOptions = {
            deviceId: cameraId,
            aspectRatio: {ideal: 9/16},
            
            frameRate: {ideal: cameraFR}
        };
```

To keep this 'TikToky', we'll force the video capture to be portrait (9/16). This is supported in Chromium browsers, but not in Firefox (so we lay out the video differently for FF users):


large_screenshot-2021-09-17-at-12-12-11.png

medium_screenshot-2021-09-17-at-12-12-11.png

small_screenshot-2021-09-17-at-12-12-11.png

thumbnail_screenshot-2021-09-17-at-12-12-11.png

screenshot-2021-09-17-at-12-12-11.png

The video from the canvas is captured and sent to the MediaRecorder. When recording is complete, the video is then uploaded to api.video.

### Routing the audio

In record.a.video, there is just one audio input source - the mic. In duet.a.video, we have 2 audio sources, the mic and the video. We cannot simply add a second audio track to the MediaRecorder - it only supports one audio track. So, we look to the Web Audio APIs to help us 'mix' the audio.

In the code below, we create audiocontexts for the streams from the mic and from the video:

```
  //audio track from mic "audioStream"
     micAudioIn = audioContext.createMediaStreamSource(audioStream);

  //audio track from video
    if(videoElem.captureStream){
                videostream = videoElem.captureStream();
   }else{
                videostream = videoElem.mozCaptureStream();
  }
  videoAudioIn = audioContext.createMediaStreamSource(videostream);
  videoAudioin2 = audioContext.createMediaStreamSource(videostream);
```

micaudioIn is the audio context form the microphone, and the videoAudioIn is the audio extracted from the video. The ```captureStream``` property is considered experimental, so Firefox requires the mozCaptureStream property. (This is where Safari fails us, there is no support for captureStream in Safari).

large_mdnsupport.png

medium_mdnsupport.png

small_mdnsupport.png

thumbnail_mdnsupport.png

mdnsupport.png

You may have noticed that we create two contexts for the audio from the video. In Chrome, when you extract the audio from a video to an audiocontext, the audio still goes to the speaker. In Firefox, the audio is extracted to the audiocontext, and does NOT get routed to the speaker.

large_audiocontextbrowser.png

medium_audiocontextbrowser.png

small_audiocontextbrowser.png

thumbnail_audiocontextbrowser.png

audiocontextbrowser.png

The solution is to create 2 audiocontexts for the video, and send the second one to the speakers (audioContext.destination is the default destination of the audio):

```
		videoAudioin2 = audioContext.createMediaStreamSource(videostream);
		//i want to send videoAudio2 to te speakers
		videoAudioin2.connect(audioContext.destination);


```

Going back to the mic and the audio from the video, we must combine them into one stream and connect them to the MediaRecorder.  This is relatively easy, but first we want to do some audio 'mixing.'

We will perform 2 operations on the video's audio stream: a volume & a delay control.

### Volume mixing

When adding 2 videos, perhaps one video is louder than the other one. The createGain() property of the audio context lets you raise or lower the volume of an audio track. Since there are only 2 tracks being mixed in, we just need to be able to adjust one track - so we modify the volume of the video. In the case of the "Wellerman" video, I found 50% to be sufficient.

I also found that the microphone audio was delayed compared to the audio from the video (try clapping along with a video when the delay is set to zero - the results are disconcerting). We can add a delay() to the video's audio to re-sync the 2 streams. You can set this value with the slider in the app (each step is 50ms of delay). For my computer, I found that 250ms helped to sync the two videos.

We then combine the two streams and add them to the mediaRecorder we created with the video.

```
     //change the volume of the video in
            var gainNode = audioContext.createGain();
            var volume = document.getElementById("volume").value/100;
            console.log("vol", volume);
            videoElem.volume = volume;
            gainNode.gain.value = volume;
            videoAudioIn.connect(gainNode);

            //delay the video in a bit
            var delay = audioContext.createDelay();
            
            delay.delayTime.value = micDelay;
            delay.connect(gainNode);

            //heres the destination for the combined audios
            audiocontextDest = audioContext.createMediaStreamDestination();

            //add the audio to the destination
            micAudioIn.connect(audiocontextDest);
            gainNode.connect(audiocontextDest);
            
            //ok so now the audio is in the audiocontextDest stream
            //grab the stream
             var audiocontextDestStream = audiocontextDest.stream;


             //grab the audio track from the stream
             var audiocontextDestStreamAudioTracks =  audiocontextDestStream.getAudioTracks();
            //add the audio track to the canvas output stream (the video)
            stream.addTrack(audiocontextDestStreamAudioTracks[0]);
            console.log("audio stream added!");
```


Now that both video and audio are added to the MediaRecorder - we can use the api.video [video uploader JS](https://docs.api.video/sdks/vod/apivideo-typescript-uploader) library to upload our duet to api.video. 




large_audioflow.png

medium_audioflow.png

small_audioflow.png

thumbnail_audioflow.png

audioflow.png

## Conclusion

That's all there is to it! Along the way, we've gotten to play with some fun web audio and video APIs to manipulate and mix the audio and video in the browser into the recording we create.  

Try out [duet.a.video](https://duet.a.video) for yourself. The code is on [GitHub](https://github.com/dougsillars/duetavideo) if you'd like to reuse and create your own duet app.

If you have any questions or suggestions, please share them on our [community forum](https://community.api.video). If you don't have an api.video account yet, you can register in just a few moments by following [this link](https://dashboard.api.video/register). Happy building! 


Video duets in the browser

thumbnail_hqdefault.jpeg

hqdefault.jpeg

video create

Uploading a video to api.video just got easier!

We have created a [JavaScript uploader](https://docs.api.video/sdks/vod/apivideo-typescript-uploader) script to abstract this code into a single function - allowing you to focus on your code and making the video upload process easier for you and your development team!


## JS Uploader Widget

You can read about uploading a video in the [tutorial](https://api.video/blog/tutorials/uploading-large-files-with-javascript/) describing the code. The JS Uploader widget abstracts the file slice, creating all of the headers, and uploading the files - it also adds retries for segments that have issues!

The new code for uploading is under 30 lines, and most of that is for updating the page during the upload.

First, we add the script to the head (with a defer tag to not slow page load)

```
   <script src="https://unpkg.com/@api.video/video-uploader" defer></script>

```
Next we have a event listener for changes in the file upload form:

```
     input.addEventListener('change', () => {
       console.log("upload commencing");
       uploadFile(input.files[0]);
       function uploadFile(files) {
           const uploader = new VideoUploader({
               file: input.files[0],
               //changed to sandbox, because we cannot have nice things
               uploadToken: "to5PoOjCz98FdLGnsrFflnYo",
               chunkSize: 1024*1024*10, // 10MB
               retries: 10
           });
           uploader.onProgress((event) => {
               var percentComplete = Math.round(event.currentChunkUploadedBytes / event.chunksBytes * 100);
               var totalPercentComplete = Math.round(event.uploadedBytes / event.totalBytes * 100);
               document.getElementById("chunk-information").innerHTML = "Chunk # " + event.currentChunk + " is " + percentComplete + "% uploaded. Total uploaded: " + totalPercentComplete +"%";
           })
           uploader.upload()
               .then((video) => {
                   console.log(video);
                   playerUrl = video.assets.player;
                   console.log("all uploaded! Watch here: ",playerUrl ) ;
                   document.getElementById("video-information").innerHTML = "all uploaded! Watch the video <a href=\'" + playerUrl +"\' target=\'_blank\'>here</a>" ;
               });
       }
     });

```

### Walking through the code

The uploadFile function takes the files and creates an uploader function:

```
 const uploader = new VideoUploader({
               file: input.files[0],
               //changed to sandbox, because we cannot have nice things
               uploadToken: "to5PoOjCz98FdLGnsrFflnYo",
               chunkSize: 1024*1024*10, // 10MB
               retries: 10
           });

```

The chunkSize defaults to 50MB, but I have lowered this to 10MB for the sake of the demo, so you can see multiple chunks uploaded.

The retry count defaults to 5.  

#### During Upload

```
 uploader.onProgress((event) => {
               var percentComplete = Math.round(event.currentChunkUploadedBytes / event.chunksBytes * 100);
               var totalPercentComplete = Math.round(event.uploadedBytes / event.totalBytes * 100);
               document.getElementById("chunk-information").innerHTML = "Chunk # " + event.currentChunk + " is " + percentComplete + "% uploaded. Total uploaded: " + totalPercentComplete +"%";
           })


```

The onProgress updates the video upload every 50ms.  We calculate the % uploaded, and update the browser - so the user is aware that the video upload is underway.

#### Upload complete

When the video upload is complete, the API will reply with the videoId, and links to the video. We take this information to display the url to the user:

```
           uploader.upload()
               .then((video) => {
                   console.log(video);
                   playerUrl = video.assets.player;
                   console.log("all uploaded! Watch here: ",playerUrl ) ;
                   document.getElementById("video-information").innerHTML = "all uploaded! Watch the video <a href=\'" + playerUrl +"\' target=\'_blank\'>here</a>" ;
               });

```


## Conclusion

The new JS video uploader widget weighs in at just 11.5 KB, and as it is not required until after the page loads, will not impact your page speed (as long as you use the defer tag).

It will make building video upload widgets in JavaScript easier, as we've abstracted all the complexity into the library - allowing you to focus on your application, and not on the intricacies of partial uploads of video files.

Read all of the [technical details](https://docs.api.video/sdks/vod/apivideo-typescript-uploader) in our documentation, and [get started](https://dashboard.api.video/register) with your video app uploads today!


New video uploader JavaScript library

large_new-video-uploader-javascript-library.png

medium_new-video-uploader-javascript-library.png

small_new-video-uploader-javascript-library.png

thumbnail_new-video-uploader-javascript-library.png

new-video-uploader-javascript-library.png

The first demo we published on a.video was a demo on how to upload a video (check it out yourself at [https://upload.a.video](https://upload.a.video). This is a great little demo that will take your video, break it into smaller chunks (1 MB in this case), and upload them into api.video. Once the uploads are complete, you get a link to the url where the video will soon be available for playback. You can read the [post describing how we built the app](https://api.video/blog/tutorials/uploading-large-files-with-javascript/).

## More than one video

What if you'd like to upload a few videos? You could use this interface multiple times, but that would be slow and tedious.  

To resolve this, I've created a new version of the uploader at [https://upload.a.video/many.html](https://upload.a.video/many.html) that allows you to upload more than one video at a time. It only took about 5 lines of added code to make the change from one video to many.

Let's walk through what I did to make this happen.

### Input

First, we need to allow the form to accept multiple files.  This is a one word change:

```
	<input type="file" id="video-file" style='display:none'>
```

to

```
	<input type="file" id="video-file" style='display:none' multiple>
```

This basically tells the browser that users can select more than one file at a time. With this line added, you can select multiple adjacent files while holding the shift key, or multiple non-adjacent files holding the command (on a Mac) key.

### Uploading multiple files

In upload a video, only one video could be uploaded at a time. When you add files via a form, they are placed in an array, so once the button to upload was clicked, we defined the video and the video name based on the file in index 0 of the array:


```

			const file = input.files[0];
			const filename = input.files[0].name;
			
			<upload stuff>

```

There's just one file, so grab the file in index 0, grab the filename and upload the file to api.video.  Extending this to more than one file is easy: create a loop over the array of files (incrementing index i), and upload each file in the array by referencing file i in the array:

```
  const numberofFiles = input.files.length;
	for( i=0;i< numberofFiles; i++){
			//do the upload for each file.

			const file = input.files[i];
			const filename = input.files[i].name;
			<upload stuff>
			
	}

```


### Make the UI look nice

So that was probably the 5 lines of code I promised, (6 if you count the comment).  But the UI was weird, since the notifications and text were updating and overlapping for each file being uploaded - and you couldn't read anything as the text was changing so quickly.  So, let's fix that.  I changed 3 lines of code here:

First: the upload information is changed to show information for each video by appending the HTML and adding the video number: 

```
			document.getElementById("video-information").innerHTML += "Video "+ i +" will be uploaded in " + numberofChunks + " chunks.<br/>"

```


Second: as the videos upload, so the upload information should update for each video:

```
document.getElementById("chunk-information").innerHTML = "Video: " +i+" Chunk # " + chunkCounter + " is " + percentComplete + "% uploaded. Total uploaded: " + totalPercentComplete +"%";
```

This one just overwrites itself all the time.  I could probably make this look nicer, but for a demo, it's ok.

When the upload is completed, we add the completed upload notice, along with the url where the playback can be watched:

```
	document.getElementById("video-information").innerHTML += "Video " +i+" is uploaded! Watch the video <a href=\'" + playerUrl +"\' target=\'_blank\'>here</a><br/>" ;

```

All three of these lines were already in the code, I just updated them to fit the multiple upload function of the application. That said, with a grand sum of 8 lines of uploaded code, we've modified [https://upload.a.video](https://upload.a.video) to [https://upload.a.video/many.html](https://upload.a.video/many.html), allowing for more than one video to be uploaded at once.

## Try it out

With ~10 lines of modified code, I've taken a page built for a single video uploaded a page that can now handle many videos, and show the links to the videos when they are completed.

That said, since this is a live demo, I have placed a limit of 3 files per upload, just to keep my account from filling up with videos.  These videos will also be stored in the sandbox: so watermarked and deleted after 24 hours.

```
var maxUpload = Math.min(numberofFiles, 3);

		for( i=0;i< maxUpload; i++){
			<file selection & upload stuff>
		}
```

The code is live at [https://upload.a.video](https://upload.a.video), and available on [Github](https://github.com/dougsillars/blobUpload/blob/master/many.html). Give it a try, and let us know what you think!

Upload many files at once with HTML and JavaScript

medium_maxresdefault.jpeg

small_maxresdefault.jpeg

thumbnail_maxresdefault.jpeg

maxresdefault.jpeg

captions

Video Status

Video captions/subtitles make it easier to follow along with your video. Whether your users have hearing issues or not, sometimes they may not want to have a loud speaker playing the video's audio, and adding captions allows them to understand the video.


medium_screenshot-2021-02-26-at-15-02-16-1.jpg

small_screenshot-2021-02-26-at-15-02-16-1.jpg

thumbnail_screenshot-2021-02-26-at-15-02-16-1.jpg

screenshot-2021-02-26-at-15-02-16-1.jpg




When adding captions to a video, you must create a WebVTT file. We've [written on the process of creating WebVTT files](https://api.video/blog/tutorials/how-to-add-captions-to-your-videos/). The format is not difficult to understand, but they are not simple to create manually, you need to break up a transcription into segments, and add start and stop times for each section.  


```

3
00:00:07.519 --> 00:00:11.759
The little train rumbled over the tracks.

4
00:00:10.880 --> 00:00:15.279
She was a happy little train for She had such

5
00:00:13.439 --> 00:00:16.719
a jolly load to carry.

6
00:00:15.599 --> 00:00:20.480
Her cars were filled full of good things for boys

7
00:00:18.879 --> 00:00:21.199
and girls.

```



In this post, we'll show how using the [Authot](https://www.authot.com/) transcription APIs can help you automatically add video captions to your videos, without the fuss of manually creating the VTT caption file.

Authot will receive the video file, make a transcription of the audio file, and then return a complete webVTT file. api.video can then ingest this file into the same videoID as the video, and the captions are added to the video.

It sounds like magic! To prove that it actually works, we've built a demo application [caption.a.video](https://caption.a.video) that utilizes api.video and Authot to host, stream and auto-caption your videos.  

## How it works

The first step is to upload your video to api.video.  This demo is built on top of a [delegated token upload](https://api.video/blog/product-updates/video-access-management-how-to-create-deliver-and-manage-private-videos-and-what/), meaning that a temporary public token was created that lets us upload right from the browser.



### Upload complete

Once the video is uploaded, api.video begins transcoding into a HLS sstream and an MP4 version of the movie.  To create a transcription, Authot requires the mp4 file, so the application uses the [video status](https://docs.api.video/reference#get-video-status/) endpoint to determine when the mp4 video has been encoded. This endpoint tells us when each video stream is ready for playback. Once the mp4 is encoded, we can submit the file to Authot for transcription.

### Transcription

Once the video has been submitted to Authot, the API returns the ID number of the transcription.  The Status endpoint tells us what state the transcription is in.  

The initial state is 0: Uploading

The final state is 10: transcoded

There are some states in between, including 2: transcribing

### Getting the WebVTT

Once the transcription is complete, (when Authot returns the status "10"),  the Node server requests the VTT file, and then uploads the file to the existing video at api.video.

### Completed

The webpage finally updates the text, saying "success".  Clicking the video link - opens the video, and the user can enable captions and watch them play back.


## Automatic captions!

Of course, automatic captions are not 100% accurate.  You may have a few words incorrectly transcribed.  However, in my testing the Authot API is pretty good, and the captions are of a very high quality.

On the other hand - manually creating captions will either take a lot of time, or cost a lot of money (to pay someone else to do the work).  The ease of use, and low cost makes auto-captioning a compelling choice


## Conclusion

We've described an application that allows you to upload a video and automatically add captions to the video.  Try it out today at [caption.a.video](https://caption.a.video). If you're curious on how we built this app, the code is available on [Github](https://github.com/dougsillars/captionavideo).  Let us know what you think by posting on our [community forum](https://community.api.video/).

Add captions, and watch your video watch time increase!

Auto Caption a video

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

If you've used delegated tokens to make uploads, you might have a bunch of tokens floating around that you don't know about. With a little bit of code, you can find out how many tokens you have and whether they're going to expire soon. You can also retrieve details about a specific token, or delete one if you have the token identifier. We'll go over how to do all of this in this tutorial! 

Take inventory of all your tokens with this code sample.

thumbnail_token.jpeg

token.jpeg

## Code Sample
For starters, here's the complete code sample for everything we'll be doing. 

## List All Delegated Tokens
You can list all delegated tokens you've created by calling the upload-tokens endpoint. Following the complete code sample posted above, after you retrieve your authentication token, you send a request with an optional query string where you can filter how the tokens are returned.

If you set currentPage in your request, the tokens will be returned from the page you choose onwards. If you don't have that many to reach that page, then you won't receive any tokens back. You can also set how many tokens come back per page. Finally, if you don't set any of this information, the default is 25 tokens per page, and information is returned from the first page onwards. 

Another way to filter how the data comes back is by token's time-to-live and when it was created. 

## Retrieve Details About One Token
You can retrieve details about a token if you have the unique identifier for the token. This is actually the value of the token itself when you create a new one. 

If you save token information, you can add it to a request to retrieve details. Otherwise, you can try list all tokens and then search for the one you want information about. 

Retrieving information about a token is straightforward, you include the token in the URL of your request, and authenticate as normal. 



## Delete a Token
You may find that you accumulate more delegated tokens than you expect. Because they don't expire if you don't add a time-to-live, you may want to delete them after awhile. To do that, use retrieve all tokens to find which tokens haven't expired, then send a DELETE request with the token as part of the URL. 

If you want to find out more about what you can do with delegated tokens, give [delegated uploads](https://api.video/blog/tutorials/delegated-uploads-for-videos-large-and-small-python/) a try! 

## You May Also Like...

* [Delegated Uploads for Videos Large and Small](https://api.video/blog/tutorials/delegated-uploads-for-videos-large-and-small-python/) - Upload files over and under 128MB with these Python code samples.
* [Upload a Big Video File](https://api.video/blog/tutorials/upload-a-big-video-file-using-python/) - If you don't want to use delegated tokens, you can upload files over 128MB with your authorization token using Python. 
* [Upload a Video with the api.video API Using a Public URL](https://api.video/blog/tutorials/upload-a-video-with-the-api-video-api-using-a-public-url-python/) - Transfer a video from a public URL to api.video using Python.

Listing, retrieving, and deleting delegated tokens

large_pexels-thisisengineering-3861959.jpg

medium_pexels-thisisengineering-3861959.jpg

small_pexels-thisisengineering-3861959.jpg

thumbnail_pexels-thisisengineering-3861959.jpg

pexels-thisisengineering-3861959.jpg

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

medium_uploadbar.jpg

small_uploadbar.jpg

thumbnail_uploadbar.jpg

uploadbar.jpg

Authenticate

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

small_BigFileWithPython.png

thumbnail_BigFileWithPython.png

Big-File-With-Python.png

Private Videos

Where I live in the UK, there are miles and miles of footpaths - publically accessible trails that cross private property.  There's an expectation that those that use the public footpaths will respect the land/plants/crops of the private owners, in exchange for access to the beautiful countryside.

## Public access to api.video

api.video has a concept of [delegated tokens](https://api.video/blog/tutorials/delegated-uploads) which works like a public key - granting anyone with the key access to upload videos into your account. Now, much like the public footpaths, the usage of the public key is expected to be reasonable, and not overused.

But...it is the internet. While most of the users will behave and use the delegated upload appropriately, there might be a bad egg or two that cause issues. To help mitigate public token upload abuse, we have added [revocation](https://docs.api.video/reference/api/Upload-Tokens#delete-an-upload-token) of delegated tokens. We also have added a 'time to live' where you can provide an expiration time (in seconds) to your token.

So we've wrapped some security around the major vector to delegated token abuse. Even with this change, we have not alleviated all the questions from our customers who are grappling with ideas of privacy with a public token.  In this post, we'll show how to address the most common concerns we've heard from our users. 






## Public, but Private

*"Can I have a 'one use' delegated token?*

This is a fabulous idea - it completely removes the issue of delegated token abuse - the token "self destructs" upon video upload.



thumbnail_single-use.jpeg

single-use.jpeg

*"Can I make a delegated upload private by default?"*


A [private video](https://api.video/blog/tutorials/tutorial-private-videos) has a unique token in the url that allows **one view** of the video.  Each time the video is served, a new URL must be requested from api.video. This prevents the general public from seeing the video, and allows you to decide on the access.  By default, all videos are public.

Sometimes, as we walk the footpaths, we come across a path that is marked as private - the landowner does not want the public in that area.  

Setting a public, delegated token to private videos is like the "No Trespassing sign" on the footpath.

medium_notrespassingbydjuradjvujcic.jpg

small_notrespassingbydjuradjvujcic.jpg

thumbnail_notrespassingbydjuradjvujcic.jpg

notrespassingbydjuradjvujcic.jpg



*"Can I disable mp4 download link by default?"*

By default, the ```mp4Support``` parameter is set to ```true```, allowing the download of a private video.  By setting this to false, you can prevent the download from occurring.  Another "keep out" sign on the public path, if you will.


medium_forbidden.jpg

small_forbidden.jpg

thumbnail_forbidden.jpg

forbidden.jpg

 
### Private access, but with the public token??

Can we make the video private and disable the mp4 *while* using the public delegated token?  You can!  

Can we create a single-use delegated token - one per video upload?  Yes, we can (to a degree).  But I think this approach is close enought to a unique upload token to be secure and protect your account from bad actors on the internet.


## Demo Time

We've created a demo showing a public/private upload.  You can try it out yourself at [privatelyupload.a.video](https://privatelyupload.a.video/).


When you visit this page, you see a form for video upload.  I am writing this post in mid-December, so will use a trailer from a classic Christmas movie in my upload:

online form for video upload. We'll be uploading the Die Hard trailer.

large_screenshot-2020-12-17-at-15-46-49.png

medium_screenshot-2020-12-17-at-15-46-49.png

small_screenshot-2020-12-17-at-15-46-49.png

thumbnail_screenshot-2020-12-17-at-15-46-49.png

screenshot-2020-12-17-at-15-46-49.png

When I begin the upload (by selecting the video), I create an XMLHTTPRequest to the server with the video name, description, and if the video should be public/private, support/not support mp4:

### Set video privacy

This request is sent to the "createVideo" endpoint on my server.  The Node server extracts the JSON from the body, and creates a video container at api.video.  When we create the container, we can set the privacy settings for the video to be uploaded - namely if it should support mp4 download, and if the video should be public or private.

>This solves 2 of the questions asked above - 'can a delegated upload be set to private?' and 'Can I disable mp4 support?'.

```javascript
	if(req.body.public === "false"){
		public=false;
	}
	var mp4  = true;
	if(req.body.mp4Support === "false"){
		mp4=false;
	}
	var title = req.body.title;
	var descr = req.body.description;

	client = new apiVideo.Client({ apiKey: apiVideoKey});	
	
	
	let result = client.videos.create(title, {	"title": title, "mp4Support": mp4,
		"public": public, 
		"description": descr,					
	});

```

The response from the create video has a videoId that we will use as the container for the video we are about to upload.  This container is already built with the privacy settings requested on the webpage!

### One use upload token

Next, we'll create a delegated token with a TTL of 90 seconds.  Note - the TTL support is not yet in the Node SDK (it launched last week!), so we make HTTP requests to the API endpoint.

1. [Authenticate our apiKey](https://api.video/blog/tutorials/authentication-tutorial). This will return an authentication key in a second request for the token.  2. [Create a delegated token](https://docs.api.video/reference/api/Upload-Tokens) with the desired TTL (set to 90s in the code).  The response will give us the delegated token, and when it expires ("expiresAt").

```
var authOptions = {
			method: 'POST',
			url: 'https://ws.api.video/auth/api-key',
			headers: {
				accept: 'application/json'
				
			},
			json: {"apiKey":apiVideoKey}

		}
		console.log(authOptions);	
		request(authOptions, function (error, response, body) {
			if (error) throw new Error(error);
			//this will give me the api key
			
			var authToken = body.access_token;
			console.log(authToken);
			//now use this to generate a delegated toke with a ttl of 90s
			var tokenTTL = 90;
			var tokenOptions = {
				method: 'POST',
				url: 'https://ws.api.video/upload-tokens',
				headers: {
					accept: 'application/json',
					authorization: 'Bearer ' +authToken
				},
				json: {"ttl":tokenTTL}
	
			}
			request(tokenOptions, function (error, response, body) {
				if (error) throw new Error(error);
				var delegatedToken = body.token;
				var tokenExpiry = body.expiresAt;
				console.log("new token", delegatedToken);
				console.log("new token expires", tokenExpiry);
				var tokenVideoIdJson = {"token": delegatedToken,
										"expires":tokenExpiry,
										"videoId": videoId};
				res.setHeader('Content-Type', 'application/json');
				res.end(JSON.stringify(tokenVideoIdJson));

			});
```

Once these two requests have been made, we then send back a JSON response to the browser with the ```videoId```, and the delegated token information.

### Token Expiration

The token expires in 90 seconds - how can we ensure that the video will upload completely in 90s? The answer is that we cannot.  However, we'll use a trick.  If we break the video to be uploaded into small segments, we just need to ensure that the first *segment* of the video is uploaded in 90s. The chunkSize is set to 6 MB - so the first 6 MB must be uploaded in 90s.  

> We're balancing your customers' upload speed with the expiry of the upload token.  If 6 MB in 90s is causing failures - you can lengthen the token expiry - the minimum upload size is 5 MB.  
> If you think this is too generous - lower the tokenTTL. 


### Video Upload

>NOTE: Since this post was written, we've published a library to simplify JavaScript upload of videos [read the blog post to learn more](https://api.video/blog/tutorials/new-video-uploader-javascript-library).


Now we can come back to the JavaScript on the page, and the ```qReq.onload``` that I omitted above:



First we grab the parameters sent from the Node server. For the purposes of the demo, we display the delegated tokenId and the time the token expires (in GMT) on the page.

We then create the delegated video upload url by appending the token to the base url. We determine the number of chunks to upload, and the initial byterange (0-chunkSize) and send the videoId and the videoFile to the createChunk function.

The createChunk function slices up the video from 0 to chunkEnd-1 (the file Slice API lists the first byte IN the slice, and the first byte NOT in the slice). *It's easy to get an off by one error here!*

```
			function createChunk(videoId, start, end){
				chunkCounter++;
				console.log("created chunk: ", chunkCounter);
				chunkEnd = Math.min(start + chunkSize , file.size );
				const chunk = file.slice(start, chunkEnd);
				console.log("i created a chunk of video" + start + "-" + chunkEnd + "minus 1	");
				const chunkForm = new FormData();
				console.log("createChunk videoId",videoId +start+end);
				if(videoId.length >0){
					//we have a videoId
					chunkForm.append('videoId', videoId);
					console.log("added videoId");	
					
				}
				chunkForm.append('file', chunk, filename);
				console.log("added file");

				
				//created the chunk, now upload iit
				uploadChunk(chunkForm, start, chunkEnd);
			}
```

Then the api calls the uploadChunk function that sets the byterange header (off by one warning!) and uploads the video.  It also updates the upload progress.  When the segment is completed, the counter is incremented, and calls the createChunk function again:

```
function uploadChunk(chunkForm, start, chunkEnd){
				var oReq = new XMLHttpRequest();
				oReq.upload.addEventListener("progress", updateProgress);	
				oReq.open("POST", url, true);
				var blobEnd = chunkEnd-1;
				var contentRange = "bytes "+ start+"-"+ blobEnd+"/"+file.size;
				oReq.setRequestHeader("Content-Range",contentRange);
				console.log("Content-Range", contentRange);
				function updateProgress (oEvent) {
					if (oEvent.lengthComputable) {  
					var percentComplete = Math.round(oEvent.loaded / oEvent.total * 100);
					
					var totalPercentComplete = Math.round((chunkCounter -1)/numberofChunks*100 +percentComplete/numberofChunks);
					document.getElementById("chunk-information").innerHTML = "Chunk # " + chunkCounter + " is " + percentComplete + "% uploaded. Total uploaded: " + totalPercentComplete +"%";
				//	console.log (percentComplete);
					// ...
				} else {
					console.log ("not computable");
					// Unable to compute progress information since the total size is unknown
				}
				}
				oReq.onload = function (oEvent) {
							// Uploaded.
								console.log("uploaded chunk" );
								console.log("oReq.response", oReq.response);
								var resp = JSON.parse(oReq.response)
								videoId = resp.videoId;
								//playerUrl = resp.assets.player;
								console.log("videoId",videoId);
								
								//now we have the video ID - loop through and add the remaining chunks
								//we start one chunk in, as we have uploaded the first one.
								//next chunk starts at + chunkSize from start
								start += chunkSize;	
								//if start is smaller than file size - we have more to still upload
								if(start<file.size){
									//create the new chunk
									createChunk(videoId, start);
								}
								else{
									//the video is fully uploaded. there will now be a url in the response
									playerUrl = resp.assets.player;
									console.log("all uploaded! Watch here: ",playerUrl ) ;
									document.getElementById("video-information").innerHTML = "all uploaded! Watch the video <a href=\'" + playerUrl +"\' target=\'_blank\'>here</a>" ;

								}
								
				};
				oReq.send(chunkForm);
		
				
				
			}
```


These two functions dance back and forth - creating slices and uploading them - until the entire video is uploaded.  When the video is fully uploaded, api.video begins assembling the video, and encoding the file.  The response conatains the player URL for the video - which we put on the page for the viewer to see. If the video is set to private - it will be a private URL with a token - only good for one view.

## Private and secure video upload

I think we've done it!  A single use public token for video upload, and the ability to protect the video **before** it is uploaded.

Now you can be sure that your users will properly "stay on the path" with their video uploads.

large_img20200822121759.jpg

medium_img20200822121759.jpg

small_img20200822121759.jpg

thumbnail_img20200822121759.jpg

img20200822121759.jpg

 The code is availabe on [Github](https://github.com/dougsillars/privatedelegatedtoken) if you'd like to take a deeper dive, or create your own version.  And don't forget to try the demo [privatelyupload.a.video](https://privatelyupload.a.video/).

Was this tutorial/demo app useful to you?  Do you have other examples of how to use api.video that you'd live to see? Let us know in our [community](https://community.api.video) forum. 

Private video upload with a public token

medium_footpath.jpg

small_footpath.jpg

thumbnail_footpath.jpg

footpath.jpg

In this post, we'll walk through the steps to upload a video. We've extended the application to not only upload the video to api.video, but to also post it to a Discord channel!

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

Delegated Upload