VEDL Language Reference

Write video edits as text. Learn VEDL with examples for cuts, photo layouts, transitions, animated props, captions, music, color grading and export.

VEDL is a text file that describes a video edit. Each line does one job: keep a part of a recording, show a photo, add a title, or mix in music. Save the file with a .vedl extension.

Photo compositions, per-scene transitions, animated props, captions, cards and the other v2 commands need CLI 1.4.0 or later. Later changes are marked with the version that brought them; 5am --version shows yours, and 5am update updates it.

Start with a short edit

No recording at hand? From CLI v1.8.6, 5am media edit sample writes 5am-sample/sample.vedl and an 8-second test video (made by your ffmpeg, with no download and no account) and prints the commands that check it and render a free draft.

Save this as talk.vedl, next to a recording named talk.mp4:

vedl
source "talk.mp4"
cut 01:12 01:32 frame=fill
cut 04:03 04:18 frame=fill
transition xfade 0.5
text "A better way to begin" at 0 for 3 pos=top size=56
fade out 0.5

This keeps two parts of the recording and joins them with a half-second crossfade. The result is 34.5 seconds: 20 + 15 − 0.5. The title appears for the first three seconds.

Render a portrait video:

sh
5am media edit render talk.vedl --aspect 9:16 --output talk-short.mp4

Examples below use placeholder filenames. Replace them with your own media. A photo-only script uses still or scene lines and needs no source line.

What you want to doCommands and examples
Choose footage and framingVideo editing: source, cut, delete, clip, prepend, append, frame, focus, join=tight
Arrange photos or add a moving characterPhoto composition: still, presentation, scene, props
Change from one scene to the nextTransitions and beat timing: transition, join, saved frame schedules
Add words, logos or speaker namesText and branding: text, captions, caption, card, brand, overlay, speaker
Show another clip over the main videoB-roll: insert
Add a soundtrack, clean the voice or balance volumeMusic and loudness: voice, music, normalize
Adjust color and finish the editColor grading and finishing: grade, grade lut, grade hsl, fade, chapter
Make a video or an editable projectRendering and export

File format

  • Write one command per line. Blank lines are ignored. Command names are case-insensitive; use the lowercase option values shown here.
  • Put filenames and text in double quotes. Use \" for a quote inside a string and \\ for a backslash. Relative paths start from the .vedl file's directory.
  • Start a comment with #, either on its own line or after whitespace. A color such as color=#ffee00 is not a comment.
  • Times accept seconds, minutes and seconds, or hours, minutes and seconds. 90, 1:30 and 0:01:30 mean the same time. Decimal seconds are allowed.
  • Durations are in seconds: 0.5, 3 and 3s. The scene, join and prop commands use integer frame counts where specified.
  • Positions such as focus=0.6,0.4 are fractions: 0,0 is the top-left corner and 1,1 is the bottom-right.
  • Quote an option value that contains spaces: font="Instrument Serif".

Two clocks: at vs atsrc

Use at for a time in the finished video. Use atsrc for a time in the original recording. Image overlays use the equivalent names from and fromsrc.

vedl
source "interview.mp4"
cut 01:00 01:20
text "Meet the founder" at 0 for 3
text "The first customer" atsrc 01:08 for 3

The first title appears when the output starts. The second appears eight seconds later, because source time 01:08 falls eight seconds into the kept footage.

Source times are adjusted for cuts and transition overlaps. If an anchor points into removed footage, the renderer moves it to a nearby kept moment and reports a warning. atsrc does not select a recording from an independent clip line. Use at for mixed-source edits and scripts made only of photos or independent clips.

Video editing

Keep or remove parts of a recording

Use source once to name the main recording. cut START END keeps a range, including its start and excluding its end. Write cuts in time order, without overlaps.

vedl
source "interview.mp4"
cut 00:10 00:25   # introduction
cut 01:00 01:20   # the answer

Or use delete START END to remove ranges and keep the rest:

vedl
source "interview.mp4"
delete 0 10
delete 00:25 01:00

Choose cut or delete for one script; do not mix them. Overlapping deletes are merged. With neither command, a source-only script keeps the whole recording. Kept ranges of 50 milliseconds or less are dropped.

Take out pauses and filler words

From CLI v1.8.4, 5am media edit tighten takes the dead air out of a cut script. It reads the recording's transcript with word timings (the .json from 5am media transcribe) and removes the pauses between words and filler words such as "um" and "uh":

sh
5am media edit tighten talk.vedl --transcript talk.transcript.json -o talk.tight.vedl
5am media edit tighten talk.vedl --preset tight --dry-run --pretty   # what would come out
PresetRemoves pauses ofKeeps next to the speech
natural (default)1 second and longer0.15 seconds
tight0.45 seconds and longer0.08 seconds

A pause is removed only when it is quiet, so laughter, applause and music the transcript does not spell stay. --pauses and --keep change the numbers, and --fillers "um,uh,you know" (or --fillers off) sets the filler words. Each cut line becomes its kept pieces, joined with join=tight:

vedl
cut 00:10 00:21.4
cut 00:22.9 00:25 join=tight

join=tight joins a cut to the one before it with a plain cut and a short sound fade, even when the script has a transition line, so the pieces play as one continuous shot. Text, captions, cards, B-roll and chapters timed with at move with the removed time, as do image overlays timed with from (including an omitted start of zero). Layers wholly inside removed time are taken out, with a warning naming each line; partially retained layers keep their required minimum duration. Cut lines that touched stay one shot, and a crop pan keeps the corresponding part of its path in each retained piece.

If a shortened cut leaves the transition longer than its 45% limit, the transition shortens too and the result warns. With -o in another folder, the script's media paths are re-pointed so it still finds the recording. A script can hold up to 256 cut lines. Tighten works on one source's cut ranges; convert delete ranges to cuts first. Independent clip lines are not supported.

Add an intro or outro

prepend "intro.mp4" and append "outro.mp4" add complete clips before or after the edit. Use at most one of each:

vedl
source "interview.mp4"
cut 10 30
prepend "intro.mp4"
append "outro.mp4"

Combine recordings with clip

clip "FILE" START END adds a range from any video in document order. Its end is exclusive, playback stays at normal speed, and the whole range must fit inside that file. It needs no source line:

vedl
clip "webcam.mp4" 10 16 frame=fill
clip "phone.mp4" 3 8 frame=fit audio=mute
transition xfade 0.4

audio=keep is the default; audio=mute silences that clip. Use frame=fill with optional focus=X,Y to crop, or frame=fit to show the whole picture. Independent clips do not accept frame=split, frame=face, focus_end or join=tight.

Clips can appear between cut, still and scene lines, but cannot be combined with delete. If a script has a source and no cut lines, its whole source plays first, before the independent clips or photos. Use output-time at anchors for annotations in mixed-source edits.

To give a clip an explicit join or scene-local props, supply id, frames and fps together:

vedl
clip "walk.mp4" 10 13 id="opening" frames=90 fps=30 frame=fill
scene "photo" frames=60 fps=30 layout=full photos="[{\"path\":\"view.jpg\",\"frame\":\"fit\"}]"
join after="opening" effect=xfade frames=12 impact=6 fps=30

The ID must be unique across clips and scenes. The frame count must match END − START at the declared fps, be positive, and last less than 180 seconds. Every named clip, scene and join shares the same fps. Clip props use the prop settings with layer:"front". Use the general transition effects at video boundaries; photo expansion and Card Deal effects need photo scenes.

Fit a video into the canvas

Add framing options to a cut:

OptionResult
frame=fillFill the canvas by cropping the source.
frame=fitKeep the whole source visible; add bars where needed.
frame=splitStack two crops of the same video, usually for two speakers. Requires a portrait canvas.
frame=faceAsk Clip Maker to find a face. It saves a concrete crop; a manually rendered unresolved face falls back to centered fill.
focus=X,YCenter the crop on this point in the source. On its own, it implies frame=fill.
focus2=X,YChoose the second crop in a video split.
focus_end=X,YMove a fill crop from focus to this point over the cut.

Keep a speaker in frame as they lean across the picture:

vedl
source "interview.mp4"
cut 10 18 frame=fill focus=0.65,0.45
cut 18 19 frame=fill focus=0.65,0.45 focus_end=0.45,0.45
cut 19 30 frame=fill focus=0.45,0.45

The middle cut moves the crop for one second. All three cuts touch, so they play continuously without a transition between them.

For two speakers:

vedl
source "interview.mp4"
cut 10 30 frame=split focus=0.25,0.5 focus2=0.75,0.5

focus controls the top panel; focus2 controls the bottom. Those two points are also the defaults when omitted. On a square or landscape canvas, video split falls back to fill with a warning. Photo layout=split is a different layout and works at those aspect ratios.

focus_end requires a starting focus and fill framing. A video cut cannot use focus with frame=fit or frame=face.

Cut between several cameras with angle

From CLI v1.8.95, a script can cut between 2 to 4 cameras of one recording while the sound stays one track. source names the program audio: the recorder, or the camera whose sound you keep. Each angle line names a camera and how it lines up with the source, and angle= on a cut shows that camera's picture:

vedl
source "program.wav"
angle wide "cam-wide.mp4" offset=-1.24 drift=12 role=wide
angle ali "cam-ali.mp4" offset=0.88 drift=-8
angle sam "cam-sam.mp4" offset=0.5
cut 10 14.2 angle=ali
cut 14.2 19.8 angle=sam
cut 19.8 25          # the wide

Every cut's sound comes from source, whichever camera it shows, so the sound never jumps to a camera's microphone at a switch. Captions, music ducking, tighten and atsrc times follow the source as usual. Touching cuts play as one continuous shot, so a switch is a hard cut on an exact frame, with no transition and no skip in the sound.

OptionMeaning
offset=SECSeconds into the camera's file at source time 0. Positive when the camera started recording before the source, negative after.
drift=PPMHow much faster the camera's clock runs than the source's, in parts per million. Cameras drift 20 to 50 ppm, a frame or more an hour.
role=wideThe wide shot: what a cut without angle= shows when the source is sound alone. One angle at most.

The camera's time is offset + source time x (1 + drift / 1,000,000). With offset=-1.24 drift=12, source time 600 s shows the camera at 598.7672 s.

A cut without angle= shows the source's own picture, or the wide angle (else the first angle) when the source has no picture. The source's picture counts as one of the 2 to 4 angles. Framing options such as frame=fill focus=X,Y apply to the picture the cut shows. Each camera must have recorded every cut that shows it.

Measure the offsets and drift with 5am media sync, which compares each camera's sound with the program audio and writes the angle lines:

sh
5am media sync program.wav cam-wide.mp4 cam-ali.mp4 cam-sam.mp4 --wide cam-wide --pretty
5am media sync program.wav cam-wide.mp4 cam-ali.mp4 --wide cam-wide --script talk.vedl

It prints each camera's offset, drift, confidence (the share of measured windows that agree) and its angle line. A camera it is not sure of (confidence under 0.6, or under --min-confidence) is reported and left out of the script: its sound may not be this recording. Line it up by hand instead; a clap at the start helps. --min-confidence 0 is taken as written: a camera then needs only 3 measured windows that agree.

Angle names come from the file names unless --names gives them. Two files that would get the same name are told apart with -2, -3 (cam.mp4 and cam.mov become cam and cam-2). With --script, the paths in the printed angle lines (lines in the JSON) are relative to the script's folder, the same as the lines it writes, so you can paste them into the script; a file outside that folder gets its full path. Sync decodes at most 512 MiB of sound per file (16 kHz mono, about 4 hours 40 minutes), and refuses a longer file with an error.

Each camera is decoded for as long as the edit shows it, so several 4K cameras take longer to render. Multi-cam scripts do not export to the web video editor yet. From CLI v1.8.95 they export to Final Cut Pro as a multicam clip: see Export to Final Cut Pro or DaVinci Resolve.

Photo composition

Show one photo with still

Use still "photo.jpg" for SECONDS. A still lasts 0.5–180 seconds and has no audio of its own. A document holds at most 256 cut lines and 256 non-cut commands. Within those non-cut commands, still, scene and clip lines total at most 64. Before CLI v1.8.4, cut lines counted toward the 64 and the 256.

vedl
still "street.jpg" for 3 frame=fill focus=0.5,0.4 motion=pan
still "cafe.jpg" for 3 frame=fill motion=zoom
still "sunset.jpg" for 4 frame=fill motion=zoomout
transition xfade 0.5

These three photos make a nine-second video after the two crossfade overlaps.

motionCamera movement
noneHold the picture still; the default.
zoomSlowly move closer.
zoomoutSlowly pull back.
panSlowly move across the picture.

Use frame=fit to keep the whole photo visible. Use frame=fill and an optional focus to control the crop.

Give photos an instant-print frame

presentation instant gives the stills a white paper border, a deeper bottom margin and a shadow:

vedl
presentation instant background="#e8e5dc" tilt=-5 animation=slide
still "friends.jpg" for 3 frame=fill motion=none
still "beach.jpg" for 3 frame=fill motion=zoom
transition xfade 0.4
SettingMeaning
background=COLORCanvas color; default #e8e5dc.
image="paper.jpg"Optional background image, cropped to fill the canvas. Takes priority over the solid color.
video="backdrop.mp4"Optional looping background video, with its sound muted. Choose either image or video.
tilt=NClockwise print rotation, from −12 to +12 degrees; default 0.
animation=none|slide|fadePrint entrance and exit; default none.

The entrance and exit happen inside the photo's duration. They do not add time or replace a transition between scenes. Tilt and these entrance settings belong to the instant-print layout.

A plain still line under a presentation always renders as an instant print, so use presentation instant there. Other photo layouts belong on scene lines; presentation supplies their shared background. A video clip with layout=billboard can use that background too.

Arrange several photos with scene

scene gives a photo layout a name, a frame count and a frame rate. At 30 fps, frames=90 means three seconds.

vedl
presentation split background="#f3ede3"
scene "details" frames=90 fps=30 layout=split photos="[{\"path\":\"detail.jpg\",\"frame\":\"fill\"},{\"path\":\"whole.jpg\",\"frame\":\"fill\"}]"

This shows two photos in vertically stacked panels. Change layout=split to layout=stack to arrange the same two photos as overlapping prints.

