Rules and requirements for customized themes

We recommend using the Pexip branding portal (https://brandingportal.pexip.com) to customize your themes. The portal provides an easy way to change the text, images and so on that are used in themes, and it generates a ZIP file that you can upload via the Administrator interface. Note that you cannot change the audio files via the branding portal.

If you want to manually customize your own themes, or have more advanced customization requirements, the following sections list the complete set of audio, configuration and image files that can be used to configure each theme. They include the requirements for each of those files, including how to manage video watermarking, and information on which files are relevant to themes used by Call Routing Rules.

Theme ZIP file

When creating or editing a theme, you upload a single ZIP file containing your own customized version of one or more of the files described here. The ZIP file does not need to contain the complete set of files or settings, just the files or settings that you want to use in place of, or as an extension to, those from the default Base theme.

If, for example, you are replacing one of the default background JPGs, icon SVG files or audio files, then you should ensure that you use the same file name as the file you are replacing. If you are using additional background or icon files that you are applying to a subset of screens, then you must also include those new files in your ZIP file.

If "theme_version": 2 is not present in a themeconfig.json file at the lowest level of the theme file hierarchy then it is assumed to be a legacy-style theme (see How do I know which files and configuration settings will be used in a particular VMR? for more information).

Therefore, even if you only want to customize a single image or sound file, you must include in your ZIP upload a themeconfig.json file that contains a "theme_version": 2 switch, if you want to use new-style themes.

If any errors are reported when trying to upload your own manually-created ZIP file, such as "Invalid file in theme: themeconfig.json", you must fix the errors and then try to upload the ZIP file again. Any errors in the themeconfig.json are typically due to invalid JSON structures, such as missing commas between any key value pairs, or having a comma after the last key value pair in any object. Graphics file related errors are typically caused by incorrect image resolutions or using an invalid filename.

Audio (sound) files

You can replace any of the audio files by using your own version of the file in your customized theme. You must use the same file name as the file you are replacing. All audio files must be:

  • .WAV format
  • RIFF (little-endian) data, WAVE audio, Microsoft PCM, 16 bit, mono 48000 Hz

Points to note:

  • mono and 48000Hz are essential - audio files that do not meet these requirements will fail to upload.
  • The volume level of the audio recording is important - use the default Pexip Infinity prompts as a guide.
  • Some endpoints may take a few seconds after a call connects before they are able to receive audio. For this reason, we have included a 2-second pause at the start of any audio files that may be played when a user first connects to Pexip Infinity. We recommend that you include a similar pause; use the default Pexip Infinity files as a guide.

If you have used the Pexip branding portal to generate your theme ZIP file and you also want to customize the audio prompts (you cannot currently customize the audio files via the branding portal), then you must add your customized audio (wav) files to the ZIP file generated by the branding portal.

The following table lists the default audio files and their content, which is contained within the Base theme:

Theme configuration file (themeconfig.json)

The themeconfig.json file is the theme's primary configuration file. It is a JSON dictionary that specifies the background and layout of the splash screens used when joining a conference (such as the Welcome screen and PIN entry screens), specifies which image files are used, and controls some of the features and overlays that are used within a conference. It does not control any of the audio (sound) elements of the theme.

Whenever you include a themeconfig.json file in your customized theme, it must contain: "theme_version": 2. If it does not contain this setting, then it is assumed to be a legacy-style theme (see Legacy themes file requirements for more information).

If any settings within your customized themeconfig.json file are not specified, Pexip Infinity will simply use the equivalent setting from the Base theme or use default behavior. For example, if the only thing you want to customize from the default settings is to disable watermarks, then your themeconfig.json file only needs to contain the disable_watermark_icon setting (in addition to "theme_version": 2). See How do I know which files and configuration settings will be used in a particular VMR? and Theme customization examples for more information.

Here is the default (Base theme) contents of themeconfig.json:

{
    "dtmf_conference_control_commands" : {
        "*7" : "toggle_lock",
        "*5" : "toggle_guest_mute",
        "##" : "end_conference"
    },
    "no_main_video_bg" : "0x000000",
    "plus_n_indicator_text_color" : "0xFFFFFF",
    "recording_indicator_text" : "Recording",
    "conference_locked_indicator_text": "Conference locked",
    "test_call_service_media_delay" : 2,
    "disable_streaming_indicator" : false,
    "disable_conference_locked_indicator": false,
    "streaming_indicator_text" : "Streaming enabled",
    "enable_dtmf_conference_control" : true,
    "disable_watermark_icon" : false,
    "plus_n_indicator_bg_color" : "0x323232",
    "test_call_service_disconnect_timeout" : 10,
    "theme_version": 2,
    "conference_unlocked_indicator_text": "Conference unlocked",
    "conference_locked_indicator_n_waiting_text": "{number_of_waiting_participants} waiting for host"
}

The default settings within the Base themeconfig.json file are described below. Note that the Base file does not contain any text overlay or splash screen layout controls, but you can add your own controls to your customized file — as described in this topic — to override the default behavior.

The themeconfig.json file must be UTF-8 encoded, therefore when editing the file you should use a UTF-8 capable editor. We recommend that you do not use Notepad on Windows computers.

Customizing the splash screens

The splash screens are used when joining a conference (such as to capture a PIN), using a Virtual Reception or the Test Call Service, or to display an error such as insufficient licenses. Each splash screen consists of a background JPG file plus other SVG images and text that are overlaid onto the background image.

The themeconfig.json file offers a lot of flexibility when customizing the appearance of the splash screens. You can override the default background image, graphics and text elements that are used on each splash screen, and modify where those elements are positioned. Each splash screen can be configured by specifying a splash_screens object and associated elements within your themeconfig.json file, as described below.

Background image

By default the Base theme contains 2 background files:

File name Image size (width, height) Content in Base theme Notes
background.jpg 1920 x 1080 pixels
JPG (RGB mode only)
The background image used by default on all splash screens except for those used by the Test Call Service.
background_test_call.jpg 1920 x 1080 pixels
JPG (RGB mode only)
The background image (a black screen) used by default on the Test Call Service splash screens.

You can replace either of these files with your own versions, or you have the flexibility to specify an alternative file to use on a specific splash screen. Ensure that the images display acceptably on both 16:9 endpoints and 4:3 endpoints (if applicable). For example, the original 1920 x 1080 pixel (16:9) images may have approximately 240 pixels cropped from both the left and right sides when displayed as 4:3. You should therefore check that any details on the far left or far right of the image are visible in both formats; for this reason we recommend keeping the image fairly central.

To specify an alternative file, use the background element to define the override and the path element to define the file to use. The filename must begin with "background". For example, to use an alternative background for the pin_entry splash screen:

{
  "splash_screens": {
    "screens": {
      "pin_entry": {
        "background": {"path": "background_pin_entry.jpg"},
		...

Make sure that you include the specified background file (background_pin_entry.jpg in this example) in the theme ZIP file that you upload.

Alternatively, instead of specifying a path you can define a color, e.g. "background": {"color": "0x323232"}

Splash screens

The following table lists the splash screens that you can configure within a theme. It describes when that screen is shown and shows its default appearance. It also identifies the screen key to use in a screens object if you want to override the default behavior, and the default icon image and text label elements used on that screen.

All of the screens used when joining a conference use background.jpg as the default background image. The Test Call Service uses background_test_call.jpg during the call.

Default element configuration for each screen

If you define elements for a splash screen, whatever you specify will completely replace all of the default icon and text elements for that screen. For example, if you want to add a new line of text to a screen, your elements object for that screen must define the original (default) icon and text as well as your new text.

Therefore it is useful to know how the icons and text elements are positioned on each splash screen by default.

Text overlays (labels)

The labels object is referenced by every text element that is overlaid onto a splash screen and is used to define the actual text displayed to users. For example:

"splash_screens": {
  "labels": {
    "welcome": "Welcome",
    "connecting": "Connecting",
    "timeout": "Time exceeded",
    ...

The keys (e.g. "timeout") are used in text elements and the associated values (e.g. "Time exceeded") are the text strings that are shown on the screen. The text content can include \n newlines if you require multi-line capability (newlines must be explicitly used and are never applied automatically). On some splash screens, strings may also reference some predefined variables, such as "{conference_name}" which is used in the virtual_reception_connecting screen.

The default font size is 66px and the default color is 0xffffffff (white, defined in ARGB hexadecimal notation).

Note that the default text labels are not contained within the Base theme's themeconfig.json file that you can download from the Management Node, but you can override the default settings by adding the relevant labels into your own themeconfig.json file. The following table contains the default keys, the default text string for each key, and the screen in which that key is used:

Splash screen elements (to control the size and position of text/graphics)

When customizing a splash screen you can define elements to control the appearance and position of images and text on that specific screen. The default screen layout and offsets are shown in this diagram (right).

If you define elements for a splash screen, whatever you specify will completely replace all of the default icon and text elements for that screen. For example, if you want to add a new line of text to a screen, your elements object for that screen must define the original (default) icon and text as well as your new text. See Default element configuration for each screen for more information and Adding an extra text element to a splash screen for a worked example.

The following example shows the JSON structure for how you can define an icon and text type element for a splash screen (the welcome screen in this example). All width, height and offset positions are measured in pixels.

{
  "theme_version": 2,
  "splash_screens": {
    "screens": {
      "welcome": {
        "elements": [
          {
            "type": "icon",
            "path": "icon_welcome.svg",
            "offset_y": 300,
            ...
          },
          {
            "type": "text",
            "label": "welcome",
            "font_size": 66,
            ...
          }
        ],
        ...

The full set of keys that you can specify for each element type are described below.

Icon elements (for SVG files used on splash screens)

Icons are the SVG files that are overlaid onto a splash screen. They can be configured by the icon element, which controls the position and scale (size) of the SVG file, and which file to use.

To change the color of an SVG image, see Changing the color of the SVG image.

Text elements

You have full control over the positioning and style of a text string by using a text element. All measurements are in pixels. The default font for the in-conference display of participant names is Roboto (which cannot be changed), or if that is not available for the character set, Noto Sans. All other overlay text (splash screen text and in-conference messages) uses GT Pressura Light and this can changed by using a customized theme. For example (and showing the default values for non-test-call conferences):

PIN digits element

The pin_digits element is a special element to render up to 20 icons (each 42x42 pixels by default) on 2 lines, and is only used for PIN entry on the pin_entry screen. For example (showing the default values):

Vertical and free form layouts

The splash screens support 2 types of layout: vertical (the default) and free form. Layouts are specified by the layout_type entry in the screen specification object.

Helper lines

To aid development, debugging and theme creation, you can display gridlines for a given splash screen by using the helper_lines object. Helper lines are added on top of the background and under the icons, text and other elements.

Overlay SVG image files used on splash screens when joining a conference

When creating your own SVG image files for use on the splash screens, do not use tools such as Adobe Photoshop or Illustrator to convert JPG or PNG files into SVG format as they typically create complex files/paths that are resource-intensive to render, or in some cases may render incorrectly.

  • Use a vector drawing program that uses SVG as its primary format, such as Inkscape.
  • Do not create a single complex path — use multiple paths instead.

Changing the color of the SVG image

The color in an SVG file is typically controlled by a fill property defined within the file itself. Most of the SVG images used in the Base Pexip theme are white (fill="#FFFFFF").

To change the color of an SVG image you can edit the SVG file in a simple text editor such as Notepad, and change the fill color as required. For example to change the color to red, you would specify fill="#ff0000".

Indicator graphics used within an ongoing conference

The following graphics may be used during a conference. The SVG indicators are rendered on top of a dark gray background (the color is 0x7f323232, where 7f is the alpha channel which makes the background slightly transparent). The gray background is not part of the actual SVG image itself and it cannot be customized. If you use your own customized SVG images, ensure that they look appropriate when displayed on sizes from 20x20px to 48x48px, and are recognizable when displayed as 12x12px for participants that use very low resolutions.

If you are using a theme to customize gateway calls only, then you only need to consider a subset of these images, as indicated in the table below.

Video watermarking

Video watermarking overlays a small transparent image onto the main speaker video during a conference (VMRs and Virtual Auditoriums). Watermarks are not added to calls placed via the Pexip Distributed Gateway.

The default watermark is a white "Pexip" logo and is enabled by default. You can change the watermark image or disable watermarking completely.

Themes used by Call Routing Rules (gateway calls)

You can assign a theme to a Call Routing Rule. Only a subset of the theme's image files are used when they are applied to a Pexip Distributed Gateway call. Thus, you only need to customize a subset of the files for any themes that are only assigned to one or more Call Routing Rules. The various tables on this page indicate, where appropriate, which image files are used in gateway calls.

Also note that:

  • the audio files are not used in themes assigned to Call Routing Rules.
  • from the themeconfig.json file, only the disable_streaming_indicator and streaming_indicator_text / recording_indicator_text settings are used (for gateway calls into an externally-hosted conference, such as a Microsoft Teams or Skype for Business meeting, or Google Hangouts Meet).