{"id":18498026,"url":"https://github.com/apivideo/api.video-typescript-uploader","last_synced_at":"2025-07-26T02:33:26.915Z","repository":{"id":39859407,"uuid":"378896252","full_name":"apivideo/api.video-typescript-uploader","owner":"apivideo","description":"The official typescript video uploader for api.video (https://api.video)","archived":false,"fork":false,"pushed_at":"2024-10-04T09:36:15.000Z","size":530,"stargazers_count":25,"open_issues_count":1,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-23T05:06:39.458Z","etag":null,"topics":["javascript","typescript","upload","uploader","video","video-uploader"],"latest_commit_sha":null,"homepage":"https://upload.a.video/JS.html","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apivideo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-21T10:43:05.000Z","updated_at":"2025-02-25T09:23:22.000Z","dependencies_parsed_at":"2023-02-13T00:46:27.390Z","dependency_job_id":"8cd3f331-aeea-482e-a466-224757a3e0a2","html_url":"https://github.com/apivideo/api.video-typescript-uploader","commit_stats":{"total_commits":69,"total_committers":7,"mean_commits":9.857142857142858,"dds":0.4347826086956522,"last_synced_commit":"639ccae8de38de446dd9e1010bc7bf4f9bcc3c7b"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/apivideo/api.video-typescript-uploader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apivideo%2Fapi.video-typescript-uploader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apivideo%2Fapi.video-typescript-uploader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apivideo%2Fapi.video-typescript-uploader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apivideo%2Fapi.video-typescript-uploader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apivideo","download_url":"https://codeload.github.com/apivideo/api.video-typescript-uploader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apivideo%2Fapi.video-typescript-uploader/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267107594,"owners_count":24037285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-26T02:00:08.937Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","typescript","upload","uploader","video","video-uploader"],"created_at":"2024-11-06T13:37:12.962Z","updated_at":"2025-07-26T02:33:26.757Z","avatar_url":"https://github.com/apivideo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\u003cdocumentation_excluded\u003e--\u003e\n[![badge](https://img.shields.io/twitter/follow/api_video?style=social)](https://twitter.com/intent/follow?screen_name=api_video) \u0026nbsp; [![badge](https://img.shields.io/github/stars/apivideo/api.video-typescript-uploader?style=social)](https://github.com/apivideo/api.video-typescript-uploader) \u0026nbsp; [![badge](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fcommunity.api.video)](https://community.api.video)\n![](https://github.com/apivideo/.github/blob/main/assets/apivideo_banner.png)\n\u003ch1 align=\"center\"\u003eapi.video typescript video uploader\u003c/h1\u003e\n\n![npm](https://img.shields.io/npm/v/@api.video/video-uploader) ![ts](https://badgen.net/badge/-/TypeScript/blue?icon=typescript\u0026label)\n\n\n[api.video](https://api.video) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand \u0026 low latency live streaming features in your app.\n\n## Table of contents\n\n- [Table of contents](#table-of-contents)\n- [Project description](#project-description)\n- [Getting started](#getting-started)\n  - [Installation](#installation)\n    - [Installation method #1: requirejs](#installation-method-1-requirejs)\n    - [Installation method #2: typescript](#installation-method-2-typescript)\n    - [Simple include in a javascript project](#simple-include-in-a-javascript-project)\n- [Documentation - Standard upload](#documentation---standard-upload)\n  - [Instantiation](#instantiation)\n    - [Options](#options)\n      - [Using a delegated upload token (recommended):](#using-a-delegated-upload-token-recommended)\n      - [Using an access token (discouraged):](#using-an-access-token-discouraged)\n      - [Using an API key (**strongly** discouraged):](#using-an-api-key-strongly-discouraged)\n      - [Common options](#common-options)\n    - [Example](#example)\n  - [Methods](#methods)\n    - [`upload()`](#upload)\n    - [`onProgress()`](#onprogress)\n    - [`cancel()`](#cancel)\n    - [`onPlayable()`](#onplayable)\n- [Documentation - Progressive upload](#documentation---progressive-upload)\n  - [Instantiation](#instantiation-1)\n    - [Options](#options-1)\n      - [Using a delegated upload token (recommended):](#using-a-delegated-upload-token-recommended-1)\n      - [Using an access token (discouraged):](#using-an-access-token-discouraged-1)\n      - [Common options](#common-options-1)\n    - [Example](#example-1)\n  - [Methods](#methods-1)\n    - [`uploadPart(file: Blob)`](#uploadpartfile-blob)\n    - [`uploadLastPart(file: Blob)`](#uploadlastpartfile-blob)\n    - [`onProgress()`](#onprogress-1)\n    - [`cancel()`](#cancel-1)\n    - [`onPlayable()`](#onplayable-1)\n- [Static wrapper](#static-wrapper)\n\n\u003c!--\u003c/documentation_excluded\u003e--\u003e\n\u003c!--\u003cdocumentation_only\u003e\n---\ntitle: api.video TypeScript video uploader\nmeta: \n  description: The official api.video TypeScript video uploader for api.video. [api.video](https://api.video/) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand \u0026 low latency live streaming features in your app.\n---\n\n# api.video TypeScript video uploader\n\n[api.video](https://api.video/) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand \u0026 low latency live streaming features in your app.\n\n\u003c/documentation_only\u003e--\u003e\n## Project description\n\nTypescript library to upload videos to api.video using delegated upload token (or usual access token) from the front-end. \n\nIt allows you to upload videos in two ways:\n- standard upload: to send a whole video file in one go\n- progressive upload: to send a video file by chunks, without needing to know the final size of the video file\n\n## Getting started\n\n### Installation\n\n#### Installation method #1: requirejs\n\nIf you use requirejs you can add the library as a dependency to your project with \n\n```sh\n$ npm install --save @api.video/video-uploader\n```\n\nYou can then use the library in your script: \n\n```javascript\n// standard upload:\nvar { VideoUploader } = require('@api.video/video-uploader');\n\nvar uploader = new VideoUploader({\n    // ... (see bellow)\n}); \n\n// progressive upload:\nvar { ProgressiveUploader } = require('@api.video/video-uploader');\n\nvar uploader = new ProgressiveUploader({\n    // ... (see bellow)\n}); \n```\n\n#### Installation method #2: typescript\n\nIf you use Typescript you can add the library as a dependency to your project with \n\n```sh\n$ npm install --save @api.video/video-uploader\n```\n\nYou can then use the library in your script: \n\n```typescript\n// standard upload:\nimport { VideoUploader } from '@api.video/video-uploader'\n\nconst uploader = new VideoUploader({\n    // ... (see bellow)\n});\n\n// progressive upload:\nimport { ProgressiveUploader } from '@api.video/video-uploader'\n\nconst uploader = new ProgressiveUploader({\n    // ... (see bellow)\n});\n```\n\n\n#### Simple include in a javascript project\n\nInclude the library in your HTML file like so:\n\n```html\n\u003chead\u003e\n    ...\n    \u003cscript src=\"https://unpkg.com/@api.video/video-uploader\" defer\u003e\u003c/script\u003e\n\u003c/head\u003e\n```\n\nThen, once the `window.onload` event has been trigered, create your player using `new VideoUploader()`:\n```html\n...\n\u003cform\u003e\n    \u003cinput type=\"file\" id=\"input\" onchange=\"uploadFile(this.files)\"\u003e\n\u003c/form\u003e\n\u003cscript type=\"text/javascript\"\u003e\n    function uploadFile(files) {\n        new VideoUploader({\n            file: files[0],\n            uploadToken: \"YOUR_DELEGATED_TOKEN\"\n        }).upload();\n    }\n\u003c/script\u003e\n```\n\n## Documentation - Standard upload\n\n### Instantiation\n\n#### Options \n\nThe upload library is instantiated 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. \n\n##### Using a delegated upload token (recommended):\n\nUsing 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](https://api.video/blog/tutorials/delegated-uploads/).\n\n\n|                   Option name | Mandatory | Type   | Description             |\n| ----------------------------: | --------- | ------ | ----------------------- |\n|                   uploadToken | **yes**   | string | your upload token       |\n|                       videoId | no        | string | id of an existing video |\n| _common options (see bellow)_ |           |        |                         |\n\n##### Using an access token (discouraged):\n\n**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 :).\n\n\n|                   Option name | Mandatory | Type   | Description                                                                                                                                     |\n| ----------------------------: | --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |\n|                   accessToken | **yes**   | string | your access token                                                                                                                               |\n|                  refreshToken | **no**    | string | your refresh token (please not that if you don't provide a refresh token, your upload may fails due to the access token lifetime of 60 minutes) |\n|                       videoId | **yes**   | string | id of an existing video                                                                                                                         |\n| _common options (see bellow)_ |           |        |                                                                                                                                                 |\n\n\n##### Using an API key (**strongly** discouraged):\n\n**Warning**: be aware that exposing your API key client-side can lead to huge security issues. Use this method only if you know what you're doing :).\n\n\n|                   Option name | Mandatory | Type   | Description             |\n| ----------------------------: | --------- | ------ | ----------------------- |\n|                       API Key | **yes**   | string | your api.video API key  |\n|                       videoId | **yes**   | string | id of an existing video |\n| _common options (see bellow)_ |           |        |                         |\n\n\n##### Common options\n\n\n|   Option name    | Mandatory | Type                                                            | Description                                                                                                                              |\n| ---------------: | --------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |\n|          file    | **yes**   | File                                                            | the file you want to upload                                                                                                              |\n|     videoName    | no        | string                                                          | the name of your video (overrides the original file name for regular uploads, overrides the default \"file\" name for progressive uploads) |\n|     chunkSize    | no        | number                                                          | number of bytes of each upload chunk (default: 50MB, min: 5MB, max: 128MB)                                                               |\n|       apiHost    | no        | string                                                          | api.video host (default: ws.api.video)                                                                                                   |\n|       retries    | no        | number                                                          | number of retries when an API call fails (default: 5)                                                                                    |\n| retryStrategy    | no        | (retryCount: number, error: VideoUploadError) =\u003e number \\| null | function that returns the number of ms to wait before retrying a failed upload. Returns null to stop retrying                            |\n| maxVideoDuration | no        | number                                                          | maximum duration allowed for the file (in seconds)                                                                                       |\n\n\n#### Example\n\n```javascript\n    const uploader = new VideoUploader({\n        file: files[0],\n        uploadToken: \"YOUR_DELEGATED_TOKEN\",\n        chunkSize: 1024*1024*10, // 10MB\n        retries: 10,\n    });\n```\n\n### Methods\n\n#### `upload()`\n\nThe 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.\nOn success, the promise embeds the `video` object returned by the API.\nOn fail, the promise embeds the status code \u0026 error message returned by the API.\n\n**Example**\n\n```javascript\n    // ... uploader instantiation\n\n    uploader.upload()\n        .then((video) =\u003e console.log(video))\n        .catch((error) =\u003e console.log(error.status, error.message));\n```\n\n#### `onProgress()`\n\nThe onProgress() method let you defined an upload progress listener. It takes a callback function with one parameter: the onProgress events.\nAn onProgress event contains the following attributes:\n- uploadedBytes (number): total number of bytes uploaded for this upload\n- totalBytes (number): total size of the file\n- chunksCount (number): number of upload chunks \n- chunksBytes (number): size of a chunk\n- currentChunk (number): index of the chunk being uploaded\n- currentChunkUploadedBytes (number): number of bytes uploaded for the current chunk\n\n#### `cancel()`\n\nThe cancel() method cancels the upload. It takes no parameter. \n\n\n**Example**\n\n```javascript\n    // ... uploader instantiation\n    \n    uploader.onProgress((event) =\u003e {\n        console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`);\n        console.log(`total size of the file: ${event.totalBytes}.`);\n        console.log(`number of upload chunks: ${event.chunksCount} .`);\n        console.log(`size of a chunk: ${event.chunksBytes}.`);\n        console.log(`index of the chunk being uploaded: ${event.currentChunk}.`);\n        console.log(`number of bytes uploaded for the current chunk: ${event.currentChunkUploadedBytes}.`);\n    });\n```\n\n\n#### `onPlayable()`\n\nThe onPlayable() method let you defined a listener that will be called when the video is playable. It takes a callback function with one parameter: the `video` object returned by the API.\n\n**Example**\n\n```html\n    \u003cdiv id=\"player-container\"\u003e\u003c/div\u003e\n\n    \u003cscript\u003e\n        // ... uploader instantiation\n    \n        uploader.onPlayable((video) =\u003e {\n            // the video is playable, we can display the player\n            document.getElementById('player-container').innerHTML = v.assets.iframe;\n        });\n    \u003c/script\u003e\n```\n\n## Documentation - Progressive upload\n\n\n### Instantiation\n\n#### Options \n\nThe progressive upload object is instantiated 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. \n\n##### Using a delegated upload token (recommended):\n\nUsing 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](https://api.video/blog/tutorials/delegated-uploads/).\n\n\n|                   Option name | Mandatory | Type   | Description             |\n| ----------------------------: | --------- | ------ | ----------------------- |\n|                   uploadToken | **yes**   | string | your upload token       |\n|                       videoId | no        | string | id of an existing video |\n| _common options (see bellow)_ |           |        |                         |\n\n##### Using an access token (discouraged):\n\n**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 :).\n\n\n|                   Option name | Mandatory | Type   | Description             |\n| ----------------------------: | --------- | ------ | ----------------------- |\n|                   accessToken | **yes**   | string | your access token       |\n|                       videoId | **yes**   | string | id of an existing video |\n| _common options (see bellow)_ |           |        |                         |\n\n\n##### Common options\n\n\n|       Option name           | Mandatory | Type                                                            | Description                                                                                                                                            |\n| --------------------------: | --------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n|           apiHost           | no        | string                                                          | api.video host (default: ws.api.video)                                                                                                                 |\n|           retries           | no        | number                                                          | number of retries when an API call fails (default: 5)                                                                                                  |\n|     retryStrategy           | no        | (retryCount: number, error: VideoUploadError) =\u003e number \\| null | function that returns the number of ms to wait before retrying a failed upload. Returns null to stop retrying                                          |\n| preventEmptyParts           | no        | boolean                                                         | if true, the upload will succeed even if an empty Blob is passed to uploadLastPart(). This may alter performances a bit in some cases (default: false) |\n| mergeSmallPartsBeforeUpload | no        | boolean                                                         | if false, parts smaller than 5MB will not be merged before upload, resulting in an error (default: true)                                               |\n\n\n#### Example\n\n```javascript\n    const uploader = new ProgressiveUploader({\n        uploadToken: \"YOUR_DELEGATED_TOKEN\",\n        retries: 10,\n    });\n```\n\n### Methods\n\n#### `uploadPart(file: Blob)`\n\nThe 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.\nOn success, the promise embeds the `video` object returned by the API.\nOn fail, the promise embeds the status code \u0026 error message returned by the API.\n\n**Example**\n\n```javascript\n    // ... uploader instantiation\n\n    uploader.uploadPart(blob)\n        .catch((error) =\u003e console.log(error.status, error.message));\n```\n\n#### `uploadLastPart(file: Blob)`\n\nThe 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.\nOn success, the promise embeds the `video` object returned by the API.\nOn fail, the promise embeds the status code \u0026 error message returned by the API.\n\n**Example**\n\n```javascript\n    // ... uploader instantiation\n\n    uploader.uploadLastPart(blob)\n        .then((video) =\u003e console.log(video))\n        .catch((error) =\u003e console.log(error.status, error.message));\n```\n\n#### `onProgress()`\n\nThe onProgress() method let you defined an upload progress listener. It takes a callback function with one parameter: the onProgress events.\nAn onProgress event contains the following attributes:\n- uploadedBytes (number): total number of bytes uploaded for this upload\n- totalBytes (number): total size of the file\n- part (number): index of the part being uploaded\n\n**Example**\n\n```javascript\n    // ... uploader instantiation\n    \n    uploader.onProgress((event) =\u003e {\n        console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`);\n        console.log(`total size of the file: ${event.totalBytes}.`);\n        console.log(`current part: ${event.part}.`);\n    });\n```\n\n#### `cancel()`\n\nThe cancel() method cancels the upload. It takes no parameter. \n\n#### `onPlayable()`\n\nThe onPlayable() method let you defined a listener that will be called when the video is playable. It takes a callback function with one parameter: the `video` object returned by the API.\n\n**Example**\n\n```html\n    \u003cdiv id=\"player-container\"\u003e\u003c/div\u003e\n\n    \u003cscript\u003e\n        // ... uploader instantiation\n    \n        uploader.onPlayable((video) =\u003e {\n            // the video is playable, we can display the player\n            document.getElementById('player-container').innerHTML = v.assets.iframe;\n        });\n    \u003c/script\u003e\n```\n\n\n## Static wrapper\n\nFor situations where managing object instances is impractical, consider using the [UploaderStaticWrapper](https://github.com/apivideo/api.video-typescript-uploader/blob/main/doc/UploaderStaticWrapper.md) class, which offers static method equivalents for all functionalities. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapivideo%2Fapi.video-typescript-uploader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapivideo%2Fapi.video-typescript-uploader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapivideo%2Fapi.video-typescript-uploader/lists"}