LayoutPhotosAppearance
full1A photo across the canvas; its frame setting controls cropping.
instant1A white instant-print frame and shadow.
gallery1A photo with its original shape, surrounded by a matte.
stack1–3Overlapping, slightly rotated prints, with the first photo on top.
split2Two vertically stacked photo panels.
contact4 or 6A contact sheet with two columns; cards flip into view one at a time.
push-drift1A quick scale settle followed by a gentle camera move.
beat-sheet4, 6, 9 or 16Photos appear in a grid, followed by full-screen views of the last three.
billboard1A fixed screen over a color, image or video background.

Each entry in photos has a path. Optional settings are frame:"fill" or "fit", motion:"none", "zoom", "zoomout" or "pan", and focus:{"x":0.5,"y":0.4}. Omitted photo motion means no additional camera move. Some layouts animate themselves: Contact Sheet holds each photo still after its flip, and Push & Drift supplies its own movement.

Keep the JSON array on the same command line. Quotes inside it need escaping, as shown above. Unknown fields and trailing JSON are rejected.

A scene ID must be unique, using 1–64 letters, digits, underscores or hyphens. Scene durations are 0.5 seconds to just under 180 seconds. fps is an integer from 1 to 120; every scene and join in the document must use the same value. An explicit render frame rate must match it.

Use presentation for shared background settings and scene layout=… for each composition. Multi-photo layouts need explicit scene photo slots. Photo scenes and ordinary video cut lines can appear together in timeline order.

Beat Sheet accepts an optional events="JSON" schedule: one { "photo": 0, "startFrame": 0, "full": false } entry per photo in order, then three full:true entries for the last three photos. Frame indexes must increase strictly and stay inside the scene. Reel Studio writes these when syncing to music; without them, the grid uses the first 65% of the available sequence and the full-screen views use the rest. Rendering the saved file does not analyze music again.

Billboard also works with video:

vedl
presentation billboard video="backdrop.mp4"
clip "demo.mp4" 0 3 id="screen" frames=90 fps=30 layout=billboard frame=fit

Billboard is a fixed screen, with no camera tracking. A prepared subject pop-out from Reel Studio can add a subject object naming its foreground file, frames and fps. Keep that generated file with the edit: it contains packed color and transparency, so an ordinary video is not a substitute. Subject foregrounds require a matching 2–8 second Billboard scene or named clip at 30 fps.

Add a bird or character with props

A prop is a transparent image that moves inside a scene. For a character that also flaps or waves, provide a sprite atlas: one PNG containing equally sized square animation frames, arranged left to right, then top to bottom.

This example expects bird-atlas.png to have four columns and four rows, with 16 frames:

vedl
scene "garden" frames=90 fps=30 layout=gallery photos="[{\"path\":\"garden.jpg\",\"frame\":\"fill\"}]" props="[{\"id\":\"bird\",\"path\":\"bird-atlas.png\",\"action\":\"fly\",\"startFrame\":15,\"frames\":60,\"x\":0.5,\"y\":0.35,\"size\":0.24,\"layer\":\"front\",\"columns\":4,\"rows\":4,\"count\":16}]"

The bird flies across the three-second scene. Its action starts at frame 15 and lasts through frame 74: two seconds at 30 fps. The atlas supplies the wing movement.

Prop settingMeaning
id, pathA unique ID within the scene and the atlas filename. Optional name is a display label, up to 80 characters.
actionfly crosses the scene, peek rises into view, hop jumps and lands, wave stays in place while the atlas supplies the gesture, hold stays in place with no fade and may span the whole scene, fade stays in place with a fade envelope, and slide-left, slide-right, slide-up and slide-down travel through the position along one axis.
startFrame, framesScene-local start and duration. Frame numbering starts at 0.
x, yResting position or flight center, from 0 to 1 across the canvas.
sizeSprite width as a fraction of canvas width: 0.05–0.6.
layerfront draws above photos; behind draws above the backdrop but below photos. A full-frame photo hides a behind prop.
flipOptional true mirrors the sprite and reverses a fly path.
columns, rows, countAtlas grid and number of used cells. Each axis is 1–8; count is 1 through the number of cells, at most 64.
aspectRatioOptional displayed width divided by height, 0.05–20; default 1. Useful for a rectangular single-image overlay.
beatOptional true lets Reel Studio's beat-sync pass align this action. It does not analyze music when a saved file is rendered.

A scene supports up to three props. Each action must fit inside it and last 2 frames to 4 seconds; hold can last from one frame to the whole scene and cannot use beat:true. A multi-cell atlas must be no larger than 4096 pixels on either side, with square cells. A single-cell image can be rectangular; set aspectRatio to preserve its shape.

Props other than hold fade in and out during the first and last 20% of their action, with at least one frame for each fade. Two-frame actions skip the fades. Captions and titles stay above props. A scene transition moves the composed picture, including its props.

Reel Studio prepares atlases from a saved Storybook character or a design from its character & sticker studio. VEDL uses the resulting PNG and frame settings; it does not generate character art or run Storybook or Lottie code during rendering.

Transitions and beat timing

Use one transition throughout

transition TYPE SECONDS sets the transition between separate shots:

vedl
source "demo.mp4"
cut 0 4
cut 10 14
cut 20 24
transition push 0.4
TypeWhat happens
cutSwitch immediately; no duration needed.
xfadeBlend the outgoing and incoming pictures.
fadeblackFade through black.
wipeReveal the next picture across the canvas.
pushMove both pictures across the canvas.
snap-zoomZoom in, switch pictures near the middle, then settle.

Omitting transition gives hard cuts. Use at most one global transition line. Durations are 0–10 seconds and are capped at 45% of the shortest shot. Transitions overlap their neighbors, so they shorten the total output.

A transition with a duration also crossfades the sound. From CLI 1.7.0 the crossfade holds a steady level; before, the sound of two different shots dipped by about 3 dB in the middle of the join.

Adjacent cuts of the same source that touch, such as cut 0 10 and cut 10 20, form one continuous shot. They never receive a transition between them. From CLI v1.8.4, a cut marked join=tight also continues the shot of the cut before it, even when the two do not touch (see Take out pauses and filler words).

Choose a transition for a particular scene

Use join after a named scene or clip. It overrides the global transition at that boundary. Its timing is in frames, not seconds.

This example expands the second photo in a split layout into the next full-frame scene:

vedl
presentation split background="#f3ede3"
scene "pair" frames=90 fps=30 layout=split photos="[{\"path\":\"detail.jpg\",\"frame\":\"fill\",\"motion\":\"none\"},{\"path\":\"whole.jpg\",\"frame\":\"fill\",\"motion\":\"none\"}]"
scene "hero" frames=90 fps=30 layout=full photos="[{\"path\":\"whole.jpg\",\"frame\":\"fill\",\"motion\":\"none\"}]"
join after="pair" effect=panel-reveal frames=14 impact=13 fps=30 source=1

The output is 166 frames: 90 + 90 − 14. The next scene starts at output frame 76, and the reveal reaches full frame at frame 89. source=1 selects the second photo; slot indexes start at 0.

A join accepts the six transition types above, plus these composition effects:

EffectRequirement
card-dealThe incoming scene is a Stack. Its last print slides into place.
hero-expandA photo in Gallery, Stack, Split or Contact Sheet expands into a following Full frame scene.
panel-revealA photo in Split expands into a following Full frame scene.

