Red5 Pro supports the generation of thumbnails for live streams. This feature is useful for creating previews or snapshots of the video content being streamed. When the CloudStorage plugin is enabled, thumbnails are pushed to cloud stroage.

Enabling Thumbnails

Edit the red5.properties file located in the conf directory of your Red5 Pro server installation. Add or modify the following properties:

# Enable thumbnail generation
thumbnail.enabled=true

Thumbnail Height and Width

Thumbnail height and width can be controlled. If you set both to 0, the thumbnail will be generated at the original resolution of the video.

Using Height and Width in Pixels

When specifying a height and width greater than 1, the value represents the number of pixels.

# Thumbnail height in pixels
thumbnail.height=360
# Thumbnail width in pixels
thumbnail.width=640

Using Height and Width in Percentage

When specifying a height and width that are less than 1, the values represent percentage of the original video dimensions. The thumbnail size will be rounded to the nearest multiple of 32.

# Thumbnail height in percentage of original video height
thumbnail.height=0.5
# Thumbnail width in percentage of original video width
thumbnail.width=0.5

Thumbnail Generation Frequency

Control how often thumbnails are generated by setting the thumbnail.frequency property. This value represents the interval in seconds at which thumbnails are generated. Setting this to the same value as your keyframe interval is recommended.

thumbnail.frequency=1

Thumbnail Count

You can control how many thumbnails are kept per stream using the thumbnail.count property. Once the limit is reached, the oldest thumbnails are deleted as new ones are created.

# Maximum number of thumbnails to keep for each stream
thumbnail.count=5

Thumbnail Storage Location

Thumbnails are saved to a configurable directory. Change the default location with the following property:

# Folder path where thumbnails are saved
thumbnail.local.path=webapps/live/streams/

Thumbnail Naming

You can define the prefix for saved thumbnails. By default, the stream name is used, but you can also override it for dynamic naming.

# Prefix for the thumbnail file names (default: stream name)
thumbnail.image.name=streamName

Key Frame Dependency

By default, thumbnails are created only on key frames (to save CPU and keep thumbnails pretty). You can force thumbnails on every frame interval (for science, or if you hate your CPU) by enabling full decoding:

# Only generate thumbnails on key frames (recommended)
thumbnail.decode.all=false

Set to true if you want thumbnails at the specified interval regardless of key frames. Trade-off: higher CPU usage.

Automatic Deletion

Control what happens to your beautiful thumbnails when a stream stops.

# Delete local thumbnails when the stream stops
thumbnail.delete.local.streamstop=true

Integration with Cloud Storage

When the CloudStorage plugin is enabled, thumbnails can be automatically uploaded to a configured bucket or path.

# Enable thumbnail upload to cloud storage
thumbnail.upload=true

# Define the cloud storage path or bucket (default: stream name)
thumbnail.cloudstorage.path=streamName

# Automatically delete cloud thumbnails when stream stops
thumbnail.delete.cloudstorage.streamstop=true

Webhook Notifications

If you have other services keen to know every time a thumbnail is created (because FOMO is real in the cloud), use a webhook endpoint. The server will POST to this endpoint after generating each thumbnail.

# URL for webhook notifications on new thumbnails
thumbnail.webhook.endpoint=http://<webhook-receiver-host>/webhooks/thumbnail

Overriding Properties via Query String

Thumbnail properties can be overridden per-stream using RTMP/connection parameters. If you’re using an app like OBS, just sprinkle thumbnail config into your stream URL:

Example:

rtmp://<host>/live/?thumbnails.active=true&thumbnails.width=0.5&thumbnails.height=0.5

To disable this behavior for the whole server:

thumbnail.allow.query.string.overrides=false

Recommended Stream Settings

For optimal thumbnailing, we recommend setting your encoder (e.g., OBS, Wirecast) to generate a key frame every 2–3 seconds. This ensures timely and predictable thumbnail updates.

Example Complete Configuration

Here’s a sample setup you can copy-paste and tailor to suit your inner control freak:

thumbnail.enabled=true
thumbnail.width=0.5
thumbnail.height=0.5
thumbnail.count=3
thumbnail.frequency=2
thumbnail.local.path=webapps/live/streams/
thumbnail.image.name=streamName
thumbnail.decode.all=false
thumbnail.delete.local.streamstop=true
thumbnail.upload=true
thumbnail.cloudstorage.path=streamName
thumbnail.delete.cloudstorage.streamstop=true
thumbnail.webhook.endpoint=http://<webhook-receiver-host>/webhooks/thumbnail
thumbnail.allow.query.string.overrides=true