Video Processing API

Scalable video REST API to convert, resize, optimize, and compress videos for the web.

https://upcdn.io

Account

/W142hJk/

API

video

File Path

/example.mp4

Parameters

?h=1080

1 Upload your video

Firstly, your video must be uploaded or accessible to Bytescale:

Use the Bytescale Dashboard to upload a video manually.

Use the Upload Widget, Bytescale SDKs or Bytescale API to upload a video programmatically.

Use our external storage options to process external videos.

2 Build your video URL

Build a video processing URL:

Get the raw URL for your file:

https://upcdn.io/W142hJk/raw/example.mp4

Replace "raw" with "video":

https://upcdn.io/W142hJk/video/example.mp4

Add querystring parameters to control the output:

https://upcdn.io/W142hJk/video/example.mp4?h=1080

3 Watch your video

Watch your video by navigating to the URL from step 2.

By default, your video will be encoded to H.264 in HD at 30 FPS.

The default HTTP response will be an HTML webpage with an embedded video player. This is for debug purposes only: developers are expected to override this behavior by specifying an f option when embedding videos into their webpages and apps.

Examples

MP4 Output

Read the docs

WebM Output

Read the docs

HLS Output

Read the docs

HLS-RT Output

Read the docs

Embed Code

Read the docs

Thumbnails

Read the docs

Metadata

Read the docs

Example #1: Embedding a video

To embed a video in a webpage using Video.js:

<!DOCTYPE html>
<html>
<head>
  <link href="https://unpkg.com/video.js@7/dist/video-js.min.css" rel="stylesheet">
  <script src="https://unpkg.com/video.js@7/dist/video.min.js"></script>
  <style type="text/css">
    .video-container {
      height: 316px;
      max-width: 600px;
    }
  </style>
</head>
<body>
  <div class="video-container">
    <video-js
      class="vjs-fill vjs-big-play-centered"
      controls
      preload="auto"
      poster="https://upcdn.io/W142hJk/image/example.mp4?input=video&f=webp&f2=jpeg">
      <p class="vjs-no-js">To view this video please enable JavaScript.</p>
    </video-js>
  </div>
  <script>
    var vid = document.querySelector('video-js');
    var player = videojs(vid, {responsive: true});
    player.on('loadedmetadata', function() {
      // Begin playing from the start of the video. (Required for 'f=hls-h264-rt'.)
      player.currentTime(player.seekable().start(0));
    });
    player.src({
      src: 'https://upcdn.io/W142hJk/video/example.mp4!f=hls-h264-rt&h=480&h=1080',
      type: 'application/x-mpegURL'
    });
  </script>
</body>
</html>

The f=hls-h264-rt output format is designed to reduce the wait time for your viewers when the given video has not been transcoded before. Like the other output formats, this video format incurs an initial delay while transcoding starts. However, unlike the other formats, once transcoding begins the video will be streamed to viewers during transcoding. As with the other formats, once transcoded, the resulting video will be cached and will not need to be transcoded again.

Example #2: Creating video thumbnails

To create a video thumbnail (also known as a "video poster image"):

Replace /raw/ with /image/ in your video's URL.

Use the Image Processing API's querystring parameters to customize your video's thumbnail.

Example #3: Creating MP4 videos

To create an MP4 video file:

Upload a video or create an external file source.

Replace /raw/ with /video/ in the video's URL, and then append ?f=mp4-h264 to the URL.

Navigate to the URL (i.e. request the URL using a simple GET request).

Wait for status: "Succeeded" in the JSON response.

The result will contain a URL to the MP4 video:

https://upcdn.io/W142hJk/video/example.mp4?f=mp4-h264

