Use MLCG.RestControl to build a C# operator panel or connect newsroom, sports and automation data to MLCG graphics. Its typed methods list published sessions, update binding values and control animation, so your application does not need to construct HTTP/JSON requests.
This guide uses public version 1.0.2. Source and release information are available in the public GitHub repository.
Jump to session discovery, data updates, output URLs, animation controls, or Demo Workspaces.
What the client controls
- MLCG Editor creates templates, exposes data bindings and publishes live sessions.
- MLCG.RestControl discovers sessions and sends data and animation commands to the server.
- The SDK HTML5 Overlay plugin renders a session's HTML output over video on the SDK machine.
The REST package does not decode video or render graphics. You can use it without the Video SDK, for example to control an HTML output consumed by another application. For design instructions, see the MLCG Editor documentation on GitBook.
The integration workflow is: publish a session → discover it → read its bindings → build and load the output URL → update data and animation.
REST commands address the session. Your rendering application controls page readiness, local visibility, video processing and output.
Install the package
The read-only console example below uses the .NET 9 SDK. Create its project and install the package:
dotnet new console --framework net9.0 --name MlcgRestQuickStart
cd MlcgRestQuickStart
dotnet add package MLCG.RestControl --version 1.0.2
For an existing project, the equivalent reference is:
<PackageReference Include="MLCG.RestControl" Version="1.0.2" />
Version 1.0.2 targets .NET Framework 4.7.2 and .NET 9.0. It includes named animation controls, timing metadata, Demo Workspaces and typed errors.
For account mode, publish a session in the editor and generate a REST token with access to it. Keep the token in secure application configuration. The hosted service address is https://cg.medialooks.com; use your configured service address for a local or on-premises deployment.
List published sessions and binding keys
Make the account token available through the MLCG_API_TOKEN environment variable using your normal secure configuration. Do not embed it in source code or a command saved in shell history.
Replace Program.cs with this complete program and run dotnet run. It lists session IDs, names and binding keys without changing graphics or printing tokens or binding values:
using System;
using System.Threading;
using System.Threading.Tasks;
using MLCG.RestControl;
internal static class Program
{
private static async Task<int> Main()
{
string token = Environment.GetEnvironmentVariable("MLCG_API_TOKEN");
if (string.IsNullOrWhiteSpace(token))
{
Console.Error.WriteLine("Configure MLCG_API_TOKEN first.");
return 1;
}
using (var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(30)))
using (var client = new MlcgRestClient("https://cg.medialooks.com"))
{
client.ApiToken = token;
try
{
var sessions = await client.GetSessionsAsync(timeout.Token);
Console.WriteLine("Published sessions: " + sessions.Count);
foreach (var session in sessions)
{
Console.WriteLine(session.Id + ": " + session.Name);
var bindings = await client.GetBindingsAsync(
session.Id, timeout.Token);
foreach (var binding in bindings)
Console.WriteLine(" Binding: " + binding.Key);
}
return 0;
}
catch (OperationCanceledException)
{
Console.Error.WriteLine("The request was canceled or timed out.");
}
catch (MlcgRestException ex)
{
Console.Error.WriteLine(ex.StatusCode.HasValue
? "MLCG request failed: HTTP " + (int)ex.StatusCode.Value
: "MLCG transport request failed.");
}
return 1;
}
}
}
The list contains published sessions visible to the token, not the entire design Library. If it is empty, check publication status and account/workspace permissions. A healthy server does not by itself confirm authorization.
Choose a session ID from this response. A Library template ID identifies a design, not a controllable published session.
Use the following examples in a controller
The remaining code blocks are fragments. They assume an authenticated client, a selectedSessionId from the returned list and a cancellationToken. Test mutations against your own test session or a private Demo instance, using binding keys exposed by that design.
For an interactive application, keep the client for the controller's lifetime and dispose it on shutdown. Keep session commands ordered. When selection or connection changes, cancel obsolete work or ignore its late responses.
Await REST requests without blocking the UI or a synchronous SDK media callback. HTTP completion confirms a request outcome, not a rendered video frame.
Update graphics data
Update values by binding key, using keys returned by GetBindingsAsync. For a design that exposes headline:
await client.UpdateBindingAsync(
sessionId: selectedSessionId,
key: "headline",
value: "Updated from our C# application",
cancellationToken: cancellationToken);
Send related changes in one request when the selected session exposes the corresponding keys:
using System.Collections.Generic;
await client.UpdateBindingsAsync(
selectedSessionId,
new Dictionary<string, string>
{
["player_name"] = "MARTA KOVACS",
["team_name"] = "RIVER CITY FC",
["score"] = "2 - 1"
},
cancellationToken);
Send only changed values with UpdateBindingAsync or UpdateBindingsAsync. Use ReplaceBindingsAsync only when your application owns the complete binding list: it replaces that list rather than updating selected values.
Data and animation commands affect all outputs using the same session. Use separate sessions for independent operators, data or test runs. Account/workspace permissions still apply.
Get the HTML output URL
string outputUrl = client.BuildOverlayUrl(
outputBaseUrl: "https://cg.medialooks.com",
sessionId: selectedSessionId,
autoplay: false,
loop: false);
Load this transparent, read-only URL with the SDK HTML5 plugin's BrowserPageLoad, or another supported browser-overlay consumer. BuildOverlayUrl does not include the REST token.
The output link grants viewing, not REST editing. Anyone with a usable link may be able to see its graphics and data, so share it only with the intended audience. Never share the control token or add it to an output URL.
Avoid a double start when loading graphics
Keep the local overlay hidden, load it with autoplay disabled, and wait for the scene, fonts and images to be ready. Then send one Restart command and reveal the overlay:
await client.RestartAnimationAsync(
selectedSessionId, loop: false,
cancellationToken: cancellationToken);
Page loading, readiness and local visibility belong to your SDK integration, not the REST wrapper. The SDK samples implement this prepare-then-reveal workflow. Enabling autoplay and immediately sending Restart can produce two visible starts; a completed HTTP command is not a painted-frame acknowledgement.
Control animation with named methods
// Start from zero; explicitly disable scene looping.
await client.RestartAnimationAsync(selectedSessionId, loop: false,
cancellationToken: cancellationToken);
// Pause at the current graphics position.
await client.PauseAnimationAsync(selectedSessionId,
cancellationToken: cancellationToken);
// Seek to 1.5 seconds and stay paused, in one command.
await client.SeekAnimationAsync(selectedSessionId, positionMs: 1500,
cancellationToken: cancellationToken);
// Resume without seeking back to zero.
await client.PlayAnimationAsync(selectedSessionId,
cancellationToken: cancellationToken);
// Change looping without restarting or seeking.
await client.SetAnimationLoopAsync(selectedSessionId, enabled: true,
cancellationToken: cancellationToken);
var timing = await client.GetSessionAnimationInfoAsync(
selectedSessionId, cancellationToken);
int maximumSliderPositionMs = timing.DurationMs;
Use DurationMs to set a seek slider's range. Send Seek when the operator commits a new position, not on every UI refresh. Timing metadata does not report the remote current playhead or confirm browser paint.
Scene Loop controls the scene animation. It does not rewrite intrinsic ticker scrolling or per-layer repeats.
Animation commands do not pause or seek source video and do not establish source-clock synchronization. Video transport in the SDK application is independent of the session animation seen by HTML output viewers.
Hide, preview Mute / Unmute, fullscreen (F11 / Esc) and the Activity window are local application/SDK controls, not REST client methods. See sample preview controls.
Offer an account-free private demo
A Demo Workspace lets a sample use real catalog templates without an account token. Each launch receives private live copies, so users do not share a password or change a common public session.
// Keep this dedicated demo client for the demo controller's lifetime.
var demoClient = new MlcgRestClient("https://cg.medialooks.com");
var launchId = Guid.NewGuid().ToString("D");
var workspace = await demoClient.StartDemoWorkspaceAsync(
launchId, "my-sample", "1.0.0", cancellationToken);
demoClient.ApiToken = workspace.ApiToken;
var catalog = await demoClient.GetDemoTemplatesAsync(cancellationToken);
// selectedTemplateId is selected from catalog in your application's UI.
var instanceKey = Guid.NewGuid().ToString("D");
var instance = await demoClient.CreateDemoSessionAsync(
workspace.Id, selectedTemplateId, instanceKey, cancellationToken);
string privateSessionId = instance.Session.Id;
Use a dedicated demo client that does not carry account credentials. The version string in this example identifies your application.
Save launch and instance UUIDs before sending creation requests. Reuse them when retrying the same creation after an uncertain outcome; generate new IDs for an intentional new launch or instance.
Manage the workspace lifecycle
Your application must renew the lease, handle expiry and clean up:
-
Renew with
HeartbeatDemoWorkspaceAsyncat the returnedHeartbeatIntervalSeconds. Adopt updated expiry and interval values, but keep the original token: renewal does not replace it. - Keep renewal independent of slow graphics preparation, with bounded requests and at most one heartbeat in flight per workspace. Ignore stale responses after reconnecting.
- Show lease and capacity errors, and disable further REST mutations when control expires. Demo edits are temporary.
-
On shutdown, call
ReleaseDemoWorkspaceAsyncwith a separate bounded cleanup token, then dispose the client. Read-only viewers may remain until expiry.
To explicitly end the workspace and its outputs, use EndDemoWorkspaceAsync. This is different from releasing control.
The wrapper does not automatically send heartbeats or cache template instances. The SDK samples provide a complete lifecycle implementation.
Handle cancellation and typed failures
try
{
await client.UpdateBindingAsync(selectedSessionId, "headline",
"New headline", cancellationToken);
}
catch (OperationCanceledException)
{
// Report cancellation or timeout to the application UI.
}
catch (MlcgRestException ex)
{
string status = ex.StatusCode.HasValue
? ((int)ex.StatusCode.Value).ToString()
: "transport";
Console.WriteLine("MLCG REST request failed: " + status);
// ex.RetryAfter may provide a rate/capacity-limit delay.
}
- 401 / 403: check the token and access to the target session.
- 404: check the session ID and the service route.
-
429: handle a rate or capacity limit; inspect
RetryAfterif supplied. - No HTTP status: investigate transport failure or cancellation.
Use the typed status instead of parsing exception text. The client does not automatically retry mutating commands. If the outcome is uncertain, follow that operation's retry and idempotency rules rather than blindly replaying it.
Keep credentials, token-bearing configuration and sensitive binding values out of logs.
Reference implementations in the SDK
The MLCG HTML REST projects combine the public wrapper with the SDK HTML5 plugin. The source separates the two responsibilities:
-
RestSessionController.csmanages REST connection, session selection, binding data, animation commands and Demo Workspaces. -
SdkVideoHost.csmanages SDK video processing and HTML rendering.
Try demo creates private temporary instances; Connect lists an account's published sessions. In the Source dropdown, choose File to open a file picker, URL / Stream to enter a transport address, or a discovered mp:// sender.
Default executable paths:
MPlatform:
C:\Program Files (x86)\Medialooks\MPlatform SDK\Samples Basic\C#\MLCG HTML REST\bin\x64\Debug\MLCG HTML REST.exe
MFormats:
C:\Program Files (x86)\Medialooks\MFormats SDK\Samples\C#\MLCG HTML REST\bin\x64\Debug\MLCG HTML REST.exe
See full solution paths and MLCG Editor: graphics workflow and SDK samples for the complete application workflow. Shared SDK prerequisites are in Before you start.
Further reading
Still have questions?
Tell us what didn’t work or what you’d like clarified.