@pixerate/editor 0.84.0 → 0.86.0

package/dist/video-editor/index.d.cts

@@ -92,6 +92,12 @@ declare function videoKeyframeFfmpegExpr(prop: VideoAnimatable | undefined, time
  */
 
 type VideoAssetKind = 'video' | 'audio' | 'image';
+/** A spoken word in an asset's transcript, timed in the source (ms). */
+interface VideoTranscriptWord {
+    word: string;
+    start: number;
+    end: number;
+}
 /** A piece of source media. The project refers to it by id; `src` is whatever the host can load. */
 interface VideoAsset {
     id: string;
@@ -108,6 +114,8 @@ interface VideoAsset {
     hasAudio?: boolean;
     /** A still to show for a video where its frames cannot be drawn (SVG renders, thumbnails). */
     poster?: string;
+    /** What is said in it, word by word, timed in the source (see `parseVideoTranscript`). */
+    transcript?: VideoTranscriptWord[];
 }
 type VideoTrackKind = 'video' | 'audio';
 interface VideoTrack {
@@ -260,6 +268,13 @@ interface VideoMediaClip extends VideoClipBase {
     in?: number;
     /** Playback speed (default 1): it uses `duration × speed` of the source. */
     speed?: number;
+    /**
+     * A speed ramp: keys mapping clip time to source time after the in point (`v` ms from `in`), so
+     * a key's slope is the speed there, a flat stretch is a freeze frame and eased keys ramp between
+     * speeds. Never runs backwards. Before the first key and after the last the picture holds. Takes
+     * the place of `speed` (see `videoSpeedRampKeys` for building one from speeds).
+     */
+    timeRemap?: VideoKeyframes;
     /** Gain (1 = unchanged, default 1), or keyframes. */
     volume?: VideoAnimatable;
     /** Silences this clip. */
@@ -336,9 +351,11 @@ declare function parseVideoAnimatable(v: unknown, path: string, range?: {
     optional?: boolean;
 }): VideoAnimatable | undefined;
 declare function parseVideoTransform(v: unknown, path: string): VideoTransform | undefined;
+declare function parseVideoTimeRemap(v: unknown, speed: unknown, path: string): VideoKeyframes | undefined;
 declare function parseVideoClipAnimation(v: unknown, path: string): VideoClipAnimation | undefined;
 declare function parseVideoGrade(v: unknown, path: string): VideoGrade | undefined;
 declare function parseVideoTransition(v: unknown, path: string): VideoTransition | undefined;
+declare function parseVideoTranscriptWords(v: unknown, path: string): VideoTranscriptWord[] | undefined;
 declare function parseVideoAsset(v: unknown, path?: string): VideoAsset;
 declare function parseVideoClip(v: unknown, path?: string): VideoClip;
 declare function parseVideoTrack(v: unknown, path?: string): VideoTrack;
@@ -626,6 +643,18 @@ type VideoEdit = ({
     clip: string;
     property: VideoKeyframeProperty;
     keys: VideoKey[] | null;
+}
+/**
+ * A speed ramp: keys mapping clip time to source ms after the in point (see `timeRemap`), or
+ * null to play at normal speed from where the ramp started. `duration` sets the clip's new length
+ * (default: unchanged); `ripple` moves later material with the change.
+ */
+ | {
+    op: 'set_time_remap';
+    clip: string;
+    keys: VideoKey[] | null;
+    duration?: number;
+    ripple?: boolean;
 } | {
     op: 'close_gaps';
     track: string;
@@ -1028,6 +1057,141 @@ declare function videoClipAnimationSpans(clip: VideoClip): {
  */
 declare function videoClipAnimated(clip: VideoClip, project: Pick<VideoProject, 'width' | 'height'>): VideoClip;
 
+/**
+ * A transcript from text a speech-to-text service or captioning tool wrote: Whisper-style JSON
+ * (`{ segments: [{ words: [{ word, start, end }] }] }` or `{ words: [...] }`, times in seconds, or a
+ * plain `[{ word, start, end }]` array in ms), SubRip (`.srt`) or WebVTT. Captions have no word
+ * timings, so their words are spread evenly across each cue (`approximate: true`). Throws when it
+ * finds no words.
+ */
+declare function parseVideoTranscript(input: string | unknown): {
+    words: VideoTranscriptWord[];
+    approximate: boolean;
+};
+/** A word where it plays on the timeline. */
+interface VideoTimelineWord {
+    word: string;
+    /** Timeline times (ms). */
+    start: number;
+    end: number;
+    /** The clip that plays it. */
+    clip: string;
+    track: string;
+    /** Its index in the asset's transcript. */
+    index: number;
+}
+/**
+ * The track whose words make the timeline transcript: `track` if given, else the first audio track
+ * with a transcribed clip, else the first video track with one. `null` when nothing is transcribed.
+ */
+declare function videoTranscriptTrack(project: VideoProject, track?: string): string | null;
+/**
+ * The words the timeline plays on one track, in order: each transcribed media clip's words whose
+ * middle falls inside the stretch of source it plays, moved to timeline time through its in point
+ * and speed and clamped to the clip.
+ */
+declare function videoTimelineTranscript(project: VideoProject, options?: {
+    track?: string;
+}): VideoTimelineWord[];
+/** A stretch of the timeline (ms) and the words in it. */
+interface VideoTranscriptRange {
+    from: number;
+    to: number;
+    text: string;
+}
+/** A word as compared: lower case, without surrounding punctuation. */
+declare const normalizeVideoWord: (word: string) => string;
+/** Every place a phrase is said (case and punctuation ignored), as timeline ranges. */
+declare function findVideoTranscriptText(words: readonly VideoTimelineWord[], query: string): VideoTranscriptRange[];
+/** Filler words and phrases removed by default. "like" and "so" are left out: too often meant. */
+declare const VIDEO_DEFAULT_FILLERS: readonly ["um", "umm", "uh", "uhh", "uhm", "erm", "er", "ah", "hmm", "mm", "you know", "i mean"];
+/** Fillers in the transcript, longest phrase first ("you know" before "you"), as timeline ranges. */
+declare function findVideoFillers(words: readonly VideoTimelineWord[], fillers?: readonly string[]): VideoTranscriptRange[];
+interface VideoPauseOptions {
+    /** Shortest gap between words that counts as a pause (ms, default 700). */
+    min?: number;
+    /** Silence to keep next to each word so speech does not sound clipped (ms, default 150). */
+    keep?: number;
+    /** Frame rate to snap the cut inward to (default: none). */
+    fps?: number;
+}
+/** Gaps between consecutive words on the same clip longer than `min`, less `keep` either side, as timeline ranges. */
+declare function findVideoTranscriptPauses(words: readonly VideoTimelineWord[], options?: VideoPauseOptions): VideoTranscriptRange[];
+/** Ranges sorted and merged where they touch or overlap. */
+declare function mergeVideoRanges(ranges: readonly {
+    from: number;
+    to: number;
+}[]): {
+    from: number;
+    to: number;
+}[];
+/**
+ * The edits that cut ranges out of the timeline and close them up: one `extract_range` per merged
+ * range, last first, so earlier ranges keep their times. Apply them together as one undo step.
+ */
+declare function videoRemoveRangesEdits(ranges: readonly {
+    from: number;
+    to: number;
+}[], tracks?: string[]): VideoEdit[];
+/** The timeline stretch from word `a` to word `b` (either order), for deleting a selection of words. */
+declare function videoWordsRange(words: readonly VideoTimelineWord[], a: number, b: number): {
+    from: number;
+    to: number;
+};
+/** The edit that attaches a transcript file's text to an asset (see `parseVideoTranscript`). Throws a readable error for text it cannot read. */
+declare function videoTranscriptEdit(assetId: string, text: string): VideoEdit;
+/** The word playing at a timeline time, as its index in `words`, or -1. */
+declare function videoWordAt(words: readonly VideoTimelineWord[], time: number): number;
+
+/**
+ * Speed ramps and freeze frames: a media clip's `timeRemap` keys map clip time to source time after
+ * its in point. The slope between two keys is the speed there; equal values are a freeze; an eased
+ * segment changes speed smoothly. These helpers read and build them.
+ */
+/** Where in the source (ms) a media clip is at clip time `clipTime`, through its speed or its ramp. */
+declare function videoClipSourceTime(clip: VideoMediaClip, clipTime: number): number;
+/** The speed a media clip plays at at clip time `clipTime` (0 in a freeze), measured over a millisecond. */
+declare function videoClipSpeedAt(clip: VideoClip, clipTime: number): number;
+/** One stretch of a ramp: `duration` ms of the clip at `speed`, or easing from `speed` to `toSpeed`. 0 is a freeze. */
+interface VideoSpeedSegment {
+    duration: number;
+    speed: number;
+    /** Ramp smoothly to this speed by the end of the stretch (default: stay at `speed`). */
+    toSpeed?: number;
+}
+/**
+ * Remap keys for stretches of speed, from the clip's start: steady stretches are linear segments,
+ * ramps a cubic-bezier ease that changes the speed evenly from one to the other (the source moves
+ * the average of the two speeds over the stretch). Returns the keys and the source the clip plays.
+ */
+declare function videoSpeedRampKeys(segments: readonly VideoSpeedSegment[]): {
+    keys: VideoKey[];
+    duration: number;
+    source: number;
+};
+/**
+ * Checks remap keys: in time order and never going back in the source, eased segments included
+ * (each is sampled, so a curve that overshoots and would play backwards is caught). Throws a
+ * readable error.
+ */
+declare function checkVideoTimeRemap(remap: VideoKeyframes, path?: string): void;
+/** The stretch of source (ms, from the in point) a ramp plays: from its first key's value to its last's. */
+declare function videoTimeRemapSpan(remap: VideoKeyframes): {
+    from: number;
+    to: number;
+};
+/** Clip time and source time pairs tracing a ramp as straight lines (eased stretches sampled every `step` ms), with freezes marked. */
+declare function videoTimeRemapBreakpoints(remap: VideoKeyframes, step: number): {
+    t: number;
+    v: number;
+}[];
+/** The edit that plays a media clip through stretches of speed from the moment it shows at its start (see `videoSpeedRampKeys`). */
+declare function videoSpeedRampEdit(clip: VideoMediaClip, segments: readonly VideoSpeedSegment[], ripple?: boolean): VideoEdit;
+/** The edit that holds the frame a media clip shows at clip time `at` for `duration` ms, then plays on (the clip gets longer). */
+declare function videoFreezeFrameEdit(clip: VideoMediaClip, at: number, duration: number, ripple?: boolean): VideoEdit;
+/** A slow-motion ramp preset for a clip of `duration` ms: normal speed for half of it, a 500 ms glide down to 0.3×, then 1.5 s at 0.3×. */
+declare const videoSlowMotionRamp: (duration: number) => VideoSpeedSegment[];
+
 /** Radius of an iris `progress` (0–1) open: from nothing to the frame's corners. */
 declare const videoIrisRadius: (frame: {
     width: number;
@@ -1426,7 +1590,28 @@ interface VideoEditorToolProviderOptions {
 }
 /** A project as agents see it: settings, assets, and each track's clips in order with their times. */
 declare function describeVideoProject(project: VideoProject): {
-    assets: VideoAsset[];
+    assets: ({
+        id: string;
+        kind: VideoAssetKind;
+        src: string;
+        name?: string;
+        duration?: number;
+        width?: number;
+        height?: number;
+        hasAudio?: boolean;
+        poster?: string;
+    } | {
+        transcriptWords: number;
+        id: string;
+        kind: VideoAssetKind;
+        src: string;
+        name?: string;
+        duration?: number;
+        width?: number;
+        height?: number;
+        hasAudio?: boolean;
+        poster?: string;
+    })[];
     tracks: {
         clips: ({
             source?: {
@@ -1438,6 +1623,7 @@ declare function describeVideoProject(project: VideoProject): {
             asset: string;
             in?: number;
             speed?: number;
+            timeRemap?: VideoKeyframes;
             volume?: VideoAnimatable;
             muted?: boolean;
             fadeInCurve?: VideoFadeCurve;
@@ -1655,4 +1841,4 @@ declare function videoKeyframeValueEdit(project: VideoProject, clipId: string, p
  */
 declare function videoKeyframeToggleEdit(project: VideoProject, clipId: string, property: VideoKeyframeProperty, time: number): VideoEdit | null;
 
-export { type CreateVideoProjectOptions, type NewVideoClip, VIDEO_BLEND_MODES, VIDEO_BLEND_MODE_LABELS, VIDEO_CLIP_ANIMATION_DURATION, VIDEO_CLIP_ANIMATION_EFFECTS, VIDEO_CLIP_ANIMATION_LABELS, VIDEO_CLIP_TYPES, VIDEO_DEFAULT_STILL_DURATION, VIDEO_DEFAULT_TITLE_DURATION, VIDEO_EASE_NAMES, VIDEO_EDIT_OPS, VIDEO_FADE_CURVES, VIDEO_FADE_CURVE_LABELS, VIDEO_FITS, VIDEO_GRADE_CONTROLS, VIDEO_GRADE_PRESETS, VIDEO_GRADE_PRESET_NAMES, VIDEO_ISSUE_CODES, VIDEO_KEYFRAME_LIMITS, VIDEO_KEYFRAME_PROPERTIES, VIDEO_PEAK_BLOCK, VIDEO_PLACEMENT_MODES, VIDEO_TIME_EPSILON, VIDEO_TRANSFORM_PROPERTIES, VIDEO_TRANSITION_LABELS, VIDEO_TRANSITION_TYPES, VIDEO_WIPE_DIRECTIONS, type VideoAnimatable, type VideoAsset, type VideoAssetKind, type VideoAudioLevel, type VideoAudioPeaks, VideoAudioPeaksCache, type VideoAudioPeaksLoader, type VideoAudioSource, type VideoBlendMode, type VideoCanvasContext, type VideoClip, type VideoClipAnimation, type VideoClipAnimationEffect, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, type VideoClipLocation, type VideoClipType, type VideoColorClip, type VideoEase, type VideoEdit, type VideoEditOp, type VideoEditOutcome, type VideoEditResult, VideoEditorController, type VideoEditorOptions, type VideoEditorState, type VideoEditorToolProviderOptions, type VideoEdlOptions, type VideoFadeCurve, type VideoFfmpegExport, type VideoFfmpegOptions, type VideoFit, type VideoFrame, type VideoGap, type VideoGrade, type VideoGradeControl, type VideoGradePreset, type VideoGradeStep, type VideoIssue, type VideoIssueCode, type VideoIssueSeverity, type VideoKey, type VideoKeyframeProperty, type VideoKeyframeRow, type VideoKeyframes, type VideoLayer, type VideoLoudnessMeasurement, type VideoLoudnessTarget, type VideoMarker, type VideoMediaClip, type VideoMediaProbe, type VideoPlacementMode, VideoPreviewEngine, type VideoPreviewImage, type VideoPreviewMedia, type VideoPreviewOptions, type VideoPreviewSource, type VideoProject, type VideoRect, type VideoRulerTick, type VideoSilenceOptions, type VideoSnapOptions, type VideoSvgOptions, type VideoTextClip, type VideoTrack, type VideoTrackKind, type VideoTransform, type VideoTransition, type VideoTransitionType, type VideoWaveformMode, type VideoWipeDirection, allVideoClipIds, applyVideoEdits, applyVideoGrade, buildVideoAudioPeaks, checkVideoProject, createVideoEditorToolProvider, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, drawVideoFrame, ffmpegFilterValue, findVideoAudioSilences, findVideoClip, findVideoGaps, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, isVideoKeyframes, nextFreeVideoSlot, normalizeVideoGrade, parseVideoAnimatable, parseVideoAsset, parseVideoClip, parseVideoClipAnimation, parseVideoGrade, parseVideoKeyframes, parseVideoLoudnessMeasurement, parseVideoMarker, parseVideoProject, parseVideoTrack, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, probeVideoMedia, removeVideoKey, retimeVideoAnimatable, setVideoKey, snapToVideoFrame, snapVideoTime, sortVideoKeys, sortedVideoClips, splitVideoAnimatable, toVideoEdl, toVideoFfmpeg, toVideoLoudnessMeasure, videoAssetDropEdit, videoAssetHasSound, videoAssetKindOf, videoAssetMap, videoAudioLevels, videoAudioPeakRange, videoAudioPeakSpans, videoAudioPeaksDuration, videoClipAfter, videoClipAnimated, videoClipAnimationProperties, videoClipAnimationSpans, videoClipBefore, videoClipEnd, videoClipHandles, videoClipKeyframes, videoClipLabel, videoClipOverhang, videoClipShowsWaveform, videoClipSoundGain, videoClipSourceRange, videoClipSpeed, videoClipTint, videoClipWaveform, videoClipWaveformPath, videoClipsAt, videoContactSheetSvg, videoDragLabel, videoDropTracks, videoEaseBezier, videoEaseProgress, videoFadeCurveGain, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoGradeCssFilter, videoGradeFfmpegFilters, videoGradeGainsFilterId, videoGradePreset, videoGradeStepMatrix, videoGradeStepSvgValues, videoGradeSteps, videoGradeSvgDefs, videoGradeSvgFilter, videoHourFrames, videoIrisRadius, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoOverlap, videoPeakDb, videoProjectDuration, videoProjectSvg, videoRulerTicks, videoSnapPoints, videoTextStyle, videoTimecodeFrames, videoTitleFrame, videoTrackSyncLocked, videoTransformAt, videoTransitionAudioCurve, videoTransitionEase, videoTransitionHasDirection, videoValueAt, videoWaveformPath, videoWipeRect };
+export { type CreateVideoProjectOptions, type NewVideoClip, VIDEO_BLEND_MODES, VIDEO_BLEND_MODE_LABELS, VIDEO_CLIP_ANIMATION_DURATION, VIDEO_CLIP_ANIMATION_EFFECTS, VIDEO_CLIP_ANIMATION_LABELS, VIDEO_CLIP_TYPES, VIDEO_DEFAULT_FILLERS, VIDEO_DEFAULT_STILL_DURATION, VIDEO_DEFAULT_TITLE_DURATION, VIDEO_EASE_NAMES, VIDEO_EDIT_OPS, VIDEO_FADE_CURVES, VIDEO_FADE_CURVE_LABELS, VIDEO_FITS, VIDEO_GRADE_CONTROLS, VIDEO_GRADE_PRESETS, VIDEO_GRADE_PRESET_NAMES, VIDEO_ISSUE_CODES, VIDEO_KEYFRAME_LIMITS, VIDEO_KEYFRAME_PROPERTIES, VIDEO_PEAK_BLOCK, VIDEO_PLACEMENT_MODES, VIDEO_TIME_EPSILON, VIDEO_TRANSFORM_PROPERTIES, VIDEO_TRANSITION_LABELS, VIDEO_TRANSITION_TYPES, VIDEO_WIPE_DIRECTIONS, type VideoAnimatable, type VideoAsset, type VideoAssetKind, type VideoAudioLevel, type VideoAudioPeaks, VideoAudioPeaksCache, type VideoAudioPeaksLoader, type VideoAudioSource, type VideoBlendMode, type VideoCanvasContext, type VideoClip, type VideoClipAnimation, type VideoClipAnimationEffect, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, type VideoClipLocation, type VideoClipType, type VideoColorClip, type VideoEase, type VideoEdit, type VideoEditOp, type VideoEditOutcome, type VideoEditResult, VideoEditorController, type VideoEditorOptions, type VideoEditorState, type VideoEditorToolProviderOptions, type VideoEdlOptions, type VideoFadeCurve, type VideoFfmpegExport, type VideoFfmpegOptions, type VideoFit, type VideoFrame, type VideoGap, type VideoGrade, type VideoGradeControl, type VideoGradePreset, type VideoGradeStep, type VideoIssue, type VideoIssueCode, type VideoIssueSeverity, type VideoKey, type VideoKeyframeProperty, type VideoKeyframeRow, type VideoKeyframes, type VideoLayer, type VideoLoudnessMeasurement, type VideoLoudnessTarget, type VideoMarker, type VideoMediaClip, type VideoMediaProbe, type VideoPauseOptions, type VideoPlacementMode, VideoPreviewEngine, type VideoPreviewImage, type VideoPreviewMedia, type VideoPreviewOptions, type VideoPreviewSource, type VideoProject, type VideoRect, type VideoRulerTick, type VideoSilenceOptions, type VideoSnapOptions, type VideoSpeedSegment, type VideoSvgOptions, type VideoTextClip, type VideoTimelineWord, type VideoTrack, type VideoTrackKind, type VideoTranscriptRange, type VideoTranscriptWord, type VideoTransform, type VideoTransition, type VideoTransitionType, type VideoWaveformMode, type VideoWipeDirection, allVideoClipIds, applyVideoEdits, applyVideoGrade, buildVideoAudioPeaks, checkVideoProject, checkVideoTimeRemap, createVideoEditorToolProvider, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, drawVideoFrame, ffmpegFilterValue, findVideoAudioSilences, findVideoClip, findVideoFillers, findVideoGaps, findVideoTranscriptPauses, findVideoTranscriptText, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, isVideoKeyframes, mergeVideoRanges, nextFreeVideoSlot, normalizeVideoGrade, normalizeVideoWord, parseVideoAnimatable, parseVideoAsset, parseVideoClip, parseVideoClipAnimation, parseVideoGrade, parseVideoKeyframes, parseVideoLoudnessMeasurement, parseVideoMarker, parseVideoProject, parseVideoTimeRemap, parseVideoTrack, parseVideoTranscript, parseVideoTranscriptWords, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, probeVideoMedia, removeVideoKey, retimeVideoAnimatable, setVideoKey, snapToVideoFrame, snapVideoTime, sortVideoKeys, sortedVideoClips, splitVideoAnimatable, toVideoEdl, toVideoFfmpeg, toVideoLoudnessMeasure, videoAssetDropEdit, videoAssetHasSound, videoAssetKindOf, videoAssetMap, videoAudioLevels, videoAudioPeakRange, videoAudioPeakSpans, videoAudioPeaksDuration, videoClipAfter, videoClipAnimated, videoClipAnimationProperties, videoClipAnimationSpans, videoClipBefore, videoClipEnd, videoClipHandles, videoClipKeyframes, videoClipLabel, videoClipOverhang, videoClipShowsWaveform, videoClipSoundGain, videoClipSourceRange, videoClipSourceTime, videoClipSpeed, videoClipSpeedAt, videoClipTint, videoClipWaveform, videoClipWaveformPath, videoClipsAt, videoContactSheetSvg, videoDragLabel, videoDropTracks, videoEaseBezier, videoEaseProgress, videoFadeCurveGain, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoFreezeFrameEdit, videoGradeCssFilter, videoGradeFfmpegFilters, videoGradeGainsFilterId, videoGradePreset, videoGradeStepMatrix, videoGradeStepSvgValues, videoGradeSteps, videoGradeSvgDefs, videoGradeSvgFilter, videoHourFrames, videoIrisRadius, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoOverlap, videoPeakDb, videoProjectDuration, videoProjectSvg, videoRemoveRangesEdits, videoRulerTicks, videoSlowMotionRamp, videoSnapPoints, videoSpeedRampEdit, videoSpeedRampKeys, videoTextStyle, videoTimeRemapBreakpoints, videoTimeRemapSpan, videoTimecodeFrames, videoTimelineTranscript, videoTitleFrame, videoTrackSyncLocked, videoTranscriptEdit, videoTranscriptTrack, videoTransformAt, videoTransitionAudioCurve, videoTransitionEase, videoTransitionHasDirection, videoValueAt, videoWaveformPath, videoWipeRect, videoWordAt, videoWordsRange };

package/dist/video-editor/index.d.ts

@@ -92,6 +92,12 @@ declare function videoKeyframeFfmpegExpr(prop: VideoAnimatable | undefined, time
  */
 
 type VideoAssetKind = 'video' | 'audio' | 'image';
+/** A spoken word in an asset's transcript, timed in the source (ms). */
+interface VideoTranscriptWord {
+    word: string;
+    start: number;
+    end: number;
+}
 /** A piece of source media. The project refers to it by id; `src` is whatever the host can load. */
 interface VideoAsset {
     id: string;
@@ -108,6 +114,8 @@ interface VideoAsset {
     hasAudio?: boolean;
     /** A still to show for a video where its frames cannot be drawn (SVG renders, thumbnails). */
     poster?: string;
+    /** What is said in it, word by word, timed in the source (see `parseVideoTranscript`). */
+    transcript?: VideoTranscriptWord[];
 }
 type VideoTrackKind = 'video' | 'audio';
 interface VideoTrack {
@@ -260,6 +268,13 @@ interface VideoMediaClip extends VideoClipBase {
     in?: number;
     /** Playback speed (default 1): it uses `duration × speed` of the source. */
     speed?: number;
+    /**
+     * A speed ramp: keys mapping clip time to source time after the in point (`v` ms from `in`), so
+     * a key's slope is the speed there, a flat stretch is a freeze frame and eased keys ramp between
+     * speeds. Never runs backwards. Before the first key and after the last the picture holds. Takes
+     * the place of `speed` (see `videoSpeedRampKeys` for building one from speeds).
+     */
+    timeRemap?: VideoKeyframes;
     /** Gain (1 = unchanged, default 1), or keyframes. */
     volume?: VideoAnimatable;
     /** Silences this clip. */
@@ -336,9 +351,11 @@ declare function parseVideoAnimatable(v: unknown, path: string, range?: {
     optional?: boolean;
 }): VideoAnimatable | undefined;
 declare function parseVideoTransform(v: unknown, path: string): VideoTransform | undefined;
+declare function parseVideoTimeRemap(v: unknown, speed: unknown, path: string): VideoKeyframes | undefined;
 declare function parseVideoClipAnimation(v: unknown, path: string): VideoClipAnimation | undefined;
 declare function parseVideoGrade(v: unknown, path: string): VideoGrade | undefined;
 declare function parseVideoTransition(v: unknown, path: string): VideoTransition | undefined;
+declare function parseVideoTranscriptWords(v: unknown, path: string): VideoTranscriptWord[] | undefined;
 declare function parseVideoAsset(v: unknown, path?: string): VideoAsset;
 declare function parseVideoClip(v: unknown, path?: string): VideoClip;
 declare function parseVideoTrack(v: unknown, path?: string): VideoTrack;
@@ -626,6 +643,18 @@ type VideoEdit = ({
     clip: string;
     property: VideoKeyframeProperty;
     keys: VideoKey[] | null;
+}
+/**
+ * A speed ramp: keys mapping clip time to source ms after the in point (see `timeRemap`), or
+ * null to play at normal speed from where the ramp started. `duration` sets the clip's new length
+ * (default: unchanged); `ripple` moves later material with the change.
+ */
+ | {
+    op: 'set_time_remap';
+    clip: string;
+    keys: VideoKey[] | null;
+    duration?: number;
+    ripple?: boolean;
 } | {
     op: 'close_gaps';
     track: string;
@@ -1028,6 +1057,141 @@ declare function videoClipAnimationSpans(clip: VideoClip): {
  */
 declare function videoClipAnimated(clip: VideoClip, project: Pick<VideoProject, 'width' | 'height'>): VideoClip;
 
+/**
+ * A transcript from text a speech-to-text service or captioning tool wrote: Whisper-style JSON
+ * (`{ segments: [{ words: [{ word, start, end }] }] }` or `{ words: [...] }`, times in seconds, or a
+ * plain `[{ word, start, end }]` array in ms), SubRip (`.srt`) or WebVTT. Captions have no word
+ * timings, so their words are spread evenly across each cue (`approximate: true`). Throws when it
+ * finds no words.
+ */
+declare function parseVideoTranscript(input: string | unknown): {
+    words: VideoTranscriptWord[];
+    approximate: boolean;
+};
+/** A word where it plays on the timeline. */
+interface VideoTimelineWord {
+    word: string;
+    /** Timeline times (ms). */
+    start: number;
+    end: number;
+    /** The clip that plays it. */
+    clip: string;
+    track: string;
+    /** Its index in the asset's transcript. */
+    index: number;
+}
+/**
+ * The track whose words make the timeline transcript: `track` if given, else the first audio track
+ * with a transcribed clip, else the first video track with one. `null` when nothing is transcribed.
+ */
+declare function videoTranscriptTrack(project: VideoProject, track?: string): string | null;
+/**
+ * The words the timeline plays on one track, in order: each transcribed media clip's words whose
+ * middle falls inside the stretch of source it plays, moved to timeline time through its in point
+ * and speed and clamped to the clip.
+ */
+declare function videoTimelineTranscript(project: VideoProject, options?: {
+    track?: string;
+}): VideoTimelineWord[];
+/** A stretch of the timeline (ms) and the words in it. */
+interface VideoTranscriptRange {
+    from: number;
+    to: number;
+    text: string;
+}
+/** A word as compared: lower case, without surrounding punctuation. */
+declare const normalizeVideoWord: (word: string) => string;
+/** Every place a phrase is said (case and punctuation ignored), as timeline ranges. */
+declare function findVideoTranscriptText(words: readonly VideoTimelineWord[], query: string): VideoTranscriptRange[];
+/** Filler words and phrases removed by default. "like" and "so" are left out: too often meant. */
+declare const VIDEO_DEFAULT_FILLERS: readonly ["um", "umm", "uh", "uhh", "uhm", "erm", "er", "ah", "hmm", "mm", "you know", "i mean"];
+/** Fillers in the transcript, longest phrase first ("you know" before "you"), as timeline ranges. */
+declare function findVideoFillers(words: readonly VideoTimelineWord[], fillers?: readonly string[]): VideoTranscriptRange[];
+interface VideoPauseOptions {
+    /** Shortest gap between words that counts as a pause (ms, default 700). */
+    min?: number;
+    /** Silence to keep next to each word so speech does not sound clipped (ms, default 150). */
+    keep?: number;
+    /** Frame rate to snap the cut inward to (default: none). */
+    fps?: number;
+}
+/** Gaps between consecutive words on the same clip longer than `min`, less `keep` either side, as timeline ranges. */
+declare function findVideoTranscriptPauses(words: readonly VideoTimelineWord[], options?: VideoPauseOptions): VideoTranscriptRange[];
+/** Ranges sorted and merged where they touch or overlap. */
+declare function mergeVideoRanges(ranges: readonly {
+    from: number;
+    to: number;
+}[]): {
+    from: number;
+    to: number;
+}[];
+/**
+ * The edits that cut ranges out of the timeline and close them up: one `extract_range` per merged
+ * range, last first, so earlier ranges keep their times. Apply them together as one undo step.
+ */
+declare function videoRemoveRangesEdits(ranges: readonly {
+    from: number;
+    to: number;
+}[], tracks?: string[]): VideoEdit[];
+/** The timeline stretch from word `a` to word `b` (either order), for deleting a selection of words. */
+declare function videoWordsRange(words: readonly VideoTimelineWord[], a: number, b: number): {
+    from: number;
+    to: number;
+};
+/** The edit that attaches a transcript file's text to an asset (see `parseVideoTranscript`). Throws a readable error for text it cannot read. */
+declare function videoTranscriptEdit(assetId: string, text: string): VideoEdit;
+/** The word playing at a timeline time, as its index in `words`, or -1. */
+declare function videoWordAt(words: readonly VideoTimelineWord[], time: number): number;
+
+/**
+ * Speed ramps and freeze frames: a media clip's `timeRemap` keys map clip time to source time after
+ * its in point. The slope between two keys is the speed there; equal values are a freeze; an eased
+ * segment changes speed smoothly. These helpers read and build them.
+ */
+/** Where in the source (ms) a media clip is at clip time `clipTime`, through its speed or its ramp. */
+declare function videoClipSourceTime(clip: VideoMediaClip, clipTime: number): number;
+/** The speed a media clip plays at at clip time `clipTime` (0 in a freeze), measured over a millisecond. */
+declare function videoClipSpeedAt(clip: VideoClip, clipTime: number): number;
+/** One stretch of a ramp: `duration` ms of the clip at `speed`, or easing from `speed` to `toSpeed`. 0 is a freeze. */
+interface VideoSpeedSegment {
+    duration: number;
+    speed: number;
+    /** Ramp smoothly to this speed by the end of the stretch (default: stay at `speed`). */
+    toSpeed?: number;
+}
+/**
+ * Remap keys for stretches of speed, from the clip's start: steady stretches are linear segments,
+ * ramps a cubic-bezier ease that changes the speed evenly from one to the other (the source moves
+ * the average of the two speeds over the stretch). Returns the keys and the source the clip plays.
+ */
+declare function videoSpeedRampKeys(segments: readonly VideoSpeedSegment[]): {
+    keys: VideoKey[];
+    duration: number;
+    source: number;
+};
+/**
+ * Checks remap keys: in time order and never going back in the source, eased segments included
+ * (each is sampled, so a curve that overshoots and would play backwards is caught). Throws a
+ * readable error.
+ */
+declare function checkVideoTimeRemap(remap: VideoKeyframes, path?: string): void;
+/** The stretch of source (ms, from the in point) a ramp plays: from its first key's value to its last's. */
+declare function videoTimeRemapSpan(remap: VideoKeyframes): {
+    from: number;
+    to: number;
+};
+/** Clip time and source time pairs tracing a ramp as straight lines (eased stretches sampled every `step` ms), with freezes marked. */
+declare function videoTimeRemapBreakpoints(remap: VideoKeyframes, step: number): {
+    t: number;
+    v: number;
+}[];
+/** The edit that plays a media clip through stretches of speed from the moment it shows at its start (see `videoSpeedRampKeys`). */
+declare function videoSpeedRampEdit(clip: VideoMediaClip, segments: readonly VideoSpeedSegment[], ripple?: boolean): VideoEdit;
+/** The edit that holds the frame a media clip shows at clip time `at` for `duration` ms, then plays on (the clip gets longer). */
+declare function videoFreezeFrameEdit(clip: VideoMediaClip, at: number, duration: number, ripple?: boolean): VideoEdit;
+/** A slow-motion ramp preset for a clip of `duration` ms: normal speed for half of it, a 500 ms glide down to 0.3×, then 1.5 s at 0.3×. */
+declare const videoSlowMotionRamp: (duration: number) => VideoSpeedSegment[];
+
 /** Radius of an iris `progress` (0–1) open: from nothing to the frame's corners. */
 declare const videoIrisRadius: (frame: {
     width: number;
@@ -1426,7 +1590,28 @@ interface VideoEditorToolProviderOptions {
 }
 /** A project as agents see it: settings, assets, and each track's clips in order with their times. */
 declare function describeVideoProject(project: VideoProject): {
-    assets: VideoAsset[];
+    assets: ({
+        id: string;
+        kind: VideoAssetKind;
+        src: string;
+        name?: string;
+        duration?: number;
+        width?: number;
+        height?: number;
+        hasAudio?: boolean;
+        poster?: string;
+    } | {
+        transcriptWords: number;
+        id: string;
+        kind: VideoAssetKind;
+        src: string;
+        name?: string;
+        duration?: number;
+        width?: number;
+        height?: number;
+        hasAudio?: boolean;
+        poster?: string;
+    })[];
     tracks: {
         clips: ({
             source?: {
@@ -1438,6 +1623,7 @@ declare function describeVideoProject(project: VideoProject): {
             asset: string;
             in?: number;
             speed?: number;
+            timeRemap?: VideoKeyframes;
             volume?: VideoAnimatable;
             muted?: boolean;
             fadeInCurve?: VideoFadeCurve;
@@ -1655,4 +1841,4 @@ declare function videoKeyframeValueEdit(project: VideoProject, clipId: string, p
  */
 declare function videoKeyframeToggleEdit(project: VideoProject, clipId: string, property: VideoKeyframeProperty, time: number): VideoEdit | null;
 
-export { type CreateVideoProjectOptions, type NewVideoClip, VIDEO_BLEND_MODES, VIDEO_BLEND_MODE_LABELS, VIDEO_CLIP_ANIMATION_DURATION, VIDEO_CLIP_ANIMATION_EFFECTS, VIDEO_CLIP_ANIMATION_LABELS, VIDEO_CLIP_TYPES, VIDEO_DEFAULT_STILL_DURATION, VIDEO_DEFAULT_TITLE_DURATION, VIDEO_EASE_NAMES, VIDEO_EDIT_OPS, VIDEO_FADE_CURVES, VIDEO_FADE_CURVE_LABELS, VIDEO_FITS, VIDEO_GRADE_CONTROLS, VIDEO_GRADE_PRESETS, VIDEO_GRADE_PRESET_NAMES, VIDEO_ISSUE_CODES, VIDEO_KEYFRAME_LIMITS, VIDEO_KEYFRAME_PROPERTIES, VIDEO_PEAK_BLOCK, VIDEO_PLACEMENT_MODES, VIDEO_TIME_EPSILON, VIDEO_TRANSFORM_PROPERTIES, VIDEO_TRANSITION_LABELS, VIDEO_TRANSITION_TYPES, VIDEO_WIPE_DIRECTIONS, type VideoAnimatable, type VideoAsset, type VideoAssetKind, type VideoAudioLevel, type VideoAudioPeaks, VideoAudioPeaksCache, type VideoAudioPeaksLoader, type VideoAudioSource, type VideoBlendMode, type VideoCanvasContext, type VideoClip, type VideoClipAnimation, type VideoClipAnimationEffect, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, type VideoClipLocation, type VideoClipType, type VideoColorClip, type VideoEase, type VideoEdit, type VideoEditOp, type VideoEditOutcome, type VideoEditResult, VideoEditorController, type VideoEditorOptions, type VideoEditorState, type VideoEditorToolProviderOptions, type VideoEdlOptions, type VideoFadeCurve, type VideoFfmpegExport, type VideoFfmpegOptions, type VideoFit, type VideoFrame, type VideoGap, type VideoGrade, type VideoGradeControl, type VideoGradePreset, type VideoGradeStep, type VideoIssue, type VideoIssueCode, type VideoIssueSeverity, type VideoKey, type VideoKeyframeProperty, type VideoKeyframeRow, type VideoKeyframes, type VideoLayer, type VideoLoudnessMeasurement, type VideoLoudnessTarget, type VideoMarker, type VideoMediaClip, type VideoMediaProbe, type VideoPlacementMode, VideoPreviewEngine, type VideoPreviewImage, type VideoPreviewMedia, type VideoPreviewOptions, type VideoPreviewSource, type VideoProject, type VideoRect, type VideoRulerTick, type VideoSilenceOptions, type VideoSnapOptions, type VideoSvgOptions, type VideoTextClip, type VideoTrack, type VideoTrackKind, type VideoTransform, type VideoTransition, type VideoTransitionType, type VideoWaveformMode, type VideoWipeDirection, allVideoClipIds, applyVideoEdits, applyVideoGrade, buildVideoAudioPeaks, checkVideoProject, createVideoEditorToolProvider, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, drawVideoFrame, ffmpegFilterValue, findVideoAudioSilences, findVideoClip, findVideoGaps, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, isVideoKeyframes, nextFreeVideoSlot, normalizeVideoGrade, parseVideoAnimatable, parseVideoAsset, parseVideoClip, parseVideoClipAnimation, parseVideoGrade, parseVideoKeyframes, parseVideoLoudnessMeasurement, parseVideoMarker, parseVideoProject, parseVideoTrack, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, probeVideoMedia, removeVideoKey, retimeVideoAnimatable, setVideoKey, snapToVideoFrame, snapVideoTime, sortVideoKeys, sortedVideoClips, splitVideoAnimatable, toVideoEdl, toVideoFfmpeg, toVideoLoudnessMeasure, videoAssetDropEdit, videoAssetHasSound, videoAssetKindOf, videoAssetMap, videoAudioLevels, videoAudioPeakRange, videoAudioPeakSpans, videoAudioPeaksDuration, videoClipAfter, videoClipAnimated, videoClipAnimationProperties, videoClipAnimationSpans, videoClipBefore, videoClipEnd, videoClipHandles, videoClipKeyframes, videoClipLabel, videoClipOverhang, videoClipShowsWaveform, videoClipSoundGain, videoClipSourceRange, videoClipSpeed, videoClipTint, videoClipWaveform, videoClipWaveformPath, videoClipsAt, videoContactSheetSvg, videoDragLabel, videoDropTracks, videoEaseBezier, videoEaseProgress, videoFadeCurveGain, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoGradeCssFilter, videoGradeFfmpegFilters, videoGradeGainsFilterId, videoGradePreset, videoGradeStepMatrix, videoGradeStepSvgValues, videoGradeSteps, videoGradeSvgDefs, videoGradeSvgFilter, videoHourFrames, videoIrisRadius, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoOverlap, videoPeakDb, videoProjectDuration, videoProjectSvg, videoRulerTicks, videoSnapPoints, videoTextStyle, videoTimecodeFrames, videoTitleFrame, videoTrackSyncLocked, videoTransformAt, videoTransitionAudioCurve, videoTransitionEase, videoTransitionHasDirection, videoValueAt, videoWaveformPath, videoWipeRect };
+export { type CreateVideoProjectOptions, type NewVideoClip, VIDEO_BLEND_MODES, VIDEO_BLEND_MODE_LABELS, VIDEO_CLIP_ANIMATION_DURATION, VIDEO_CLIP_ANIMATION_EFFECTS, VIDEO_CLIP_ANIMATION_LABELS, VIDEO_CLIP_TYPES, VIDEO_DEFAULT_FILLERS, VIDEO_DEFAULT_STILL_DURATION, VIDEO_DEFAULT_TITLE_DURATION, VIDEO_EASE_NAMES, VIDEO_EDIT_OPS, VIDEO_FADE_CURVES, VIDEO_FADE_CURVE_LABELS, VIDEO_FITS, VIDEO_GRADE_CONTROLS, VIDEO_GRADE_PRESETS, VIDEO_GRADE_PRESET_NAMES, VIDEO_ISSUE_CODES, VIDEO_KEYFRAME_LIMITS, VIDEO_KEYFRAME_PROPERTIES, VIDEO_PEAK_BLOCK, VIDEO_PLACEMENT_MODES, VIDEO_TIME_EPSILON, VIDEO_TRANSFORM_PROPERTIES, VIDEO_TRANSITION_LABELS, VIDEO_TRANSITION_TYPES, VIDEO_WIPE_DIRECTIONS, type VideoAnimatable, type VideoAsset, type VideoAssetKind, type VideoAudioLevel, type VideoAudioPeaks, VideoAudioPeaksCache, type VideoAudioPeaksLoader, type VideoAudioSource, type VideoBlendMode, type VideoCanvasContext, type VideoClip, type VideoClipAnimation, type VideoClipAnimationEffect, type VideoClipDragInput, type VideoClipDragMode, type VideoClipDragPlan, type VideoClipLocation, type VideoClipType, type VideoColorClip, type VideoEase, type VideoEdit, type VideoEditOp, type VideoEditOutcome, type VideoEditResult, VideoEditorController, type VideoEditorOptions, type VideoEditorState, type VideoEditorToolProviderOptions, type VideoEdlOptions, type VideoFadeCurve, type VideoFfmpegExport, type VideoFfmpegOptions, type VideoFit, type VideoFrame, type VideoGap, type VideoGrade, type VideoGradeControl, type VideoGradePreset, type VideoGradeStep, type VideoIssue, type VideoIssueCode, type VideoIssueSeverity, type VideoKey, type VideoKeyframeProperty, type VideoKeyframeRow, type VideoKeyframes, type VideoLayer, type VideoLoudnessMeasurement, type VideoLoudnessTarget, type VideoMarker, type VideoMediaClip, type VideoMediaProbe, type VideoPauseOptions, type VideoPlacementMode, VideoPreviewEngine, type VideoPreviewImage, type VideoPreviewMedia, type VideoPreviewOptions, type VideoPreviewSource, type VideoProject, type VideoRect, type VideoRulerTick, type VideoSilenceOptions, type VideoSnapOptions, type VideoSpeedSegment, type VideoSvgOptions, type VideoTextClip, type VideoTimelineWord, type VideoTrack, type VideoTrackKind, type VideoTranscriptRange, type VideoTranscriptWord, type VideoTransform, type VideoTransition, type VideoTransitionType, type VideoWaveformMode, type VideoWipeDirection, allVideoClipIds, applyVideoEdits, applyVideoGrade, buildVideoAudioPeaks, checkVideoProject, checkVideoTimeRemap, createVideoEditorToolProvider, createVideoProject, decodeVideoAudioPeaks, describeVideoProject, drawVideoFrame, ffmpegFilterValue, findVideoAudioSilences, findVideoClip, findVideoFillers, findVideoGaps, findVideoTranscriptPauses, findVideoTranscriptText, formatVideoSeconds, formatVideoTimecode, formatVideoTimecodeFrames, isVideoDropFrameRate, isVideoKeyframes, mergeVideoRanges, nextFreeVideoSlot, normalizeVideoGrade, normalizeVideoWord, parseVideoAnimatable, parseVideoAsset, parseVideoClip, parseVideoClipAnimation, parseVideoGrade, parseVideoKeyframes, parseVideoLoudnessMeasurement, parseVideoMarker, parseVideoProject, parseVideoTimeRemap, parseVideoTrack, parseVideoTranscript, parseVideoTranscriptWords, parseVideoTransform, parseVideoTransition, placeVideoRect, planVideoClipDrag, probeVideoMedia, removeVideoKey, retimeVideoAnimatable, setVideoKey, snapToVideoFrame, snapVideoTime, sortVideoKeys, sortedVideoClips, splitVideoAnimatable, toVideoEdl, toVideoFfmpeg, toVideoLoudnessMeasure, videoAssetDropEdit, videoAssetHasSound, videoAssetKindOf, videoAssetMap, videoAudioLevels, videoAudioPeakRange, videoAudioPeakSpans, videoAudioPeaksDuration, videoClipAfter, videoClipAnimated, videoClipAnimationProperties, videoClipAnimationSpans, videoClipBefore, videoClipEnd, videoClipHandles, videoClipKeyframes, videoClipLabel, videoClipOverhang, videoClipShowsWaveform, videoClipSoundGain, videoClipSourceRange, videoClipSourceTime, videoClipSpeed, videoClipSpeedAt, videoClipTint, videoClipWaveform, videoClipWaveformPath, videoClipsAt, videoContactSheetSvg, videoDragLabel, videoDropTracks, videoEaseBezier, videoEaseProgress, videoFadeCurveGain, videoFrameAt, videoFrameDuration, videoFrameToSvg, videoFrames, videoFreezeFrameEdit, videoGradeCssFilter, videoGradeFfmpegFilters, videoGradeGainsFilterId, videoGradePreset, videoGradeStepMatrix, videoGradeStepSvgValues, videoGradeSteps, videoGradeSvgDefs, videoGradeSvgFilter, videoHourFrames, videoIrisRadius, videoIssueKey, videoKeyframeBreakpoints, videoKeyframeFfmpegExpr, videoKeyframeRows, videoKeyframeToggleEdit, videoKeyframeValueEdit, videoKeysOf, videoOverlap, videoPeakDb, videoProjectDuration, videoProjectSvg, videoRemoveRangesEdits, videoRulerTicks, videoSlowMotionRamp, videoSnapPoints, videoSpeedRampEdit, videoSpeedRampKeys, videoTextStyle, videoTimeRemapBreakpoints, videoTimeRemapSpan, videoTimecodeFrames, videoTimelineTranscript, videoTitleFrame, videoTrackSyncLocked, videoTranscriptEdit, videoTranscriptTrack, videoTransformAt, videoTransitionAudioCurve, videoTransitionEase, videoTransitionHasDirection, videoValueAt, videoWaveformPath, videoWipeRect, videoWordAt, videoWordsRange };