{
  "jobUrl": "https://api.bytescale.com/v2/accounts/W142hJk/jobs/ProcessFileJob/01H3211XMV1VH829RV697VE3WM",
  "jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
  "jobId": "01H3211XMV1VH829RV697VE3WM",
  "jobType": "ProcessFileJob",
  "accountId": "W142hJk",
  "created": 1686916626075,
  "lastUpdated": 1686916669389,
  "status": "Succeeded",
  "summary": {
    "result": {
      "type": "Artifact",
      "artifact": "/video.mp4",
      "artifactUrl": "https://upcdn.io/W142hJk/video/example.mp4!f=mp4-h264&a=/video.mp4"
    }
  }
}

Example #4: Creating WebM videos

To create a WebM video file:

Upload a video or create an external file source.

Replace /raw/ with /video/ in the video's URL, and then append ?f=webm-vp9 to the URL.

Navigate to the URL (i.e. request the URL using a simple GET request).

Wait for status: "Succeeded" in the JSON response.

The result will contain a URL to the WebM video:

https://upcdn.io/W142hJk/video/example.mp4?f=webm-vp9

{
  "jobUrl": "https://api.bytescale.com/v2/accounts/W142hJk/jobs/ProcessFileJob/01H3211XMV1VH829RV697VE3WM",
  "jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
  "jobId": "01H3211XMV1VH829RV697VE3WM",
  "jobType": "ProcessFileJob",
  "accountId": "W142hJk",
  "created": 1686916626075,
  "lastUpdated": 1686916669389,
  "status": "Succeeded",
  "summary": {
    "result": {
      "type": "Artifact",
      "artifact": "/video.webm",
      "artifactUrl": "https://upcdn.io/W142hJk/video/example.mp4!f=webm-vp9&a=/video.webm"
    }
  }
}

Example #5: Creating HLS videos with multiple resolutions

To create an HTTP Live Streaming (HLS) video file:

Upload a video or create an external file source.

Replace /raw/ with /video/ in the video's URL, and then append ?f=hls-h264 to the URL.

Add parameters from the Video Transcoding API, Video Compression API, or Video Resizing API.

You can create adaptive bitrate (ABR) videos by specifying multiple groups of resolution and/or bitrate parameters. The end-user's video player will automatically switch to the most appropriate variant during playback. By default, a single HD variant is produced.

You can specify up to 10 variants per video. Each variant's parameters must be adjacent on the querystring. For example: h=480&q=6&h=1080&q=8 specifies 2 variants, whereas h=480&h=1080&q=6&q=8 specifies 3 variants (which would most likely be a mistake). You can add next=true between groups of parameters to forcefully split them into separate variants.

Navigate to the URL (i.e. request the URL using a simple GET request).

Wait for status: "Succeeded" in the JSON response.

The result will contain a URL to the HTTP Live Streaming (HLS) video:

https://upcdn.io/W142hJk/video/example.mp4?f=hls-h264&h=480&q=6&h=1080&q=8

{
  "jobUrl": "https://api.bytescale.com/v2/accounts/W142hJk/jobs/ProcessFileJob/01H3211XMV1VH829RV697VE3WM",
  "jobDocs": "https://www.bytescale.com/docs/job-api/GetJob",
  "jobId": "01H3211XMV1VH829RV697VE3WM",
  "jobType": "ProcessFileJob",
  "accountId": "W142hJk",
  "created": 1686916626075,
  "lastUpdated": 1686916669389,
  "status": "Succeeded",
  "summary": {
    "result": {
      "type": "Artifact",
      "artifact": "/video.m3u8",
      "artifactUrl": "https://upcdn.io/W142hJk/video/example.mp4!f=hls-h264&h=480&q=6&h=1080&q=8&a=/video.m3u8"
    }
  }
}

Example #6: Creating HLS videos with real-time transcoding

Real-time transcoding allows you to return HLS manifests (.m3u8 files) while they're being transcoded, rather than having to wait for the full transcode job to complete.

To create an HTTP Live Streaming (HLS) video with real-time transcoding:

Complete the steps from creating an HLS video.

Replace f=hls-h264 with f=hls-h264-rt.

The result will be an M3U8 file that's dynamically updated as new segments finish transcoding:

