Next.js video transformations

Overview

The Next.js SDK provides the CldVideoPlayer component for rendering videos with transformations and playback controls. The component is built on top of the Cloudinary Video Player, providing a feature-rich video experience with powerful transformation capabilities.

If you haven't yet installed the Next.js SDK, you might want to jump to the quick start first.

See also: Next.js 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 from one format to another
• Apply video effects such as fade-in/out, accelerating or decelerating, adjusting volume, playing in reverse
• Play video-in-video, trim videos, or concatenate multiple videos
• Set video and audio 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
• Generate thumbnails or animated images from video
• Deliver your video using 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 Next.js

To transform a video asset, use the CldVideoPlayer component with transformation props. The component handles video playback and transformations. For example:

In the above example, the walking_talking video is cropped to a 300 x 300 pixel video, focusing on the faces.

Alternative: Using getCldVideoUrl helper

You can also generate Cloudinary video URLs directly using the getCldVideoUrl helper method, then use the URL in a standard video tag:

Common video transformations

The transformation prop accepts an object or array of objects to apply transformations. Here are some examples of common video transformations.

Cropping and resizing

Crop a video to 300 x 300 pixels, using a fill crop with automatic gravity (keeping the important parts of the video in the crop):

Blur effect

Blur a video:

Accelerate

Speed up a video:

Brightness

Adjust the brightness of a video:

Image overlay

Add an image on top of the video:

Text overlay

Add text on top of the video:

Video overlay

Add a video on top of another video:

Adaptive Bitrate Streaming

Enable adaptive bitrate streaming for optimal playback across different network conditions:

Player configuration

Customize the video player's appearance, behavior, and functionality using the configuration options in the following sections.

General props

Prop Name	Type	Default	Description	Example
className	string	-	Additional class names added to the video container	"my-video-player"
height	string | number	-	Required: Player height	1080
id	string	-	Video instance ID, defaults to src value	"my-video"
logo	boolean | object	true	Logo to display in Player UI	See Logo
onDataLoad	Function	-	Triggered when video metadata is loaded	See Event handlers
onError	Function	-	Triggered on video error	See Event handlers
onMetadataLoad	Function	-	Triggered when video data is loaded	See Event handlers
onPause	Function	-	Triggered on video pause	See Event handlers
onPlay	Function	-	Triggered on video play	See Event handlers
onEnded	Function	-	Triggered when video has ended play	See Event handlers
playerRef	Ref	-	React ref to access Player instance	See Refs
poster	string | object	-	Customize the video's poster	See Poster
src	string	-	Required: Video public ID	"videos/my-video"
videoRef	Ref	-	React ref to access video element	See Refs
width	string | number	-	Required: Player width	1920

Player visuals props

Prop Name	Type	Default	Description	Example
aiHighlightsGraph	boolean	false	Display AI-generated highlights graph for video navigation	true
bigPlayButton	boolean | string	true	Show or customize the large play button in the center of the player	false | "init"
colors	object	See Theme colors	Player chrome colors	See Theme colors
controlBar	object	-	Customize the player control bar appearance and controls. More Info	{ pictureInPictureToggle: false }
controls	boolean	true	Show player controls	true
floatingWhenNotVisible	string	-	Enable floating player when scrolled out of view. Options: "left", "right"	"right"
fluid	boolean	-	Player fills container width while maintaining aspect ratio	true
fontFace	string	-	Player UI font. Uses Google Fonts.	"Source Serif Pro"
hideContextMenu	boolean	false	Hide the right-click context menu	true
interactionAreas	any	-	Define clickable areas within the video for interactive experiences. More Info	[{ x: 0, y: 0, width: 100, height: 100 }]
playbackRates	array	-	Available playback speed options	[0.5, 1, 1.5, 2]
playlistWidget	object	-	Configure playlist widget appearance and behavior. More Info	{ direction: "vertical" }
posterOptions	object	-	Advanced poster image configuration options	{ transformation: { effect: "blur" } }
showJumpControls	boolean	-	Show skip forward/backward buttons in the control bar	true
showLogo	boolean	true	Show the Cloudinary logo on Player	false
seekThumbnails	boolean	true	Show thumbnail previews when hovering over the seek bar	false
videoJS	object	-	Pass additional Video.js configuration options. More Info	{ nativeControlsForTouch: true }

Player behavior props

