Skip to main content

Use an exported graphic on a website

The reusable packages/ograf-web-player/ograf-player.js browser module plays an actual exported OGraf graphic inside a page. Export a certified single graphic or coordinated package, extract the .ograf.zip into a website folder, and serve its manifest, JavaScript and assets over HTTP(S) with their paths intact. Copy the player module to the website and use the manifest URL; Studio and its MCP server are not required by the published page. packages/ograf-web-player/demo.html is a small example of website controls. See the player package README for integration and the JavaScript API.

For coordinated packages, use the exported manifest's declared custom actions and data schema to control lanes. The player hosts the coordinator as one graphic. The module does not read .ogs documents or directly extract ZIP files. A web server must provide suitable MIME types, and cross-origin files require explicit permission and appropriate CORS headers.

OGraf graphics contain executable JavaScript. Only load trusted packages on the same website origin; the player is not a security sandbox. If accepting untrusted packages, use a separately isolated origin and narrowly scoped communication. Playback also depends on browser support and permissions for features such as WebGL, audio, webcam and external data. Validate the real hosted package in the target browser before publishing a tutorial.

Find a layer by export key​

Select a layer and set Export key in Properties to give it a stable identifier in an export. Use up to 64 letters, digits, underscores or hyphens, starting with a letter. Keys are case sensitive and unique within each template. Renaming or moving the layer keeps its key, and duplicating it leaves the new layer's key blank.

JavaScript with access to the exported web component can look up a layer on a live instance. The same lookup works for a single graphic or a coordinated set.

const scoreline = graphic.instances[instanceId]?.layers['scoreline'];

Object.values(graphic.instances) lists the current instances. A single graphic has one entry after load. Coordinated entries include templateId and laneId to identify the mounts that are on air, including overlapping graphics during transitions. Read the map again after a transition. Use the graphic's data fields and OGraf updateAction() to change values during playout. Re-export a previously exported package to use the shared instance lookup.

Receive a frame cue during playback​

Move the playhead to the desired frame and choose + Cue in the Timeline. Set the cue's name, frame, and optional JSON payload, then click Apply. Select its marker to edit or delete it.

Open Frame Cue Log in Studio's Preview & Export pane and take the graphic in or out. In an exported preview page, press D to show the controls and open the same section. The log records the 20 most recent cues during real-time playback, including their authored frames, instance IDs, and any payload. Coordinated cues also show their lane and template IDs. The count updates while the section is collapsed. Use Clear to start a fresh log. Re-export an existing preview page to include the panel.

The graphic dispatches ograf-studio-cue on forward real-time playback. The event detail contains the cue's id, name, frame, instanceId, and optional payload. A coordinated cue also includes templateId and laneId. The frame is on the template's authored timeline.

graphic.addEventListener('ograf-studio-cue', ({ detail }) => {
  if (detail.name === 'score-revealed') {
    const scoreline = graphic.instances[detail.instanceId]?.layers['scoreline'];
    console.log(scoreline, detail.payload);
  }
});

Each cue fires once when playback crosses its frame, even if the browser misses a display frame. Playback from Start includes a cue on frame zero. Take Out fires cues in the portion of the Out phase that plays. In coordinated sets, cues follow phases that play the template's authored animation. Scrubbing, reverse playback, skips and non-real-time frame renders stay silent. A host in a separate renderer or cross-origin iframe needs a bridge to receive the event.