Displaying an in-conference timer / countdown

You can set an in-conference timer or countdown clock that is displayed at the top of the screen to all conference participants. It is supported in Virtual Meeting Rooms and Virtual Auditoriums, the calling party in Infinity Gateway calls, and in all layouts.

This is a technology preview feature in v39.

To use this feature you must ensure that Enable clock is selected in Platform > Global settings > Tech preview features.

How it works

When a timer is displayed, the video layout shrinks slightly to make space for the timer banner at the top-left of the layout.

Timer options

There are 3 types of timer that can be displayed:

  • Elapsed time since initiating the timer
  • Time remaining countdown (from a provided starting value)
  • Current time (UTC in either dd/mm/yyyy or mm/dd/yyyy format)

You can also optionally specify some prefix and suffix text to display either side of the timer.

The timer message takes the format: {PREFIX} {DATE} HH:MM:SS {SUFFIX}

Note that:

  • When a countdown timer reaches zero it remains displayed as 00:00:00.

  • The in-conference timer can be combined with a banner message and any classification message. For example:

  • The message may appear differently for each participant, depending on the receiving participant's aspect ratio and resolution. If there is not enough space for the entire message it is cropped and ended with "...".
  • The banner message is only displayed in main video (including when presentation is part of the layout mix); it is not included in presentation streams.

Setting a timer

A conference Host can set the timer via the client APIs.

REST client API

If you are using the REST client API:

To set a timer:

POST: https://<node_address>/api/client/v2/conferences/<conference_alias>/set_clock

Request fields:

type string

The clock options are:

  • "elapsed": the clock increments starting from 0.
  • "remaining": the clock decrements from starting_value.
  • "time": displays the current local time.
starting_value number

The starting value in seconds for the countdown timer.

Only applies for a type of remaining.

Range: 1-31536000
prefix string Optional text to display before the clock.
suffix string Optional text to display after the clock.
date string

The required date format. The options are:

  • "dd/mm/yyyy"
  • "mm/dd/yyyy"

Only applies for a type of time.

Request example to set a countdown clock of 5 minutes:

{
    "type": "remaining",
    "starting_value": 300,
    "prefix": "Time remaining: "
}

To retrieve the timer configuration that was last assigned:

GET: https://<node_address>/api/client/v2/conferences/<conference_alias>/get_clock

which returns the same configuration as applied via set_clock.

To remove the timer:

POST: https://<node_address>/api/client/v2/conferences/<conference_alias>/set_clock without any request fields.

PexRTC client API

If you are using the PexRTC client API:

Call the setClock(clock_values) conference control function and specify the same fields as for the REST API.

You can use setClock() to remove the timer.

You can use getClock() to retrieve the timer configuration that was last assigned.

Customizing the timer

The default colors are dark gray text on a light background, although the text, background and border colour of the banner are configurable via message_box_config theme settings.

You cannot customize the size or position of the banner, the position of the items within the banner, or the font used for the message text.