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

Extracting or editing one stream never modifies the other stream in a COMBINED value.

Time and stream editing

These operations accept either video or audio where shown, but never subtitles or combined values.

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

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, or COMBINED value on the stack. SUBTITLES, DURATION, SCALAR, and BOOL cannot be final results. A combined result maps video and audio separately; attached subtitles are mapped as an additional output stream.