Prop Name	Type	Default	Description	Example
autoplay	string | boolean	"never"	When, if, should the video automatically play. Note that if the value passed is a boolean then the value will be passed to autoplay but if the value passed is a string then the value will be passed to autoplayMode. See autoplayMode in Video Player docs	"on-scroll" / true
autoShowRecommendations	boolean	false	Automatically show recommended videos when playback ends	true
disableRemotePlayback	boolean	false	Disable the ability to use remote playback (cast video) on the video element	true
loop	boolean	false	Loop the video	true
maxTries	number	3	Maximum number of retry attempts if video fails to load	5
muted	boolean	false	Load muted by default	true
pictureInPictureToggle	boolean	false	Uses browser's Picture-in-Picture API to add floating video UI.	true
playedEventPercents	array	[25, 50, 75, 100]	Percentage milestones that trigger played events for analytics	[10, 25, 50, 75, 90, 100]
playedEventTimes	array | null	null	Specific time points (in seconds) that trigger played events for analytics	[5, 10, 30, 60]
playsinline	boolean	-	Play video inline on mobile devices instead of fullscreen	true
videoTimeout	number	55000	Timeout (in milliseconds) before considering video load failed	60000
withCredentials	boolean	-	Include credentials in cross-origin video requests	true

Video config props

Prop Name	Type	Default	Description	Example
chapters	object	-	Define chapter markers for video navigation. More Info	{ 0: "Intro", 30: "Main Content", 120: "Conclusion" }
preload	string	auto	How much video data to preload. Options: "auto", "metadata", "none"	"metadata"
publicId	string	-	Alternative way to specify the video public ID (use src instead)	"my-video"
sourceTransformation	object	-	Transformations applied to the source before other transformations	{ quality: "auto" }
sourceTypes	array	-	Streaming format	['hls']
textTracks	object	-	Captions or subtitles for the active video	See Text Tracks
transformation	object | array	-	Transformations to apply to the video	{ width: 200, height: 200, crop: 'fill' }

Ads and analytics props

Prop Name	Type	Default	Description	Example
ads	object	-	Configure video ads using IMA SDK. More Info	{ adTagUrl: "https://example.com/ad-tag" }
analytics	boolean	false	Enable Cloudinary video analytics to track playback metrics	true
allowUsageReport	boolean	true	Allow the player to send anonymous usage data to Cloudinary	false

Logo

The logo prop gives the option to customize the player's logo.

logo defaults to true, showing the Cloudinary logo and linking to https://cloudinary.com when clicked.

When logo is set to false, no logo will be displayed.

To customize the logo, the following options are available in the form of an object:

Prop Name	Type	Default	Description
imageUrl	string	-	Image URL for player logo.
onClickUrl	string	-	URL to browse to on logo click.

Example:

Or hide the logo entirely:

Poster

The poster prop optionally takes a string or object to customize the generated poster.

When passing a string, you can either pass a Cloudinary Public ID or a remote URL to render the desired image.

When passing an object, use the same configuration and API as getCldImageUrl to customize the image. You can either specify a src option with a custom public ID or omit the src, which will use the video's ID to render an automatically generated preview image.

Using a Cloudinary public ID:

Using a remote URL:

Using transformations:

When passing an object, you can use the same API as getCldImageUrl to customize the poster. Omit the src to use the video's ID for an auto-generated preview:

Selecting a frame from the video:

You can select a specific frame from the video itself to use as the poster by specifying a start offset (so_<seconds>) in the transformation. This example uses a frame at 3.0 seconds:

Text tracks

The textTracks prop allows you to add captions or subtitles to the player.

Each Text Track is an object containing details about where the captions or subtitles should be loaded from as well as any customization of that track.

Example:

Theme colors

The colors prop takes an object that can control what colors are used in the player:

Prop Name	Type	Default	Description
accent	string	"#FF620C"	Seek bar, volume control and for highlighting interactions.
base	string	"#000000"	Player controls bar, information bar, central play button, and right-click context menu.
text	string	"#FFFFFF"	All the text and icons that are present within the video player UI.

Example:

Autoplay

Control when videos automatically play:

Loop

Make videos loop continuously:

Controls

Show or hide player controls:

Event handlers

React to player events. All event handlers receive an object containing the player instance:

Available event handlers:

• onPlay - Triggered when video starts playing
• onPause - Triggered when video is paused
• onEnded - Triggered when video playback ends
• onMetadataLoad - Triggered when video metadata is loaded
• onDataLoad - Triggered when video data is loaded
• onError - Triggered when a video error occurs

Refs

Access the player instance and video element directly using refs:

Advanced features

Picture-in-Picture

Enable picture-in-picture mode:

Playback rates

Allow users to change playback speed:

Analytics

Enable Cloudinary video analytics:

Chapters

Add chapters to your video with a chapter selector button:

Disable remote playback

Prevent the video from being cast to remote devices:

Localization

Customize the player's language and labels:

Configuration and delivery

Cloudinary environment configuration

Configure the Cloudinary environment:

Custom domain (CNAME)

Use a custom domain for video delivery:

Secure distribution

For private CDN distributions:

Query parameters

Add custom query parameters to video URLs: