Video transformation reference

The table below lists all supported video transformation parameters. For each parameter, you can see the short name, which is used when manually building transformation URLs, and the longer name for use when delivering videos using our SDKs.

You can create a wide range of effects and transformations by chaining together any combination of the parameters listed below.

For more in-depth information on transforming videos, see the video transformation guide.

Note: Except where specifically noted, the parameter names are relevant for all SDKs. However, you may need to adjust the case style to fit the language you are using. For example, for some languages, you may need to use camelCase or PascalCase instead of snake_case. For details, see the Capitalization and data type guidelines section of the relevant SDK guide.

Library Parameter URL Parameter Value Description

Resizing and cropping videos

width w Integer or float The required width of a transformed video.
80 An integer value resizing width to 80 pixels.
0.2 A float value resizing video to 20% of its original size.
height h Integer or float The required height of a transformed video.
40 An integer value resizing height to 40 pixels.
0.3 A float value resizing video to 30% of its original size.
crop c String A crop mode that determines how to transform the video for fitting into the desired width & height dimensions.
scale Change the size of the video to match the given width and/or height. All original video parts will be visible and are stretched if necessary to fill the new dimensions, This is the default cropping mode.
fill Create a video with the exact given width and height while retaining original proportions. Uses only a portion of the original video that fills the given dimensions.
fit Change video size to fit in the given width and height while retaining original proportions. All original video parts are visible and the resulting image will fit in the given dimensions, maintaining aspect ratio and scaling up or down as needed.
limit Used for creating a video that does not exceed the given width or height while retaining original proportions. All original video parts are visible and scaled down if needed.
pad Scale the video up or down as needed to fit in the given width and height while retaining original proportions. Padding will be added if the original video proportions do not match the required ones.
lpad Same as the 'pad' mode but doesn't scale the video up if your requested dimensions are larger than the original video's.
crop Used to extract a given width and height out of the original video. The original proportions are retained and so is the size of the graphics. Used together with x and y coordinates for specifying the section to crop (or with the gravity parameter).
aspect_ratio ar String or float Resizes the video to a new aspect ratio.
4:3 A string value in the form a:b, where a is the width and b is the height. The example value resizes the aspect ratio to 4/3.
2.5 A decimal value representing the width divided by the height. The example value resizes the aspect ratio to 5/2.
gravity g String Decides which part of the video to keep while 'crop', 'pad' and 'fill' crop modes are used. For overlays, this decides where to place the overlay.
north_west North west corner (top left).
north North center part (top center).
north_east North east corner (top right).
west Middle west part (left).
center The center of the video (default value).
east Middle east part (right).
south_west South west corner (bottom left).
south South center part (bottom center).
south_east South east corner (bottom right).
background b String Defines the background color to use in the case of padding.
blue Fill the background with a named color.
rgb:9090ff Fill the background with the color defined by a RGB hex triplet. Client libraries support a # shortcut (e.g. #9090ff).
rgb:999 Fill the background with the color defined by a 3 character RGB value. Client libraries support a # shortcut (e.g. #999).

Rotating videos

angle a Integer Rotate a video by the given degrees.
90 Rotate video by 90 degrees clockwise.
-20 Rotate video by 20 degrees counterclockwise.

Video Settings

format or fetch_format f (or file extension) String Format conversion to the given web format while normalizing and optimizing for web and mobile viewing.
webm Convert a video to the WebM format.
mp4 Convert a video to the MP4 format.
ogv Convert a video to the OGV format.
flv Convert a video to the FLV format.
m3u8 Create the index and fragment files necessary for HTTP Live Streaming (HLS).
video_codec vc String The video codec (with video profile and level if relevant). In URLs, use the syntax: <codec>[:<profile>:[<level>]].
Supported video codecs:
vp9 | vp8 | prores (422HQ) | h264 | h265 | theora
auto Normalize and optimize the video for web viewing with the following settings for each format:

MP4

Video codec: h264, profile: baseline, quality: 70, audio codec: aac, audio frequency: 22050.

WebM

Video codec: vp8, quality: 70, audio codec: vorbis, audio frequency: 22050.

