@api.video/video-uploader

api.video video uploader

Usage no npm install needed!

<script type="module">
  import apiVideoVideoUploader from 'https://cdn.skypack.dev/@api.video/video-uploader';
</script>

README

badge   badge   badge

api.video typescript video uploader

npm ts

api.video is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.

Table of contents

Project description

Typescript library to upload videos to api.video using delegated upload token (or usual access token) from the front-end.

It allows you to upload videos in two ways:

  • standard upload: to send a whole video file in one go
  • progressive upload: to send a video file by chunks, without needing to know the final size of the video file

Getting started

Installation

Installation method #1: requirejs

If you use requirejs you can add the library as a dependency to your project with

$ npm install --save @api.video/video-uploader

You can then use the library in your script:

// standard upload:
var { VideoUploader } = require('@api.video/video-uploader');

var uploader = new VideoUploader({
    // ... (see bellow)
}); 

// progressive upload:
var { ProgressiveUploader } = require('@api.video/video-uploader');

var uploader = new ProgressiveUploader({
    // ... (see bellow)
});

Installation method #2: typescript

If you use Typescript you can add the library as a dependency to your project with

$ npm install --save @api.video/video-uploader

You can then use the library in your script:

// standard upload:
import { VideoUploader } from '@api.video/video-uploader'

const uploader = new VideoUploader({
    // ... (see bellow)
});

// progressive upload:
import { ProgressiveUploader } from '@api.video/video-uploader'

const uploader = new ProgressiveUploader({
    // ... (see bellow)
});

Simple include in a javascript project

Include the library in your HTML file like so:

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

Then, once the window.onload event has been trigered, create your player using new VideoUploader():

...
<form>
    <input type="file" id="input" onchange="uploadFile(this.files)">
</form>
<script type="text/javascript">
    function uploadFile(files) {
        new VideoUploader({
            file: files[0],
            uploadToken: "YOUR_DELEGATED_TOKEN"
        }).upload();
    }
</script>

Documentation - Standard upload

Instanciation

Options

The upload library is instanciated using an options object. Options to provide depend on the way you want to authenticate to the API: either using a delegated upload token (recommanded), or using a usual access token.

Using a delegated upload token (recommended):

Using delegated upload tokens for authentication is best options when uploading from the client side. To know more about delegated upload token, read the dedicated article on api.video's blog: Delegated Uploads.

Option name Mandatory Type Description
uploadToken yes string your upload token
videoId no string id of an existing video
common options (see bellow)

Using an access token (discouraged):

Warning: be aware that exposing your access token client-side can lead to huge security issues. Use this method only if you know what you're doing :).

Option name Mandatory Type Description
accessToken yes string your access token
videoId yes string id of an existing video
common options (see bellow)

Common options

Option name Mandatory Type Description
file yes File the file you want to upload
chunkSize no number number of bytes of each upload chunk (default: 50MB, min: 5MB, max: 128MB)
apiHost no string api.video host (default: ws.api.video)
retries no number number of retries when an API call fails (default: 5)

Example

    const uploader = new VideoUploader({
        file: files[0],
        uploadToken: "YOUR_DELEGATED_TOKEN",
        chunkSize: 1024*1024*10, // 10MB
        retries: 10,
    });

Methods

upload()

The upload() method starts the upload. It takes no parameter. It returns a Promise that resolves once the file is uploaded. If an API call fails more than the specified number of retries, then the promise is rejected. On success, the promise embeds the video object returned by the API. On fail, the promise embeds the status code & error message returned by the API.

Example

    // ... uploader instanciation

    uploader.upload()
        .then((video) => console.log(video))
        .catch((error) => console.log(error.status, error.message));

onProgress()

The onProgress() method let you defined an upload progress listener. It takes a callback function with one parameter: the onProgress events. An onProgress event contains the following attributes:

  • uploadedBytes (number): total number of bytes uploaded for this upload
  • totalBytes (number): total size of the file
  • chunksCount (number): number of upload chunks
  • chunksBytes (number): size of a chunk
  • currentChunk (number): index of the chunk being uploaded
  • currentChunkUploadedBytes (number): number of bytes uploaded for the current chunk

Example

    // ... uploader instanciation
    
    uploader.onProgress((event) => {
        console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`);
        console.log(`total size of the file: ${event.totalBytes}.`);
        console.log(`number of upload chunks: ${event.chunksCount} .`);
        console.log(`size of a chunk: ${event.chunksBytes}.`);
        console.log(`index of the chunk being uploaded: ${event.currentChunk}.`);
        console.log(`number of bytes uploaded for the current chunk: ${event.currentChunkUploadedBytes}.`);
    });

Documentation - Progressive upload

Instanciation

Options

The progressive upload object is instanciated using an options object. Options to provide depend on the way you want to authenticate to the API: either using a delegated upload token (recommanded), or using a usual access token.

Using a delegated upload token (recommended):

Using delegated upload tokens for authentication is best options when uploading from the client side. To know more about delegated upload token, read the dedicated article on api.video's blog: Delegated Uploads.

Option name Mandatory Type Description
uploadToken yes string your upload token
videoId no string id of an existing video
common options (see bellow)

Using an access token (discouraged):

Warning: be aware that exposing your access token client-side can lead to huge security issues. Use this method only if you know what you're doing :).

Option name Mandatory Type Description
accessToken yes string your access token
videoId yes string id of an existing video
common options (see bellow)

Common options

Option name Mandatory Type Description
apiHost no string api.video host (default: ws.api.video)
retries no number number of retries when an API call fails (default: 5)

Example

    const uploader = new ProgressiveUploader({
        uploadToken: "YOUR_DELEGATED_TOKEN",
        retries: 10,
    });

Methods

uploadPart(file: Blob)

The upload() method starts the upload. It takes no parameter. It returns a Promise that resolves once the file is uploaded. If an API call fails more than the specified number of retries, then the promise is rejected. On success, the promise embeds the video object returned by the API. On fail, the promise embeds the status code & error message returned by the API.

Example

    // ... uploader instanciation

    uploader.uploadPart(blob)
        .catch((error) => console.log(error.status, error.message));

uploadLastPart(file: Blob)

The upload() method starts the upload. It takes no parameter. It returns a Promise that resolves once the file is uploaded. If an API call fails more than the specified number of retries, then the promise is rejected. On success, the promise embeds the video object returned by the API. On fail, the promise embeds the status code & error message returned by the API.

Example

    // ... uploader instanciation

    uploader.uploadLastPart(blob)
        .then((video) => console.log(video))
        .catch((error) => console.log(error.status, error.message));

onProgress()

The onProgress() method let you defined an upload progress listener. It takes a callback function with one parameter: the onProgress events. An onProgress event contains the following attributes:

  • uploadedBytes (number): total number of bytes uploaded for this upload
  • totalBytes (number): total size of the file

Example

    // ... uploader instanciation
    
    uploader.onProgress((event) => {
        console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`);
        console.log(`total size of the file: ${event.totalBytes}.`);
    });