JPEG thumbnails¶

Video is a stream of pictures. Sometimes you need to extract these pictures and handle them separately from each other. Such separate pictures are called thumbnails or screenshots.

Flussonic Media Server can create thumbnails of a video stream. They allow you to:

• show an instant preview of a live stream on a web page to know what is happening there right now,
• take a look at the quality of a stream,
• freeze a point in time to use the screenshot somewhere else,
• make a fast search in the DVR archive for some fragment of video identifiable by the screenshot,
• create a wall of screenshots to quickly look at a whole day of recording,
• do whatever else with small static images extracted from a large video stream.

Flussonic Media Server can create thumbnails in two different ways:

• Extracting video frames as JPEG images. This is a resource-intensive operation. Flussonic can save JPEG thumbnails in the DVR archive. Learn more on this page.
• Creating resource-saving MP4 video thumbnails. In H.264 streams with keyframes, all compressed images are available without resource-intensive processing. Flussonic Media Server takes the first keyframe from each segment and displays it as an MP4 video consisting of one frame. Learn more in Video thumbnails section.

About JPEG thumbnails¶

Flussonic Media Server does a rather CPU-intensive job: it takes the first keyframe of each segment, decodes it to raw video, and encodes back to a JPEG image. This seems rather simple, but when you have, say, 300 streams, this process can take a lot of CPU time.

Flussonic allows some optimization here – by changing a segment's duration you can change the total number of JPEG thumbnails. The fact that Flussonic Media Server takes only the first keyframe of a segment means that if you configure the segment duration of 3 seconds, you'll have 20 JPEGs per minute. If you configure the segment duration to be 6 seconds, you'll have 10 JPEGs per minute. If you take a stream from an IP camera, you may have 60 keyframes per minute, but Flussonic Media Server will create a smaller number of JPEGs.

It is possible to optimize the CPU usage by accessing thumbnails by their URL. Usually it is suitable for IP cameras because IP camera maintain fresh JPEG screenshot for the currently shown video. In this case Flussonic Media Server will download a JPEG image each time video segment starts.

Configuring JPEG thumbnail generation¶

To create JPEG thumbnails, Flussonic Media Server uses a built-in package.

Add the thumbnails option to the stream settings:

stream example {
  input fake://fake;
  thumbnails;
}

This will start the flussonic-thumbnailer process. It may be rather resource-hungry — this is the nature of video and image compression.

All the settings for JPEG thumbnails can be specified through the administrator's panel in a stream's settings on the Output tab (Media > select a stream > Output). Select the enabled option in the Thumbnails section.

Configuring JPEG thumbnails downloading from camera¶

To reduce CPU usage on thumbnail generation, you can specify the URL where Flussonic Media Server can get thumbnails. Many cameras have a special URL for screenshots:

stream example {
  input rtsp://localhost:554/source;
  thumbnails url=http://examplehost:5000/snapshot;
}

You can try to find the screenshot URL in your camera's documentation, or look for that information on the web.

All the settings for JPEG thumbnails can be specified through the administrator's panel in a stream's settings on the Output tab (Media > select a stream > Output). Select the enabled option in the Thumbnails section and specify Thumbnail URL.

Getting JPEGs from live streams¶

After you have enabled thumbnails in Flussonic Media Server, you need to access them.

The URL for getting thumbnails is as follows:

http://FLUSSONIC-IP:80/STREAM_NAME/preview.jpg — a stream's last screenshot.

http://FLUSSONIC-IP:80/STREAM_NAME/preview.mjpeg — an MJPEG screenshot stream.

We strongly recommend that you never use the MJPEG stream because it is an uncontrollable way of streaming video with a very high bitrate. You can end up with an MJPEG stream with 50% of the original bitrate, streaming at 0.1fps. But if you still need it, you can use it.

Getting JPEGs from DVR by specific time¶

Screenshots are automatically saved to the archive if DVR is turned on for the stream. They can be obtained using the HTTP API.

The best way (in terms of resources) of getting JPEG screenshots is to specify an approximate UTC time as part of the URL. Flussonic will return the URL corresponding to the nearest keyframe (an actual screenshot).

http://FLUSSONIC-IP:80/STREAM_NAME/1652936935.jpg

The old human-readable GMT format is also supported for compatibility:

http://FLUSSONIC-IP:80/STREAM_NAME/2022/05/19/05/08/11.jpg

You then use this URL to access the screenshot.

See Streaming API reference.

Getting JPEGs from DVR by UTC time range¶

First, you need to identify a time range for which you want to get DVR. For example, right now it is 2017 April 21, 13:10 GMT, so it is 1492780200 UTC. If you want to get thumbnails for the last hour, you need to request the following URL:

curl 'http://FLUSSONIC-IP:80/STREAM_NAME/recording_status.json?from=1492776600&to=1492780200&request=brief_thumbnails'

By default, Flussonic does not include the list of timestamps in the response. To get them, we need to add request=brief_thumbnails to the query string.

The response will look like this:

[{"stream":"clock","ranges":[{"duration":3642,"from":1492776599}],"brief_thumbnails":[1492776599,1492776605,
1492776617,1492776629,1492776641,1492776653,1492776665,1492776677,1492776689,1492776701,1492776713,1492776725,
....]}]

Here you get a very long list of timestamps that you need to convert to paths to screenshots. For example, the timestamp 1492776605 will be converted to http://FLUSSONIC-IP:80/STREAM_NAME/2017/04/21/12/10/05.jpg.

You will only get a list of timestamps, you will need to get the thumbnails themselves by requesting them individually.

On-demand JPEG thumbnail generation¶

Sometimes it is very expensive to store all JPEG images on the disk, so you can ask Flussonic Media Server to generate JPEGs on demand. In this case, add the parameter thumbnails enabled=ondemand to the stream configuration. For example:

stream channel {
  input fake://fake;
  thumbnails enabled=ondemand;
  dvr /storage;
}

You can also configure JPEG thumbnails on-demand generation through the administrator's panel in a stream's settings on the Output tab (Media > select a stream > Output). Select the On demand option in the Thumbnails section.

Request a URL with a certain time specified in UTC format:

http://FLUSSONIC-IP:80/STREAM_NAME/1643797938-preview.jpg

The old human-readable datetime format is also supported for compatibility:

http://FLUSSONIC-IP:80/STREAM_NAME/2022/02/21/12/10/05-preview.jpg

Flussonic Media Server will find a segment, take the first keyframe after the specified moment and generate a JPEG image from it.

If no keyframes are found in the current segment, Flussonic will take the first keyframe of the next segment, create its URL, return 302 redirect, and the browser will make the second request with the new URL and get the JPEG image of the found keyframe. Such redirection ensures storing only one unique response for each URL in the cache. So, if no keyframes are found for a requested time, the already saved correct URL can be taken from the cache after the redirection. And two requests to neighbouring seconds without keyframes will result in downloading only one JPEG image.

This method might lead to unpredictable CPU usage, so it is not recommended.

With the JPEG thumbnailer enabled, you will have smooth and moderate CPU usage, without spikes in load. With on-demand JPEG generation, you may have low CPU usage overall, but during prime time you may get spikes, and your server may become unstable.

See Streaming API reference.