Player Full Settings Structure

This section documents all the available options in the player configuration.

Playback settings

Example

"playback": {
  "autoplay": {
    "enabled": true,
    "loop": {
      "enabled": false
    },
    "mobile": true,
    "onlyMuted": false
  },
  "noPause": false,
  "onEnd": "redirect",
  "resume": true,
  "smartPause": true,
  "smartPauseResume": true,
  "skipAndRewindWithKeyboard": false,
},

Properties

Property	Type	Description
`autoplay.enabled`	boolean	Enables autoplay on page load.
`autoplay.loop.enabled`	boolean	If true, the Smart Autoplay will be looped.
`autoplay.mobile`	boolean	Enables autoplay on mobile devices.
`autoplay.onlyMuted`	boolean	Restricts autoplay to muted playback only (required on most mobile browsers).
`noPause`	boolean	Prevents the user from pausing the video.
`onEnd`	string	Action to perform when video ends. Allowed values: `pause`, `redirect`, `replay`, `display_thumbnail`.
`resume`	boolean	Resumes playback for returning viewers from where they left off.
`smartPause`	boolean	Automatically pauses the video when the user switches tabs.
`smartPauseResume`	boolean	If true, playback resumes automatically after a smart pause.
`skipAndRewindWithKeyboard`	boolean	Enables keyboard shortcuts for skipping forward/backward (← / →).

UI Settings

The ui object contains configuration for the visual elements of the player, including colors, control bar, overlays, and more.

Colors

Example

"ui": {
  "color": {
    "foreground": "#ffffff",
    "background": "#3974ff",
    "force": true
  },
  ...
}

Properties

Property	Type	Description
`color.foreground`	string	Foreground color for overlays and UI elements (HEX format).
`color.background`	string	Background color for overlays and UI elements (HEX format).
`color.force`	boolean	If true, overrides all other color settings with the specified foreground and background.

Control Bar settings

Example

"ui": {
  ...
  "controlBar": {
    "fullscreen": {
      "show": false,
      "customFullscreen": {
        "default": {
          "enabled": true
        },
        "mobile": {
          "enabled": true
        },
        "minimizeOnPause": true,
        "expandOnPlay": true
      }
    },
    "play": {
      "show": true
    },
    "rewind": {
      "show": true
    },
    "seekBar": {
      "show": true,
      "showToReturningViewers": false
    },
    "smartSeekBar": {
      "show": false,
      "desktopSpeed": 1,
      "mobileSpeed": 1
    },
    "speedControl": {
      "show": true
    },
    "qualityControl": {
      "show": true
    },
    "volume": {
      "show": true
    },
    "alwaysShow": false,
    "playbackTimer": {
      "show": true
    },
    "allowSeekNavigation": true,
    "hideOnPause": false,
    "accessibilityTooltips": true
  },
  ...
}

Properties

Property	Type	Description
`controlBar.fullscreen.show`	boolean	Whether the fullscreen button in the control bar is visible.
`controlBar.fullscreen.customFullscreen.default.enabled`	boolean	Enables Focused Fullscreen on desktop.
`controlBar.fullscreen.customFullscreen.mobile.enabled`	boolean	Enables Focused Fullscreen on mobile.
`controlBar.fullscreen.customFullscreen.minimizeOnPause`	boolean	Minimizes Focused Fullscreen when the video is paused.
`controlBar.fullscreen.customFullscreen.expandOnPlay`	boolean	Expands to Focused Fullscreen when the video starts playing.
`controlBar.play.show`	boolean	Shows or hides the play button.
`controlBar.rewind.show`	boolean	Shows or hides the rewind button.
`controlBar.seekBar.show`	boolean	Displays the seek bar.
`controlBar.seekBar.showToReturningViewers`	boolean	If true, hides the seek bar during the first view and shows it for returning viewers.
`controlBar.smartSeekBar.show`	boolean	Enables the Smart Seek Bar feature.
`controlBar.smartSeekBar.desktopSpeed`	number	Speed multiplier for Smart Seek Bar on desktop.
`controlBar.smartSeekBar.mobileSpeed`	number	Speed multiplier for Smart Seek Bar on mobile.
`controlBar.speedControl.show`	boolean	Shows or hides the speed control.
`controlBar.qualityControl.show`	boolean	Shows or hides the quality selector.
`controlBar.volume.show`	boolean	Shows or hides the volume control.
`controlBar.alwaysShow`	boolean	If true, the control bar is always visible.
`controlBar.playbackTimer.show`	boolean	Shows or hides the playback timer.
`controlBar.allowSeekNavigation`	boolean	Enables seeking through the video using the seek bar.
`controlBar.hideOnPause`	boolean	Hides the Control Bar when the video is paused.
`controlBar.accessibilityTooltips`	boolean	Displays accessibility tooltips on hover.

