Grammar

Revision as of 20:15, 31 January 2016

Statements, Expressions, Types and Operators

All basic AviSynth scripting statements have one of these forms:

1. variable_name = expression
2. expression
3. return expression

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

• In the first form, expression is evaluated and the result is assigned to variable_name.
• In the second form, expression is evaluated and the result, if a clip, is assigned to the special variable Last.
• In the third form, 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.

An Expression can have one of these forms:

1. constant
2. variable_name or clip_property_name
3. function_name ( argument_list )
4. expression . function_name ( argument_list )
5. expression1 operator expression2
6. expression1 ? expression2 : expression3

• In the first form, the value of the expression is the value of the (numeric, string or boolean) constant—a literal value such as '42'.
• In the second form, the value equals the value of the specified variable or clip property (possibly undefined).
• In the third form, the value is the return value of a function (see below).
• The fourth form is an alternate syntax called "OOP notation" in AviSynth:

expression . function_name ( argument_list ) is equivalent to

function_name ( expression , argument_list )

• The fifth form has an operator; 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.
• 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)

• The sixth form 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.

Functions, Filters and Arguments

Functions in AviSynth are usually also Filters (functions that return a clip). Although a function can return any type it chooses, functions which do not return a clip are only used for intermediate processing. The script should always return a clip as its final value. After all, AviSynth is a video processing application.

Functions can take up to sixty arguments (hope that's enough), and the return value can be of any Avisynth type (clip, int, float, bool, string).

The term parameter is often used interchangeably with the term argument; while this usage is not strictly correct, it happens—even on this Wiki.

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.

To see the usage syntax for each built-in filter, see the internal filters page. There are also many useful non-clip-returning internal functions.

argument_list (see Expression, forms 3 and 4) is a list of function arguments separated by commas. Each argument must be an expression whose type matches the parameter type in the function's definition.

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.

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.

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

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)

Back to AviSynth_Syntax.