Hero Expand and Panel Reveal must use the same photo and focus in the outgoing slot and incoming scene. Set both to frame:"fill" and motion:"none". Use source=N to choose between repeated copies of a photo; otherwise the first matching slot is used. These three effects require join, not a global transition.

Deal a new print into a stack:

vedl
scene "opening" frames=60 fps=30 layout=full photos="[{\"path\":\"first.jpg\",\"frame\":\"fill\"}]"
scene "prints" frames=90 fps=30 layout=stack photos="[{\"path\":\"first.jpg\",\"frame\":\"fill\"},{\"path\":\"second.jpg\",\"frame\":\"fill\"}]"
join after="opening" effect=card-deal frames=12 impact=11 fps=30 direction=left

Join rules:

  • after names an existing scene or named clip that has a following segment. Only one join may follow that segment.
  • frames=0 impact=0 is required for effect=cut. Other effects use 1 through 2*fps frames, no more than 45% of either neighboring scene. A hand-written join outside that limit is rejected.
  • impact is a frame within the transition: 0 through frames-1. It marks the moment to align with a beat. It does not change the effect's animation.
  • direction=left|right|up|down applies to Push, Wipe and Card Deal. Omitted means left.

For a hard cut, use join after="opening" effect=cut frames=0 impact=0 fps=30 instead of the Card Deal line.

Sync to music and replay the result

Beat sync is a planning option in Reel Studio; it is not a VEDL command. The planner measures the music and writes concrete scene durations and join frames into the saved file.

For photo compositions, it keeps the selected effects and total output length. Cut lands on the first incoming frame. Xfade, Fade through black, Wipe and Snap Zoom use the middle frame, floor(frames/2). Push, Card Deal and the two expansion effects use the last transition frame, frames-1.

Props marked beat:true can move their impact to a nearby measured beat, at most half a second away, while keeping the action inside its scene. Hop uses its landing frame; the other actions use the midpoint. This also works in a single-scene reel. If the music has no reliable beat or the timing does not fit, the planner keeps the original timing.

A saved .vedl file replays those decisions without another analysis pass. Playing it again does not choose new beats or regenerate the atlas. Older one-photo still plans use mood-based cuts or dissolves; the per-scene join path preserves your chosen effects.

Text and branding

Titles, captions and cards serve different purposes. text is a simple title; caption is a line in the caption style; card is a designed callout, quote, list or lower third.

Renderer support: caption, card and speaker-name layers below are attached by Clip Maker and Reel Studio, and from CLI 1.7.0 by the standalone media edit render command too. Earlier versions of media edit render attach simple text titles only. See Rendering and export.

Simple titles with text

vedl
source "talk.mp4"
cut 0 12
text "A small change, a big difference" at 0 for 3 pos=top size=56 color=white

text "WORDS" at|atsrc TIME for SECONDS accepts pos, size and color. Defaults are pos=bottom size=48 color=white. Duration is greater than 0 and at most 60 seconds; size is 8–300.

Positions are top, bottom, center, top-left, top-right, bottom-left and bottom-right. Size is pixels on a 1080-pixel-wide canvas and scales with output width: size=72 is a 72-pixel font in a video 1080 pixels wide and a 48-pixel font in one 720 pixels wide, and its capital letters are about 0.73 of that tall (about 53 and 35 pixels), so measure a title on the video you rendered. It is the font size, the same on every render path: from CLI v1.8.8, burned-in titles draw at that size. Earlier releases drew them smaller, by about a sixth for Latin text and up to about a third for Persian and Japanese, so a title you sized on an older release grows when you render it again: for a Latin title, multiply its size by about 0.84 to keep the old look. Clip scripts from Clip Maker and 5am media clips write their title at size=47 from CLI v1.8.8, which draws it as large as the size=56 of earlier clip scripts did. Long titles wrap and may shrink to fit.

