mcut, open source video editing for agents

Types

TranscribeInput

interface TranscribeInput {
  audio: Blob | ArrayBuffer | Uint8Array | string
  mimeType?: string
}

Audio handed to a provider as a blob, buffer, byte array, or URL string, with an optional MIME type.

TranscribeOptions

interface TranscribeOptions {
  language?: string
  vocabulary?: readonly string[]
  signal?: AbortSignal
}

Per-call transcription options, a language hint, names and terms to spell right, and an abort signal. Providers that take no hints ignore vocabulary.

TranscriptionProvider

interface TranscriptionProvider {
  readonly id: string
  transcribe(input: TranscribeInput, options?: TranscribeOptions): Promise<TranscriptResult>
}

A transcription backend with an id and a transcribe method that returns a normalized TranscriptResult.

TranscriptResult

interface TranscriptResult extends z.infer<typeof transcriptResultSchema> {}

Normalized transcription output as inferred from transcriptResultSchema, with full text, optional language and duration, timed words, and timed segments.

TranscriptSegment

interface TranscriptSegment extends z.infer<typeof transcriptSegmentSchema> {}

A timed span of transcript text with text, startMs, endMs, and an optional speaker label.

TranscriptWord

interface TranscriptWord extends z.infer<typeof transcriptWordSchema> {}

One timed word with text, startMs, endMs, and optional confidence and speaker fields.

SubtitleCue

interface SubtitleCue {
  startMs: number
  endMs: number
  text: string
}

A subtitle cue with start and end in milliseconds and its text.

BuildApplyCaptionsOptions

interface BuildApplyCaptionsOptions extends ToCaptionElementsOptions {
  trackId?: TrackId
  replace?: boolean
}

Options for buildApplyCaptionsCommand, adding a target track id and a replace flag to ToCaptionElementsOptions.

CaptionElementInput

interface CaptionElementInput {
  type: 'caption'
  startMs: number
  durationMs: number
  text: string
  words?: CaptionWord[]
  style?: Partial<CaptionStyle>
}

A caption element without an id, ready for insertion through the applyCaptions command.

GroupWordsOptions

interface GroupWordsOptions {
  maxChars?: number
  maxDurationMs?: number
  maxGapMs?: number
}

Limits for groupWords, maximum characters, maximum duration, and maximum silent gap per group.

ToCaptionElementsOptions

interface ToCaptionElementsOptions extends GroupWordsOptions {
  style?: Partial<CaptionStyle>
  timeOffsetMs?: number
  sourceStartMs?: number
  sourceEndMs?: number
}

Options for toCaptionElements, adding a caption style, a time offset, and a source range to GroupWordsOptions.

WordGroup

interface WordGroup {
  text: string
  startMs: number
  endMs: number
  words: TranscriptWord[]
}

A run of consecutive words with joined text and the span they cover.

CaptionContentPatch

interface CaptionContentPatch {
  captionId: string
  text: string
  words?: CaptionWord[]
}

A computed caption text and words change for one caption, ready for an updateElement patch.

CaptionMergeResult

interface CaptionMergeResult {
  startMs: number
  durationMs: number
  text: string
  words?: CaptionWord[]
}

The merged caption produced by mergeCaptions, with start, duration, text, and optional words.

CaptionCorrectionPatch

interface CaptionCorrectionPatch extends CaptionContentPatch {
  startMs: number
  durationMs: number
}

One caption changed by correctCaptions, with its new position, since a match across two captions moves the boundary between them.

TranscriptCorrection

interface TranscriptCorrection {
  patches: CaptionCorrectionPatch[]
  removedIds: string[]
  count: number
}

The result of correctCaptions, with the captions to update, the captions to remove, and the number of matches replaced.

CaptionSplitResult

interface CaptionSplitResult {
  left: { text: string; words: CaptionWord[]; durationMs: number }
  right: {
    startMs: number
    durationMs: number
    text: string
    words: CaptionWord[]
  }
}

The two halves produced by splitCaptionAtWord, each with text, words, and duration.

MappedWord

interface MappedWord {
  word: CaptionWord
  startChar: number
  endChar: number
}

A caption word together with the character range it occupies in the caption text.

TranscriptCaption

interface TranscriptCaption {
  id: string
  startMs: number
  durationMs: number
  text: string
  words?: CaptionWord[]
}

The caption element shape the transcript tools operate on, with word timings relative to startMs.

TranscriptSearchResult

interface TranscriptSearchResult {
  query: string
  count: number
  matches: TranscriptSearchMatch[]
}

TranscriptSearchMatch

interface TranscriptSearchMatch {
  text: string
  startMs: number
  endMs: number
  before: string
  after: string
  pauseBeforeMs: number | null
  pauseAfterMs: number | null
  captionId: string
  trackId: string
  trackName: string
}

startMs and endMs are timeline ms. pauseBeforeMs and pauseAfterMs are the gaps to the neighboring words on the same track, or null at either end of it.

TranscriptMatch

interface TranscriptMatch {
  captionId: string
  startChar: number
  endChar: number
  firstWord?: number
  lastWord?: number
  timeMs: number
  endTimeMs: number
}

A search hit inside one caption with its character range, the mapped word span when available, and absolute start and end times.

CaptionsCommandOptions

type CaptionsCommandOptions = z.infer<typeof captionsCommandOptionsSchema>

Options for buildCaptionsCommand as inferred from captionsCommandOptionsSchema.

Schemas

transcriptResultSchema

const transcriptResultSchema = z.object({
  text: z.string(),
  language: z.string().optional(),
  durationMs: z.number().optional(),
  words: z.array(transcriptWordSchema),
  segments: z.array(transcriptSegmentSchema),
})

Zod schema for a TranscriptResult, where each word has text, startMs, endMs, and optional confidence and speaker, and each segment has text, startMs, endMs, and optional speaker.

transcriptInputSchema

const transcriptInputSchema = transcriptResultSchema.extend({
  text: z.string().default(''),
  words: z.array(transcriptWordSchema).default([]),
  segments: z.array(transcriptSegmentSchema).default([]),
})

Zod schema for a transcript arriving from a file or an MCP tool call, where text, words, and segments may be omitted and default to empty.

captionsCommandOptionsSchema

const captionsCommandOptionsSchema: z.ZodType<CaptionsCommandOptions>

Zod object schema for CaptionsCommandOptions, shared by the CLI captions command and the apply_captions MCP tool, with five optional fields.

Field	Meaning
`elementId`	Scope the transcript to one clip with source audio, including a multicam audio source, and position captions at its timeline location. Without it the transcript starts at timeline 0.
`styleId`	A preset id from `CAPTION_STYLE_PRESETS`, such as `classic`, `karaoke`, or `spotlight`.
`maxChars`	Soft maximum characters per caption, a positive integer, default 36.
`maxGapMs`	A silence gap longer than this starts a new caption, default 800.
`replace`	Clear existing captions on the target track first.

RetakeCandidate

RetakeCandidate has startMs and endMs in the input word times, the abandonedText to cut, the opening keptText of the take that stays, and matchedWords.

RetakeOptions

RetakeOptions is z.input<typeof retakeOptionsSchema>, every field optional.

Types

On this page