Video Transcoding

Adaptive video streaming over HTTP is key to have videos load fast any where on any device. Filerobot can transcode your videos in multiple target resolutions and generate the playlist (also called manifest) for your DASH or HLS video player to consume. Before leveraging Filerobot's video transcoding capabilities, we recommend getting a basic understand of the technologies involved: adaptive streaming, DASH and HLS.

Video transcoding must be enabled on your Filerobot token, please contact us for activating it.

POST /v4/upload?postprocess=transcode

The API endpoint for the Filerobot APIs is:

API Permissions

FILE_UPLOAD

Upload Parameters

ParameterTypeDefaultDescription
postprocessstring-required Sets the postprocess operation:
transcode The video is transcoded after uploading.
folderstring/videosoptional Specifies the directory to upload the file into. If it does not exist, it will be created
Example: /path/to/folder

Video Settings

ParameterTypeDefaultDescription
video-resolutionstringautooptional Specifies the resolutions the video needs to be transcoded to:
auto Automatic quality setting based on input file resolution
mobile Optimize for mobile device delivery
tablet Optimize for mobile device delivery with a higher resolution
desktop Optimize for desktop device delivery
hq Optimize for highest quality
video-protocolsstringhlsoptional Specifies the streaming protocol setting
hls Sets the protocol to HLS (HTTP Live Streaming)
dash Sets the protocol to MPEG-DASH.
hls,dash Transcodes to support both protocols

How does it work?

Obtaining transcoded chunks and the corresponding playlist file (.mpd for DASH and .m3u8 for HLS) for the video player to consume is achieved in 3 simple steps:

  1. Upload origin video file: high resolution video file is uploaded into Filerobot via API, Asset Hub or Widget
  2. Transcode into lower resolution chunks: Filerobot backend will generate transcoded chunks and store them in your storage container
  3. Playlist generation: Filerobot generates the playlist file, stores it into your storage container and adds link to it to in the meta data of the original video file

Steps 2 and 3 are transparent for you, you just need to call the standard Upload API by adding the below documented parameters to your request JSON.

Supported formats and codecs

formatsmp4, avi, mkv, webm
video codecsXviD, H.263, AVC (H.264), HEVC (H.265), MPEG-1, MPEG-2, MPEG-4, WMV2, Theora, VP8, VP9
audio codecsAAC, AC3, MP3, PCM, FLAC, Vorbis, Opus

Try it out

You can upload video files for transcoding using the 2 following methods:

Method 1 - multipart/form-data request

Request

curl --request POST \ 
--url 'https://api.filerobot.com/{token}/v4/upload?folder=/{folder_path}&postprocess=transcode' \ 
--header 'content-type: multipart/form-data' \ 
--header 'X-Filerobot-Key: {filerobot_api_key}' \ 
--form file=@{video_file_path.ext} \ 
--form 'info[file]={"video-resolutions":"auto", "video-protocols":"hls|dash|hls,dash"}'
parameterdescription
filerobot_api_keyA Filerobot key (see API Authentification)
video_file_path.extThe path to the local video file

Response

{
  "status": "success", 
  "file": {
    "uuid": "86314cb0-115b-5d3f-a34d-c77b78550000", 
    "name": "11_mp4_h264_mp3.m4v", 
    "size": {
      "bytes": 10740270, 
      "pretty": "10.24 MB"
    }, 
    "type": "video/mp4", 
    "url": {
      "public": "https://fldytuwm.airstore.io/mango/11_mp4_h264_mp3.m4v", 
      "permalink": "https://fldytuwm.api.airstore.io/v4/get/86314cb0-115b-5d3f-a34d-c77b78550000", 
      "cdn": "", 
      "path": "/mango/11_mp4_h264_mp3.m4v"
    }, 
    "hash": {
      "sha1": "95c9ec91a7fa765401a5b4656bb79e0819c5ad96", 
      "blur_hash": null
    }, 
    "created_at": "2021-03-19T11:57:43Z", 
    "modified_at": "2021-03-19T11:57:43Z", 
    "overwrite": false, 
    "folder": {
      "uuid": "b9fd0305-afd2-52be-8a31-c5ddaef8d9c4", 
      "name": "/mango"
    }, 
    "info": {
      "playlists": [
        "https://fldytuwm.filerobot.com/yviDp3wK_11_mp4_h264_mp3/hls/video.m3u8"
      ], 
      "progress": "https://api.filerobot.com/fldytuwm/v4/transcode/MTUyLjIyOC4xNjAuMzY6ODczMQ__4f95351d-33fb-46d8-8d1c-cf105d880410", 
      "transcode_uuid": "4f95351d-33fb-46d8-8d1c-cf105d880410", 
      "video_w": 1920, 
      "video_h": 1080, 
      "video_duration": 20.02, 
      "video_bit_rate": 4121956
    }, 
    "meta": {}
  }, 
  "info": {
    "version": 2.16, 
    "trace": "t9pQ-gpu-test-001", 
    "uniq_id": "a2208ba3e0654aa3a608e0db6fe60766", 
    "project_uuid": "1e007984-ab9a-46f1-8abc-f736e128794d", 
    "company_uuid": "c543bc43-0000-1111-2222-b5293daf15f4", 
    "uploaded_files": 1, 
    "files_count": 1, 
    "init_db": "atom008:45"
  }
}

Method 2 - URL(s) of remotely hosted file(s)

Request