Use a typographic apostrophe (’) in text. A straight apostrophe (') is rejected. This restriction does not apply to caption or card text.

Caption style and written captions

captions sets one style for transcript captions and written caption lines. It does not create or load a transcript. Clip Maker supplies the transcript separately.

For a standalone render, add captions style=clean to talk.vedl and pass a transcript explicitly:

sh
5am media edit render talk.vedl --transcript talk.transcript.json --output talk-captioned.mp4 --draft

The transcript can be JSON from 5am media transcribe, SRT or VTT. Explicit transcripts use the original source's clock by default; add --transcript-timeline output if their times already refer to the finished edit. With a captions or speaker line and no --transcript, the renderer looks beside the script for <name>.transcript.json, then transcript.json (both source time), then <name>.srt (output time). For talk.vedl, <name> is talk. A source transcript does not supply words for independent clip lines; use a transcript of the finished edit for captions across all recordings.

vedl
still "cafe.jpg" for 4 frame=fill
captions style=pop color=white accent=#ffee00 size=48 pos=bottom
caption "Coffee before the city wakes" at 0.5 for 3

The written line appears for three seconds starting half a second into the photo. No transcript is needed for a caption line.

SettingChoices
styleclean, bold, minimal, karaoke, pop, none; default clean. The app calls pop Kinetic.
colorMain text color.
keywords="coffee,city"Up to 16 keywords to highlight.
accentHighlight color; falls back to the brand accent, then the style default.
posbottom, center or top; default bottom.
size8–200 pixels on a 1080-wide canvas, scaled with output width like a title's; omitted uses the style's size. It sets the full line height, so caption letters are about 1/1.2 the height of a title's at the same number.
font="Family"Font family, such as Inter or Instrument Serif.
casekeep or upper; default keep.

Use at most one captions line. A written caption lasts 0.2–180 seconds and has at most 200 characters. A font is a family name: commas, braces and control characters are rejected. Its only timing options are at|atsrc TIME for SECONDS; set its appearance on captions. Animated styles create word timing for written lines.

From CLI 1.7.0, long transcript captions are split into readable blocks. A sentence too long for the frame becomes several blocks of at most two lines each (one line for bold), each shown for 1 to 7 seconds. A pause of a second or more starts a new block, and a block stays up long enough to read when the next one does not follow straight away. Highlighted keyword phrases stay in one block. pop already shows a few words at a time, and a written caption line keeps its own text and timing. The .srt files Clip Maker hands out use the same split, at up to 42 characters per line.

Callouts, quotes, lists and title cards

vedl
source "talk.mp4"
cut 0 20
card callout "37%" at 2 for 3 sub="less time spent on setup"
card quote "Start with one small habit." at 7 for 4 speaker="Ali"
card list "Try this today" at 13 for 6 items="Pick one task|Set a timer|Review the result"
Card typeContent
calloutA large number or short phrase; sub supplies its label.
quoteA pull quote over a blurred background; speaker supplies attribution.
listA heading and up to six items, separated by |. Items appear one by one.
titleA heading with an optional sub line.

All cards accept at|atsrc TIME for SECONDS, accent=COLOR and pos=center|top|bottom. Default position is center. Duration is 1–15 seconds. A list needs items; allow enough time for its 1.2-second item spacing.

From CLI v1.8.8, card text shrinks to fit the frame: a number or word too wide for the frame, or a card too tall for it, is drawn smaller instead of running off the edge, and text that fits keeps its size. Text too long to fit even when shrunk is a warning from 5am media edit check, before you render. A callout reads best as a number or a couple of words; in a portrait frame, keep a callout's number to about six characters ("37%", "$1.2M") to draw it at full size.

Lower thirds

From CLI v1.8.95, a lower_third card names the person on screen the way a news broadcast does: their name, and under it their title or role.

vedl
source "talk.mp4"
cut 0 20
captions style=clean
speaker "Speaker 1" name="Maya Okafor"
card lower_third "Maya Okafor" atsrc 0.5 for 4 sub="Head of Research, Lumen Labs"

The name sits in white on a dark plate with a bar in the accent colour beside it, and the title or role sits under it on a plate in the accent colour. It slides in from the side and fades out like the other cards. sub is optional, and accent=COLOR and the brand accent and font apply as they do to every card.

  • Where it sits. At the bottom by default, or pos=top. A lower third is never centred: pos=center is an error. On a 9:16 frame it stays clear of the bottom and right edges, where short-form apps draw their buttons and captions.
  • With captions. When the clip burns captions on the same edge, the lower third sits just above them, so the two never overlap, whatever the caption style or size. Top captions push a pos=top lower third down the same way.
  • Name chips. A lower third that names a speaker replaces their name chip while it shows.
  • Right-to-left names. A name in Arabic script or Hebrew mirrors the whole graphic: it starts at the right edge and slides in from the right.
  • Long names. A name or title too wide for the frame is drawn smaller to fit. Past its smallest size it wraps, and 5am media edit check warns.
  • The words. Use the name the person goes by and the title they give. When Clip Maker's AI proposes a lower third, or answers a note with one, it uses only a name you set for a speaker (or one said in the recording) and a title said in the recording. It puts the lower third at that person's first line in the clip; near the clip's end it is shortened to fit, or left out when there is no room.

From CLI v1.8.95, a card's options may also come before its time, as in card lower_third "Maya Okafor" sub="Host" at 2 for 4. The script is written back with them after the time.

Brand settings and image overlays

Use brand for a shared accent, font and full-duration logo. Use overlay for an image that appears at a particular time:

vedl
source "demo.mp4"
cut 0 15
brand name="Field Notes" accent=#e8b04a font="Inter" logo="logo.png" logo_pos=top-right logo_scale=0.14
overlay "badge.png" from 5 for 4 pos=bottom-left scale=0.18 opacity=0.9

Use one brand line, with at least one setting. The logo defaults to the top-right at 14% of canvas width. logo_scale must be greater than 0 and at most 0.5. The brand logo is drawn above ordinary image overlays.

overlay accepts from|fromsrc TIME, for SECONDS, pos, scale and opacity. Defaults are output time zero, top-right, scale 0.2 and opacity 1. Omit for to continue to the end; an explicit duration is greater than 0 and at most 3600 seconds. For example, overlay "logo.png" for 8 shows it for the first eight seconds. Scale is a fraction of canvas width, greater than 0 through 1.5; opacity is greater than 0 through 1.

Inter and Instrument Serif ship with the shared clip renderer. Clip Maker can also use an uploaded brand font. A font family name alone does not embed a font in a .vedl file; the renderer needs access to it.

Speaker names

Match the labels in a diarized transcript:

vedl
source "interview.mp4"
cut 10 30 frame=split focus=0.25,0.5 focus2=0.75,0.5
captions style=clean
speaker "Speaker 1" name="Ali" side=left color=#e8b04a chip=intro
speaker "Speaker 2" name="Sara" side=right color=#82bdab chip=turns

intro introduces a speaker once for four seconds; turns shows their name for three seconds at the start of each turn; always keeps it visible while they speak; off hides it. Default is intro. A speaker without name has no visible name label. Speaker lines do not detect voices or create a transcript.

B-roll

insert shows another video or image while the main recording's audio keeps playing. The inserted video's audio is not used.

vedl
source "tutorial.mp4"
cut 0 20
insert "screen-recording.mp4" at 5 for 6 from=2 mode=pip pos=top-left scale=0.3 shape=rect

At output second 5, show six seconds of the screen recording, starting two seconds into that file.

ModeResult
cutawayThe inserted picture fills the canvas. Default.
pipThe inserted picture sits in a small window over the main video.
swapThe inserted picture fills the canvas; the main video moves into the small window.
overlayFrom CLI v1.8.95: a transparent graphic laid over the main video, which shows through wherever the graphic is clear.

Use at or atsrc for placement. for is 0.5–30 seconds; from defaults to 0. Window settings are pos, scale=0.15..0.5 and shape=rect|circle. Defaults are top-right, 0.35 and circle.

overlay takes a file with an alpha channel: ProRes 4444 in a .mov, which 5am motion render --alpha writes, or a PNG with transparency. It is fitted inside the canvas, never cropped (the space around it stays clear), and has no window settings. A file without alpha covers the video like a cutaway, and the check warns about it.

vedl
source "talk.mp4"
cut 0 20
insert "lower-third.mov" at 2 for 4 mode=overlay

An insert covers the timeline for its duration; it does not extend the edit. Use prepend or append to add time before or after it.

Music and loudness

Clean up the voice

From CLI 1.7.0, voice cleans the recording's speech before it is mixed: it cuts low rumble, notches out mains hum, lowers steady room noise, softens harsh "s" sounds, evens out the level and brings the voice forward.

vedl
source "interview.mp4"
cut 10 30
voice clean=auto
normalize

auto listens to the kept speech and picks the amounts. A hum notch is used only when the quiet moments between words show a clear peak at 50 or 60 Hz (the mains frequency) and its multiples. It makes four narrow cuts at those frequencies. light and strong use gentler or stronger settings, but every mode limits denoising when speech is close to the noise floor to protect quiet words. Presence and treble boosts also ease off on noisy recordings. hum=50 or hum=60 always notches that frequency, hum=off never notches, and nr=12 sets the noise reduction in dB (0 to 30), overriding the automatic strength. From CLI v1.8.4, each recording is measured and cleaned on its own, so a studio take and a noisy phone clip get separate settings. The render's result says what it measured and used for each recording.

From CLI v1.8.4, it also turns the room down between words: by up to 12 dB with auto (6 with light, 18 with strong). A quiet recording brought up to a normal loudness would otherwise bring its room noise up with it, which you hear in every pause. The threshold is set below the measured speech level to protect quiet syllables and word endings. expand=8 sets how far, in dB (0 to 24), and expand=0 turns it off. If speech and room noise remain too close after denoising, expansion is disabled; an explicit expand request then produces a warning. Listen to the result, especially on faint speech.

It cleans the speech of the recording and of clip lines; a prepend or append clip, such as an end card with music, keeps its sound. Use at most one voice line; clean=off turns it off.

Add music under speech

vedl
source "interview.mp4"
cut 10 30
music "bed.mp3" style=podcast level=-22 duck=10
normalize target=-16 peak=-1.5

The renderer measures the recording and music, then mixes the bed below the voice. It lowers the music further while speech is present. A short track loops; a long track is trimmed to the output.

From CLI v1.8.4, the music looks ahead: it starts dipping just before each sentence and stays down through the short breaths between words, instead of reacting after the speaker starts. The speech comes from the transcript when the render has one, and otherwise from the sound itself. A transcript of the source recording has no words for clip lines (even of the same file), so in those the music dips where the speech is heard. Add duck_mode=sidechain to go back to the older behavior, which reacts to the voice as it plays.

SettingMeaning
startSource position where the music begins. Defaults to 0; accepts seconds or a timestamp such as 0:13.5.
style=podcastSpeech-focused mix; the default.
style=documentaryDocumentary mix preset.
style=promoPromotional mix preset.
style=ambientAmbient soundtrack preset.
levelMusic level relative to the voice, −40 through 0 dB. More negative is quieter.
duckAdditional reduction while the voice is active, 0–30 dB.
fadeHow long the music fades out at the end, 0–30 seconds; 0 turns it off. Defaults to the style's: podcast 2, documentary 3, promo 1.5, ambient 4.
duck_modelookahead (the default from CLI v1.8.4) dips before each sentence; sidechain reacts to the voice as it plays.

Use at most one music line. Start with a style and add level or duck only when you need to change the balance. These values are decibels, not volume percentages.

Choose where the music starts

Use start=TIME to pick the part of a track that fits your reel:

vedl
still "morning.jpg" for 5
still "evening.jpg" for 5
music "piano.mp3" start=0:13.5 style=ambient

Here the soundtrack starts at 13.5 seconds into the song as the first photo appears. You can write 13.5, 0:13.5, or 00:00:13.5. The start defaults to zero, must be non-negative and before the end of the track, and cannot exceed 86400 seconds.

When playback reaches the track's end, it loops from 0:00. Later loops use the full track, and the soundtrack ends with the video.

In Reel Studio, seek with the audio player's scrubber and press Set start here. The marked time applies to the rough cut and your next render. Reset music start returns it to zero; choosing another track also resets it. If Sync to music is enabled, beat timing is recalculated for the selected starting point on render.

Give a photo reel a soundtrack

vedl
still "morning.jpg" for 3 frame=fill motion=pan
still "evening.jpg" for 3 frame=fill motion=zoomout
transition xfade 0.5
music "piano.mp3" style=ambient
fade out 0.8

Photos are silent, so the music becomes the main soundtrack. It is adjusted to the style's target loudness without voice ducking. The same behavior applies to a silent video recording.

Adding music does not turn on beat sync. Enable that planning option in Reel Studio; see Transitions and beat timing.

Set the output loudness

normalize sets the measured loudness target and peak limit. Use it with or without music:

vedl
source "talk.mp4"
cut 0 20
normalize target=-16 peak=-1.5

target is −36 through −8 LUFS; default −16. peak is −9 through 0 dBTP; default −1.5. LUFS describes overall loudness; dBTP limits the loudest peaks. Use at most one normalize line. Normalizing a silent recording cannot add sound and produces a warning.

From CLI v1.8.4, the render also checks the peak of the file it wrote. The AAC encoder can push a sharp "s" or "t" slightly over the limit; when it does, the sound is encoded again with a little more headroom, and the picture is left as it is. The render's result reports the peak it measured.

From CLI v1.8.4, when a script uses two or more recordings (a source and clip lines of other files), normalize first brings them to the same loudness, so a loud phone clip sits evenly next to a quiet webcam recording. Each recording is evened out as a whole, so a speaker's own soft and loud moments stay. Several clip lines of one file, or a source and a clip of the same file, count as one recording. Add match=off to keep each recording's own level.

Color grading and finishing

Adjust the whole picture

vedl
source "walk.mp4"
cut 0 15
grade exposure=0.3 contrast=1.08 saturation=1.12

This slightly brightens the picture and increases contrast and color intensity.

SettingRangeUnchanged value
exposure−3 to +3 stops0
brightness−1 to +10
contrast0–31
saturation0–31
gamma0.1–31

A grade applies across the main timeline, including photo compositions. It is not a timed or per-scene setting. B-roll inserts and output text/image overlays are added after this grade.

Adjust one color range

vedl
source "garden.mp4"
cut 0 15
grade saturation=1.05
grade hsl greens hue=-5 sat=8 lum=4
grade hsl blues sat=-10

grade hsl changes a color band: reds, yellows, greens, cyans, blues or magentas. hue shifts the color by −180 to +180 degrees; sat and lum change saturation and lightness by −100 to +100. Zero leaves a setting unchanged. Each HSL line needs at least one nonzero adjustment.

HSL grading requires FFmpeg's huesaturation filter. A build without it skips these adjustments with a warning. Exposure uses a brightness approximation when FFmpeg lacks its exposure filter.

Apply a LUT

From CLI v1.8.4, grade lut applies a 3D LUT (a .cube file) such as a look from a colorist or a LUT pack:

vedl
source "walk.mp4"
cut 0 15
grade exposure=0.1
grade lut "teal-orange.cube" mix=0.8

The LUT applies after the grade settings and before grade hsl. mix (above 0, up to 1; default 1) sets how much of the look to use: 0.5 is halfway between the picture and the LUT's version of it. Use one grade lut line per script. The file must be a 3D .cube LUT of size 2 to 65; the render names the line of a file it cannot read.

Use creative LUTs made for ordinary video (Rec.709). HLG and PQ HDR recordings, such as an iPhone's, are converted to SDR before grading. Do not apply a camera-log conversion LUT to footage already converted to SDR. The web video editor cannot apply a LUT: an exported project preserves its path and mix as grading metadata and warns that the preview will differ.

To put the finished look in your library, see Grade and upload a video.

Fade the start or end

vedl
source "walk.mp4"
cut 0 15
fade in 0.5
fade out 1

fade affects video and audio at the output's edges. It does not add time. Its duration must be greater than 0 and at most 10 seconds. Use at most one fade-in and one fade-out. If their combined duration exceeds the edit, both are shortened with a warning. A fade through black between scenes belongs to transition or join instead.

Add chapter markers

vedl
source "lesson.mp4"
cut 0 30
chapter "The idea" at 0
chapter "The demonstration" at 12
card title "The demonstration" at 12 for 2

chapter "TITLE" at|atsrc TIME adds a navigation marker to the output container when rendered through the shared clip renderer. It does not draw text. The title card in this example supplies the on-screen heading.

Markers are sorted, kept at least half a second apart, and dropped when they fall past the end. Chapter display depends on the player. Before CLI 1.7.0, standalone media edit render did not attach the chapter metadata.

From CLI 1.7.0, edit render and edit inspect also print the chapters as the lines a YouTube description takes, under youtube_chapters:

text
00:00 The idea
00:12 The demonstration

YouTube turns those lines into chapters only when the first is at 0:00, there are at least three, and each runs at least 10 seconds. When the chapters break one of those rules, ok is false and problems says which; nothing is moved for you.

Rendering and export

Render a video file

sh
5am media edit render edit.vedl --aspect 9:16 --output reel.mp4

Choose --aspect 9:16, 1:1 or 16:9, or set both --width and --height. You can also pair one dimension with --aspect. Without a size override, the canvas follows the source, first independent clip, or first photo. From CLI v1.8.95, a clip script in a Clip Maker project folder renders on that project's canvas (its aspect, filled as Clip Maker fills it) unless you pass a size. Named scenes and clips use their declared fps; other video edits derive the frame rate from the source or first clip. Plain still-only scripts default to 30 fps. From CLI 1.7.0, a 29.97, 23.976 or 59.94 fps source keeps its exact rate; earlier versions rounded it to 30, 24 or 60 and repeated a frame about every 33 seconds.

From CLI 1.7.0, a render can also carry its captions as a subtitle track that viewers turn on and off in their player. --soft-captions auto (the default) adds it when the script has captions style=none, so the captions are available without being burned into the picture; on adds it to any render with captions; off never. MP4 and MOV players may show a lone subtitle track by default, so over burned captions use .mkv if the track should start off.

Every render is standard dynamic range (SDR) in BT.709 colour. From CLI 1.7.0, HDR video, such as an iPhone HDR clip (HLG) or a PQ export, is converted to SDR as it is read: highlights are compressed rather than washed out, and photos in the same edit keep their colours.

When framing is omitted, standalone edit render keeps the whole picture with bars as needed. Clip Maker and Reel Studio normally crop to fill. Write frame=fill explicitly, or "frame":"fill" in photo slots, when you want a script to keep the same crop across entry points.

Rendering needs local FFmpeg and the referenced files. From CLI v1.8.4, FFmpeg 5.1 or later (we test with 8): renders with normalize, music or voice use filter options older versions lack. Basic hand-written edits need no AI call or API key. From CLI v1.8.0, a render while signed out is a draft with a small mark (see Drafts and exports); before, signing in removed the mark.

Know which renderer you are using

FeatureCurrent rendering support
Cuts, framing, stills, compositions, joins, props, B-roll, logos, titles, music and fadesSupported by standalone edit render and the shared clip renderer (CLI 1.4.0 or later).
Independent video clip lines (with their overlays)Supported by standalone edit render and the shared clip renderer; the web editor export keeps their overlays as metadata with a warning.
Transcript captions, written captions, cards and speaker namesAttached by Clip Maker/Reel Studio's shared renderer, and from CLI 1.7.0 by standalone edit render; need FFmpeg with libass. See Caption style and written captions for transcript files and timing.
Chapter metadataWritten by the shared clip renderer, and from CLI 1.7.0 by standalone edit render.
Text shaping and font fallbackSimple titles use libass when available. Without it, the fallback uses one font file, selected with --font if needed.

A .vedl file stores editing instructions, not the media, transcript, fonts or generated sprite pixels. Keep those assets with the project to reproduce the result.

Drafts and exports

  • A draft is free and offline, with a small "Powered by 5AM" mark. Use one while you iterate: 5am media edit render edit.vedl --output draft.mp4 --draft. Every render while signed out is a draft.
  • An export is the file without the mark, for 50 AI credits at the current price (prices may change), on every account, your own Gemini key included. 5am media edit render without --draft exports; --dry-run checks your balance and prints the price without rendering or charging.

The render happens on your computer and your video never uploads: 5AM charges the fee by the finished file's fingerprint, so the same file is never charged twice. From CLI v1.8.95, one fee covers a clip version's video and its Final Cut Pro XML: rendering a clip and exporting its XML, in either order, costs one fee, and so does a version you already exported from Clip Maker. If the fee is refused (no credits left, or a network error), the render is kept for 24 hours: buy credits, then 5am media edit finalize <id> pays for it and delivers it without rendering again (finalize with no id lists the kept ones). media highlight exports the same way (--draft for a draft), and media clips pays the same fee per clip.

Check an edit before rendering

From CLI 1.7.0, four commands let you (or an AI agent) check an edit without rendering the whole video:

sh
5am media edit ops --pretty                 # every command, with its options and allowed values
5am media edit inspect edit.vedl --pretty   # the timeline: each part's times in seconds and frames
5am media edit sheet edit.vedl -o sheet.jpg # a labelled contact sheet of the key frames
5am media edit stills edit.vedl --times 2,7.5 --out-dir stills

inspect reports the exact number of frames the render will write. The sheet and stills are drawn exactly as edit render draws them. A script with several mistakes reports every bad line at once.

From CLI v1.8.6, 5am media edit check edit.vedl --pretty does the first check in one step: every mistake on its line, then the media (missing files, a cut past the end), and it exits with code 3 when the edit would not render, so a script can stop there. From CLI v1.8.8, check and inspect also warn about card text too long to fit the frame even when it is drawn smaller; a warning does not stop the render.

After rendering, 5am media edit measure out.mp4 --doc edit.vedl --pretty checks the video against its script: the frame count, loudness against the normalize target, black or frozen frames and silence near cuts, and whether titles, captions and cards stay inside the safe area. From CLI v1.8.8, a safe-area warning names the edge a layer crosses and by how many pixels, with the safe area and frame size, for example card title crosses the left 5% title-safe margin by 34 px, and lists the edges in edges; one about the area short-form apps cover with buttons says which zone, bottom or right. Add --strict to make it exit with an error when anything needs a look.

From CLI v1.8.9, measure checks each title, caption and card on its own. Earlier releases measured every layer on screen at the same moment as one box, so with two titles showing together, a centred one could be reported in the bottom app zone because of the other: when an older measure flags a layer that looks fine, check the text beside it.

sheet, stills, tighten and sample never replace an existing file unless you pass --overwrite. edit render replaces its output, so you can render a draft to the same file again while you work, and edit generate replaces its script.

Grade and upload a video

Save this as grade.vedl beside your video and LUT. With no cuts, it grades the whole video:

vedl
source "input.mp4"
grade lut "look.cube" mix=0.8

Review the grade in a draft first. When ready, render and upload in one command chain:

sh
5am media edit render grade.vedl --output graded.mp4 &&
5am media upload graded.mp4 --album CoolAlbumName

&& starts the upload only when rendering succeeds. The standard export price applies; add --draft to render and upload a free copy with the 5AM mark. The library receives the rendered MP4 with the LUT applied.

In MCP, enable the edit,media toolsets. The agent checks the script with edit_check, reviews a draft, and, after you agree to the export, calls edit_render with the script inline:

json
{
  "vedl": "source \"input.mp4\"\ngrade lut \"look.cube\" mix=0.8\n",
  "base_dir": "/media",
  "output": "/media/graded.mp4"
}

After the render succeeds, it passes the returned output path to media_upload:

json
{
  "paths": ["/media/graded.mp4"],
  "album": "artemis"
}

For a custom ffmpeg binary, pass --ffmpeg /path/to/ffmpeg to both CLI commands, or add options: {"ffmpeg":"~/Downloads/ffmpeg"} to both MCP calls and the check. Videos over 2 GiB need ffmpeg during upload too. Check each file's upload status; retry a failed upload from the existing MP4 without rendering or paying for the export again.

Export an editable project

sh
5am media edit export edit.vedl --new-album "My reel assets" --project-name "My reel"

Export uploads the media and creates a Video Editor project, and prints a url that opens it (/video-editor?projectId=…). It requires login and either --album or --new-album. It is free; the media counts toward your storage. AI agents do the same with the edit_web_editor_export tool (AI agents).

Cuts, supported transitions, titles, image overlays, framing, B-roll, cards and compatible grading become editor items. From CLI v1.8.8, a title opens in the editor at the size it renders at; earlier exports passed size without scaling it to the canvas, so on a canvas other than 1080 pixels wide the editor drew it too small or too large. Written captions can be exported from caption lines; transcript captions also need the transcript supplied by the exporting app. Clip Maker supplies it when publishing an editable project; standalone CLI export does not. From CLI v1.8.97, exported captions are the short pages the render shows (at most two lines, one for bold), not the transcript's whole sentences, and when Clip Maker combines several clips each clip keeps its own caption style and keywords.

The general Video Editor does not yet reproduce photo-layout choreography, animated props or the newer composition effects. Their settings and asset URLs are preserved as metadata, with warnings. Gamma/HSL/LUT grading, speaker labels, chapter markers and the ducked music mix also have rendering limits in the editor. Fades produce a warning and are not preserved as an editable effect.

When Clip Maker combines several clips into one editable project, each clip keeps its own captions (from CLI v1.8.97; earlier, every clip took the first clip's caption style), and the first clip's grading wins. Its LUT path and mix are retained as metadata; if it has no LUT, the merged project has none. A different LUT file, mix amount, or presence on a later clip produces a conflict warning. Identical LUT settings merge without a conflict, but the editor still warns that it cannot display the LUT.

Keep the rendered MP4 when exact playback matters. An editable export can look different from the VEDL render.

Export to Final Cut Pro or DaVinci Resolve

From CLI v1.8.95, a clip can go to Final Cut Pro as an editable project:

sh
5am media edit export-fcpxml clip-01.vedl -o clip-01.fcpxml

It writes an FCPXML 1.10 file, which Final Cut Pro and DaVinci Resolve both open, with the captions beside it as clip-01.srt (Resolve often drops captions from an XML). The timeline is the render's, frame for frame: every cut lands on the frame the render cuts on.

In the scriptIn Final Cut Pro
source and its cut linesClips on the primary storyline, with their source in and out points
transition xfadeA Cross Dissolve centred on the cut. A dissolve an odd number of frames long is one frame shorter, because Final Cut centres dissolves on their cut
join=tight, and cuts that touchPlain cuts, never dissolves
CaptionsFinal Cut captions (iTT), plus the .srt; at the top edge for pos=top, else at the bottom edge
text and cardsBasic Titles with the same words and timing
card lower_thirdFrom CLI v1.8.95, a Basic Title where the render puts it, aligned on the left (on the right for a right-to-left name)
frame=fill, fit, focus= and focus_end=From CLI v1.8.95, Fill is an explicit Scale and Position (Spatial Conform None), cropped where the render crops it (from CLI v1.8.97, the Scale fills the frame exactly whatever the source's size and shape; in v1.8.95 and v1.8.96 a source of another shape than the frame could be zoomed too far, or fall short of the frame), with Position keyframes for a pan that follows a face. Fit is Spatial Conform Fit
frame=splitThe first speaker on the storyline and the second as a connected clip, each cropped to its half
insert (B-roll)Connected clips above the storyline; a cutaway at the Scale that fills the frame (Spatial Conform None); picture in picture as Scale and Position; an overlay fitted to the frame, its alpha kept (Final Cut reads a ProRes 4444 file's transparency)
musicConnected audio with volume keyframes for the duck
fade in, fade outOpacity and volume keyframes
Speaker names, chapterMarkers and chapter markers
angle lines (multi-cam, from CLI v1.8.95)One multicam clip with every camera and the program audio as its angles. Each cut shows its camera's picture with the program's sound, so the sound never switches at a camera cut, and you can switch any cut to another angle in Final Cut

What does not carry over exactly: caption styles the renderer draws (karaoke, kinetic, keyword colours) become plain captions at the top or bottom edge of the picture (Final Cut has no other place for one, and the render draws them further in), cards become Basic Titles, a round picture in picture is square, and the grade, LUT, voice clean-up and the measured music mix are left out. The output's notes lists what applies to your clip, and the project carries the same note.

From CLI v1.8.95, a multi-cam script exports as a Final Cut multicam clip. Each camera sits at its sync to the nearest frame, as in the render, and a camera whose clock drifts is cut into pieces inside its angle, a new piece each time it has drifted a whole frame, so it stays in sync for the whole recording. A cut's picture can be one frame from the render's when its cameras' syncs fall between frames. Framing is set on each cut's own angle, so a cut you switch to another angle in Final Cut shows that angle unframed until you reframe it. A camera of another shape than the main picture is fitted inside the multicam's frame.

The XML points to your media where they are on this computer. To hand the project to someone else, add --include-media <folder>: the source, B-roll, music, logo and every camera of a multi-cam script are copied there and the XML names them by relative paths, so the folder and the XML move together.

The export pays the clip fee, 50 AI credits at the current price (prices may change). One fee covers a clip version's video and its XML: a version you already exported, as a video (from Clip Maker or with 5am media edit render) or as an XML, costs nothing again, and moving the project folder does not change that. --dry-run prints the price (0 when the version is paid for) and writes nothing. The canvas and captions are found as media edit render finds them, so use the same flags for both: --aspect, --width and --height (fit inside the frame, or --fit cover to fill it), else, for a script in a Clip Maker project folder, that project's canvas, else the source's own. The captions come from --transcript, or a transcript or .srt beside the script.

In Clip Maker, the same export is Final Cut Pro (XML) on the Share & export tab in the clip workspace, with Include media to download one .zip instead.

Troubleshooting

ProblemWhat to check
A photo has bars or a different cropSet frame=fill explicitly, or use frame=fit when bars are intended. Check each composition slot separately.
A join is rejectedCheck the scene ID, matching fps, impact range and 45% overlap limit. Reveal effects also need matching photos, focus, Fill framing and no camera motion.
A scene's JSON will not parseKeep it on one line, escape its inner quotes, and remove trailing text or unknown fields.
A prop is missingCheck the atlas path, grid, transparent pixels, frame interval and layer. A behind prop is hidden by a full-frame photo. wave needs changing atlas cells to show a gesture.
Captions or cards are missingCheck the renderer support table, libass availability and transcript where needed. For missing burned captions, also check that captions style=none is not selected; that setting does not hide cards.
An iPhone HDR clip looks gray or washed outRender with CLI 1.7.0 or later, which converts HDR video to SDR.
A title with an apostrophe is rejectedReplace ' with ’ in text commands.
A title is larger than it used to beFrom CLI v1.8.8, size is the font size on every render path. For a Latin title, multiply an older script's size by about 0.84 to keep its look; a clip script's size=56 becomes size=47.
Card text runs off the edge of the frameRender with CLI v1.8.8 or later, which draws it smaller to fit. If check still warns about it, shorten the text: a callout is a number or a couple of words.
Media cannot be readCheck paths relative to the .vedl file and whether FFmpeg can decode each file. A still image reporting no intrinsic duration is normal; its scene supplies the duration.

Where scripts come from

Clip Maker and 5am media clips save one document per clip. Reel Studio saves one per reel, using simple stills or named photo compositions. 5am media highlight saves the edit for its highlight reel. You can also generate a script from a transcript with 5am media edit generate, or write one by hand. Its --transcript takes the JSON from 5am media transcribe, or an .srt or .vtt caption file. From CLI 1.7.0 it also reads files saved as UTF-16 or Windows-1252, files without cue numbers, and WebVTT cue settings; a WebVTT voice tag such as <v Ana> becomes the speaker.

See also