Video Tasks

Introduction

Video files are commonly used in <video> tags on the web, or as input for mobile, TV, and other media players on a range of devices.

You can use video tasks to:

• Convert video files to different formats for broader compatibility
• Compress video files to save bandwidth
• Resize video files to fit different screen sizes
• Add text and image overlays to video files

Required props

As with all Tasks, you must provide:

• either a file_id or a url to use as the input file
• the kind of task to create

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
}
// Pass options to an SDK or API request e.g:
const task = await ittybit.tasks.create(options);

File ID

The file_id should be the unique ID of a file in your project's Files collection.

e.g. "file_id": "file_abcdefgh1234"

URL

The url should be the URL of the video file to process.

This should be a publicly accessible or signed URL.

e.g. "url": "https://example.com/video.mp4"

Kind

For video tasks, this is always video.

e.g. "kind": "video"

Default settings

If you don't specify any options, the default task will create a new video file with the following settings:

If you just want to normalise uploaded videos for web playback, this is a reasonable set of defaults.

Shared options

All tasks support the following (optional) props:

• filename
• folder
• ref

See the Tasks documentation for more information on these options.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  folder: "uploads/user123",
  filename: "intro-20250101.mp4"
}

Video options

Video tasks support a number of optional properties, which are used to control the output video.

If you want to go wild you can create a video with a custom width, height, fit, position, background, fps, format, start, and end ... then add some overlays.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  width: 720,
  height: 1280,
  fit: 'contain',
  position: 'center',
  background: '#20B075',
  fps: 30,
  format: 'mp4',
  quality: 80,
  start: 0,
  end: 10,
  layers: [
    {
      kind: 'image',
      url: 'https://example.com/image.png',
      position: 'bottom right',
      width: 100,
      height: 100,
    },
    {
      kind: 'text',
      text: 'Hello, world!',
      font: 'Inter',
      font_size: 32,
      color: '#FFFFFF',
      position: 'bottom left',
    },
  ],
}
const task = await ittybit.tasks.create(options);

Width

The width of the video to encode in pixels or as a percentage of the input file. ²

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  width: 720, // or e.g. "50%"
}

If you specify a percentage, the output file's width will be relative to the input file's width. For example, if the input file is 1920x1080, and you specify "width": "50%", the output file will be 960px wide.

Height

The height of the video to encode in pixels or as a percentage of the input file.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  height: 1280, // or e.g. "50%"
}

If you specify a percentage, the output file's height will be relative to the input file's height. For example, if the input file is 1920x1080, and you specify "height": "50%", the output file will be 540px tall.

Fit

How the video should be scaled to fit the width and height.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  width: 720,
  height: 1280,
  fit: 'contain',
}

Available fits are:

• fill: (default) This will stretch the video to fit the width and height values given, even if that changes the aspect ratio and distorts the video.
• cover - This will scale the video up to cover the width and height given. Therefore, the output video may be cropped but it will retain the original aspect ratio.
• contain - This will scale the video down to fit the width and height given. Therefore the output video may have extra empty padding but the aspect ratio will be preserved.

If only one of width or height is specified, the other will be calculated to maintain the original aspect ratio and fit will be ignored.

Position

Used in conjunction with fit: cover or fit: contain, this will specify the position of the video within the width and height.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  width: 720,
  height: 1280,
  fit: 'contain',
  position: 'top left',
}

Available positions are:

• center: (default) The video will be scaled to fit the width and height, and then centered within the output frame.
• top | bottom: The video will be placed against the top or bottom of the output frame, and centered horizontally (same as passing top center or bottom center).
• left | right: The video will be placed against the left or right of the output frame, and centered vertically (same as passing center left or center right).
• top left | top right | bottom left | bottom right: The video will be placed against both edges specified.

If only one of width or height is specified, the other will be calculated to maintain the original aspect ratio. Then position will have no effect and will be ignored.

Background

Used in conjunction with fit: contain, this will specify the color used to fill any extra space in the output frame.

The background color is specified as a hex color.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  width: 720,
  height: 1280,
  fit: 'contain',
  background: '#20B075',
}

If not specified, the background will be black (hex color: #000000).

If only one of width or height is specified, or any value other than fit: contain is passed in, then background will have no effect and will be ignored.

FPS

The frame rate of the output video in frames per second. The value should be a number (integer or float) between 1 and 60.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  fps: 30,
}

If not specified, the frame rate will be the same as the input file.

If the input file has a frame rate that is not supported by the output format, the frame rate will be converted to the nearest supported value.

Format

The format of the video to encode. Shorthand for container and codec.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  format: 'mp4',
}

Available formats are:

• mp4 (shorthand for "container": "mp4", "codec": "h264")
• webm (shorthand for "container": "webm", "codec": "vp9")

Codec

The codec of the output video.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  codec: 'h264',
}

Available codecs are:

• h264 (audio will use aac audio codec)
• vp9 (audio will use opus audio codec)

Container

The container of the output video.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  codec: 'h264',
  container: 'mp4',
}

Available containers are:

• mp4
• webm

Whilst you can technically specify a vp9 codec inside an mp4 container, or h264 codec inside a webm container, these files are not supported by all players.

Quality

The desired quality of the output video. This is a number between 1 and 100, and it's a relative scale to the input file's quality.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  quality: 80,
}

Default is 80, which balances quality and filesize.

Start

From where in the video to start encoding in seconds.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  start: 10.0,
}

If not specified, the video will start at the beginning of the input file.

If your value is greater than the input file duration, the task will fail.

End

Where in the video to stop encoding in seconds.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  end: 30.0,
}

If not specified, the video will be encoded to the end of the input file.

If your value is greater than the input file duration, the output file will stop at the end of the input file.

Duration

The duration of the output video in seconds. An alternative to end.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  duration: 20.0,
}

If not specified, the video will be encoded to the end of the input file.

If your value is greater than the input file duration, the output file will stop at the end of the input file.

You can combine start and end, start and duration, or end and duration props. This gives you a lot of flexibility to output a specific segment of the input file.

Layers

Layers are used to add text and image overlays to the output video. The layers prop accepts an array of layer objects.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  layers: [
    {
      kind: 'image',
      url: 'https://example.com/logo.png',
      position: 'top left',
      width: 100,
      height: 100,
    },
    {
      kind: 'text',
      text: '@exampleusername',
      font: 'Inter',
      font_size: 32,
      color: '#FFFFFF',
      position: 'bottom right',
    },
  ],
}

Note: we're adding a complete guide to layers, packed with visual examples, soon. If you'd like to see an early preview, please contact us and we'd be happy to show you a draft.

Supported Inputs

Input files can contain:

Limits

Output files can be:

• upto 4096px on the longest edge
• upto 16MP in total pixels
• upto 4 hours in duration
• upto 4TB in size

Guides