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:
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:
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 do | Commands and examples |
|---|---|
| Choose footage and framing | Video editing: source, cut, delete, clip, prepend, append, frame, focus, join=tight |
| Arrange photos or add a moving character | Photo composition: still, presentation, scene, props |
| Change from one scene to the next | Transitions and beat timing: transition, join, saved frame schedules |
| Add words, logos or speaker names | Text and branding: text, captions, caption, card, brand, overlay, speaker |
| Show another clip over the main video | B-roll: insert |
| Add a soundtrack, clean the voice or balance volume | Music and loudness: voice, music, normalize |
| Adjust color and finish the edit | Color grading and finishing: grade, grade lut, grade hsl, fade, chapter |
| Make a video or an editable project | Rendering 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.vedlfile's directory. - Start a comment with
#, either on its own line or after whitespace. A color such ascolor=#ffee00is not a comment. - Times accept seconds, minutes and seconds, or hours, minutes and seconds.
90,1:30and0:01:30mean the same time. Decimal seconds are allowed. - Durations are in seconds:
0.5,3and3s. Thescene,joinand prop commands use integer frame counts where specified. - Positions such as
focus=0.6,0.4are fractions:0,0is the top-left corner and1,1is 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.
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.
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:
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":
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
| Preset | Removes pauses of | Keeps next to the speech |
|---|---|---|
natural (default) | 1 second and longer | 0.15 seconds |
tight | 0.45 seconds and longer | 0.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:
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:
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:
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:
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:
| Option | Result |
|---|---|
frame=fill | Fill the canvas by cropping the source. |
frame=fit | Keep the whole source visible; add bars where needed. |
frame=split | Stack two crops of the same video, usually for two speakers. Requires a portrait canvas. |
frame=face | Ask Clip Maker to find a face. It saves a concrete crop; a manually rendered unresolved face falls back to centered fill. |
focus=X,Y | Center the crop on this point in the source. On its own, it implies frame=fill. |
focus2=X,Y | Choose the second crop in a video split. |
focus_end=X,Y | Move a fill crop from focus to this point over the cut. |
Keep a speaker in frame as they lean across the picture:
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:
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:
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.
| Option | Meaning |
|---|---|
offset=SEC | Seconds into the camera's file at source time 0. Positive when the camera started recording before the source, negative after. |
drift=PPM | How 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=wide | The 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:
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.
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.
motion | Camera movement |
|---|---|
none | Hold the picture still; the default. |
zoom | Slowly move closer. |
zoomout | Slowly pull back. |
pan | Slowly 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:
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
| Setting | Meaning |
|---|---|
background=COLOR | Canvas 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=N | Clockwise print rotation, from −12 to +12 degrees; default 0. |
animation=none|slide|fade | Print 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.
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.
| Layout | Photos | Appearance |
|---|---|---|
full | 1 | A photo across the canvas; its frame setting controls cropping. |
instant | 1 | A white instant-print frame and shadow. |
gallery | 1 | A photo with its original shape, surrounded by a matte. |
stack | 1–3 | Overlapping, slightly rotated prints, with the first photo on top. |
split | 2 | Two vertically stacked photo panels. |
contact | 4 or 6 | A contact sheet with two columns; cards flip into view one at a time. |
push-drift | 1 | A quick scale settle followed by a gentle camera move. |
beat-sheet | 4, 6, 9 or 16 | Photos appear in a grid, followed by full-screen views of the last three. |
billboard | 1 | A 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:
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:
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 setting | Meaning |
|---|---|
id, path | A unique ID within the scene and the atlas filename. Optional name is a display label, up to 80 characters. |
action | fly 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, frames | Scene-local start and duration. Frame numbering starts at 0. |
x, y | Resting position or flight center, from 0 to 1 across the canvas. |
size | Sprite width as a fraction of canvas width: 0.05–0.6. |
layer | front draws above photos; behind draws above the backdrop but below photos. A full-frame photo hides a behind prop. |
flip | Optional true mirrors the sprite and reverses a fly path. |
columns, rows, count | Atlas grid and number of used cells. Each axis is 1–8; count is 1 through the number of cells, at most 64. |
aspectRatio | Optional displayed width divided by height, 0.05–20; default 1. Useful for a rectangular single-image overlay. |
beat | Optional 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:
source "demo.mp4"
cut 0 4
cut 10 14
cut 20 24
transition push 0.4
| Type | What happens |
|---|---|
cut | Switch immediately; no duration needed. |
xfade | Blend the outgoing and incoming pictures. |
fadeblack | Fade through black. |
wipe | Reveal the next picture across the canvas. |
push | Move both pictures across the canvas. |
snap-zoom | Zoom 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:
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:
| Effect | Requirement |
|---|---|
card-deal | The incoming scene is a Stack. Its last print slides into place. |
hero-expand | A photo in Gallery, Stack, Split or Contact Sheet expands into a following Full frame scene. |
panel-reveal | A 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:
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:
afternames an existing scene or named clip that has a following segment. Only one join may follow that segment.frames=0 impact=0is required foreffect=cut. Other effects use 1 through2*fpsframes, no more than 45% of either neighboring scene. A hand-written join outside that limit is rejected.impactis a frame within the transition: 0 throughframes-1. It marks the moment to align with a beat. It does not change the effect's animation.direction=left|right|up|downapplies 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
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:
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.
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.
| Setting | Choices |
|---|---|
style | clean, bold, minimal, karaoke, pop, none; default clean. The app calls pop Kinetic. |
color | Main text color. |
keywords="coffee,city" | Up to 16 keywords to highlight. |
accent | Highlight color; falls back to the brand accent, then the style default. |
pos | bottom, center or top; default bottom. |
size | 8–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. |
case | keep 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
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 type | Content |
|---|---|
callout | A large number or short phrase; sub supplies its label. |
quote | A pull quote over a blurred background; speaker supplies attribution. |
list | A heading and up to six items, separated by |. Items appear one by one. |
title | A 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.
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=centeris 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=toplower 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 checkwarns. - 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:
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:
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.
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.
| Mode | Result |
|---|---|
cutaway | The inserted picture fills the canvas. Default. |
pip | The inserted picture sits in a small window over the main video. |
swap | The inserted picture fills the canvas; the main video moves into the small window. |
overlay | From 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.
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.
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
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.
| Setting | Meaning |
|---|---|
start | Source position where the music begins. Defaults to 0; accepts seconds or a timestamp such as 0:13.5. |
style=podcast | Speech-focused mix; the default. |
style=documentary | Documentary mix preset. |
style=promo | Promotional mix preset. |
style=ambient | Ambient soundtrack preset. |
level | Music level relative to the voice, −40 through 0 dB. More negative is quieter. |
duck | Additional reduction while the voice is active, 0–30 dB. |
fade | How 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_mode | lookahead (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:
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
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:
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
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.
| Setting | Range | Unchanged value |
|---|---|---|
exposure | −3 to +3 stops | 0 |
brightness | −1 to +1 | 0 |
contrast | 0–3 | 1 |
saturation | 0–3 | 1 |
gamma | 0.1–3 | 1 |
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
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:
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
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
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:
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
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
| Feature | Current rendering support |
|---|---|
| Cuts, framing, stills, compositions, joins, props, B-roll, logos, titles, music and fades | Supported 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 names | Attached 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 metadata | Written by the shared clip renderer, and from CLI 1.7.0 by standalone edit render. |
| Text shaping and font fallback | Simple 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 renderwithout--draftexports;--dry-runchecks 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:
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:
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:
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:
{
"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:
{
"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
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:
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 script | In Final Cut Pro |
|---|---|
source and its cut lines | Clips on the primary storyline, with their source in and out points |
transition xfade | A 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 touch | Plain cuts, never dissolves |
| Captions | Final Cut captions (iTT), plus the .srt; at the top edge for pos=top, else at the bottom edge |
text and cards | Basic Titles with the same words and timing |
card lower_third | From 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=split | The 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) |
music | Connected audio with volume keyframes for the duck |
fade in, fade out | Opacity and volume keyframes |
Speaker names, chapter | Markers 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
| Problem | What to check |
|---|---|
| A photo has bars or a different crop | Set frame=fill explicitly, or use frame=fit when bars are intended. Check each composition slot separately. |
| A join is rejected | Check 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 parse | Keep it on one line, escape its inner quotes, and remove trailing text or unknown fields. |
| A prop is missing | Check 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 missing | Check 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 out | Render with CLI 1.7.0 or later, which converts HDR video to SDR. |
| A title with an apostrophe is rejected | Replace ' with ’ in text commands. |
| A title is larger than it used to be | From 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 frame | Render 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 read | Check 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.