> ## 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.

# Python video transformations

## Overview

After uploading videos to Cloudinary, they can be transformed in many ways. 

The syntax for transforming and streaming videos is generally the same as 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 size, shape, speed, duration, quality, and appearance. There are also some features that are specific to audio.  

This section introduces you to the basics of Python video streaming and transformation.
For complete details on all video transformation functionality, see [Video transformations](video_manipulation_and_delivery) and the [Transformation URL API Reference](transformation_reference).

## 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 tag helper method

You can optionally specify all of the above transformations with the `video` method of the `CloudinaryVideo` class, which automatically generates an HTML5 video tag including the transformation URL sources for the main formats supported by web browsers (`webm`, `mp4` and `ogv`), as well as a poster thumbnail image. This enables the browser to automatically select and play the video format it supports. The video files are created dynamically when first accessed by your users.

For example:

```python
from cloudinary import CloudinaryVideo

CloudinaryVideo("blue_sports_car").video(loop=True, controls=True, 
 transformation = 
        {"height": 360, "width":480, "quality": 70, "duration": 10, "crop": "pad"}, 
 fallback_content="Your browser does not support HTML5 video tags.")
```  

> **NOTE**: Import the `CloudinaryVideo` method to use the simplified syntax as shown in many examples within in this guide. If you import only `cloudinary` without `CloudinaryVideo`, you can still access this class with `cloudinary.CloudinaryVideo`.

The above statement results in the following HTML:

```html
<video controls loop poster="https://res.cloudinary.com/demo/video/upload/c_pad,du_10,h_360,q_70,w_480/blue_sports_car.jpg">
  <source src="https://res.cloudinary.com/demo/video/upload/c_pad,du_10,h_360,q_70,w_480/blue_sports_car.webm" type="video/webm">
  <source src="https://res.cloudinary.com/demo/video/upload/c_pad,du_10,h_360,q_70,w_480/blue_sports_car.mp4" type="video/mp4">
  <source src="https://res.cloudinary.com/demo/video/upload/c_pad,du_10,h_360,q_70,w_480/blue_sports_car.ogv" type="video/ogg">
  Your browser does not support HTML5 video tags.
</video>
```

