mcut, open source video editing for agents

Types

SequentialCollageLayout

type SequentialCollageLayout = 'horizontal' | 'vertical' | 'auto'

Slot arrangement for a collage, side by side, stacked, or auto, which stacks landscape videos and places portrait or square videos side by side.

SequentialVideoCollageOptions

interface SequentialVideoCollageOptions {
  assets: readonly AssetRef[]
  layout?: SequentialCollageLayout
  zooms?: readonly number[]
  replaceTimeline?: boolean
  lockTracks?: boolean
  magnetic?: boolean
}

Options for createSequentialVideoCollage, the assets in playback order plus layout, per-video zoom, and track replacement, locking, and magnetic flags.

SequentialVideoCollageResult

interface SequentialVideoCollageResult {
  layout: Exclude<SequentialCollageLayout, 'auto'>
  totalDurationMs: number
  groupIds: GroupId[]
  visualTrackIds: `t-${string}`[]
  activeVideoElementIds: `e-${string}`[]
  freezeElementIds: `e-${string}`[]
  audioElementIds: `e-${string}`[]
  trackIds: `t-${string}`[]
  videoElementIds: `e-${string}`[]
}

The ids and layout produced by a collage build, including group, track, active video, freeze, and audio element ids.

TextPreset

interface TextPreset {
  name: string
  text: string
  durationMs: number
  style: Partial<TextStyle>
  y?: number
}

A named text style bundle with default text, duration, style overrides, and an optional vertical offset.

AutoCrossfadePlanInput

interface AutoCrossfadePlanInput {
  elementId: ElementId
  desiredStartMs: number
  minAttemptedOverlapMs?: number
  maxAttemptedOverlapMs?: number
  minDurationMs?: number
  maxDurationMs?: number
  transitionType?: TransitionType
}

Input for planAutoCrossfade, the dragged element, its desired start, overlap and duration limits, and the transition type.

ClipDragBase

interface ClipDragBase {
  startMs: number
  durationMs: number
  trimStartMs?: number
  reversed?: boolean
  hasTimeMap?: boolean
  trackIndex: number
}

The state of one clip when a drag starts.

ClipDragMode

type ClipDragMode =
  | 'move'
  | 'trim-start'
  | 'trim-end'
  | 'ripple-start'
  | 'ripple-end'
  | 'roll-start'
  | 'roll-end'
  | 'slip'
  | 'slide'

The drag tools a clip gesture can perform.

DuplicateClipsToNewTracksOptions

interface DuplicateClipsToNewTracksOptions {
  createTrackId?: () => Track['id']
  createElementId?: () => ElementId
}

Optional id factories for the tracks and elements created by planDuplicateClipsToNewTracks.

DuplicateClipsToNewTracksPlan

interface DuplicateClipsToNewTracksPlan {
  commands: BuiltinCommand[]
  ids: ElementId[]
  createdTrackIds: Track['id'][]
}

The commands, new element ids, and new track ids produced by planDuplicateClipsToNewTracks.

ResolvedClipDragMode

interface ResolvedClipDragMode {
  mode: ClipDragMode
  rollTargetId: ElementId | null
}

The drag mode after fallback, with the id of the clip whose edge rolls or null.

ZoomRegionDragMode

type ZoomRegionDragMode = 'move' | 'start' | 'in' | 'out' | 'end'

The part of a zoom region a drag moves. move shifts the whole zoom. start moves the start and gives the difference to the hold, so the end stays put. in and out move the inner edge of a ramp and trade time with the hold. end lengthens or shortens the hold.

ZoomShape

ZoomShape is Pick<ZoomRegion, 'scale' | 'inMs' | 'holdMs' | 'outMs' | 'easing'>, an explicit zoom that planZoomAtPlayhead places instead of a preset. Studio builds one from each saved zoom template.

SilenceCutOptions

type SilenceCutOptions = z.infer<typeof silenceCutOptionsSchema>

Thresholds for planSilenceCuts as inferred from silenceCutOptionsSchema, the minimum gap, padding around cuts, minimum kept speech, and whether to trim both ends.

SilenceCutPlan

interface SilenceCutPlan {
  silences: SilenceWindow[]
  commands: BuiltinCommand[]
  removedMs: number
  project: Project
}

The silences cut, the commands applied in order, the total removed time, and the resulting project.

SilenceCutTranscript

interface SilenceCutTranscript {
  words: Array<{ startMs: number; endMs: number }>
}

The word timings planSilenceCuts reads, in source media time.

SilenceWindow

interface SilenceWindow {
  startMs: number
  endMs: number
}

A span of source media time.

LintIssue

interface LintIssue {
  severity: 'error' | 'warning'
  code: string
  message: string
}

One finding from lintProject, with a severity, a code such as missing-asset or empty-track, and a message naming the offending track or element.

PlatformPreset

interface PlatformPreset {
  id: string
  label: string
  width: number
  height: number
  fps: number
  safeArea: { top: number; bottom: number }
  notes: string
}

A delivery target's canvas size, frame rate, the fractions of frame height covered by platform chrome at the top and bottom, and notes on how to use it.

CenterPersonOptions

type CenterPersonOptions = z.infer<typeof centerPersonOptionsSchema>

Options for planCenterPerson as inferred from centerPersonOptionsSchema, the output aspect, how calmly the framing follows the face, and whether a video fills the frame.

FaceSample

FaceSample is { sourceMs, box }, one face reading at a source media time. box is the face as { x, y, w, h } fractions of the source frame, or null when the sample found none. detect from createLocalFaceDetector in @mcut/media returns this shape.

Schemas

silenceCutOptionsSchema

const silenceCutOptionsSchema = z.object({
  minGapMs: z
    .number()
    .nonnegative()
    .optional()
    .describe('Word gaps shorter than this are speech rhythm, not silence. Default 600.'),
  paddingMs: z
    .number()
    .nonnegative()
    .optional()
    .describe('Breathing room kept on each side of a cut. Default 120.'),
  minKeepMs: z
    .number()
    .nonnegative()
    .optional()
    .describe('Speech chunks shorter than this merge into the surrounding cut. Default 250.'),
  trimEnds: z
    .boolean()
    .optional()
    .describe('Also cut silence before the first and after the last word. Default true.'),
})

Zod schema for SilenceCutOptions, which the apply_silence_cuts MCP tool extends for its input.

centerPersonOptionsSchema

Field	Type	Meaning
`aspect`	positive number, default 9/16	Output width over height. A video crops to it, and a multicam ignores it
`smoothing`	0 to 1, default 0.5	How calmly the framing follows the face, from 0 for a tight follow to 1 for a steady frame
`fill`	optional boolean	Video only. `true` scales the clip to fill the frame and centers it, and `false` keeps its size. Unset, it fills only when the crop aspect is within 1% of the project aspect

Zod schema for CenterPersonOptions. The center_person MCP tool spreads its shape into its input.

Types

On this page