Grammar

Revision as of 18:48, 24 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 Avisynth Type (clip, int, float, bool, string) – these are sometimes called utility functions. A list of built-in utility functions can be found here.

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. numeric_constant or string_constant or boolean_constant
2. variable_name or clip_property_name
3. function_name ( argument_list )
4. expression . function_name ( argument_list )
5. expression operator expression
6. boolean_expression ? expression : expression

• In the first form, the value of the expression is the value of the constant.
  (syntactically, a constant is indistinguishable from a variable; by convention, you set the value of a constant once and once only)
• 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; 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 sixth form supports conditional execution with the ternary operator.

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 of the function call 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. The list can be empty. Each argument must be an expression whose type matches the one expected by the function. 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.

Function definitions may specify an additional argument "type": var, which accepts any of the AviSynth types.

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 the filter will choose default values for any that you leave off (they will be undefined within the function body). This makes certain filters much easier to use. For example, you can now write

Subtitle("Hello, World!", text_color=$00FF00, x=100, y=200)

instead of

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

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.

If no arguments are passed to the function, you can omit the parentheses:

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

versus

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

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 the '[* ... *]' style nested block comment in this situation:

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

Back to AviSynth_Syntax.