Overlays

Create overlays

"Overlay" is a live HTML widget, which rendered and inserted over the live stream. There are can be more that 1 overlay over a stream, which are small or stretched over full frame. Overlays can have transparent areas. Frequency of update is 1 FPS. Automatic size scaling for Adaptative Bitrate qualities is applied. ![HTML Overlays](https://demo-files.gvideo.io/apidocs/`coffee_run_overlays`.gif) How to activate and use in simple steps: - Activate feature on your account, ask the Support Team - Set “`html_overlay`” attribute to "true" for a stream - Set array of overlays - Start or restart your stream again - Enjoy :-) For the first time an overlay should be enabled **before** start pushing of a live stream. If you are pushing the stream already (stream is alive and you are activating overlay for the first time), then overlay will become active after restart pushing. Once you activate the overlay for the stream for the first time, you can add, change, move, delete widgets on the fly even during a live stream with no affection on a result stream. Tech limits: - Max original stream resolution = FullHD. - It is necessary that all widgets must fit into the original frame of the source stream (width x height). If one of the widgets does not fit into the original frame, for example, goes 1 pixel beyond the frame, then all widgets will be hidden. - Attributes of overlays: - url – should be valid http/https url - 0 < width <= 1920 - 0 < height <= 1080 - 0 <= x < 1920 - 0 <= y < 1080 - stretch – stretch to full frame. Cannot be used with positioning attributes. - HTML widget can be access by HTTP 80 or HTTPS 443 ports. - HTML page code at the "url" link is read once when starting the stream only. For dynamically updating widgets, you must use either dynamic code via JavaScript or cause a page refresh via HTML meta tag <meta http-equiv="refresh" content="N">. - Widgets can contain scripts, but they must be lightweight and using small amount memory, CPU, and bandwidth. It is prohibited to run heavy scripts, create a heavy load on the network, or run other heavy modules. Such widgets can be stopped automatically, and the ability to insert widgets itself is banned. - If feature is disabled, you will receive HTTP code: 422. Error text: Feature disabled. Contact support to enable. Please, pay attention to the content of HTML widges you use. If you don't trust them, then you shouldn't use them, as their result will be displayed in live stream to all users. **Will there be a widget in the recording?** Right now overlay widgets are sent to the end viewer in the HLS/DASH streams, but are not recorded due to technical limitations. We are working to ensure that widgets remain in the recordings as well. Follow the news.

POST

streaming

streams

{stream_id}

overlays

Create overlays

curl --request POST \
  --url https://api.gcore.com/streaming/streams/{stream_id}/overlays \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "url": "http://domain.com/myoverlay1.html",
    "width": 120,
    "height": 40,
    "x": 30,
    "y": 30,
    "stretch": false
  }
]'

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

Authorizations

Authorization

string

header

required

API key for authentication. Make sure to include the word apikey, followed by a single space and then your token. Example: apikey 1234$abcdef

Path Parameters

stream_id

integer

required

Stream ID

Body

application/json · object[]

The body is of type object[].

Response

200

application/json

Successful

The response is of type object[].

Get all overlays Change overlays

Create overlays

curl --request POST \
  --url https://api.gcore.com/streaming/streams/{stream_id}/overlays \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "url": "http://domain.com/myoverlay1.html",
    "width": 120,
    "height": 40,
    "x": 30,
    "y": 30,
    "stretch": false
  }
]'

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

Overview

IAM

CDN

Managed DNS

Cloud

DDoS Protection

FastEdge

WAAP

Streaming

Object Storage

Create overlays

Authorizations

Path Parameters

Body

Response