The native support for playing images in player V7 was introduced in Player 7.58 (release version 3.10.0) in order to provide a more comprehensive support for media content types that are managed in Kaltura, and in order to provide native support for playing non-video assets
There are two types of image playback supported by player or in other words two modes an image can be played in:
- Non-Durational Image
- Durational image
The mode an image will be played in, will be determined according to the value of the image duration as will be detailed later in the guide
Non-Durational Image will be displayed by the player without a seek-bar and without the standard player controls (except full screen button)
Durational Image will be played by the player as if it is a video, with a seek-bar and all standard player controls (except the volume control) In fact it will behave just like a video for everything
The image will be aligned to the player dimensions, and maintain its aspect ratio, as will be detailed later in the Size & Quality section.
If the image is played as part of a playlist, it will automatically play as a Durational Image with a default duration of 5 seconds
The width of the image (in pixels) to be loaded will be derived from the width of the player container (and the height from its aspect ratio. and will be aligned to the player (container) dimensions, while maintaining its aspect ratio,
To improve load time, by default the image size to be loaded will be derived from the player’s width as mentioned above.
If you would like to load a higher quality of the image, the width param can be provided which will be passed to the Thumbnail API while loading the image, see here the configuration options.
By default, the image will be loaded at the best possible quality. But if you prefer to improve load time instead, this can be configurable (0-100 integer).
When the player enters into FullScreen mode, the image will automatically be reloaded with the new player width to improve the quality of the image being rendered in full screen.
Don't confuse the image aspect ratio with the player aspect ratio while the image aspect ratio will be kept, the player ratio will not.
Which will sometimes create blank areas around the image as long as their aspect ratio is different
Therefore, if your container size is not set to fixed size but responsive in adapting to the screen size, and you want to avoid the blank areas, you can set the player container aspect ratio along with the container size, with the same aspect ratio as the image, for example, given your original image is - 4 / 3 ratio, and you want to set the player size to be - 400px * 300px, then you can do:
<div id="player-container-id" style="width:50%;aspect-ratio: 4 / 3;"></div>
In this way, the player aspect ratio will always be the same as the image aspect ratio on any screen size.
First include playkit-image-player.js
after kaltura-player script in your web page.
<script src="https://raw.githack.com/kaltura/kaltura-player-js/master/dist/kaltura-ovp-player.js"></script>
<script src="./playkit-image-player.js"></script>
In order to play an image entry as a Non-Durational image, the duration must be set to zero (which is the default for an img entry loaded from the KMC)
const config = {
targetId: 'player-placeholder',
provider: {
partnerId: '<YOUR_PARTNERI_ID>',
},
}
const player = KalturaPlayer.setup(config);
player.loadMedia({ entryId: '1_ktrfo5hl' });
In order to play an image entry as a Durational image
All you need to do is to set the source duration
The image mode will be determined according to the duration configured with the entry
The duration is part of PKSourcesConfigObject which is set by the KMC if you use the loadMedia()
API
Currently, the duration of an image entry type is not configurable in the KMC
So the only way to play an img as a Durational image is to override the duration value using
the mediaOption second parameter of loadMedia()
or pass it through the sources object in case of the setMedia()
API usage
const config = {
targetId: 'player-placeholder',
provider: {
partnerId: '<YOUR_PARTNERI_ID>',
},
}
const player = KalturaPlayer.setup(config);
player.loadMedia({ entryId: '1_ktrfo5hl' }, { duration: 30 });
You can do the same with setMedia API
player.setMedia({
sources: {
duration: 30,
image: [{
id: '1_ktrfo5hl',
url: 'https://cfvod.kaltura.com/p/2068231/sp/206823100/thumbnail/entry_id/1_jgmxn561',
mimetype: ''
}]
}
});
The only optional configuration image entry can get, is the Thumbnail API Parameters (relevant only when your img served from kaltura Thumbnail API)
The configuration is part of the mediaOptions
(loadMedia's second parameter) which is of type PKSourcesConfigObject
and under the imageSourceOptions
configuration option
player.loadMedia({ entryId: '1_ktrfo5hl' }, {
imageSourceOptions: {
thumbnailAPIParams: {
quality: 100,
width: 1000
}
}
});
The imageSourceOptions
type is ImageSourceOptions
And the thumbnailAPIParams
type is ThumbnailApiParams
You can read more about Thumbnail API configuration Parameters options here
Images played as part of a playlist will always be played in Durational mode (with a default duration of 5 second)
The image duration will be the same for all image items in the playlist
If you want to change the default playlist image items duration you can set it through the player options configuration, as in the example below:
player.loadPlaylist({ playlistId: '1_1b6sw5ze' }, { options: { imageDuration: 20 } });
See here The full list of image events
Durational Image is fully supported and integrated with IMA Plugin
which means you can configure any type (pre-roll, mid-roll and post-roll) of ad using the IMA Plugin
Non-Durational Image only pre-roll ads are supported
Image entry can be integrated with Kava and Youbora analytics plugins,
In this case the reported PlaybackType info will be 'img'
(instead of 'Vod'
or 'Live'
)
You can find here the full list of Kava Analytics events supported in Image Entry playback.
You can find full working code example here