OGV

Video codec: theora, quality: 70, audio codec: vorbis, audio frequency: 22050.

FLV

Video codec: h264, profile: high, quality: 70, audio codec: aac, audio frequency: 22050.

<codec>[:<profile>:[<level>]] Specific values to apply for video codec, profile and level. Examples:
  • h264:baseline
  • h264
  • h264:baseline:3.1
quality q Integer Control the video quality. 1 is the lowest quality and 100 is the highest. Reducing quality generates videos smaller in file size. See the video_codec parameter for the default values for each format.
50 Generate a video using a low quality of 50.
bit_rate br Integer or String Advanced control of video bitrate in bits per second. By default the video uses a variable bitrate (VBR), with this value indicating the maximum bitrate. If constant is specified, the video plays with a constant bitrate (CBR).
Supported codecs: h264, h265 (MPEG-4); vp8, vp9 (WebM).
500000 Maximum number of bits per second as an integer.
500k Maximum number of bits per second as a string, supporting k and m for kilobits and megabits respectively e.g., 500k or 1m. The k and m are supported on the server-side.
500k:constant or 500000:constant Constant number of bits per second (CBR). When constant is used, the quality parameter is ignored.
streaming_profile sp String The name of the streaming profile to apply to an HLS or MPEG-DASH adaptive bitrate streaming video.
The value can be one of the pre-defined streaming profiles or a custom-defined one.
You can use the streaming_profiles method of the Admin API to get a list of the available streaming profiles or to create new custom profiles.
full_hd Apply the `full_hd` pre-defined streaming profile to the HLS or MPEG-DASH video.

Video Effects

effect e String:Integer Apply a filter or an effect on a video. The value includes the name of the effect and an additional parameter that controls the behavior of the specific effect.
accelerate:100 Speeds up the video playback speed by %100. A negative value would slow down the playback speed (Range: -50 to 100 Default: 0).
noise:10 Adds 10% visual noise to the video, visible as a random flicker of "dots" or "snow" (Range: 0 to 100 Default: 0).
deshake:32 Remove small motion shifts from the video with a maximum extent of movement in the horizontal and vertical direction of 32 pixels (Range: 16, 32, 48 or 64 Default: 16).
fade:2000 Fade in to the beginning of the video over 2000 milliseconds. A negative value would fade out at the end of the video (Default: 1000).
blur:500 Blur the video. (Range: 1-2000 Default: 100).
contrast:50 Increase the contrast by 50.
brightness:30 Increase the brightness by 30.
saturation:-20 Decrease the saturation by 20.
gamma:15 Increase the gamma by 15.
vignette:40 Apply a vignette effect with a value of 40.
volume:70 Increase the volume by 70%.
reverse Play the video or audio file in reverse.
loop:2 Deliver a video or animated GIF that contains 2 additional loops (a total of 3 iterations) of the video/GIF. For animated GIFs only, you can also specify the loop effect without a numeric value to instruct it to loop the GIF infinitely.

Video Flags

flags fl String Set a flag that alters the default transformation behavior.
animated Use when delivering a video file as an image format that supports animation, such as animated WebP. Plays all frames rather than just delivering the first one as a static image. Use this flag in addition to the flag or parameter controlling the delivery format, for example f_auto or fl_awebp.

Note: When delivering a video in GIF format, it is delivered as an animated GIF by default and this flag is not necessary. To deliver a single frame of a video in GIF format, use the page parameter.
awebp Deliver the specified file as an animated WebP. Note that animated WebPs are not supported in all browsers and versions.
hlsv3 Deliver an HLS adaptive bitrate streaming file as HLS v3 instead of the default version (HLS v4). Delivering in this format requires a private CDN configuration. For more information about delivering HLS files, see Adaptive bitrate streaming - HLS and MPEG DASH.
layer_apply Apply all chained transformations, until a transformation component that includes this flag, on the last added overlay instead of applying them on the containing video.
no_stream Don't stream a video that is currently being generated on the fly. Wait until the video is fully generated.
mono Convert the audio channel to mono
relative Modify percentage-based width & height parameters of overlays (e.g., 0.5) to be relative to the containing video instead of the added layer.
splice Splice the video stipulated as an overlay on to the end of the container video instead of adding it as an overlay.
truncate_ts Truncate (trim) a video file based on the start time defined in the metadata (relevant only where the metadata includes a directive to play only a section of the video).
waveform Create a waveform image (in the format specified by the file extension) from the audio or video file.

