The videos and live streams on your TwentyThree account each has a still image to represent the video or stream whenever it is shown on overview pages or inside your video player (before playback has started). In TwentyThree, these images are called thumbnails (for videos) and preview images (for live streams). For the individual videos and streams you can easily set up what image to use as thumbnail or preview image, and for videos you can even select a frame directly from the video to be used. Working with videos, simply follow the instructions on this page, and for live streams you can change the preview image in the settings for the live event.

When building your video website or interfacing with the TwentyThree API, you always have immediate access to urls pointing to thumbnails and preview images in the formats and sizes that has been setup under "Design" → "Thumbnails" in the backend of your video website. These urls are available directly on the photo or live objects in Liquid templates, and they are returned as properties on objects returned on requests to the API methods /api/photo/list and /api/live/list:

Video thumbnails

In Liquid templates, the thumbnail_url property of the photo object points to the thumbnail in the size that has been chosen for the layout block in question. To get ahold of thumbnails in the rest of the predefined sizes, the photo objects has properties like small_download, standard_download and medium_download which each contains the url to a thumbnail in the corresponding size.

Liquid example

<pre><code></code></pre>

Live stream preview images

For live streams as well, the preview images are available on the live object, both in Liquid templates and through the API. The property names has the format of preview_<size>_download, thus the properties preview_small_download, preview_standard_download and preview_medium_download will provide you with urls to the small, standard and medium sizes, respectively, of the the preview image.

Liquid example

<pre><code></code></pre>

Custom thumbnails and preview images

Sometimes, however, you may wish to get ahold of a thumbnail or preview image in a size that is not set up in your thumbnail settings. For this purpose, you can specify the size directly in the url of the image on the following form:

Custom video thumbnails

http://video.example.com/<tree_id>/<photo_id>/<token>/<width>x<height><cropping_method>:<time>/thumbnail.png

The tree_id, photo_id and token values are all available on the photo object (in Liquid templates and through the API) - the rest of the values is where you specify the properties of the thumnails that you are loading:

width & height: Through these values, you choose the pixel dimensions of the image. If you specify both of these value, the returned image will have those exact dimensions. However, you can omit either of the values if you want the omitted value to be automatically set to fit the aspect ratio of the video. Examples: 400x225 - The image will be 400 pixels wide and 225 pixels high 400x - The image will be 400 pixels wide, and the height will be automatically set to fit the video's aspect ratio x225 - The image will be 225 pixels high, and the width will be automatically set to fit the video's aspect ratio

cropping_method: If you have provided both a width and a height value, the cropping method determines how the image is scaled to fit the exact dimensions that you have specified, in case the dimensions do not exactly match the aspect ratio of the video. You can choose between the following values: cr - The image is cropped to the horizontally and vertically centered part of the image that has the specified dimensions. This is the default cropping method being used if you do not specify another method. st - The image is stretched to fit the dimensions, meaning that no part of the image is cropped away. mtw - The image is padded/letter boxed with solid white either on the top and bottom or the left and right to fit the dimensions. With this method, you always get an uncropped and unstretched version of the image, possibly surrounded by solid white bars. mtb - Same as mtw except the image is padded with solid black bars instead of white.

time: This value allows you to specify a duration in seconds for a place in the video where you wish to grap a frame to be used as the thumbnail image. This value is optional, but if you choose to specify it, it must be prefixed with a colon (:). If no value is specified, the normal thumbnail image is used. :10 - Grab a frame 10 seconds into the video to be used as thumbnail image

Liquid examples

<pre><code>Grab a frame 20 seconds into the video and scale it to 400 pixels wide and 225 pixels high, letter boxing the image with black bars if needed to match the dimensions:////400x225mtb:20/thumbnail.pngScale the thumbnail image to 500 pixels wide and automatically adjust the height to match the video's aspect ratio:////500x/thumbnail.png</code></pre>

Custom live stream preview images

http://video.example.com/<preview_tree_id>/<preview_photo_id>/<preview_token>/<width>x<height><cropping_method>/thumbnail.png

The format for live stream preview image urls is almost the same as for video thumbnails. The tree_id, photo_id and token values is substituted by preview_tree_id, preview_photo_id and preview_token values which are all available on the live object, both in Liquid templates and through the API. Furthermore, the time value is not supported for live streams so it should simply be ommitted.

Liquid examples

Scale the preview image to 300 high and autmatically adjust the width to match the aspect ratio of the image////x300/thumbnail.pngStretch the preview image be 400 pixels wide and 200 pixels high////400x200st/thumbnail.png