Video slideshow generation (Beta)
Last updated: Nov-14-2022
Combine your new and existing assets to create auto-generated video slideshows. Build up your slideshows using videos and images and select how you want to transition between each.
Some examples of how you might use video slideshows include:
- Creating a personalized video of a user's recent items.
- Creating a personalized video of items a user left in their shopping cart.
- Creating a daily sale video of different products automatically.
- Creating a real-estate video out of apartment images.
See also: Cross fade transitions for a simple way to concatenate media on the fly.
Generating a slideshow
You can generate a slideshow in two different ways depending on your use case:
- Using a delivery URL - Combine the relevant components in a delivery URL. This method uses a CLT template file that is uploaded to Cloudinary. All slideshows will be generated as a derived version of this template file and you can edit and tweak the various settings by applying URL transformations and seeing the resulting derived version.
- Using the Upload API - Use the
create_slideshow
method of the Upload API. This method creates a new original video in Cloudinary based on the parameters provided. Once the video slideshow is created you can generate subsequent derived versions with standard Cloudinary transformations. To edit the slideshow itself you must generate a new video or overwrite the existing one using the API.
Using a delivery URL
Components
Each slideshow is comprised of a number of components:
- Template: Defined by Cloudinary specifically for video slideshows. Download the template and upload it to Cloudinary as a video file. In the future, template creation will be available to support additional use cases.
- Manifest transformation: The components of the slideshow itself including all the relevant slides, transitions and transformations:
- Global settings: Settings to apply to the whole video, such as resolution, duration and frames per second.
- Slide settings: Settings to apply to all slides, such as:
- Slide duration
- Transition effect - see supported transitions
- Transition duration
- Transformation
- Individual slides: The media to include in the individual slides and any settings specific to that slide.
- Global transformations: Transformations to apply post-production to the generated slideshow, see the Transformation URL API Reference for all available transformations.
- You must have the template file (.clt) stored in Cloudinary for slideshow generation to work. Download the template and upload it to Cloudinary as a video file. The public ID is used as part of the slideshow URL.
- If the configured duration is less than the combined total duration of the individual videos and transitions, the video will be cut short.
Syntax
Use the following URL syntax to create a video slideshow using a delivery URL:
https://res.cloudinary.com/<cloudname>/video/upload/fn_render:<global-settings>;vars_(<slide-settings>(<individual-slide>))/<global-transformations>/<template>.<ext>
The URL syntax is designed to allow the slideshow settings to be constructed as a URL instead of a data structure. The characters used are defined as:
(
- Start of list or object (key/value list))
- End of list or object;
- Separator between values in list or object_
- Key/value separator in a object
Additional syntax is used to signify the beginning of the relevant components:
fn_render
- Signals the beginning of the transformation as a whole.vars
- Signals the beginning of the slide settings data structure.
See the reference for full details on the relevant options.
HTTP 423
error will be returned whilst the final slideshow is generated. Refresh your browser after several seconds or minutes to see the result.Examples
Example with images only:
- Images: 4
- Width: 500px
- Height: 500px
- Duration: 20 seconds
- Slide Duration: 3000 milliseconds
- Transition Duration: 1500 milliseconds
- Transition: circlecrop
Example with videos and images:
- Images: 3
- Videos: 1
- Width: 640px
- Height: 480px
- Duration: 20 seconds
- Slide Duration: 3000 milliseconds
- Transition Duration: 1500 milliseconds
- Transition: hexagonalize
Example with custom slide durations:
- Images: 4
- Width: 500px
- Height: 500px
- Duration: 18 seconds
- Slide Durations: 2000, 4000, 3000, 3000 milliseconds
- Transition Duration: 1500 milliseconds
- Transition: hexagonalize
Example with slide transformation:
- Images: 4
- Width: 500px
- Height: 500px
- Duration: 18 seconds
- Slide Durations: 2000, 4000, 3000, 3000 milliseconds
- Transition Duration: 1500 milliseconds
- Transition: hexagonalize
- Slide Transformation: Fes filter
Using the Upload API
To create a new slideshow using the Upload API, send a POST
request to the create_slideshow method. Your slideshow will be generated asynchronously as a video and will be added as an original to your media library.
Syntax
You need to provide the manifest_json parameter as part of your request. This parameter includes all of the relevant configuration for the slideshow itself including all the relevant slides, transitions and transformations:
- Global settings: Settings to apply to the whole video, such as resolution, duration and frames per second.
- Slide settings: Settings to apply to all slides, such as:
- Slide duration
- Transition effect - see supported transitions
- Transition duration
- Transformation
- Individual slides: The media to include in the individual slides and any settings specific to that slide.
manifest_json
The manifest_json
parameter is a stringified json parameter, allowing you to define your slideshow settings in a structured data format, which then needs to be converted to a string.
See the reference for full details on the relevant options.
Here's an example manifest_json
:
"manifest_json": { "w": 500, "h": 500, "du": 6, "fps": 30, "vars": { "sdur": 500, "tdur": 500, "slides": [ { "media": "i:sample" }, { "media": "i:sample2" }, { "media": "i:sample3" }, { "media": "i:sample4" } ] } }
Examples
Example signed upload with images only
var slideshowParams = new CreateSlideshowParams() { ManifestJson = new SlideshowManifest { Width = 500, Height = 500, Duration = 8, Variables = new Slideshow { SlideDuration = 1500, TransitionDuration = 3000, Slides = new List<Slide> { new Slide { Media = "i:sample" }, new Slide { Media = "i:sample" }, }, } }, PublicId = "test_slideshow" } var slideshowResult = cloudinary.CreateSlideshow(slideshowParams);
https://api.cloudinary.com/v1_1/demo/video/create_slideshow -X POST --data 'public_id=test_slideshow&resource_type=video&manifest_json={"w":500,"h":500,"du":8,"vars":{"sdur":3000,"tdur":1500,"slides":[{"media":"i:sample"},{"media":"i:sample"}]}}×tamp=173719931&api_key=436464676&signature=a781d61f86a6f818af'
Example unsigned upload with images only
$cloudinary->uploadApi->createSlideshow([ 'manifest_json' => [ "w" => 500, "h" => 500, "du" => 8, "vars" => [ "sdur" => 3000, "tdur" => 1500, "slides" => [ ["media" => "i:sample"], ["media" => "i:sample"], ], ], ], 'public_id' => 'test_slideshow', 'upload_preset' => 'Default' ] ]);
var slideshowParams = new CreateSlideshowParams() { ManifestJson = new SlideshowManifest { Width = 500, Height = 500, Duration = 8, Variables = new Slideshow { SlideDuration = 1500, TransitionDuration = 3000, Slides = new List<Slide> { new Slide { Media = "i:sample" }, new Slide { Media = "i:sample" }, }, } }, PublicId = "test_slideshow", UploadPreset = "Default" } var slideshowResult = cloudinary.CreateSlideshow(slideshowParams);
Sample Response
The following is a sample response based on the examples above. As slideshow generation occurs asynchronously, a notification is sent once the slideshow has been successfully generated. You can see an example of the notification response below.
{ "status": "processing", "public_id": "test_slideshow", "batch_id": "00b45635e533ab11e63585dd145ab7816ca19bff2bf3f298a0e66d87405ab7793" }
{ "notification_type": "upload", "timestamp": "2021-08-11T07:44:41+00:00", "request_id": "799b0f8305df4206b6d8f5dbdde0cdfc", "asset_id": "640cb419bed70ef5b86e2bbe7cbb388a", "public_id": "test_slideshow", "version": 1628667799, "version_id": "afcd9bdec6552adc43d7f316da077200", "width": 500, "height": 500, "format": "mp4", "resource_type": "video", "created_at": "2021-08-11T07:43:19Z", "tags": [], "pages": 0, "bytes": 521868, "type": "upload", "etag": "d7b3ecf1f5508af9fb8518158e78642f", "placeholder": false, "url": "http://res.cloudinary.com/demo/video/upload/v1628667799/test_slideshow.mp4", "secure_url": "https://res.cloudinary.com/demo/video/upload/v1628667799/test_slideshow.mp4", "access_mode": "public", "audio": {}, "video": { "pix_format": "yuv420p", "codec": "h264", "level": 30, "profile": "High", "bit_rate": "163900", "time_base": "1/15360" }, "frame_rate": 30, "bit_rate": 166997, "duration": 25, "rotation": 0, "nb_frames": 750 }
Reference
Global settings
Parameter | Description |
---|---|
w | Required. The width of the slideshow in pixels. |
h | Required. The height of the slideshow in pixels. |
du | The duration of the slideshow in seconds. Default: 10 . |
fps | The frames per second of the slideshow. Default: 20 . |
Slide settings
Parameter | Description |
---|---|
vars_ | Signals the start of the slide settings. |
transition_s: |
The transition to use for all slides. Default: CrossZoom . |
transformation_s: |
A single transformation to apply to all slides. Default: null . |
sdur | The duration for all slides in milliseconds. Default: 3000 . |
tdur | The duration for all transitions in milliseconds. Default: 1000 . |
slides_ | The slides to appear in the video. See Individual slide settings. |
Individual slide settings
Parameter | Description |
---|---|
media_ |
The type of media. Specify images as media_i:<public_id> . Specify videos as media_v:<public_id> . |
type_s | The slide type. Set to video when using a video for a slide. For example: media_v:my-public-id;type_s:video . Default: image . |
transition_s | The transition to use from the individual slide to the next. Default: CrossZoom . |
sdur | The slide duration in milliseconds. Default: 3000 . |
tdur | The transition duration in milliseconds. Default: 1000 . |