Audio Settings

audio_codec ac String Control the audio codec or remove the audio channel
none Remove audio channel
aac Set audio codec to aac (mp4 or flv only)
vorbis Set audio codec to vorbis (ogv or webm only)
mp3 Set audio codec to mp3 (mp4 or flv only)
audio_frequency af Integer Control audio sample frequency.
44100 This parameter represents an integer value in Hz and can only take one of the following values: 8000, 11025, 16000, 22050, 32000, 37800, 44056, 44100, 47250, 48000, 88200, 96000, 176400 or 192000.

Animated GIFs and animated WebPs

video_sampling vs Integer or String Relevant for conversion of video to animated GIF or WebP. If not specified, the resulting GIF or WebP samples the whole video (up to 400 frames, at up to 10 frames per second). By default the duration of the animated image is the same as the duration of the video, no matter how many frames are sampled from the original video (use the delay parameter to adjust the amount of time between frames).
20 Integer - The total number of frames to sample from the original video. The frames are spread out over the length of the video, e.g. 20 takes one frame every 5%.
'2.3s' String - The number of seconds between each frame to sample from the original video. e.g. 2.3s takes one frame every 2.3 seconds.
delay dl Integer Controls the time delay between the frames of an animated image, in milliseconds.
20 Sets the delay between frames of the animated image to 20 milliseconds.

Adding overlays

overlay l String Add an overlay over the base video. You can control the dimension and position of the overlay using the width, height, x, y and gravity parameters. The string identifier is the public ID of an uploaded image you want to overlay or one of the special overlay types.
badgeAdd the overlay of an uploaded image with the public ID 'badge'.
text:Roboto_30p:Hello WorldAdd a 'Hello World' text overlay using the Roboto font and 30px size characters.
subtitles:sample.srtAdd subtitles as specified in the 'sample.srt' file to the video.
subtitles:arial_20:sample.srtAdd subtitles in 20 pixel Arial font as specified in 'sample.srt'.
lut:lut_name.3dlApply the specified 3D LUT file to the video.
video:dogAdd the overlay of an uploaded video with the public ID 'dog'.

Offset parameters for Trimming and Overlays

start_offset so Float or string Offset in seconds or percent of a video, normally used together with the end_offset and duration parameters. Used to specify one of the following:
  • The start of the video to be kept after trimming.
  • The frame to use when generating an image thumbnail.
  • When an overlay starts displaying.
2.63 Float representing seconds
'35p' String representing a percent value
'35%' String representing a percent value (only supported in client libraries and is converted to 35p in the generated URL.).
auto Automatically selects a suitable frame from the first few seconds of the video (only relevant for generating image thumbnails).
end_offset eo Float or string Offset in seconds or percent of a video, normally used together with the start_offset and duration parameters. Used to specify:
  • The end of the video to be kept after trimming.
  • When an overlay ends displaying.
5.33 Float representing seconds.
'75p' String representing a percent value.
'55%'' String representing a percent value (only supported in client libraries and is converted to 55p in the generated URL).
duration du Float or string Offset in seconds or percent of a video, normally used together with the start_offset and end_offset parameters. Used to specify:
  • The duration the video displays.
  • The duration an overlay displays.
6.12 Float representing seconds
'60p' String representing a percent value.
'40%' String representing a percent value (only supported in client libraries and is converted to 40p in the generated URL).
offset - [float, float] or [string, string] or a range Shortcut to set video cutting using a combination of start_offset and end_offset values. Client library only.
[2.66, 3.21] Float values in seconds.
['35%', '70%'] Strings representing percent values.
['35p', '70p'] Strings representing percent values.
2.66..3.21 or '35p..65p' Range of float values in seconds, or range of strings representing percent values (in frameworks supporting ranges only).