HTML5 Overlay: properties reference

Configure how the HTML5 plugin renders a page and places it over video: destination geometry, opacity, browser viewport, page capabilities, storage and diagnostics. Set these properties on the MFOverlayHTMLClass instance that processes your video, not on the preview or the video source.

The same property calls are available with MFORMATSLib and MPLATFORMLib. They configure the SDK plugin, not CSS or MLCG template data. For pipeline integration, see HTML5 Overlay: getting started; shared deployment requirements are in Before you start.

Apply properties at the correct lifecycle stage

// html is your pipeline's MFOverlayHTMLClass instance.
// Browser options: set before the first BrowserPageLoad.
html.PropsSet("cef.web_security", "true");
html.PropsSet("cef.mute_audio", "true");
html.PropsSet("transparency", "true");

// Composition: these can also change at runtime.
html.PropsSet("dst.x", "0%");
html.PropsSet("dst.y", "0%");
html.PropsSet("dst.w", "100%");
html.PropsSet("dst.h", "100%");
html.PropsSet("dst.alpha", "50%");

string alpha;
html.PropsGet("dst.alpha", out alpha);

• Runtime composition includes destination geometry, opacity and crop. It does not select the source video format.
• Browser recreation is triggered by changes to settings such as webGL.enabled, cef.mute_audio, cef.web_security, cef.default_css and scrollbars.enabled. These are not animation controls: changing them can discard page state.
• CEF initialization settings include cache/profile paths, logging, debugging and additional switches. Set them before the first page load. A page reload is not CEF reinitialization. For later changes, stop using the browser, close/recreate it deliberately, reapply settings, then load the page.
• Read back and verify. PropsGet confirms the stored value; actual frames, browser diagnostics and page behavior confirm its effect. Available options depend on the installed SDK and CEF build.

Composition and transparency

Destination geometry is resolved against the video frame, not the size of the preview control. The implementation can align coordinates for the negotiated pixel format, so do not rely on subpixel placement at the composition boundary.

Page viewport, crop, and scrolling

For an MLCG ticker, configure its messages and motion through MLCG. Scrolling the browser document with these properties is a different operation.

Browser capabilities and page audio

Load only trusted pages when exposing the cef_plugin application bridge. Web-security restrictions are not an authorization layer for your application's commands.

Page audio can be part of the SDK output. Supporting plugin builds capture CEF audio as PCM, attach it to rendered SDK frames and can mix it into the processed video frame; page audio is not necessarily limited to the operating system's audio output. This is build-, page- and codec-dependent, not a promise that every page or recorder receives audio automatically. Default overlay mixing can also depend on destination area and dst.alpha. If page audio is required, set cef.mute_audio to false before browser initialization and verify PCM samples, channel layout and sample rate in the processed frames and the actual recording/output. Check page autoplay and downstream audio configuration separately. Keep cef.mute_audio set to true for visual-only graphics.

Typical graphics page. Enable WebGL only if the page uses it, mute browser audio if the overlay is visual-only, and keep web security enabled. Host page resources with appropriate CORS rather than disabling security to make a failing request work. These choices do not change the source video's audio or guarantee an all-GPU path.

// Before BrowserPageLoad; choose capabilities your page actually needs.
html.PropsSet("webGL.enabled", "true");
html.PropsSet("cef.mute_audio", "true");
html.PropsSet("cef.web_security", "true");
html.PropsSet("js_dialogs.enabled", "false");

Cache, logs, and advanced configuration

Keep a browser profile and capture useful logs

Use an application-owned writable folder, not the SDK installation directory. This example enables a persistent profile and warning/error logging. Apply it before the first page load; restore your normal logging level after diagnosis.

// Use a separate profile directory for each concurrently running CEF host.
string profile = System.IO.Path.Combine(
    Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
    @"MyCompany\MyVideoApp\HtmlProfile");
System.IO.Directory.CreateDirectory(profile);

