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.

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 timeline edits and concatenation are rendered through temporary subtitle stages before final output.

Subtitle burning

Burning accepts VIDEO, not COMBINED; extract or take a video track first. Bitmap subtitle codecs such as PGS, DVD, DVB, and XSUB are rejected. 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.

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. BURN_STYLE, DURATION, INDEX, SCALAR, and BOOL cannot be final results. A combined result maps every track in per-type collection order.