Markers
Named points and spans on the timeline, for chapters, steps and notes.
Coming in the next release
Markers are built and tested in @miraiclip/core and @miraiclip/editor, and ship in the next SDK release.
project.dispatch({ type: "marker/add", payload: { id: "intro", timeUs: 0, label: "Intro" } });
project.dispatch({
type: "marker/add",
payload: { id: "step-1", timeUs: 6_000_000, label: "Open settings", data: { kind: "step", selector: "#settings" } },
});A marker is a named point on the timeline, or a span if it has a durationUs. Markers don't render. Other parts of Miraiclip read them:
| Reader | Uses markers as |
|---|---|
<miraiclip-player> | Chapters in the scrubber and chapter menu |
| Screen recordings | Tutorial steps: guide sections, narration lines, callouts |
describeProject | Part of the project summary an AI agent reads |
| Your UI | Flags on the ruler, review notes, sections |
Markers live in doc.markers, are saved with the document and are undoable like any edit.
The marker
| Field | Meaning |
|---|---|
id | Unique id |
timeUs | Timeline position |
label | Display name |
durationUs | Optional span length |
data | Optional free-form JSON, for whoever placed the marker |
Commands
| Command | Payload |
|---|---|
marker/add | { id?, timeUs, label, durationUs?, data? } |
marker/update | { markerId, timeUs?, label?, durationUs?, data? }. null for durationUs or data removes it. data is replaced, not merged |
marker/remove | { markerId } |
marker/update and marker/remove reject with marker-not-found for an unknown id.
Markers stay where they are when clips move. A ripple edit doesn't shift them, so move them with marker/update if they belong to a clip.
Read markers
import { listMarkers, markerChapters, markersInRange } from "@miraiclip/core";
const doc = project.getState().doc;
listMarkers(doc); // every marker, in time order
markersInRange(doc, 0, 10_000_000); // markers that touch [0 s, 10 s)
markerChapters(doc); // [{ id, label, startUs, endUs, data? }]markerChapters turns markers into chapters. Each chapter lasts its marker's durationUs, or else until the next marker. The last one runs to the end of the composition.
In an editor
import { createCommands } from "@miraiclip/editor";
const commands = createCommands(project);
commands.addMarker({ timeUs: project.getState().playheadUs, label: "Review this" });
commands.updateMarker("step-1", { label: "Open the settings page" });
commands.removeMarker("step-1");