curl --request POST \ 
--url 'http://api.filerobot.com/{token}/v4/upload?folder={folder_path}&postprocess=transcode)' \ 
--header 'content-type: application/json' \ 
--header 'X-Filerobot-Key: {filerobot_api_key}' \ 
 --data '{
 "files_urls": [
  {"url": "{video_url_path.ext}", "info":{"video-resolutions":"auto", "video-protocols":"hls,dash"}}
 ]
}'
parameterdescription
filerobot_api_keyA Filerobot key (see API Authentification)
video_file_path.extThe URL to the video file

Response

{
  "status": "success", 
  "files": [
    {
      "uuid": "26535010-3367-59da-b325-898df8d5002e", 
      "name": "demo.mp4", 
      "size": {
        "bytes": 1035166, 
        "pretty": "1010.9 KB"
      }, 
      "type": "video/mp4", 
      "url": {
        "public": "https://fldytuwm.airstore.io/mango/demo.mp4", 
        "permalink": "https://fldytuwm.api.airstore.io/v4/get/26535010-3367-59da-b325-898df8d5002e", 
        "cdn": "", 
        "path": "/mango/demo.mp4"
      }, 
      "hash": {
        "sha1": "3354b0dff8e02eadaa26d3b5a413de087853c621", 
        "blur_hash": null
      }, 
      "created_at": "2021-03-19T11:48:52Z", 
      "modified_at": "2021-03-19T11:48:52Z", 
      "overwrite": false, 
      "folder": {
        "uuid": "b9fd0305-afd2-52be-8a31-c5ddaef8d9c4", 
        "name": "/mango"
      }, 
      "info": {
        "video-resolutions": "auto", 
        "video-protocols": "hls", 
        "video-name": "dalis", 
        "playlists": [
          "https://fldytuwm.filerobot.com/dalis/hls/video.m3u8"
        ], 
        "progress": "https://api.filerobot.com/fldytuwm/v4/transcode/MTUyLjIyOC4xNjAuMzY6ODczMQ__a928e6a9-75c4-4e01-b316-1d8b8108b618", 
        "transcode_uuid": "a928e6a9-75c4-4e01-b316-1d8b8108b618", 
        "video_w": 1280, 
        "video_h": 720, 
        "video_duration": 42.34, 
        "video_bit_rate": 2940
      }, 
      "meta": {}
    }, 
    {
      "uuid": "d599f852-9a1b-5255-8133-333321a50008", 
      "name": "demo2.mp4", 
      "size": {
        "bytes": 54625140, 
        "pretty": "52.09 MB"
      }, 
      "type": "video/mp4", 
      "url": {
        "public": "https://fldytuwm.airstore.io/mango/demo2.mp4", 
        "permalink": "https://fldytuwm.api.airstore.io/v4/get/d599f852-9a1b-5255-8133-333321a50008", 
        "cdn": "", 
        "path": "/mango/demo2.mp4"
      }, 
      "hash": {
        "sha1": "031b5ff7d26d6de20d1af37b8fc3987348ff2711", 
        "blur_hash": null
      }, 
      "created_at": "2021-03-19T11:48:53Z", 
      "modified_at": "2021-03-19T11:48:53Z", 
      "overwrite": false, 
      "folder": {
        "uuid": "b9fd0305-afd2-52be-8a31-c5ddaef8d9c4", 
        "name": "/mango"
      }, 
      "info": {
        "video-resolutions": "auto", 
        "video-protocols": "hls", 
        "playlists": [
          "https://fldytuwm.filerobot.com/quG1BMo1_demo2/hls/video-sample.m3u8", 
          "https://fldytuwm.filerobot.com/quG1BMo1_demo2/hls/video.m3u8"
        ], 
        "progress": "https://api.filerobot.com/fldytuwm/v4/transcode/MTUyLjIyOC4xNjAuMzY6ODczMQ__ead14798-d4cb-421b-b027-a36c244506ad", 
        "transcode_uuid": "ead14798-d4cb-421b-b027-a36c244506ad", 
        "video_w": 1280, 
        "video_h": 720, 
        "video_duration": 42.34, 
        "video_bit_rate": 10298981
      }, 
      "meta": {}
    }
  ], 
  "info": {
    "version": 2.16, 
    "trace": "3hm-gpu-test-001", 
    "uniq_id": "cfda38f7c6b14808b742bb83752e86d5", 
    "project_uuid": "1e007984-ab9a-46f1-8abc-f736e128794d", 
    "company_uuid": "c543bc43-0000-1111-2222-b5293daf15f4", 
    "uploaded_files": 2, 
    "files_count": 2, 
    "init_db": "atom006:150"
  }
}

Checking transcoding progress

You can read the status of the video transcoding task by querying the following API:

GET /v4/transcode/{transcode_uuid}

The check progress request containing the{transcode_uuid} of the task can be found in the reponse of the upload query (file->info->transcode_uuid). The request URL is also included in the upload query response (file->info->progress).

Response

{
    "status":"OK",
    "UUID":"ead14798-d4cb-421b-b027-a36c244506ad",
    "progress":83,
    "ready":false
}
{
    "status":"OK",
    "UUID":"ead14798-d4cb-421b-b027-a36c244506ad",
    "progress":100,
    "ready":true
}

Testing with VideoJS player

Multiple players are supporting HLS and DASH for adaptive streaming, for testing we recommend using VideoJS. VideoJS offers following two test pages, where you can paste the CDN link to your playlist file and view the result by changing your connection speed from your browser's inspector:

DASH: https://videojs.github.io/videojs-contrib-dash HLS: https://videojs.github.io/videojs-contrib-hls