Use IMFBrowser to load a page, update its content and forward mouse or keyboard input. The cef_plugin JavaScript bridge lets the page exchange events with your application and receive optional frame metadata or images.
This article covers lower thirds, scoreboards, dashboards and other HTML pages controlled by your application. For shared requirements, see Before you start. To connect the plugin to video, start with the overview.
For an MLCG output URL, use the MLCG REST Client to select sessions, update bindings and control animation. Do not change MLCG's internal DOM or start its animation with injected JavaScript. The MLCG HTML REST samples show this separation: the SDK renders the page; REST controls the graphics.
Choose the control path
| What you need | Use | Keep in mind |
|---|---|---|
| Load a URL, local file or generated HTML | BrowserPageLoad, BrowserHtmlDisplay |
Loading is asynchronous. Wait for the page's ready signal before using it. |
| Update content without reloading | BrowserJavascriptExecute, BrowserCSSSet |
Use your page's elements or functions. Serialize values and acknowledge updates with events. |
| Let an operator interact with the page | BrowserMouse*, BrowserKeyEvent, BrowserCommand |
Map preview coordinates to the page. Forward focus, modifiers and complete input sequences. |
| Exchange events between the page and C# |
OnEventSafe, put_event, set_on_event
|
Validate event data. Queue notifications; do not block media callbacks. |
| Read frame metadata or deliver an image to the page |
set_on_frame, IMCallback.OnFrame / set_on_image
|
Metadata and images use different operations. Neither automatically provides frame-accurate browser timing. |
| Manage readiness and shutdown |
Readiness protocol, BrowserClose and owner cleanup
|
A loaded page, ready assets, a browser paint and a presented video frame are separate milestones. |
For position, opacity, page size, cache, logs and supported CEF options, see the properties reference. You can try the methods below with the installed samples and the test page at the end of this article.
Load and control a page
The examples use MFORMATSLib.MFOverlayHTMLClass. For MPlatform, use the matching types from MPLATFORMLib. Keep the plugin alive and send commands through your application's SDK-owner thread or queue, never from an SDK event callback.
| Method | Use |
|---|---|
BrowserPageLoad(string filenameOrUrl) |
Load a URL or local page. Return from the call means navigation was accepted, not that the page is ready or painted. |
BrowserHtmlDisplay(string html) |
Display an HTML string. Use a hosted page instead when relative assets, modules or network dependencies need a base URL. |
BrowserJavascriptExecute(string script) |
Run JavaScript. The method has no return-value out parameter; send results or acknowledgements through a page event. |
BrowserCSSSet(string css) |
Inject CSS into the page. This does not update a template model or MLCG bindings. |
BrowserCommand(eMFBrowserCommand command, string parameters) |
Reload, go back or forward, or stop loading. |
BrowserClose() |
Close browser resources during shutdown. Stop using or processing the plugin first. Never close it from its own callback. |
// On the SDK-owner thread, with html already created and the
// browser-controls.html test page linked below loaded and ready:
html.BrowserCSSSet("#headline { color: white; font-weight: 700; }");
// Serialize values instead of concatenating untrusted text into JavaScript.
string text = "Example headline";
string literal = new System.Web.Script.Serialization.JavaScriptSerializer()
.Serialize(text);
html.BrowserJavascriptExecute(
"document.getElementById('headline').textContent = " + literal + ";");
The headline element belongs to the test page below. In .NET Framework, this serialization example needs a reference to System.Web.Extensions.
For your own page, use its documented elements or expose a small function for updates. Do not assume that these element IDs exist on another website, and never evaluate arbitrary remote code.
Use BrowserPageLoad for a document with an asset/base URL. For a small document with no relative assets, pass the HTML directly to BrowserHtmlDisplay:
html.BrowserHtmlDisplay(
"<!doctype html><html><meta charset='utf-8'>" +
"<body style='margin:0;background:transparent'>" +
"<div id='headline' style='background:#173247;color:white;" +
"padding:24px;font:28px Arial'>Ready</div></body></html>");
Wait for the new page's required state before sending script commands. Use navigation commands as separate actions: reloading immediately after a text update discards that change.
html.BrowserCommand(eMFBrowserCommand.eMFBC_Reload, "");
// Other commands: eMFBC_GoBack, eMFBC_GoForward, eMFBC_StopLoad.
Receive events in C#
Subscribe to OnEventSafe before loading. The callback receives the channel, event name, parameter and event-object context. Retain the delegate so you can unsubscribe during shutdown.
using System;
using System.Collections.Concurrent;
using MFORMATSLib; // Use MPLATFORMLib for the MPlatform edition.
// This helper observes a plugin owned by the application; it does not own it.
public sealed class BrowserNotifications
{
private readonly MFOverlayHTMLClass _html;
private readonly IMEventsEvent_OnEventSafeEventHandler _handler;
private readonly ConcurrentQueue<Tuple<string, string, string>> _events =
new ConcurrentQueue<Tuple<string, string, string>>();
public BrowserNotifications(MFOverlayHTMLClass html)
{
_html = html ?? throw new ArgumentNullException(nameof(html));
_handler = OnBrowserEvent;
_html.OnEventSafe += _handler;
}
private void OnBrowserEvent(string channel, string name,
string parameter, object eventObject)
{
// Copy managed values only. No SDK calls, UI invocation, network I/O,
// blocking waits, or plugin teardown inside this callback.
_events.Enqueue(Tuple.Create(channel, name, parameter));
// Do not retain or final-release the shared event-object context.
}
public bool TryRead(out Tuple<string, string, string> notification)
{
return _events.TryDequeue(out notification);
}
// Call from the owner after stopping processing and draining callbacks.
public void Detach()
{
_html.OnEventSafe -= _handler;
}
}
Drain this queue from your application loop or UI dispatcher. Update controls there, not inside the SDK callback.
- Filter or coalesce high-rate notifications to prevent an unbounded backlog.
- Validate the channel, event name and payload before acting.
- The event-object context may be an existing COM object owned by your application. Do not treat it as a new plugin to close or final-release.
| Channel / event | Meaning |
|---|---|
CEF / on_load_start
|
A frame started loading; the parameter is its URL. |
CEF / on_load_end
|
A frame finished loading; the parameter is its URL. Subframes also raise this event. It does not confirm that graphics are ready or a new GPU frame has been painted. |
CEF / on_load_error
|
A frame failed to load or was aborted; the parameter is its URL. Check logs for details. An aborted navigation is not always an application failure. |
| Application-defined channel and event | A notification emitted by the page with cef_plugin.put_event. |
Send a notification from JavaScript
The SDK browser injects cef_plugin; an ordinary desktop browser does not provide it. Send strings through the bridge:
if (window.cef_plugin) {
cef_plugin.put_event("my-overlay", "score-changed",
JSON.stringify({ home: 2, away: 1 }));
}
C# receives channel my-overlay, event name score-changed and the JSON string as the parameter. The payload format is yours to define; this is not an MLCG REST request. Keep credentials out of events and avoid logging sensitive page data.
Wait until the page is ready
Navigation can finish before data, fonts and images are usable. Have your page send a ready event after applying its data and preparing required resources:
async function notifyOverlayReady(instanceId) {
try {
if (document.fonts && document.fonts.ready) {
await document.fonts.ready;
}
await Promise.all(Array.from(document.images).map(function (image) {
if (image.decode) return image.decode();
if (image.complete) {
return image.naturalWidth > 0 ? Promise.resolve() :
Promise.reject(new Error("Image is unavailable"));
}
return new Promise(function (resolve, reject) {
image.addEventListener("load", resolve, { once: true });
image.addEventListener("error", reject, { once: true });
});
}));
requestAnimationFrame(function () {
if (window.cef_plugin) {
cef_plugin.put_event("my-overlay", "ready", instanceId);
}
});
} catch (error) {
if (window.cef_plugin) {
cef_plugin.put_event("my-overlay", "not-ready", instanceId);
}
}
}
Match each response to a new navigation/request identifier, and give the application a timeout and cancellation path. Never wait indefinitely on the UI thread or inside a callback.
Decide which resources are required, how optional image failures are handled and when dynamically added assets count as ready. Font readiness and image decoding are separate operations.
A ready event confirms prepared resources, not pixels at the SDK output. requestAnimationFrame is not a GPU-paint fence. For frame-accurate work, verify processed/presented frames and timestamps. For MLCG, use its readiness and playback workflow; do not restart playback on every load event or substitute this custom-page protocol.
Read SDK frame metadata in JavaScript
Register a global function by name to receive SDK frame metadata. The argument is an SDK parameter string, not a JavaScript object or JSON. Parse it with cef_plugin.parse_parameters.
Load the script before DOMContentLoaded and provide a timecode element to display the result. A listener added after that event has fired will not run retroactively.
function on_frame_my(frameInfo) {
if (!frameInfo || !window.cef_plugin) return;
var info = cef_plugin.parse_parameters(frameInfo);
var timecode = document.getElementById("timecode");
if (timecode) timecode.textContent = info.timecode || "";
// info.time and info.vid_props are formatted SDK strings as well.
}
document.addEventListener("DOMContentLoaded", function () {
if (window.cef_plugin) cef_plugin.set_on_frame("on_frame_my");
});
Define the callback in a classic/global script, or attach it to window. Keep per-update work small: avoid network calls, synchronous property reads, DOM rebuilds and unnecessary layout measurements.
A callback does not guarantee a fresh browser paint for each video frame. Interlaced processing can also produce field-related updates, so do not time animation by counting callbacks.
Receive host events in the page
Use set_on_event to register a page function for events from the plugin or host. Arguments are strings; optional values may be empty or absent depending on the event and SDK build. The object description is text, not a callable COM object.
function on_event_my(channel, name, parameter, objectDescription) {
var label = document.getElementById("last-event");
if (label) label.textContent = channel + ": " + name;
// Validate names and payloads before acting on application events.
}
if (window.cef_plugin) cef_plugin.set_on_event("on_event_my");
Host information depends on where the overlay is attached. An MPlatform playlist can expose host::current::file::info::path and host::next::file::info::path. An MFormats frame processor does not provide an MPlatform playlist host.
MPlatform can forward host events. To send your own notification, call the plugin's IMCallback interface on the SDK-owner thread. The page receives it through set_on_event:
((IMCallback)html).OnEvent(
0, "my-overlay", "refresh-requested", "current-data", null);
cef_plugin.props_get(name) is synchronous. Reserve it for occasional, event-driven diagnostics, not per-frame animation. props_set(name, value) writes a property; it is not a REST call. Allow only trusted page code and known property names to use these methods.
Deliver an SDK image to the page
An image callback receives a name and an ImageData object. This transfers image data to JavaScript; it is not zero-copy GPU texture access. Subscribe only when the page needs images:
function on_image_my(imageName, imageData) {
var canvas = document.getElementById("received-image");
if (!canvas || !imageData) return;
canvas.width = imageData.width;
canvas.height = imageData.height;
canvas.getContext("2d").putImageData(imageData, 0, 0);
}
if (window.cef_plugin) cef_plugin.set_on_image("on_image_my");
The example displays the image at native size. Use a separate canvas to scale it, and avoid large per-frame canvas allocations. Subscription alone does not supply video: the application or host must send the image.
Send an SDK frame through IMCallback.OnFrame after the page registers set_on_image. Image delivery is separate from set_on_frame timing/format notifications:
public static class BrowserImageBridge
{
public static void Send(MFOverlayHTMLClass html, object sourceFrame)
{
if (html == null) throw new ArgumentNullException(nameof(html));
if (sourceFrame == null)
throw new ArgumentNullException(nameof(sourceFrame));
((IMCallback)html).OnFrame(0, "diagnostic", sourceFrame);
}
}
sourceFrame must be a valid frame from the matching SDK family, not a bitmap or URL. The helper borrows it without releasing it; your application retains frame ownership.
Delivery is asynchronous and can be busy. It is not an acknowledged per-frame queue or a zero-copy replacement for video composition. Use it for page image features and diagnostics; frequent full-frame transfers add memory copies and JavaScript work.
Forward mouse and keyboard input
The browser renders off-screen. To make a preview interactive, forward input with BrowserMouseClick, BrowserMouseMove, BrowserMouseWheel and BrowserKeyEvent.
| C# method | Input contract |
|---|---|
BrowserMouseClick(ref MF_MOUSE_EVENT mouse, eMFMouseButtons button, int mouseUp, int clickCount) |
Use 0 for button-down and 1 for button-up; forward both. The example below sends one left click. |
BrowserMouseMove(ref MF_MOUSE_EVENT mouse, int mouseLeave) |
Forward the mapped position and indicate when the pointer leaves the page area. |
BrowserMouseWheel(ref MF_MOUSE_EVENT mouse, int deltaX, int deltaY) |
Forward the mapped pointer location and wheel deltas, such as the UI mouse-wheel event's delta. |
BrowserKeyEvent(ref MF_KEY_EVENT key) |
Supply the correct event type, key/character fields and actual modifier state. Character input needs an editable page element to have focus. |
MF_MOUSE_EVENT.bAbsolutePos = 0 uses normalized coordinates from 0.0 to 1.0. On an overlay object, these refer to the video frame and are adjusted for the destination rectangle.
- Map preview coordinates to video coordinates first; exclude letterboxing.
- Map absolute coordinates, crop and zoom explicitly to the browser viewport.
- Forward both mouse-down and mouse-up. Preserve modifiers and character events.
Do not use a global dx11.windowless registry change as a general mouse fix. Routing depends on the preview renderer and SDK build. Start with explicit forwarding and test the actual output geometry. See the overview for pipeline setup and the properties reference for destination coordinates.
This example clicks the center of a full-frame overlay. Run it on the SDK-owner thread after the page is ready. Explicit input does not require a preview-window mouse hook or registry change.
var mouse = new MF_MOUSE_EVENT
{
bAbsolutePos = 0, // Normalized video coordinates, not desktop pixels.
dblPosX = 0.5,
dblPosY = 0.5,
eFlags = eMFEventsFlags.eMFEF_LEFT_MOUSE_BUTTON
};
html.BrowserMouseClick(ref mouse, eMFMouseButtons.eMFMB_Left, 0, 1); // Down.
mouse.eFlags = 0;
html.BrowserMouseClick(ref mouse, eMFMouseButtons.eMFMB_Left, 1, 1); // Up.
Change the coordinates to target a page control. For text entry, focus an editable field first. Sending a character neither focuses the field nor replaces a complete physical key sequence.
After focusing the field, this sends the A character, not a modifier shortcut or a key-down/key-up sequence:
var key = new MF_KEY_EVENT
{
eType = eMFKeyEventType.eMFKT_Char,
windows_key_code = 'A',
character = 'A',
unmodified_character = 'A'
};
html.BrowserKeyEvent(ref key);
Shut down safely
- Keep SDK browser calls on the application's SDK-owner path; keep event callbacks short and non-blocking.
- Stop accepting new page/UI commands before shutdown. Stop processing or detach the plugin from its host and drain in-flight work.
- Unsubscribe the retained event delegate before closing and releasing the application-owned plugin.
- Do not retain callback COM context or pass frame/COM objects to UI work without an explicit lifetime owner. Copy managed strings/statistics instead.
- Close browser/plugin resources and release each application-owned COM object deterministically. Do not use forced garbage collection as shutdown logic.
Try browser controls in the SDK samples
Use these samples to inspect navigation, input and JavaScript behavior. The paths below use the default installation folders; adjust the root if you installed elsewhere.
MPlatform: advanced Playlist Sample
Run:
C:\Program Files (x86)\Medialooks\MPlatform SDK\Samples Advanced\C#\Playlist Sample\bin\x64\Debug\Playlist Sample.exe
Solution:
C:\Program Files (x86)\Medialooks\MPlatform SDK\Samples Advanced\C#\Playlist Sample\Playlist Sample.sln
Browser-controls source:
C:\Program Files (x86)\Medialooks\MPlatform SDK\Samples Advanced\C#\MControls Library\OverlayHTMLWindow.cs
Play a video, enable HTML overlay and open Props. Use the advanced Playlist Sample listed above, not the basic Internal Playlist Sample.
MFormats: Sample File Playback
Run:
C:\Program Files (x86)\Medialooks\MFormats SDK\Samples\C#\Sample File Playback\bin\x64\Debug\Sample File Playback.exe
Solution:
C:\Program Files (x86)\Medialooks\MFormats SDK\Samples\C#\Sample File Playback\Sample File Playback.sln
Browser-controls source:
C:\Program Files (x86)\Medialooks\MFormats SDK\Samples\C#\Sample File Playback\OverlayHTMLWindow.cs
Choose Load File, start playback, enable HTML overlay and open Props. In both editions, OverlayHTMLWindow provides a page address, interactive preview, navigation and JavaScript controls.
Test with a self-contained page
Save this HTML as C:\Graphics\browser-controls.html. It needs no external assets and defines the element IDs used above. In the SDK browser, Apply text updates the headline and sends an applied event.
Use this page for a DOM/bridge test, not as an element-ID contract for other websites or MLCG outputs.
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<style>
html, body { margin: 0; background: transparent; font: 28px Arial; }
.card { position: absolute; left: 6%; top: 10%; padding: 24px;
background: #173247; color: white; }
input, button { font: inherit; margin-top: 12px; }
</style>
<div class="card">
<div id="headline">Ready to update</div>
<input id="message" aria-label="Headline" value="Hello from the SDK">
<button id="apply">Apply text</button>
</div>
<script>
document.getElementById("apply").onclick = function () {
var text = document.getElementById("message").value;
document.getElementById("headline").textContent = text;
if (window.cef_plugin) {
cef_plugin.put_event("my-overlay", "applied", text);
}
};
</script>
</html>
Check the page in a sample
- In Props, enter
C:\Graphics\browser-controls.htmlin the page address and click InitSource (MPlatform) or Init Source (MFormats). - Once the page appears, click its input and type, then click Apply text. The Props preview forwards mouse, wheel and supported keyboard events; focus the editable field before typing.
- In the JavaScript box, run the following with Run Java script (MPlatform) or Run Java Script (MFormats). The card should display the new text.
- R reloads the page; <- and -> navigate available browser history. These actions affect this browser instance, not REST data or a saved MLCG template.
document.getElementById("message").value = "Updated through JavaScript";
document.getElementById("apply").click();
Related: Getting started · Properties reference · MLCG HTML REST samples.
Still have questions?
Tell us what didn’t work or what you’d like clarified.