Grammar

[edit] Statements, Expressions, Types and Operators

All basic AviSynth scripting statements have one of these forms:

1. variable_name = expression

   expression is evaluated and the result is assigned to variable_name.

2. expression

   expression is evaluated and the result, if a clip, is assigned to the special variable Last.

3. return expression

   expression is evaluated and is used as the return value of the active script block (function), or the entire script.

   As a shorthand, if return is not present in the final executable statement of a script (or script block), it is implied – the statement is treated as if return was present.

Most of the time the result of an expression will be a video clip; however an expression's result can be any type supported by AviSynth (clip, int, float, bool, string) and this is how utility functions such as Internal script functions operate.

If the return value of the script is a clip, which is the normal case, it can be "played" as a video by a frameserving client.

► Two higher-level constructs also exist - the function declaration (dicussed below) and the try..catch statement.

► GScript, a support plugin, extends the language to include if–else, for and while loops; AVS+ has native support of GScript.

An Expression can have one of these forms:

1. constant

   The value of the expression is the value of the (numeric, string or boolean) constant—a literal value such as '42'.

2. variable_name or clip_property_name

   The value equals the value of the specified variable or clip property (possibly undefined).

3. function_name ( argument_list )

   The value is the return value of a function (see below).

4. expression . function_name ( argument_list )

   This alternate syntax is called "OOP notation" in AviSynth:

   expression . function_name ( argument_list ) is equivalent to

   function_name ( expression , argument_list ).

5. expression1 operator expression2

   AviSynth operators are discussed here; in addition to the normal math operators you would expect, there are several special operators; for example,

   • strings can be concatenated (joined together) with '+', and compared with relational operators like '>='.
   • video clips can be spliced (joined together) with '+':

   a + b is equivalent to UnalignedSplice(a, b)

   a ++ b is equivalent to AlignedSplice(a, b).

   The value of the expression will depend on the specific operator; for example,

   • the value of string + string is the concatenated string
   • the value of string == string is a boolean (true/false) value (it is a boolean expression).

6. expression1 ? expression2 : expression3

   Supports conditional execution with the ternary operator;

   • If the value of expression1 evaluates to true, the value of the whole expression is the value of expression2; otherwise it is the value of expression3
   • If expression1 is true and expression2 is a function, that function will be executed. This is the main method of code branching in AviSynth.

   For more on ternary operators, see The Conditional (or Ternary) Operator (cplusplus.com)

► Incidentally, Avisynth ignores case: avisource or aViSouRCe is just as good as AVISource.

► As a special case, comparisons may be chained:

(3 <= x <= 5) can be used where normally something like

(3 <= x && x <= 5) would be required.^(doom9)

[edit] Functions, Filters and Arguments

All functions take one or more inputs, do some processing, and return a value. The return value can be of any Avisynth type: clip, int, float, bool or string. A filter in AviSynth is simply a function that processes audio/video information, normally returning a clip.

A function must have a declaration: the function keyword, a name, an argument list (see below), an opening brace '{', one or more statements, and a closing brace '}':

function UsefulFunction(int a, int b) 
{
    return a + b
} 

function UsefulFilter(clip C) 
{ 
    C
    Invert
    return Last
}

Functions always produce a new value and never modify an existing one. What that means is that all arguments to a function are passed by value and not by reference; in order to alter a variable's value in AviSynth, you must assign it a new value.

Not all functions are typed into your script (or another script that has been imported); some, listed here, are built into AviSynth itself, while others, listed here, are packaged in external plugins. There are also many useful non-clip-returning internal functions, described here. More about creating your own user-defined functions can be found here.

