Insert an overlay (HTML widgets) in your live stream

What is an overlay?

An overlay (or an HTML widget) is a graphic placed over the stream footage. Overlays include webcam pop-up, chat, alert, advertisement banner, and time or weather widgets. Streamers from different industries (games, education, news, sports events) use overlays to enhance their streams’ visual appeal and functionality.

There are two approaches to implementing overlays:

1. Overlays are embedded OVER the live stream in the player. In this case, you get two “layers”: the lower one is the video stream, and the upper one is the overlay shown by the particular player.

2. Overlays are embedded INTO the live stream. In this case, the overlay is part of the live stream.

The drawback of the first approach is that if you change the player, the overlay will be lost. In the second case, the overlay will be shown no matter the player used.

Overlay example

In the example below, you can see the game score widget in the upper left corner, the weather widget in the upper right corner, the poll widget in the lower right corner, and the time and date widget in the lower left corner.

Gcore supports HTML overlays

Gcore Video Streaming now supports overlays embedded into the live stream, which can be managed using the API. Contact support (via email or chat—click the chat icon on the bottom right of our webpages) or your personal manager to enable the ability to send API requests to the overlay feature endpoints.

The main features of overlays via API are:

• Use more than one overlay per live stream
• Size options: small overlays or overlays stretched over a full frame
• Transparent areas in overlays
• 1 FPS frequency update
• Automatic size scaling for adaptive bitrate qualities
• Place overlays in any area of the screen

Comparison of Gcore overlays and OBS studio overlays

OBS has functionality for using overlays. Let’s compare it to Gcore’s overlay feature:

*While using OBS overlays, you need to keep the OBS app open. Computational resources are enough for only one live stream with overlay, which cannot be scaled to multiple live streams. While using Gcore overlays, you embed the overlay into a live stream. The widget is automatically available everywhere (for Gcore’s player, .m3u8 link, and .mpd link) and scales to any number of live streams. We scale the service automatically—you don't need to do anything, just start as many streams as you need.

**OBS allows you to use animated widgets of different complexity within a single stream. We allow the overlay in 1000+ streams, but the Frame rate (FPS) will be 1 second. Therefore, animations will freeze.

Configure Gcore overlays via API

We support the following types of overlays: times and clocks, weather, statistics, exchange rates, and banner ads. For the graphic component of your overlay, you can use the following methods:

• Create your own (e.g., with the Free Twitch overlay maker from Canva)
• Use a template (e.g., Bernardo’s Streamer Toolkit)
• Use ready overlay systems (e.g., DonationAlerts, Stream Overlays from Tracker Network)

Note: Before using overlays, ask tech support or your personal manager to enable the feature for your account. Then, set the html_overlay attribute to true for your live stream and specify the array of live streams.

For detailed information, refer to our API documentation.

Get all overlays

The API method returns a list of HTML overlay widgets attached to a live stream.

Example of the request:

      Copy
      
    curl -L -X GET 'https://api.gcore.com/streaming/streams/12345/overlays' \
-H 'Authorization: APIKey 1234$0d1659...' \
-H 'Content-Type: application/json' \

In response, you will receive an array of overlays. Example of the response:

      Copy
      
    [
    {
        "id": 1,
        "stream_id": 12345,
        "url": "http://domain.tld/myoverlay1.html",
        "width": 120,
        "height": 40,
        "x": 10,
        "y": 10,
        "stretch": false,
        "created_at": "2023-09-20T00:01:01.000Z",
        "updated_at": "2023-10-01T12:01:01.000Z"
    },
    {
    }
]

Create overlays

The API method lets you insert overlays into your live stream. Please review the requirements for overlays to work correctly in the API documentation.

Example of the request:

      Copy
      
    curl -L -X POST https://api.gcore.com/streaming/streams/12345/overlays \
-H 'Authorization: APIKey 1234$0d1659...' \
-H 'Content-Type: application/json' \
-d '{
    "url": "http://domain.tld/myoverlay1.html",
    "width": "120",
    "height": "40",
    "x": "30",
    "y": "30",
    "stretch": "false",      
}'

Example of the response:

      Copy
      
    {
    "url": "http://domain.tld/myoverlay1.html",
    "width": 120,
    "height": 40,
    "x": 30,
    "y": 30,
    "stretch": false,
    "id": 1,
    "stream_id": 12345,
    "created_at": "2023-09-20T00:01:01.000Z",
    "updated_at": "2023-10-01T12:01:01.000Z"
}

After creating the overlay, you can request it with the API method by specifying its ID.

Change overlays

The API method updates settings for a set of overlays. This method allows changing the settings of several overlays. If you have only one, try this one.

Example of the request:

      Copy
      
    curl -L -X PATCH https://api.gcore.com/streaming/streams/12345/overlays \
-H 'Authorization: APIKey 1234$0d1659...' \
-H 'Content-Type: application/json' \
-d '{
    "url": "http://domain.tld/myoverlay_new_3.html",
    "width": "120",
    "height": "40",
    "x": "0",
    "yt": "0",
    "stretch": "false",
    "id": "1",
}'

Example of the response:

      Copy
      
    [
    {
        "url": "http://domain.tld/myoverlay_new_3.html",
        "width": 120,
        "height": 40,
        "x": 0,
        "y": 0,
        "stretch": false,
        "id": 1
    }
]

Delete an overlay

The API method lets you delete the overlay.

Here’s an example of the request:

      Copy
      
    curl -L -X DELETE https://api.gcore.com/streaming/streams/12345/overlays/1 \
-H 'Authorization: APIKey 1234$0d1659...' \

If all IDs are correct, you will get a response 200: Overlay has been deleted successfully.