https://upcdn.io/W142hJk/video/example.mp4?f=hls-h264-rt

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-STREAM-INF:BANDWIDTH=2038521,AVERAGE-BANDWIDTH=2038521,CODECS="avc1.4d4032,mp4a.40.2",RESOLUTION=2048x1080,FRAME-RATE=30.000
example.mp4!f=hls-h264-rt&a=/0f/manifest.m3u8

Example #7: Extracting video metadata

The Video Metadata API allows you to extract the video's duration, resolution, frame rate, and more.

To extract a video's duration and resolution using JavaScript:

<!DOCTYPE html>
<html>
<body>
  <p>Please wait, loading video metadata...</p>
  <script>
    async function getVideoDurationAndDimensions() {
      const response = await fetch("https://upcdn.io/W142hJk/video/example.mp4?f=meta");
      const jsonData = await response.json();
      const videoTrack = (jsonData.tracks ?? []).find(x => x.type === "Video");
      if (videoTrack === undefined) {
        alert("Cannot find video metadata.")
      }
      else {
        alert([
          `Duration (seconds): ${videoTrack.duration}`,
          `Width (pixels): ${videoTrack.width}`,
          `Height (pixels): ${videoTrack.height}`,
        ].join("\n"))
      }
    }
    getVideoDurationAndDimensions().then(() => {}, e => alert(`Error: ${e}`))
  </script>
</body>
</html>

Supported Inputs

The Video Processing API can generate video outputs from the following input file types:

File Extension(s)	Video Container	Video Codecs
.gif	No Container	GIF 87a, GIF 89a
.m2v, .mpeg, .mpg	No Container	AVC (H.264), DV/DVCPRO, HEVC (H.265), MPEG-1, MPEG-2
.3g2	3G2	AVC (H.264), H.263, MPEG-4 part 2
.3gp	3GP	AVC (H.264), H.263, MPEG-4 part 2
.wmv	Advanced Systems Format (ASF)	VC-1
.flv	Adobe Flash	AVC (H.264), Flash 9 File, H.263
.avi	Audio Video Interleave (AVI)	Uncompressed, Canopus HQ, DivX/Xvid, DV/DVCPRO, MJPEG
.m3u8	HLS (MPEG-2 TS segments)	AVC (H.264), HEVC (H.265), MPEG-2
.mxf	Interoperable Master Format (IMF)	Apple ProRes, JPEG 2000 (J2K)
.mxf	Material Exchange Format (MXF)	Uncompressed, AVC (H.264), AVC Intra 50/100, Apple ProRes (4444, 4444 XQ, 422, 422 HQ, LT, Proxy), DV/DVCPRO, DV25, DV50, DVCPro HD, JPEG 2000 (J2K), MPEG-2, Panasonic P2, SonyXDCam, SonyXDCam MPEG-4 Proxy, VC-3
.mkv	Matroska	AVC (H.264), MPEG-2, MPEG-4 part 2, PCM, VC-1
.mpg, .mpeg, .m2p, .ps	MPEG Program Streams (MPEG-PS)	MPEG-2
.m2t, .ts, .tsv	MPEG Transport Streams (MPEG-TS)	AVC (H.264), HEVC (H.265), MPEG-2, VC-1
.dat, .m1v, .mpeg, .mpg, .mpv	MPEG-1 System Streams	MPEG-1, MPEG-2
.mp4, .mpeg4	MPEG-4	Uncompressed, DivX/Xvid, H.261, H.262, H.263, AVC (H.264), AVC Intra 50/100, HEVC (H.265), JPEG 2000, MPEG-2, MPEG-4 part 2, VC-1
.mov, .qt	QuickTime	Uncompressed, Apple ProRes (4444, 4444 XQ, 422, 422 HQ, LT, Proxy), DV/DVCPRO, DivX/Xvid, H.261, H.262, H.263, AVC (H.264), AVC Intra 50/100, HEVC (H.265), JPEG 2000 (J2K), MJPEG, MPEG-2, MPEG-4 part 2, QuickTime Animation (RLE)
.webm	WebM	VP8, VP9

