Mdh.GraphicsInserts 1.0.14

MDH Graphics Inserts — .NET client

MDH Graphics Inserts lets a production team and event organizers manage on-screen graphics ("inserts": name cards, info tags, tickers, countdowns…) online — organizers fill in the content from a share link, the operator takes them to air from the graphics machine. These packages put that library inside your own Windows graphics application, whatever render engine it drives.

dotnet add package Mdh.GraphicsInserts
dotnet add package Mdh.GraphicsInserts.Wpf

How it works

• Live, but never behind the operator's back. The client keeps a WebSocket to the event; a newer version of the tree arrives as a pending update and is applied only when the operator clicks Apply update. What is on screen never changes by itself.
• Works offline. The last applied tree is cached on disk and restored on start. Edits made in the panel (new graphic, changed texts, moves, deletes) go into a local outbox and are synced when the server is reachable again — the panel shows how many changes are waiting.
• Your engine, your rules. The library never touches your render engine directly. You implement IInsertRenderer (draw / take / clear / actions); optional interfaces add preview capture and on-air reporting.
• Previews for the organizers. Every graphic the operator previews is captured and uploaded, so the people filling in the content see what their text looks like on screen. "Preview all" renders the whole tree in one go.
• Listed and reachable from the web UI. Beside the event socket the client holds one socket to its organisation's hub, so the web UI shows it under Sync clients → Connected clients (machine, app, signed-in user, the event it has open) and can ask it to render every preview of an event — any event of the organisation, not only the one on air (another event's tree is fetched just for the run; the on-air tree is untouched). Progress streams back to the page frame by frame. The host sets SyncClient.ClientApp/ClientVersion for the listing; the RenderPreviewsRequested event is handled by the WPF panel, or by your own code when you use the library without it.
• Sockets that notice they are dead. Both sockets run a ping/pong heartbeat (25 s / 10 s); a socket that stops answering is replaced instead of waited on, and the reason it ended is in the Sync info window (Socket last closed). A dropped socket reads as Connected (polling), not as offline — offline is what a failed fetch means.

Quick start (WPF)

using Mdh.GraphicsInserts.Auth;
using Mdh.GraphicsInserts.Rendering;
using Mdh.GraphicsInserts.Sync;
using Mdh.GraphicsInserts.Wpf;
using Mdh.GraphicsInserts.Wpf.Controls;

var serverUrl  = "https://inserts.example.com";
var dataDir    = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "MyApp", "inserts");

var tokenStore = new DpapiTokenStore();                     // encrypted per Windows user
var auth       = new OAuthAuthenticator(serverUrl, tokenStore);
var sync       = new SyncClient(
    () => tokenStore.Load(),
    new SnapshotFileCache(dataDir),                          // offline copy of the tree
    outboxStore:  new OutboxFileStore(dataDir),              // edits made while offline
    previewCache: new PreviewFileCache(dataDir));            // preview images

// 1. Sign in through the system browser (PKCE); the token is stored for next time.
if (tokenStore.Load() == null) await auth.SignInAsync();

// 2. Let the operator pick the event this production is linked to.
var events = await sync.ListEventsAsync(serverUrl);
var picker = new EventPickerDialog(events, currentEventId: null);
if (picker.ShowDialog() != true) return;

// 3. Start syncing and show the panel.
await sync.StartAsync(serverUrl, picker.SelectedEvent!.Id);

IInsertRenderer renderer = new MyEngineRenderer();          // see below
var panel = new InsertsPanel
{
    DataContext = new InsertsPanelViewModel(sync, renderer, serverUrl,
        previewSource:   renderer as IInsertPreviewSource,  // optional
        previewUploader: new PreviewUploader(() => tokenStore.Load())),
};

Put panel anywhere in your window — it lays itself out for a narrow dock (editor under the tree) or a wide one (editor beside it).

Implementing the renderer

IInsertRenderer is the whole contract between the library and your engine. An InsertGraphic carries the graphic's scene key and its values as "node/property" → text, exactly as filled in online.

public sealed class MyEngineRenderer : IInsertRenderer, IInsertAirNotifier
{
    public event EventHandler<InsertGraphicAirEventArgs>? TakenLive;

    public Task DrawAsync(InsertGraphic insert, CancellationToken ct = default)
    {
        var scene = Engine.LoadScene(insert.SceneKey);
        foreach (var slot in insert.Values)                  // "text_name/Text" → "Jane Doe"
            scene.Set(slot.Key, slot.Value);
        scene.Prepare();                                     // on preview, not on air
        return Task.CompletedTask;
    }

    public Task TakeInAsync(CancellationToken ct = default)  { Engine.Take();  return Task.CompletedTask; }
    public Task TakeOutAsync(CancellationToken ct = default) { Engine.Clear(); return Task.CompletedTask; }
    public Task ExecuteActionAsync(string action, CancellationToken ct = default)
    {
        Engine.CallAction(action);                           // scene-defined: "next page", "start crawl"…
        return Task.CompletedTask;
    }
}

Optional capabilities, each detected automatically by the panel:

Using the library without the WPF panel

Everything the panel does is available on SyncClient:

sync.UpdateAvailable += (_, e) => /* show "update available (v{e.Snapshot.Version})" */;
sync.SnapshotApplied += (_, e) => RebuildTree(e.Snapshot.Tree);
sync.ApplyPendingUpdate();                                   // the operator's choice

var node = sync.AddInsert(new NewInsertRequest
{
    ParentId = folderId, Name = "Jane Doe", SceneKey = "NameCard",
    Values = new Dictionary<string, string> { ["text_name/Text"] = "Jane Doe" },
});
sync.UpdateInsert(node.Id, new InsertPatch { Values = new Dictionary<string, string> { ["text_role/Text"] = "Referee" } });
sync.MoveInsertUp(node.Id);
await sync.FlushAsync();                                     // or let the client sync in the background

Requirements

• Windows for Mdh.GraphicsInserts.Wpf (.NET Framework 4.8 or .NET 8); Mdh.GraphicsInserts itself runs anywhere .NET Standard 2.0 does.
• An MDH Graphics Inserts account with access to the event.

© MDH Technologies · https://mdh.technology