html.PropsSet("cef.cache_path", profile);
html.PropsSet("cef.log_file", System.IO.Path.Combine(profile, "cef.log"));
html.PropsSet("cef.log_severity", "3");

A persistent profile can retain page storage and downloaded resources; it is not template preloading. Give independently running CEF hosts separate profile directories. In newer CEF builds, cef.root_cache_path controls the common profile root and must be compatible with cef.cache_path; do not add that property to an older SDK without checking support. See the version-specific CEF settings reference and use the documentation matching the runtime delivered with your SDK. A profile does not share a running overlay between applications.

Inspect a page during development

// Before the first BrowserPageLoad, in a local development build only.
html.PropsSet("cef.remote_debugging_port", "9222");

Open chrome://inspect/#devices in Chrome and discover localhost:9222 to inspect the embedded page's network requests, console and performance. Inspection grants control of the page: use a trusted local machine, restrict network access and never expose this port as a public service. Set the option back to 0 before browser initialization in production. An already running debug listener requires browser/host recreation to disable it.

Use additional Chromium switches only for a measured requirement

cef.config_string is a plugin-parsed list, not a shell command or a JSON object. Entries are separated by whitespace, commas or semicolons. A plain switch name is forwarded to AppendSwitch; a name=value entry goes to AppendSwitchWithValue. Prefer the named SDK property when one exists—for example, cef.remote_debugging_port instead of injecting a debugging flag. The parser is not a general shell-quoting parser; do not assume it can preserve separators or multiple equals signs inside a switch value.

One conditional use case is a trusted application page that must autoplay HTML audio/video without a user click. Chromium defines the following policy switch; verify it on your delivered runtime, rather than adding it as a default for every overlay:

// Optional: before CEF initialization, only when the page requires it.
html.PropsSet("cef.config_string", "autoplay-policy=no-user-gesture-required");

This changes browser media autoplay policy, not MLCG animation timing. It does not add codec/DRM support or unmute audio when cef.mute_audio is enabled. The switch and policy value are defined in Chromium's media switches. Retain any other required switches when constructing your configuration: this assignment replaces the property string.

Switch availability, defaults and GPU behavior vary by runtime. Verify an individual switch in the matching CEF command-line API and Chromium source, apply it before CEF initialization, then compare the same page and video workload against a clean baseline. Disabling web security, GPU synchronization or browser safety checks is not a general performance recipe.

Prefer per-instance settings. Older installations also read creation defaults from HKEY_CURRENT_USER\Software\Medialooks\HTMLOverlay. Those values affect the current Windows user and do not reconfigure an already running browser automatically.

Legacy options

adobe_flash.enabled exists in older property sets for historical Flash integrations. It is not a supported way to add Flash to modern Chromium/CEF and should not be enabled in new HTML5 applications. Migrate the page to HTML/CSS/JavaScript instead.

SDK samples for trying properties

These full paths refer to a default x64 installation; a custom installation can use a different root.

Play a video, enter a page URL beside HTML overlay and enable that checkbox. Click its Props button—not CG Props—then edit values in Properties. The window also provides a preview, a page-address box, Init Source, a local-file ... button and Presets. After editing the main sample's URL while HTML overlay is enabled, press Enter to navigate.

Verify a configuration change

1. Record the installed SDK version, browser runtime and current property values.
2. Apply initialization options before the first page load. Recreate the browser/host deliberately when changing CEF initialization settings; reloading a page alone is insufficient.
3. Check page-load errors, asset access and actual rendered frames at the required video format.
4. For performance tests, compare the same page, video, format and workload. WebGL, cache or a Chromium switch alone does not establish a frame-rate guarantee.

Related: Browser control and events · HTML5 as a live source · MLCG HTML REST samples · MLCG REST Client for C#. For an older runtime, the CEF 120.2 settings reference is available separately; it is not the current version for every SDK.