Overlays

The overlay object controls additional UI overlays shown on top of the video, such as Big Play button, redirect message, resume message, Smart Autoplay overlay.

Example

"ui": {
  ...
  "overlay": {
    "play": {
      "button": {
        "show": true
      },
      "seekButtons": {
        "show": false
      }
    },
    "multiPause": {
      "r_EtAxz0Zek1Zhcy": {
        "from": 10,
        "to": 20,
        "source": "https://fast.vidalytics.com/video/LgjdU9my/2yA5q5AloqHQSpfc/img/custom-pause/processed_image-679eaa4407139.jpg"
      },
      "eICPC2bpcc5J3Ywd": {
        "from": 30,
        "to": 40,
        "source": "https://fast.vidalytics.com/video/LgjdU9my/2yA5q5AloqHQSpfc/img/custom-pause/processed_image-679eaa4407139.jpg"
      }
    },
    "redirect": {
      "color": {
        "foreground": "#ffffff",
        "background": "#3974ff"
      },
      "show": true,
      "timeout": 5,
      "url": "https://vidalytics.com",
      "text": "You will be redirected in %d seconds"
    },
    "resume": {
      "button": {
        "replay": {
          "text": "Start from \u003Cbr\u003E Beginning?"
        },
        "resume": {
          "text": "Continue \u003Cbr\u003E watching?"
        }
      },
      "color": {
        "foreground": "#ffffff",
        "background": "#3974ff"
      },
      "show": true,
      "text": "Welcome Back!\u003Cbr\u003EYou've already started\u003Cbr\u003Ewatching this video..."
    },
    "unmute": {
      "color": {
        "foreground": "#ffffff",
        "background": "#3974ff"
      },
      "doReplay": true,
      "goFullscreen": {
        "default": {
          "enabled": false
        },
        "mobile": {
          "enabled": false
        }
      },
      "mobile": {
        "enabled": false,
        "textBottom": {
          "text": "Tap for Sound"
        },
        "textTop": {
          "text": "Click To Unmute"
        }
      },
      "textBottom": {
        "text": "Click To Unmute"
      },
      "textTop": {
        "text": "Your Video Is Playing"
      },
      "type": "box"
    },
    "expire": {
      "enabled": true,
      "dateExpire": "2025-05-24T00:00:00+00:00",
      "textTop": {
        "text": "This Video Has Expired"
      },
      "textBottom": {
        "text": "Click Here to Go Back"
      },
      "link": {
        "href": "",
        "blank": false
      },
      "color": {
        "foreground": "#ffffff",
        "background": "#3974ff"
      }
    },
    "playGate": {
      "O4pSUihIm0ynf_Cu": {
        "button": {
          "color": {
            "foreground": "#ffffff",
            "background": "#d0021b"
          },
          "text": {
            "text": "Keep Watching"
          }
        },
        "color": {
          "foreground": "#ffffff",
          "background": "#3974ff"
        },
        "email": {
          "show": true
        },
        "name": {
          "show": true
        },
        "phone": {
          "show": false
        },
        "skippable": false,
        "textBottom": {
          "text": "We hate spam and will never ever spam you. You can opt out at any time."
        },
        "textSkip": {
          "text": "Skip this"
        },
        "textTop": {
          "text": "Enter your info to get this video in your inbox."
        },
        "time": 10,
        "type": "time",
        "checkbox": false,
        "checkboxRequired": false
      }
    }
  },
  ...
}

