tencent cloud


Live Screencapture

Last updated: 2022-04-14 09:52:15

    The live screencapture feature takes screenshots of a real-time live stream at regular intervals and generates images. You can get the screenshot information through the callback notification. These screenshots have various uses, such as porn detection and thumbnails.

    Live Screencapture Process

    Overall process:

    1. Configure the live screencapture feature in the console or through TencentCloud API.
    2. Start live push.
    3. The screencapture service generates screenshot data according to the configuration and stores it in COS.
    4. Information about the generated screenshot is returned in a callback.

    Live Screencapture Configuration

    Screencapture configuration method

    Screencapturing interval configuration

    You can specify the screencapturing frequency based on your business needs, i.e., the screencapturing interval (SnapshotInterval). The available range is between 5–300 seconds with a default interval of 10 seconds.

    Screenshot width and height configuration

    The screencapturing service supports taking screenshots by the specified width and height:


    If you do not need to specify the width and height, the default screenshot width and height (set to 0) will be the width and height of the pushed video stream, and you can ignore the configuration instructions below and skip to the next section.

    First, look at the following three concepts of width and height:

    • Push width and height, i.e., the width and height of the live streaming video, which are set to (X, Y) in this document.
    • Configured width and height, i.e., the width and height configured in the console/through the TencentCloud API, which are set to (W, H) in this document.
    • Screenshot width and height, i.e., the width and height of the screenshot generated by the screencapturing service, which are set to (N, M) in this document.

    The screencapturing service supports the following configurations:

    • If the width and height are not set, then (W, H) = (0, 0) is used by default. The screenshot width and height are the same as the push width and height, i.e., (N, M) = (X, Y).
    • If only the width W is set, then the screenshot width will be N = W, and the screenshot height is scaled proportionally, i.e., M = N / X * Y.
    • If only the height H is set, then the screenshot height will be M = H, and the screenshot width is scaled proportionally, i.e., N = M / Y * X.
    • If (W, H) are set at the same time, then the screenshot width and height are the same as the configured width and height, i.e., (N, M) = (W, H).

    The automatic swap of configured width and height is suitable for the following scenario:

    • If W is set to be smaller than H, both W and H are greater than 0, and X is set to be greater than Y during the push, then the configured width is smaller than the height, but the push width is greater than the height.

    In this case, if a screenshot is directly taken, it will be distorted. In order to avoid the distortion, the backend of the live screencapture service will automatically swap the values of W and H to ensure that the configured aspect ratio is consistent with that of the live stream.

    Event Message Notification for Live Screencapture

    For event message notification configuration, please see Event Message Notification. The screencapturing callback notification is sent to the pre-configured receiving server through the HTTP POST protocol in JSON format.

    Screencapturing callback fields

    Field Name Type Description
    event_type int Callback information type, which is always 200 for screencapturing callback
    stream_id string Stream name
    channel_id string Same as the stream name
    create_time int64 UNIX timestamp when the screenshot is generated
    file_size int Screenshot file size in bytes
    width int Screenshot width in pixels
    height int Screenshot height in pixels
    pic_url string Screenshot file path /path/name.jpg. For more information, please see Field details below
    pic_full_url string Full screenshot URL. For more information, please see Field details below
    sign string Callback signature. For more information, please see Event Message Notification
    t int64 UNIX timestamp when the callback signature expires. For more information, please see Event Message Notification

    Field details

    • pic_url details:
    • path: year-month-day
    • name: live stream name-screenshot-hour-minute-second-widthxheight.jpg

    This field can be used to put together a custom COS CDN domain name. If you do not need a CDN domain name, use pic_full_url directly.

    • pic_full_url details:
    • http://COS domain name+pic_url

    Sample screencapturing callback

    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support