Functions get their input from arguments (and global variables). An argument must have a type and a name. An argument_list is a list of arguments, separated by commas. The list can contain up to sixty arguments (hope that's enough). When the function is called, argument values must be supplied (ignoring optional named arguments for the moment – see below). Each argument the caller supplies must be an expression whose type matches the declared type in the argument list.

function UsefulFunction(int a, int b) 
{
    return a + b
} 
ColorBars

## All these function calls result in a script that fails to load;
## the error message is: 
##    Invalid arguments to function "UsefulFunction"
#c = UsefulFunction()               ## not enough arguments
#c = UsefulFunction("ted", "alice") ## wrong argument types
#c = UsefulFunction(5, 3.141)       ## 2nd argument type wrong

## This call works correctly - both arguments match the declaration:
u = UsefulFunction(5, 11)
Subtitle(String(u))
return Last

If the function expects a video clip as its first argument, and that argument is not supplied, then the clip in the special variable Last will be used.

ColorBars
Invert() ## built-in filter expects a clip argument

The list can be empty. If so, you can omit the parentheses:

AviSource("my.avi").AssumeFrameBased.AssumeTFF.SeparateFields

versus

AviSource("my.avi").AssumeFrameBased().AssumeTFF().SeparateFields()

Function definitions may specify an additional argument type: var, which accepts any of the AviSynth types. It is up to the function to determine the argument's actual type using functions such as IsClip, before attempting to use it.

Any variable_name which has never been assigned a value is an undefined variable. Undefined variables may be passed to functions, which in turn can determine their status with the Defined function.

Functions can take named arguments. Named arguments can be specified in any order, and they are always optional–the function should set default values for any that you leave off (the Default function is useful for this). This makes certain filters much easier to use. For example, instead of

Subtitle("Hello, World!", 100, 200, 0, Framecount-1, "Arial", 18, $FFFF00, $0, 7, 0, 0, 0, 0, false)

you can say

Subtitle("Hello, World!", x=100, y=200)

The result is the same; all missing arguments are set by default.

By the way, colors can be specified in hexadecimal as in the example above, or in decimal. They may be specified as an RGB value, even if the clip itself is YUV. They may also be specified by name using one of the preset colors, eg color_yellow.

[edit] Comments

Avisynth ignores anything from a '#' character to the end of that line. This can be used to add comments to a script.

# this is a comment

It is possible to add block and nested block comments in the following way:

/* 
this is a
block comment
*/

/* this is a
    block comment
  [* this is
     a nested comment
     [* and another one *]
  *] 
*/

Avisynth ignores anything from the __END__ keyword (with double underscores) to the end of the script file.

Version()
__END__
ReduceBy2()
Result is not reduced and we can write any text here

[edit] Line breaks and continuation

Multiple statements on a single line can be made with OOP-style (dot) notation, or by embedding filters as arguments to another function:

AviSource("c:\video.avi").Trim(0, 499)
-or-
AudioDub(AviSource("c:\video.avi"), WavSource("c:\audio.wav"))

The parser recognises it has reached the end of a statement when the next symbol is not a valid continuation of what it parsed so far; the next symbol it encounters begins a new statement. Although it is conventional to use newlines to separate statements (and good practice for readability), the grammar is such that it is only strictly necessary if the following statement starts with a unary minus (or plus) operator. See Multiple statements on a single line @ doom9.org

For example:

x = 1  y = 2  z = 3 

Statements can be split across multiple lines by placing a backslash ('\') either as the last non-space character of the line being extended, or as the first non-space character on the next line.

Line splitting examples (both valid and equal):

Subtitle("Hello, World!", 100, 200, 0, \
  999999, "Arial", 24, $00FF00)

-or-

Subtitle("Hello, World!", 100, 200, 0,
  \ 999999, "Arial", 24, $00FF00)

When splitting across multiple lines you may place '#'-style comments only at the end of the last line. Mixing comments with backslashes at an intermediate line of the line-split will either produce an error message or result in hard-to-trace bugs.

Example of a silent bug (no error is raised) by improper mixing of comments and line separation:

ColorBars
ShowFrameNumber
Trim(0,9) # select some frames  \
  + Trim(20,29)

The above example does not return frames [0..9, 20..29] as intended because the '\' is masked by the '#' character before it; thus the line continuation never happens.

However you may use block comments in this situation:

ColorBars
ShowFrameNumber
Trim(0,9) [* select some frames *] \
  + Trim(20,29)

[edit] For More Information

For a longer explanation, see The Full AviSynth Grammar.