Properties

Property	Type	Description
`play.button.show`	boolean	Displays the Big Play button.
`play.seekButtons.show`	boolean	Shows or hides skip forward/back buttons alongside the Big Play button.
`multiPause.[id].from`	number	Time in seconds when the video should pause and the exit thumbnail appears.
`multiPause.[id].to`	number	Time in seconds when the video resumes playback.
`multiPause.[id].source`	number	URL of the exit thumbnail to display during the paused interval.
`redirect.color.foreground`	string	Foreground color for the redirect overlay (HEX format).
`redirect.color.background`	string	Background color for the redirect overlay (HEX format).
`redirect.show`	boolean	Enables the redirect overlay after the video ends.
`redirect.timeout`	number	Delay (in seconds) before redirection occurs.
`redirect.url`	string	URL to redirect the viewer to.
`redirect.text`	string	Text displayed to the viewer before redirection. Supports `%d` for countdown.
`resume.show`	boolean	Enables the resume overlay for returning viewers.
`resume.text`	string	Message shown above the resume/replay buttons. Supports `<br>` tags.
`resume.color.foreground`	string	Foreground color for the resume overlay (HEX format).
`resume.color.background`	string	Background color for the resume overlay (HEX format).
`resume.button.resume.text`	string	Label for the resume button.
`resume.button.replay.text`	string	Label for the replay button.
`unmute.color.foreground`	string	Foreground color for the Smart Autoplay overlay (HEX format).
`unmute.color.background`	string	Background color for the Smart Autoplay overlay (HEX format).
`unmute.doReplay`	boolean	If true, replays the video from the beginning after unmuting.
`unmute.goFullscreen.default.enabled`	boolean	If true, the video enters fullscreen on desktop when unmuted.
`unmute.goFullscreen.mobile.enabled`	boolean	If true, the video enters fullscreen on mobile when unmuted.
`unmute.mobile.enabled`	boolean	Enables a mobile-specific Smart Autoplay overlay.
`unmute.mobile.textTop.text`	string	Top message shown in the Smart Autoplay overlay on mobile.
`unmute.mobile.textBottom.text`	string	Bottom message shown in the Smart Autoplay overlay on mobile.
`unmute.textTop.text`	string	Default top message shown in the Smart Autoplay overlay.
`unmute.textBottom.text`	string	Default bottom message shown in the Smart Autoplay overlay.
`unmute.type`	string	Sets the style of the Smart Autoplay overlay. Possible values: `box`, `button`, `overlay`, `none`, etc.
`expire.enabled`	boolean	Enables the expiration overlay after a certain date.
`expire.dateExpire`	string	ISO date string when the video should expire.
`expire.textTop.text`	string	Top message shown in the expire overlay.
`expire.textBottom.text`	string	Bottom message shown in the expire overlay.
`expire.link.href`	string	URL that the expiration overlay button redirects to.
`expire.link.blank`	boolean	If true, opens the link in a new tab.
`expire.color.foreground`	string	Foreground color for the expire overlay (HEX format).
`expire.color.background`	string	Background color for the expire overlay (HEX format).
`playGate.[id].color.foreground`	string	Foreground color for the Play Gate (HEX format).
`playGate.[id].color.background`	string	Background color for the Play Gate (HEX format).
`playGate.[id].button.color.foreground`	string	Foreground color for the button in the Play Gate (HEX format).
`playGate.[id].button.color.background`	string	Background color for the button in the Play Gate (HEX format).
`playGate.[id].button.text.text`	string	Button label text.
`playGate.[id].email.show`	boolean	Whether to show the email input field.
`playGate.[id].name.show`	boolean	Whether to show the name input field.
`playGate.[id].phone.show`	boolean	Whether to show the phone input field.
`playGate.[id].skippable`	boolean	Allows skipping the Play Gate if true.
`playGate.[id].textTop.text`	string	Top message shown in the Play Gate.
`playGate.[id].textBottom.text`	string	Bottom message shown in the Play Gate.
`playGate.[id].textSkip.text`	string	Label for the skip button.
`playGate.[id].time`	number	Time (in seconds) when the Play Gate should appear.
`playGate.[id].type`	string	Type of Play Gate trigger. Possible values: `time`, `exit`.
`playGate.[id].checkbox`	boolean	Whether to show a checkbox field.
`playGate.[id].checkboxRequired`	boolean	If true, the checkbox must be selected to proceed.

