> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.
# React video transformations
[shortcuts-link]:#shortcuts_and_aliases
## Overview
After uploading videos to Cloudinary, they can be transformed in many ways.
The syntax for transforming and delivering videos is generally similar to that for images, and you can apply the majority of available image transformations to video as well. For example, you can resize, crop, rotate, set video quality and format or use auto quality and/or auto format, add text or image overlays to your videos, and more.
There are also a number of special options you can use for transforming and delivering video content. For example, you can adjust their speed, duration, sound, and appearance. There are also some features that are specific to audio.
This section introduces you to the basics of video transformations using the `@cloudinary/url-gen` package.
For complete details on all video transformation functionality, see [Video transformations](video_manipulation_and_delivery) and the [Transformation URL API reference](transformation_reference).
If you haven't yet installed the React SDK, you might want to jump to the [quick start](react_quick_start) first.
See also: [React image transformations](react_image_transformations)
## Video transformation functionality
In addition to transformation features that are equally relevant for images and video, such as resizing, cropping, rotating, adding text or image overlays, and setting video quality or format, there are a variety of special transformations you can use for video. For example, you can:
* [Transcode videos](video_manipulation_and_delivery#transcoding_videos_to_other_formats) from one format to another
* Apply [video effects](video_effects_and_enhancements) such as fade-in/out, accelerating or decelerating, adjusting volume, playing in reverse
* Play [video-in-video](video_layers#video_overlays), [trim](video_trimming_and_concatenating#trimming_videos) videos, or [concatenate](video_trimming_and_concatenating#concatenating_media) multiple videos
* Set [video](video_manipulation_and_delivery#video_codec_settings) and [audio](audio_transformations#audio_settings) quality options such as bitrate, video codec, audio sampling frequency, or audio codec
* Adjust the visual tone of your video with [3-color-dimension LUTs](video_effects_and_enhancements#3_color_dimension_luts_3d_luts)
* Generate [thumbnails](video_effects_and_enhancements#video_thumbnails) or [animated](videos_to_animated_images) images from video
* Deliver your video using [adaptive bitrate streaming](adaptive_bitrate_streaming) in HLS or MPEG-DASH
You can optionally specify all of the above transformations to videos using methods that generate image tags or via direct URL-building directives.
## Video transformations with React
To transform a video asset, use the `@cloudinary/url-gen` package to create the transformation, then pass the transformed video object to the `cldVid` attribute in your `AdvancedVideo` component to render the video on your site. For example:
```react
import React from 'react'
import {AdvancedVideo} from '@cloudinary/react';
import {Cloudinary} from "@cloudinary/url-gen";
// Import required actions and qualifiers.
import {fill} from "@cloudinary/url-gen/actions/resize";
import {byRadius} from "@cloudinary/url-gen/actions/roundCorners";
import {FocusOn} from "@cloudinary/url-gen/qualifiers/focusOn";
import {Gravity} from "@cloudinary/url-gen/qualifiers";
import {AutoFocus} from "@cloudinary/url-gen/qualifiers/autoFocus";
const App = () => {
// Create and configure your Cloudinary instance.
const cld = new Cloudinary({
cloud: {
cloudName: 'demo'
}
});
// Use the video with public ID, 'docs/walking_talking'.
const myVideo = cld.video('docs/walking_talking');
// Apply the transformation.
myVideo.resize(fill().width(150).height(150)
.gravity(Gravity.autoGravity().autoFocus(AutoFocus.focusOn(FocusOn.faces())))) // Crop the video, focusing on the faces.
.roundCorners(byRadius(20)); // Round the corners.
// Render the transformed video in a React component.
return (
)
};
```
In the above example, the walking_talking video is cropped to a 150 x 150 pixel video with rounded corners, focusing on the faces, resulting in this video element:
```html
```
The `@cloudinary/url-gen` package installs an additional [transformation-builder-sdk](https://github.com/cloudinary/js-transformation-builder-sdk) library as a dependency, which handles the transformation generation part of the URL.
You can use the [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation-builder/index.html) to find all available transformations, syntax and examples.### Syntax overview
The `@cloudinary/url-gen` package provides an intuitive coding experience for transforming an asset:
* The SDK supports an action-based syntax, designed to make building delivery URLs and transformations logical and discoverable.
* It allows discovering the available options from within your development environment, and ensures that only options that are supported can be used together.
The general form of the syntax is:
An example being:
[//]: # (source file: https://docs.google.com/presentation/d/1uSIigbItua-GFIY9Ppd0btXC7F1juyDACveokLlXlSw/edit?usp=sharing)
#### Actions and ActionGroups
* Assets expose methods called **ActionGroups** (`myVideo.adjust()`) that represent a directive to Cloudinary on how to transform a specific aspect of an asset
* ActionGroups receive an **Action** object as a parameter that defines the specific action to apply
* Action objects are created through Factory methods (`Adjust.brightness()`)
* Some actions require a qualifier as a parameter (`20`)
* You can find more Actions in `@cloudinary/url-gen/actions`
* You can import all actions with `import {Actions} from '@cloudinary/url-gen'`
#### Qualifiers and QualifierValues
* Actions expose methods to define their behaviors (`level()`)
* We call the methods on Actions, **Qualifiers**
* Qualifiers usually accept a **QualifierValue** (`20` in `level(20)`)
* QualifierValues can be primitive (numbers, strings) or predefined SDK values that can be imported
* Many QualifierValues are functions
* You can find more QualifierValues in `@cloudinary/url-gen/qualifiers`
The output of each ActionGroup is a complete [transformation component](video_manipulation_and_delivery#chained_transformations) in the URL.
#### Tree shaking
The `@cloudinary/url-gen` package allows you to import only what you need, to minimize your bundle size.
See the [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation-builder/list_namespace.html) for all actions and qualifiers.
For example, if you import `Effect`, you import all effect actions, which may be more than you need. The only reason you may want to do this is to make other methods discoverable. Without tree shaking, actions require qualification (for example, `Effect.blur()`).
* **Without tree shaking**:
```js
import {Effect} from "@cloudinary/url-gen/actions/effect";
// Effect.blur()
```
You can also use:
```js
import {Effect} from "@cloudinary/url-gen/actions/effect";
const {blur} = Effect;
// blur()
```
In this case `blur()` is equivalent to `Effect.blur()`.
* **With tree shaking**:
```js
import {blur} from '@cloudinary/url-gen/actions/effect';
// blur()
```
Similarly, for qualifier values:
* **Without tree shaking**:
```js
import {Gravity} from "@cloudinary/url-gen/qualifiers/gravity";
// Gravity.autoGravity()
```
* **With tree shaking**:
```js
import {autoGravity} from "@cloudinary/url-gen/qualifiers/gravity";
// autoGravity()
```
Most of the examples shown in this guide use tree shaking.
#### Shortcuts and aliases
To simplify some of the syntax, you can use [string shortcuts](https://github.com/cloudinary/js-url-gen/blob/master/src/types/types.ts) for nested qualifiers. For example, rather than:
```js
myVideo.delivery(Delivery.format(Format.mp4()));
```
you can say:
```js
myVideo.delivery(Delivery.format('mp4'));
```
Additionally, there are aliases for delivery format and quality, to shorten the syntax further. For example, the above can be shortened to:
```js
myVideo.format('mp4');
```
For quality, instead of:
```js
myVideo.delivery(Delivery.quality('auto'));
```
you can say:
```js
myVideo.quality('auto');
```
### Alternative ways to apply transformations
There are a couple of other ways to apply transformations to your videos that you may prefer to use, for example if a new transformation is not yet supported by the SDK, or if you're more familiar with other SDKs. Note, however, that you won't benefit from your IDE's code completion feature for building the transformations in these ways.
**See also**: [Shortcuts and aliases][shortcuts-link] for other ways to simplify the syntax.
#### URL syntax
You can add any transformation in [URL syntax](transformation_reference) using the `addTransformation` method.
For example:
```js
myVideo.addTransformation('c_thumb,g_face,h_150,w_150/r_20');
```
This can be used together with other actions and qualifiers in the usual way. It's useful if a new transformation is added but not yet available in the SDK, or if you're just more familiar with the URL syntax.
#### Object syntax
If you prefer the more concise syntax used for [transformations in the Node.js SDK](node_image_manipulation), you can use the `transformationStringFromObject` method to build the transformation, and add it to your video using `addTransformation`, importing only `transformationStringFromObject` instead of all the individual actions and qualifiers.
For example:
```js
import { transformationStringFromObject } from "@cloudinary/url-gen";
const transformation = transformationStringFromObject([
{gravity: "face", height: 150, width: 150, crop: "thumb"},
{radius: 20}
]);
myVideo.addTransformation(transformation);
```
> **NOTE**: The JavaScript required for this syntax is likely to be heavier than importing the actions and qualifiers separately.
### AdvancedVideo properties
The `AdvancedVideo` component accepts the following properties:
* [The cldVid property](#the_cldvid_property)
* [The cldPoster property](#the_cldposter_property)
* [HTML video attributes](#html_video_attributes)
* [HTML media events](#html_media_events)
* [Plugins](#plugins)
* [Sources](#sources)
#### The cldVid property
The `cldVid` property accepts a `CloudinaryVideo` object.
#### The cldPoster property
The `cldPoster` property accepts a `CloudinaryImage` object, or a `CloudinaryVideo` transformed to an image format.
For example:
```react
```
This takes the center frame of the video as the poster:
You can also set `cldPoster` to `"auto"` to select the best frame of the video to use as the poster (`so_auto`), and apply automatic quality (`q_auto`) to the image:
```react
```
#### HTML video attributes
The `AdvancedVideo` component accepts the following properties, which result in standard HTML `video` attributes:
AdvancedVideo property | HTML video attribute
--|--
autoPlay | autoplay
controls | controls
loop | loop
muted | muted
playsInline | playsinline
poster | poster
preload | preload
For example, this video would play inline, with controls, loop and start with the specified poster image:
```react
```
> **NOTE**: The [cldPoster](#the_cldposter_property) property takes precedence over the `poster` property if both are specified.
#### HTML media events
The `AdvancedVideo` component accepts the following properties, which result in standard HTML media event attributes:
AdvancedVideo event | HTML media event
--|--
onEnded | onended
onError | onerror
onLoadStart | onloadstart
onPlay | onplay
onPlaying | onplaying
For example, this video would call the `playFunction` function when played and the `endFunction` function when it ends:
```react
```
#### Plugins
You can lazy load your videos, in the same way as you can for images, using the [lazyload plugin](react_image_transformations#lazy_loading).
For example, this video would only load when it comes into the viewport, then play automatically:
```react
```
#### Sources
You can optionally specify sources in the `sources` property, such as:
```react
import { videoCodec } from "@cloudinary/url-gen/actions/transcode";
import { auto, vp9 } from '@cloudinary/url-gen/qualifiers/videoCodec';
const sources = [
{
type: 'mp4',
codecs: ['avc1.4d002a'],
transcode: videoCodec(auto())
},
{
type: 'webm',
codecs: ['vp8', 'vorbis'],
transcode: videoCodec(vp9())
}];
```
For example, this video would have a choice of two sources:
```react
```
It results in the following `video` element:
```html
```
### Direct URL building
You can build a video URL by:
1. Configuring your Cloudinary instance.
1. Instantiating a `CloudinaryVideo` object for the video you want to deliver, using `cld.video()`.
1. Calling the `toURL()` method of the `CloudinaryVideo` class to return the delivery URL:
```js
import {Cloudinary} from "@cloudinary/url-gen";
// Create and configure your Cloudinary instance.
const cld = new Cloudinary({
cloud: {
cloudName: 'demo'
}
});
// Instantiate a CloudinaryVideo object for the video with public ID, 'elephants'.
const myVideo = cld.video('elephants');
// Get the URL of the video.
const myURL = myVideo.toURL();
```
The resulting URL, `myURL`, is:
#### Specifying a version of your video to deliver
You can specify a particular version of your video to deliver by using the `setVersion` method. The version is added to the delivery URL as explained in [Asset versions](advanced_url_delivery_options#asset_versions).
For example, to specify version `1510668637` of the elephants video from the example above:
```js
myVideo.setVersion(1510668637);
```
The resulting URL is now:
#### Transforming your video
Videos are transformed by adding serialized transformation instructions to the video delivery URL. For example, to scale your video to a width of 400 pixels, add `c_scale,w_400`.
`https://res.cloudinary.com/demo/video/upload/c_scale,w_400/elephants.mp4`
Using the `@cloudinary/url-gen` package, you transform a video by performing one or more transformation actions on the `CloudinaryVideo` object (see the [syntax overview](#syntax_overview)). Remember to import the actions that you are using:
```js
import {Cloudinary} from "@cloudinary/url-gen";
// Import the scale mode from the resize action.
import {scale} from "@cloudinary/url-gen/actions/resize";
// Create and configure your Cloudinary instance.
const cld = new Cloudinary({
cloud: {
cloudName: 'demo'
}
});
// Instantiate a CloudinaryVideo object for the video with public ID, 'elephants'.
const myVideo = cld.video('elephants');
// Scale the video to a width of 400 pixels.
myVideo.resize(scale().width(400));
// Get the URL of the video.
const myURL = myVideo.toURL();
```
The resulting URL is:
> **TIP**: Discover [alternative ways to apply transformations](#alternative_ways_to_apply_transformations) to your videos.
## Code explorer: React video transformations
In this React app, you can see all the transformations that are used throughout this guide. Each transformation example has its own JavaScript file showing the imports and syntax required. (Use the hamburger menu to see all the files.)
**Videos.jsx** imports all the functions and uses `AdvancedVideo` components to display the transformed videos on a simple web page.
This code is also available in [GitHub](https://github.com/cloudinary-devs/react-image-video-transformations).
> **TIP**: Enjoy interactive learning? Check out more [code explorers](code_explorers)!## Video transformation examples
This section provides examples of using the `@cloudinary/url-gen` package to apply some of the video transformation features mentioned in the previous section.
### Example 1:
The following example resizes the `elephants` video to 20% of its original size and rotates it by 20 degrees. It also adds a semi-transparent Cloudinary logo in the bottom right corner, using a southeast gravity with adjusted x and y coordinates to reach the corner of the rotated video.
```js
import {Cloudinary} from "@cloudinary/url-gen";
import {Transformation} from "@cloudinary/url-gen";
import {scale} from "@cloudinary/url-gen/actions/resize";
import {byAngle} from "@cloudinary/url-gen/actions/rotate";
import {source} from "@cloudinary/url-gen/actions/overlay";
import {opacity} from "@cloudinary/url-gen/actions/adjust";
import {image} from "@cloudinary/url-gen/qualifiers/source";
import {Position} from "@cloudinary/url-gen/qualifiers/position";
import {compass} from "@cloudinary/url-gen/qualifiers/gravity";
// Create and configure your Cloudinary instance.
const cld = new Cloudinary({
cloud: {
cloudName: 'demo'
}
});
// Use the video with public ID, 'elephants'.
const myVideo = cld.video('elephants');
// Apply the transformation.
myVideo
.resize(scale().width(0.2))
.rotate(byAngle(20))
.overlay(
source(
image('cloudinary_icon')
.transformation(new Transformation()
.resize(scale().width(60))
.adjust(opacity(50))
)
)
.position(new Position().gravity(compass('south_east')).offsetX(60).offsetY(15))
);
// Get the URL of the video.
const myURL = myVideo.toURL();
```
The resulting URL is:
### Example 2:
The following example adjusts the brightness of the video, and sets its radius to max in order to give a telescope-like effect. It then appends a copy of the video in reverse, and then plays forward again, but in slow motion.
```js
import {Cloudinary} from "@cloudinary/url-gen";
import {Transformation} from "@cloudinary/url-gen";
import {reverse,accelerate} from "@cloudinary/url-gen/actions/effect";
import {brightness} from "@cloudinary/url-gen/actions/adjust";
import {max} from "@cloudinary/url-gen/actions/roundCorners";
import {concatenate} from "@cloudinary/url-gen/actions/videoEdit";
import {Concatenate} from "@cloudinary/url-gen/qualifiers/concatenate";
// Create and configure your Cloudinary instance.
const cld = new Cloudinary({
cloud: {
cloudName: 'demo'
}
});
// Use the video with public ID, 'ski_jump'.
const myVideo = cld.video('ski_jump');
// Apply the transformation.
myVideo
.videoEdit(concatenate(Concatenate.videoSource('ski_jump').transformation(new Transformation().effect(reverse()))))
.videoEdit(concatenate(Concatenate.videoSource('ski_jump').transformation(new Transformation().effect(accelerate(-50)))))
.adjust(brightness(10))
.roundCorners(max());
// Get the URL of the video.
const myURL = myVideo.toURL();
```
The resulting URL is:
## Video tutorial: Optimizing videos in React
Watch this video tutorial to learn how to optimize the delivery of your videos:
This video is brought to you by Cloudinary's video player - embed your own!Use the controls to set the playback speed, navigate to chapters of interest and select subtitles in your preferred language.
### Tutorial contents This tutorial presents the following topics. Click a timestamp to jump to that part of the video.
### Why optimize videos for delivery?
{table:class=tutorial-bullets}| |
| --- | --- |
|{videotime:id=media :min=0 :sec=00 :player=cld} | Adding videos to your application can significantly add weight to your page, impacting performance and user experience. Cloudinary provides ways to reduce the weight of videos by automatically optimizing their quality and format for delivery.
|
### Automatic quality
{table:class=tutorial-bullets}| |
| --- | --- |
|{videotime:id=media :min=0 :sec=18 :player=cld} | Once you've installed and configured the [Cloudinary React SDK](react_quick_start#1_set_up_and_configure_the_sdk), and you're using the `cld.video` method to [create the delivery URL](react_video_transformations#direct_url_building) for your video, you can add the `quality` method set to `auto` to deliver your video with the best encoding to minimize the file size without impacting visual quality.
|
```react
```
### Automatic format
{table:class=tutorial-bullets}| |
| --- | --- |
|{videotime:id=media :min=0 :sec=36 :player=cld} | Use the `AdvancedVideo` component to deliver the video in its optimal format. This component automatically creates sources for modern formats allowing the browser to select the best format that it supports.
|
```react
import { AdvancedVideo } from '@cloudinary/react';
```
### Further optimizations
{table:class=tutorial-bullets}| |
| --- | --- |
|{videotime:id=media :min=1 :sec=18 :player=cld} | You can optimize your videos further by delivering the size you need using [resize transformations](video_resizing_and_cropping).
|