You can also add other, non-transformation parameters to the `video` method such as the asset version, configuration parameters and HTML5 video tag attributes.
* The `version` parameter is added to the delivery URL as explained in [Asset versions](advanced_url_delivery_options#asset_versions).
* [Configuration parameters](cloudinary_sdks#configuration_parameters) that you specify here override any that you have set globally.
* [HTML5 video tag attributes](https://www.w3schools.com/tags/tag_video.asp) are added to the resulting `<video>` tag. The video is delivered from Cloudinary using the width and height in the transformation but is displayed at the dimensions specified in the tag.

For details, see the [video tag](video_manipulation_and_delivery#embedding_videos_in_web_pages_using_sdks) documentation and the [HTML5 Video Player](https://cloudinary.com/blog/how_to_get_the_most_from_the_html5_video_player) blog post.

### Direct URL builder

The `video` method described above generates an HTML5 video tag. In certain conditions, you might want to generate a transformation URL directly, without the containing video tag. To return only the URL, either use the `build_url` method of the `CloudinaryVideo` class, or using a standard Python command - `cloudinary.utils.cloudinary_url`. 

Here's an example:

```python
from cloudinary import CloudinaryVideo

CloudinaryVideo("docs/sunglasses").build_url(secure=True, transformation=[
    {"start_offset": "7.5", "end_offset": "10"},
    {"effect": "boomerang"},
    {"width": 0.2, "crop": "scale"}
    ])

## Output: `https://res.cloudinary.com/demo/video/upload/so_7.5,eo_10.0/e_boomerang/c_scale,w_0.2/v1/docs/sunglasses.mp4`
```

Best practices for each method with examples...

#### CloudinaryVideo class (build_url method)
**When to Use:**

Use the`build_url` method when you're working directly with instances of Cloudinary videos and need to generate URLs specific to those videos.

**Advantages:**

* Provides a more object-oriented approach for URL generation, particularly when dealing with Cloudinary videos and their transformations.
* Transformations based on this method are clear, direct and focused because URLs are tailored specifically for individual video instances.

**Example:**

Generate customized thumbnail videos for user profile pictures, where the cropping and dimensions vary based on user preferences.
```python
from cloudinary import CloudinaryVideo

# Retrieve video's public ID from database
video_id = "<public_id>"

# Instantiate a CloudinaryVideo object with the its ID
preview_video = CloudinaryVideo(video_id)

# Generate URL with custom transformations based on user preferences
preview_video_url = preview_video.build_url(transformation={'width': 300, 'height': 300, 'crop': 'thumb'})
print("User Preview Video URL:", preview_video_url)
```

#### cloudinary.utils.cloudinary_url method
**When to Use:**

Use `cloudinary.utils.cloudinary_url` when dynamically generating Cloudinary URLs based on transformation parameters and other options, without direct reliance on Cloudinary video instances. This method can be applied to various asset types, not just videos, allowing for diverse transformations and options. For instance, you may need to apply distinct transformations based on the asset type or specific criteria like file size or aspect ratio.

**Advantages:**

* Provides flexibility for dynamically generating URLs based on changing conditions or user input, decoupled from specific image instances.
* Allows for granular control over transformation parameters and options, facilitating intricate transformations or conditional logic within your code.

**Example:**

Generate dynamic asset URLs with conditional logic based on user preferences or application settings.
```python
# User's preferred asset dimensions retrieved from database
user_preferred_width = <width>
user_preferred_height = <height>

# Check if user prefers square thumbnails
if user_preferred_width == user_preferred_height:
    # Generate square thumbnail with crop mode
    dynamic_asset_url, _ = cloudinary.utils.cloudinary_url('sample', transformation={'width': user_preferred_width, 'height': user_preferred_height, 'crop': 'fill'})
else:
    # Generate rectangular thumbnail without crop
    dynamic_asset_url, _ = cloudinary.utils.cloudinary_url('sample', transformation={'width': user_preferred_width, 'height': user_preferred_height, 'crop': 'scale'})

print('Dynamic Asset URL:', dynamic_asset_url)
```

## Video transformation examples 

Here are some examples of using Python to apply some of the video transformation features mentioned in the previous section using the video tag helper method.

#### Example 1: 

The following example resizes the video to 30% of it's original size and rounds the corners by 20 pixels. 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 video.

```python
CloudinaryVideo("glide-over-coastal-beach").video(controls=True, transformation=[
    {"width": 0.3, "radius": 20},
    {"overlay": "cloudinary_icon_white", "width": 60, "opacity": 50, "gravity": "south_east", "y": 15, "x": 60}
    ])
```

![video with cloudinary icon](https://res.cloudinary.com/demo/video/upload/w_0.3,r_20/l_cloudinary_icon_white,w_60,o_50,g_south_east,y_15,x_60/glide-over-coastal-beach.mp4 "with_url: false, with_code: false, poster:https://res.cloudinary.com/demo/video/upload/w_0.3,r_20/l_cloudinary_icon_white,w_60,o_50,g_south_east,y_15,x_60/glide-over-coastal-beach.png")

#### 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 plays forward again, but in slow motion. 

```python
CloudinaryVideo("old_camera").video(controls=True, transformation=[
    {"overlay": "video:old_camera", "flags": "splice", "effect": "reverse"},
    {"overlay": "video:old_camera", "flags": "splice", "effect": "accelerate:-50"},
    {"effect": "brightness:10", "radius": "max"}
    ])
```

![video forward and reverse](https://res.cloudinary.com/demo/video/upload/l_video:old_camera,fl_splice,e_reverse/l_video:old_camera,fl_splice,e_accelerate:-50/e_brightness:10,r_max/old_camera.mp4 "with_url: false, with_code: false, width:400, poster: https://res.cloudinary.com/demo/video/upload/l_video:old_camera,fl_splice,e_reverse/l_video:old_camera,fl_splice,e_accelerate:-50/e_brightness:10,r_max/old_camera.png")

#### Example 3:

The following example generates a `<video>` tag for a video whose first 10 seconds will loop continuously in an HTML5 video player with default controls. The video is cropped to 360X480, using the pad cropping method, and it is generated at 70% quality to control file size.

```python
CloudinaryVideo("blue_sports_car").video(loop=True, controls=True, 
 transformation = 
        {"height": 360, "width":480, "quality": 70, "duration": 10, "crop": "pad"}, 
 fallback_content="Your browser does not support HTML5 video tags.")
```  

  
  
  
  Your browser does not support HTML5 video tags.

#### Example 4:

The following example uses direct URL building. It delivers the 2 seconds of a video between seconds 1 and 3 and loops 3 times. The video is resized to a fraction of its width.

```python
cloudinary.utils.cloudinary_url("docs/sunglasses", 
    resource_type="video", 
    transformation=[
      {"start_offset": "1", "end_offset": "3"},
      {"effect": "loop:3"},
      {"width": 0.2, "crop": "scale"}
    ])
```
![sunglasses video with loop](https://res.cloudinary.com/demo/video/upload/so_1,eo_3/e_loop:3/c_scale,w_0.2/v1/docs/sunglasses "with_url: true, with_code: false")

#### Example 5:

The following example uses direct URL building. It delivers the 2.5 seconds of a video between seconds 7.5 and 10 with a light blue border, and then appends a boomeranged (reversed) version of that same clip, resizing the video to a fraction of its original size. An overlay is applied to the top right corner (`north_east`) of the video with a height 25 pixels and opacity of 90.

```python
CloudinaryVideo("docs/sunglasses").build_url(transformation=[
  {"start_offset": "7.5", "end_offset": "10.0"},
  {"effect": "boomerang"},
  {"width": "0.2", "crop": "scale"},
  {"overlay": "cloudinary"},
  {"opacity": 90},
  {"height": 25, "crop": "scale"},
  {"flags": "layer_apply", "gravity": "north_east"}])
```
![sunglasses video with loop](https://res.cloudinary.com/demo/video/upload/eo_10.0,so_7.5/e_boomerang/c_scale,w_0.2/l_cloudinary/o_90/c_scale,h_25/fl_layer_apply,g_north_east/v1/docs/sunglasses "with_url: true, with_code: false")