Bytescale supports up to 16384x16384 inputs for most video codecs. AVC (H.264) inputs are limited to 16384x8192.

Some codec profiles are not supported by Bytescale. It is worth noting that AVC (H.264) High 4:4:4 Predictive is currently not supported. We aim to provide a full list of supported profiles in the near future.

Video Metadata API

Use the Video Metadata API to extract the duration, resolution, FPS, and other information from a video.

Instructions:

Replace raw with video in your video URL.
Append ?f=meta to the URL.
The result will be a JSON payload describing the video's tracks (see below).

Example video metadata JSON response:

{
  "tracks": [
    {
      "bitRate": 2500000,
      "chromaSubsampling": "4:2:0",
      "codec": "AVC",
      "codecId": "avc1",
      "colorSpace": "YUV",
      "duration": 766.08,
      "frameCount": 19152,
      "frameRate": 25,
      "height": 576,
      "rotation": 0,
      "scanType": "Progressive",
      "type": "Video",
      "width": 720
    },
    {
      "bitRate": 159980,
      "bitRateMode": "VBR",
      "channels": 2,
      "codec": "AAC",
      "codecId": "mp4a-40-2",
      "frameCount": 35875,
      "frameRate": 46.875,
      "samplingRate": 48000,
      "title": "Stereo",
      "type": "Audio"
    }
  ]
}

Video Transcoding API

Use the Video Transcoding API to encode your videos into a specific format.

Output Format f

Use the f parameter to change the output format of the video:

Format	Transcoding	Compression	Browser Support
f=webm-vp8	medium	good	all (except IE11)
f=webm-vp9	slow	good	all (except IE11)
f=mp4-h264 recommended	fast	good	all
f=mp4-h265	fast	excellent	limited
f=hls-h264	fast	good	all (requires SDK)
f=hls-h265	fast	excellent	none
f=hls-h264-rt	very fast	good	all (requires SDK)
f=hls-h265-rt	very fast	excellent	none

f=webm-vp8

Transcodes the video to WebM (VP8 codec).

Caveat: WebM is slower at transcoding than MP4 and HLS.

Response: JSON for an asynchronous transcode job. The JSON will contain the URL to the WebM file on job completion.

Browser support: all browsers (except Internet Explorer 11 and below)

f=webm-vp9

Transcodes the video to WebM (VP9 codec).

Caveat: WebM is slower at transcoding than MP4 and HLS.

Response: JSON for an asynchronous transcode job. The JSON will contain the URL to the WebM file on job completion.

Browser support: all browsers (except Internet Explorer 11 and below)

f=mp4-h264

Transcodes the video to MPEG-4 (H.264/AVC codec).

Response: JSON for an asynchronous transcode job. The JSON will contain the URL to the MP4 file on job completion.

Browser support: all browsers

f=mp4-h265

Transcodes the video to MPEG-4 (H.265/HEVC codec).

Response: JSON for an asynchronous transcode job. The JSON will contain the URL to the MP4 file on job completion.

Browser support: limited (only Chrome and Edge)

f=hls-h264

Transcodes the video to HLS (H.264/AVC codec).

Response: JSON for an asynchronous transcode job. The JSON will contain the URL to the M3U8 file on job completion.

Browser support: all browsers (requires a video player SDK with HLS support, like Video.js).

f=hls-h265

Transcodes the video to HLS (H.265/HEVC codec).

Response: JSON for an asynchronous transcode job. The JSON will contain the URL to the M3U8 file on job completion.

Browser support: none

f=hls-h264-rt

Transcodes the video to HLS (H.264/AVC codec) and returns the video while it's being transcoded.

This output format is designed to reduce the wait time for your viewers when the given video has not been transcoded before. Like the other output formats, this video format incurs an initial delay while transcoding starts. However, unlike the other formats, once transcoding begins the video will be streamed to viewers during transcoding. As with the other formats, once transcoded, the resulting video will be cached and will not need to be transcoded again.

Caveat: This format introduces challenges for some video players and video SDKs due to the use of a live M3U8 playlist during transcoding. As such, we generally recommend using one of the asynchronous formats (which don't end with -rt) for a simpler implementation.

Response: M3U8

Browser support: all browsers (requires a video player SDK with HLS support, like Video.js)

f=hls-h265-rt

Transcodes the video to HLS (H.265/HEVC codec) and returns the video while it's being transcoded.

Response: M3U8

Browser support: none

f=html-h264

Returns a webpage with an embedded video player that's configured to play the requested video in H.264.

Useful for sharing links to videos and for previewing/debugging video transformation parameters.

Response: HTML

Browser support: all browsers

This is the default value.

f=meta

Returns metadata for the video (resolution, dimensions, duration, FPS, etc.).

See the Video Metadata API docs for more information.

Response: JSON (video metadata)

Frames Per Second fps

fps=<number>

Sets the output video's frame rate.

Supports decimal places.

Include Audio mute

mute=<bool>

Removes the audio track from the generated video.

Tip: you can set mute=true to hide the Picture in Picture (PiP) button added by FireFox for embedded videos.

Default: false

Real-time Transcoding rt

rt=auto

If this flag is present, the video variant expressed by the adjacent parameters on the querystring (e.g. q=6&rt=true&q=8&rt=auto) will be returned to the user while it's being transcoded only if the transcode rate is faster than the playback rate.

Only supported by f=hls-h264-rt, f=hls-h265-rt and f=html-h264.

This is the default value.

rt=false

If this flag is present, the video variant expressed by the adjacent parameters on the querystring (e.g. q=6&rt=true&q=8&rt=false) will never be returned to the user while it's being transcoded.

Use this option as a performance optimization (instead of using rt=auto) when you know the variant will always transcode at a slower rate than its playback rate:

•When rt=auto is used, the initial HTTP request for the M3U master manifest will block until the first few segments of each rt=auto and rt=true variants have been transcoded, before returning the initial M3U playlist.

•In general, you want to exclude slow-transcoding HLS variants to reduce this latency.

If none of the HLS variants have rt=true or rt=auto then the fastest variant to transcode will be returned during transcoding.

Only supported by f=hls-h264-rt, f=hls-h265-rt and f=html-h264.

rt=true

If this flag is present, the video variant expressed by the adjacent parameters on the querystring (e.g. q=6&rt=true&q=8&rt=auto) will always be returned to the user while it's being transcoded.

Only supported by f=hls-h264-rt, f=hls-h265-rt and f=html-h264.

Video Encoding Passes passes

passes=single

Single pass encoding (fastest option).

This is the default value.

passes=single-hq

High-quality single pass encoding.

Only supported by h264 formats.

Video Compression API

Use the Video Compression API to control the file size of your video.

Video Quality q

q=<int>

Sets the video quality when QBR (brm=qbr) is being used to control the video's bitrate:

•1 is the lowest quality (fastest transcoding, smallest file size).

•10 is the highest quality (slowest transcoding, largest file size).

Only supported by h264 and h265 formats: you can use br to adjust the quality/bitrate of other formats.

Default: 8

Video Bitrate Mode brm

brm=qbr

Makes the output video track use a quality-defined bitrate (QBR).

The bitrate will be automatically adjusted based on the given quality score (see q).

Recommended for most cases, except where you need control over the resulting file size.

This is the default value.

brm=vbr

Makes the output video track use a variable bitrate (VBR).

More complex scenes will use a higher bitrate, whereas less complex scenes will use a lower bitrate.

brm=cbr

Makes the output video track use a constant bitrate (CBR).

Video Bitrate br

br=<int>

Sets the output video bitrate (kbps):

•If brm=qbr then br will be interpreted as a maximum bitrate and q will be used to automatically set the mean bitrate.

•If brm=vbr then br will be interpreted as a mean bitrate.

•If brm=cbr then br will be interpreted as a constant bitrate.

Accepts any value between 1 and 100000.

Audio Bitrate abr

abr=<int>

Sets the output audio bitrate (kbps).

Supported values for f=mp4-h264, f=hls-h264, f=hls-h264-rt and f=html-h264:

•16

•20

•24

•28

•32

•40

•48

•56

•64

•80

•96

•112

•128

•160

•192

•224

•256

•288

•320

•384

•448

•512

•576

Supported values for f=webm-vp8 and f=webm-vp9:

•32

•40

•48

•56

•64

•72

•80

•88

•96

•104

•112

•120

•128

•136

•144

•152

•160

•168

•176

•184

•192

Default: 96

Video Resizing API

Use the Video Resizing API to resize videos to a different size.

W w

w=<int>

Width to resize the video to.

H h

h=<int>

Height to resize the video to.

Sharpness sh

sh=<int>

Sets the video sharpness to use when resizing the video:

•0 is the softest.

•100 is the sharpest.

Default: 50

Fit fit

fit=crop

Resizes the video to the given dimensions (see: w and h).

The resulting video may be cropped in one dimension to preserve the aspect ratio of the original video.

The cropped edges are determined by the crop parameter.

•Resulting video size: = w x h

•Aspect ratio preserved: yes

•Cropping: yes

Requires: h, w

fit=enlarge

Enlarges the video to the given dimensions (see: w and h) but won't shrink videos that already exceed the dimensions.

If enlargement occurs, the video will be enlarged until at least one dimension is equal to the given dimensions, while the other dimension will be ≤ the given dimensions.

•Resulting video size: ≥ w | ≥ h

•Aspect ratio preserved: yes

•Cropping: no

fit=enlarge-cover

Enlarges the video to the given dimensions (see: w and h) but won't shrink videos that already exceed the dimensions.

If enlargement occurs, the resulting video's dimensions will be ≥ the given dimensions.

•Resulting video size: ≥ w & ≥ h

•Aspect ratio preserved: yes

•Cropping: no

fit=height

Resizes the video to the given height (see: h).

Width will be automatically set to preserve the aspect ratio of the original video.

•Resulting video size: = h

•Aspect ratio preserved: yes

•Cropping: no

Requires: h

fit=max

Resizes the video to the given dimensions (see: w and h).

The resulting video may be smaller in one dimension, while the other will match the given dimensions exactly.

•Resulting video size: (≤ w & = h) | (= w & ≤ h)

•Aspect ratio preserved: yes

•Cropping: no

fit=min

Resizes the video to the given dimensions (see: w and h).

The resulting video may be larger in one dimension, while the other will match the given dimensions exactly.

•Resulting video size: (≥ w & = h) | (= w & ≥ h)

•Aspect ratio preserved: yes

•Cropping: no

fit=shrink

Shrinks the video to the given dimensions (see: w and h) but won't enlarge videos that are already below the dimensions.

If shrinking occurs, the resulting video's dimensions will be ≤ the given dimensions.

•Resulting video size: ≤ w & ≤ h

•Aspect ratio preserved: yes

•Cropping: no

fit=shrink-cover

Shrinks the video to the given dimensions (see: w and h) but won't enlarge videos that are already below the dimensions.

If shrinking occurs, the video will be shrunk until at least one dimension is equal to the given dimensions, while the other dimension will be ≥ the given dimensions.

•Resulting video size: ≤ w | ≤ h

•Aspect ratio preserved: yes

•Cropping: no

fit=stretch

Resizes the video to the given dimensions, stretching to fit if required (see: w and h).

•Resulting video size: = w x h

•Aspect ratio preserved: no

•Cropping: no

fit=width

Resizes the video to the given width (see: w).

Height will be automatically set to preserve the aspect ratio of the original video.

•Resulting video size: = w

•Aspect ratio preserved: yes

•Cropping: no

Requires: w

Crop crop

crop=bottom

Automatically crops to the bottom of the video.

The crop is performed by removing pixels evenly from the left and right of the video, or from the top of the video, but never both.