ℹ️ Each playGate is uniquely identified by its key (e.g., playGate.O4pSUihIm0ynf_Cu). The ID must be taken from your account’s VidSettings page, as random values won't be recognized in our stats.

Closed Captions

Example

"ui": {
  ...
  "closedCaptions": {
    "default": {
      "enabled": false,
      "displayWhenMuted": false
    },
    "mobile": {
      "enabled": true,
      "displayWhenMuted": false
    },
    "source": "https://fast.vidalytics.com/video/LgjdU9my/ogMsWEWBw2ydWmYV/closed-captions/vtt-683235a3bf28b-sonic-the-hedgehog-3.vtt"
  },
  ...
}

Properties

Property	Type	Description
`closedCaptions.default.enabled`	boolean	Enables closed captions by default on desktop.
`closedCaptions.default.displayWhenMuted`	boolean	If true, captions are automatically shown when the video is muted (desktop only).
`closedCaptions.mobile.enabled`	boolean	Enables closed captions by default on mobile devices.
`closedCaptions.mobile.displayWhenMuted`	boolean	If true, captions are automatically shown when the video is muted (mobile only).
`closedCaptions.source`	string	URL to the `.vtt` subtitle file used for closed captions.

Thumbnails

The thumbnail section defines which image or video snippet is used as the preview before playback begins. It also allows specifying separate sources for desktop and mobile, as well as a placeholder image and override behavior.

Example

"ui": {
  ...
  "thumbnail": {
    "fullSize": false,
    "default": {
      "type": "image",
      "source": "https://fast.vidalytics.com/video/LgjdU9my/ogMsWEWBw2ydWmYV/190859/181246__FFMPEG/thumb/thumbnail-5_0.jpg"
    },
    "mobile": {
      "type": "image",
      "source": "https://fast.vidalytics.com/video/LgjdU9my/ogMsWEWBw2ydWmYV/190859/181246__FFMPEG/thumb/thumbnail-5_0.jpg"
    },
    "forceDefault": true,
    "placeholder": {
      "source": "https://fast.vidalytics.com/video/LgjdU9my/ogMsWEWBw2ydWmYV/190859/181246__FFMPEG/thumb/preview-5_0.jpg"
    }
  },
  ...
}

Properties

Property	Type	Description
`thumbnail.fullSize`	boolean	If true, stretches the thumbnail to fill the player area entirely.
`thumbnail.default.type`	string	Type of the default thumbnail. Possible values: `image`, `video`.
`thumbnail.default.source`	string	URL of the default thumbnail shown on desktop.
`thumbnail.mobile.type`	string	Type of the mobile thumbnail. Possible values: `image`, `video`.
`thumbnail.mobile.source`	string	URL of the thumbnail shown on mobile devices.
`thumbnail.forceDefault`	boolean	If true, always uses the `default` thumbnail on all devices (ignores `mobile`).
`thumbnail.placeholder.source`	string	URL of a lightweight image shown as a placeholder while the video loads.

Chapters

The chapters section allows you to define logical video segments that are displayed in the player UI. Viewers can use them to quickly navigate to specific parts of the video.

Example

"ui": {
  ...
  "chapters": {
    "enabled": true,
    "data": [
      {
        "time": 10,
        "title": "Chapter 1"
      },
      {
        "time": 30,
        "title": "Chapter 2"
      },
      {
        "time": 50,
        "title": "Chapter 3"
      },
      {
        "time": 70,
        "title": "Chapter 4"
      }
    ]
  },
  ...
}

Properties

Property	Type	Description
`chapters.enabled`	boolean	Enables the chapters feature in the player.
`chapters.data`	array	An array of chapter definitions. Each entry must include a `time` and `title`.
`chapters.data[].time`	number	Time in seconds when the chapter begins.
`chapters.data[].title`	string	Title of the chapter displayed in the UI.

Player Themes

Specifies the player theme and associated style settings.

⚠️ This section describes a feature that is currently being developed.

Example

"ui": {
  ...
  "theme": {
    "name": "classic",
    "style": {
      "borderRadius": 5,
      "opacityLevel": 5
    }
  }
  ...
}

Properties

Property	Type	Description
theme.name	string	Name of the theme to apply. Possible values: `classic`, `sleek`.
theme.style.borderRadius	number	Defines how rounded the corners of the player UI elements are. This is a relative unit (not pixels). A value of 5 is roughly equal to `10px`, and 8 corresponds to about `16px`.
theme.style.opacityLevel	number	Sets the overall opacity of the player UI. A value of `1` means almost fully transparent, and `5` means almost fully opaque. The default in the Vidalytics player is `5`.

Call To Actions

The callToActions section defines custom buttons (CTAs) that appear during video playback.

Example

"ui": {
  ...
  "callToActions": {
    "eScsJwu6naOORcXl": {
      "color": {
        "background": "#3974ff",
        "foreground": "#ffffff"
      },
      "colorHover": {
        "background": "#2d57ba",
        "foreground": "#ffffff"
      },
      "displayMode": "reserveSpace",
      "link": {
        "blank": false,
        "href": "https://www.vidalytics.com/"
      },
      "shadow": true,
      "showToReturningViewers": false,
      "showOnlyWhenTriggeredBefore": false,
      "autoScroll": false,
      "scrollOffset": 0,
      "time": {
        "from": 0,
        "to": 131
      },
      "title": "Let’s Do This",
      "type": "time"
    }
  }
  ...
}

Properties

Property	Type	Description
`callToActions.[id].color.background`	string	Background color of the CTA button (HEX format).
`callToActions.[id].color.foreground`	string	Text color of the CTA button (HEX format).
`callToActions.[id].colorHover.background`	string	Background color of the button on hover.
`callToActions.[id].colorHover.foreground`	string	Text color of the button on hover.
`callToActions.[id].displayMode`	string	Layout mode of the CTA. Possible values: `reserveSpace`, `expandContainer`, `onTop`, `customHTML`.
`callToActions.[id].link.href`	string	URL the button navigates to when clicked.
`callToActions.[id].link.blank`	boolean	If true, opens the link in a new tab.
`callToActions.[id].shadow`	boolean	Adds a drop shadow to the button for visual emphasis.
`callToActions.[id].showToReturningViewers`	boolean	If true, hides the CTA during the first view and shows it for returning viewers.
`callToActions.[id].showOnlyWhenTriggeredBefore`	boolean	If true, the CTA appears only if it was triggered in a previous session.
`callToActions.[id].autoScroll`	boolean	If true, automatically scrolls to the section when the CTA appears.
`callToActions.[id].scrollOffset`	number	Offset (in pixels) to apply when auto-scrolling.
`callToActions.[id].time.from`	number	Time (in seconds) when the CTA should appear.
`callToActions.[id].time.to`	number	Time (in seconds) when the CTA should disappear.
`callToActions.[id].title`	string	Text label displayed on the CTA button.
`callToActions.[id].type`	string	Trigger type for the CTA. Possible values: `time`, `exit`.

ℹ️ Each callToAction is uniquely identified by its key (e.g., callToActions.eScsJwu6naOORcXl). The ID must be taken from your account’s VidSettings page, as random values won't be recognized in our stats.

