Language reference

vedit programmes are postfix: literals and sources push values, while operations consume values from the top of the stack and push results. Signatures below show the stack from left to right, with the rightmost value at the top. For example, VIDEO DURATION -> VIDEO means that the duration is popped first, followed by the video.

Comments begin with # outside a quoted path. Each source, literal, or operation occupies one line.

Value types

Sources and literals

Paths must be quoted and may contain spaces or # characters.

Quoted strings support positional interpolation: video "$1" substitutes the first script argument, while video "clips/$2.mp4" inserts the second argument into a larger string. $0 and references to missing arguments are rejected. Source paths must remain quoted.

Stack operations

A, B, and C may be values of any type. Duplicated media is automatically routed through an FFmpeg split or asplit only when multiple reachable consumers require it.

Combined media

The compatibility extractors select track zero and discard the remaining combined value. Indexed operations preserve or modify the collection:

Indexes are zero-based. Invalid indexes fail during compilation. Per-type collection order determines the final mapping order and therefore each type's default track.

combined also retains chapters, arbitrary container tags, and every attachment from the source. video-to-combined carries that source-side data with the video. mux uses the video's global metadata and chapters and unions attachments from both operands.

Metadata, chapters, and attachments

Track metadata follows its track through indexed and timeline operations. Existing disposition flags such as hearing-impaired, visual-impaired, commentary, and original are preserved. Timeline operations clip, rebase, shift, or scale chapters with the media. Concatenation keeps the left container tags, appends right chapters at the left duration, and unions attachments. Attachments currently require Matroska output.

Time and stream editing

Timeline operations accept bare tracks and combined values. On a combined value they transform every video, audio, and subtitle track together.

length fails at compilation if no duration can be determined. Source durations come from ffprobe; edited durations are propagated without creating temporary media.

Combined concatenation requires equal video, audio, and subtitle counts on both operands. Subtitle codecs are handled internally as plain text, ASS/SSA, or bitmap (PGS, DVD/VobSub, DVB, XSUB). Untouched compatible streams are mapped with stream copy. Edited text stays text, edited ASS/SSA stays ASS, and edited bitmap subtitles use Matroska intermediates with stream copy. Subtitle concat requires matching codecs. ASS cue ends are clipped exactly after slice and take; bitmap timing is packet-based. ASS/SSA and bitmap subtitles require Matroska output (standalone ASS is also accepted) rather than being silently converted to a lossy or incompatible representation.

Subtitle burning

Burning accepts VIDEO, not COMBINED; extract or take a video track first. Plain text and ASS/SSA are supported. Bitmap subtitle codecs such as PGS, DVD, DVB, and XSUB are rejected. Font attachments found beside the subtitle stream are extracted into a temporary libass font directory. A burn-style is a semicolon-separated list containing:

Unknown properties and malformed values fail during compilation. Styles are translated to validated libass overrides; raw ASS syntax is not accepted. On ASS/SSA, inline override tags remain part of the subtitle events.

Audio operations

Speed and fades

Speed must be greater than zero. Fades preserve stream duration. fade-out requires a known input duration so its start time can be calculated.

Arithmetic and comparisons

T must be the same type on both sides. Media values are not comparable. Division by zero, non-finite arithmetic, and negative duration results are rejected.

Conditionals

Conditionals use structured if, optional else, and end markers:

video "$1"
dup
length
duration 10s
gt
if
  duration 10s
  take
else
  # The original video remains unchanged.
end

if consumes a BOOL. Both branches begin with the same remaining stack and must leave identical stack types. Both branches are typechecked, but only the selected branch is compiled, probed, and added to the FFmpeg graph. Omitting else is equivalent to an empty false branch, so the true branch must preserve the stack shape in that case.

Conceptually, if both branches transform S into T:

S BOOL if ... else ... end -> T

Unrollable loops

Loops use Forth-style begin, while, and repeat markers:

video "$1"
scalar 0
begin
  dup
  scalar 3
  lt
while
  swap
  duration 1s
  take
  swap
  scalar 1
  add
repeat
drop

At begin, let the current stack shape be S. The condition section must transform S into S BOOL. while consumes that Boolean. The body must transform S back into exactly S before repeat. When the condition becomes false, the loop leaves S on the stack.

Loops execute during compilation and are fully unrolled into the FFmpeg graph. Consequently, every condition must be computable from literals, arithmetic, Boolean operations, and known probed media durations. There is no frame-time or sample-time control flow. A loop that attempts more than 10,000 iterations is rejected.

Programme result

A valid programme must leave exactly one VIDEO, AUDIO, SUBTITLES, or COMBINED value on the stack. Helper values such as BURN_STYLE, STRING, CHAPTER, ATTACHMENT, DURATION, INDEX, SCALAR, and BOOL cannot be final results. A combined result maps every track in per-type collection order.