Headless editor logic

@miraiclip/editor is the logic behind an editor UI, with no framework. The React package and its components build on it, and you can use it directly from vanilla JS, Vue or Svelte. Everything except the media-import helpers runs without a DOM, so it works in Node and tests too.

npm install @miraiclip/core @miraiclip/editor

Timeline geometryCopy Anchor Link

SelectorsCopy Anchor Link

Results are cached per document object. The core replaces doc.clips only on an edit, so during playback these are lookups, not scans.

Dragging and trimming clipsCopy Anchor Link

beginClipDrag(project, clipId, mode, options) handles a move ("move") or a trim ("trim-start", "trim-end"). You feed it pointer movement; it returns where the clip would land, and dispatches one clip/move or clip/trim when you commit.

import type { Clip, Project, ProjectDocument } from "@miraiclip/core";
import { beginClipDrag, clipsByTrack, isTrackFree, pxToUs, usToPx } from "@miraiclip/editor";

export { usToPx };

/** The clips on one track, in time order. */
export function clipsOnTrack(doc: ProjectDocument, trackId: string): Clip[] {
  return clipsByTrack(doc.clips).get(trackId) ?? [];
}

/**
 * Drag a clip along its track. The element follows the pointer, snapping to
 * clip edges, 0 and the playhead; one `clip/move` is dispatched on release,
 * and only when the new range is free. Clips on locked tracks don't move.
 */
export function dragClip(
  project: Project,
  clipId: string,
  el: HTMLElement,
  down: { pointerId: number; clientX: number },
  pxPerSecond: number,
) {
  const drag = beginClipDrag(project, clipId, "move", { snapThresholdUs: pxToUs(8, pxPerSecond) });
  if (!drag) return;
  const fromUs = drag.preview.startUs;

  const onMove = (e: PointerEvent) => {
    const { startUs } = drag.update(pxToUs(e.clientX - down.clientX, pxPerSecond));
    el.style.translate = `${usToPx(startUs - fromUs, pxPerSecond)}px 0`;
  };
  const onUp = () => {
    el.removeEventListener("pointermove", onMove);
    el.style.translate = "";
    const { trackId, startUs, durationUs } = drag.preview;
    if (isTrackFree(project.getState().doc, trackId, startUs, startUs + durationUs, clipId)) drag.commit();
  };

  el.setPointerCapture(down.pointerId);
  el.addEventListener("pointermove", onMove);
  el.addEventListener("pointerup", onUp, { once: true });
  el.addEventListener("pointercancel", onUp, { once: true });
}

Track cutsCopy Anchor Link

Added in 0.2.0. trackCuts(clips, transitions?) lists the cuts on one track: places where one visual clip ends exactly where the next starts, which is where a transition can go. Pass one track's start-sorted clips (a list from clipsByTrack) and its transitions (from transitionsByTrack).

import { clipsByTrack, trackCuts, transitionsByTrack } from "@miraiclip/editor";

const { doc } = project.getState();
const cuts = trackCuts(clipsByTrack(doc.clips).get("main") ?? [], transitionsByTrack(doc.transitions).get("main"));
for (const { from, to, atUs, transition } of cuts) {
  console.log(`${from.id} → ${to.id} at ${atUs} µs`, transition ? transition.kind : "no transition");
}

Core's findCuts(doc) covers the whole project and adds each cut's longest allowed transition; trackCuts is the cheap per-track version a timeline draws from. <Timeline.Cuts> uses it.

Preview transformsCopy Anchor Link

Added in 0.2.0. Move, scale and rotate a clip on the preview by dragging. The geometry works in composition pixels, from the bounds the preview reports (getClipBounds or hitTest on the preview controller).

import { beginTransformDrag } from "@miraiclip/editor";

// `bounds`: controller.getClipBounds(clipId). `start`: the pointer, in composition px.
const drag = beginTransformDrag(project, bounds, "move", start, { snapThresholdPx: 6 / scale });
if (drag) {
  // On each pointer move: applies the edit live and returns the snap lines to draw.
  const guides = drag.update(pointer, { altKey: event.altKey, shiftKey: event.shiftKey });
  // On release: the whole drag is one undo step.
  drag.end();
}

beginTransformDrag returns null for a clip that can't be transformed (missing, audio, or on a locked track). dragThresholdPx makes small movements a click: drag.moved stays false and nothing is written.

<TransformBox.*> is the React component built on these.

Commands and gesturesCopy Anchor Link

createCommands(project) returns typed builders for every built-in command, so UI code never writes raw command objects:

import { createCommands } from "@miraiclip/editor";

const commands = createCommands(project);
commands.splitClip("intro", 2_000_000);
commands.setClipProperty("title", { text: "Hello", color: "#ffffff" });

beginGesture(project, label) turns a continuous edit (a canvas drag, a slider) into one history entry. Each update(apply) replaces the previous one, and end() finishes. If anything else touches history mid-gesture, the next update starts a new entry instead of undoing someone else's.

ShortcutsCopy Anchor Link

import { matchEditorShortcut, runEditorAction } from "@miraiclip/editor";
import { project } from "./project";

// Delete / Backspace, S (split at the playhead), ⌘/Ctrl+Z, ⇧⌘/Ctrl+Shift+Z or Ctrl+Y.
// Delete and split act on every selected clip on an unlocked track, as one undo step.
window.addEventListener("keydown", (e) => {
  const el = e.target as HTMLElement;
  if (el.isContentEditable || ["INPUT", "TEXTAREA", "SELECT"].includes(el.tagName)) return;
  const action = matchEditorShortcut(e);
  if (action && runEditorAction(project, action)) e.preventDefault();
});

import { createProject } from "@miraiclip/core";

// One project instance for the whole app. Pass it to components as a prop.
export const project = createProject({ width: 1280, height: 720, fps: 30 });

matchEditorShortcut(event) only maps keys, so you can rebind them or add your own before calling runEditorAction.

Placing assetsCopy Anchor Link

Both select the new clip and return its id, or null when nothing was placed.

Importing mediaCopy Anchor Link

Added in 0.1.1. probeMediaFile(file) reads a picked or dropped file in the browser: its kind, duration, size and a thumbnail, with an object URL as src. isSourceReachable(src) tells whether a saved project's media can still be fetched.

import { placeAssetAtPlayhead, probeMediaFile } from "@miraiclip/editor";
import { project } from "./project";

/** Probe a picked or dropped file, register it, and place it at the playhead. */
export async function importFile(file: File): Promise<string | null> {
  const media = await probeMediaFile(file); // null for anything but video, audio, images
  if (!media) return null;
  const assetId = crypto.randomUUID();
  project.transaction(() => {
    project.dispatch({
      type: "asset/add",
      payload: {
        id: assetId,
        kind: media.kind,
        src: media.src, // an object URL: upload the file and use your own URL to keep it across reloads
        durationUs: media.durationUs,
        ...(media.width ? { width: media.width, height: media.height } : {}),
        name: file.name,
      },
    });
    placeAssetAtPlayhead(project, assetId);
  }, "import");
  return assetId;
}

import { createProject } from "@miraiclip/core";

// One project instance for the whole app. Pass it to components as a prop.
export const project = createProject({ width: 1280, height: 720, fps: 30 });

For codec checks before import, use the renderer's demuxer instead (see Asset import).

FramingCopy Anchor Link

ASPECT_PRESETS lists common output sizes. fillScale(asset, settings) is the scale that makes a clip cover the frame, and refillForAspect(doc, nextSize) lists the clips to rescale so filled clips stay filled after an aspect change.