Player Configuration

The player section defines core video playback settings, including media sources, dimensions, aspect ratio, and rendering behavior.

Example

"player": {
  "startupQuality": "auto",
  "lowerBandwidthUsage": false,
  "media": {
    "mp4": {
      "source": "https://fast.vidalytics.com/video/LgjdU9my/ogMsWEWBw2ydWmYV/190859/181246__FFMPEG/mp4/video/480x270_h264_1000000/video.mp4"
    },
    "hls": {
      "source": "https://fast.vidalytics.com/video/LgjdU9my/ogMsWEWBw2ydWmYV/190859/181246__FFMPEG/stream.m3u8"
    }
  },
  "vtt": {
    "seekingBar": "https://fast.vidalytics.com/video/LgjdU9my/ogMsWEWBw2ydWmYV/190859/181246__FFMPEG/vtt/sprites.vtt"
  },
  "aspectRatio": "16:9",
  "height": 1080,
  "width": 1920
},

Properties

Property	Type	Description
`player.startupQuality`	string	Preferred startup quality. Possible values: `auto`, `low`, `medium`, `high`.
`player.lowerBandwidthUsage`	boolean	If enabled, reduces bandwidth usage by stripping high-quality resolution from the stream.
`player.media.mp4.source`	string	Direct URL to the MP4 version of the video (used as a fallback).
`player.media.hls.source`	string	URL to the HLS stream (`.m3u8`) used for adaptive streaming.
`player.vtt.seekingBar`	string	URL to the VTT sprite file used for preview thumbnails on the seek bar.
`player.aspectRatio`	string	Aspect ratio of the player, in the format `width:height` (e.g., `16:9`).
`player.height`	number	Height of the video in pixels.
`player.width`	number	Width of the video in pixels.

Video Metadata

The video section provides basic metadata about the video.

Example

"video": {
  "title": "sonic-movie-2-trailer",
}

Properties

Property	Type	Description
`video.title`	string	Internal title of the video.

Triggers

The triggers section defines custom events that are executed at specific times during playback. These is be used to tag users and integrate with external systems.

Example

"triggers": {
  "items": {
    "gWqomkNCK8mDgTxE": {
      "time": 10,
      "name": "email tag",
      "type": "time",
      "params": {
        "email": "user@example.com",
      }
    }
  }
},

Properties

Property	Type	Description
`triggers.items`	object	A collection of individual trigger definitions, each keyed by a unique ID.
`triggers.items.[id].time`	number	Time (in seconds) when the trigger should fire.
`triggers.items.[id].name`	string	Name or label of the trigger.
`triggers.items.[id].type`	string	Trigger type. Possible values: `time`, `interactive`, `callToAction`.
`triggers.items.[id].params`	object	Parameters list to include with the trigger payload.

ℹ️ Each trigger is uniquely identified by its key (e.g., triggers.items.gWqomkNCK8mDgTxE). The ID must be taken from your account’s VidSettings page, as random values won't be recognized in our stats.

Player Full Settings Structure

Playback settings​

Example​

Properties​

UI Settings​

Colors​

Example​

Properties​

Control Bar settings​

Example​

Properties​

Overlays​

Example​

Properties​

Closed Captions​

Example​

Properties​

Thumbnails​

Example​

Properties​

Chapters​

Example​

Properties​

Player Themes​

Example​

Properties​

Call To Actions​

Example​

Properties​

Player Configuration​

Example​

Properties​

Video Metadata​

Example​

Properties​

Triggers​

Example​

Properties​

Playback settings

Example

Properties

UI Settings

Colors

Example

Properties

Control Bar settings

Example

Properties

Overlays

Example

Properties

Closed Captions

Example

Properties

Thumbnails

Example

Properties

Chapters

Example

Properties

Player Themes

Example

Properties

Call To Actions

Example

Properties

Player Configuration

Example

Properties

Video Metadata

Example

Properties

Triggers

Example

Properties