Grammar

Revision as of 18:32, 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 case, expression is evaluated and the result is assigned to variable_name.
• In the second case, expression is evaluated and the result, if a clip, is assigned to the special variable Last.
• In the third case, 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 case, 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 case, the value equals the value of the specified variable or clip property (possibly undefined).
• In the third case, the value is the return value of a function (see below).
• The fourth case is an alternate syntax called "OOP notation" in AviSynth:

expression . function_name ( argument_list ) is equivalent to

function_name ( expression , argument_list )

• The fifth case contains an arithmetic or logical 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 case 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 parameters of 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 already has. Although it is conventional to use newlines to separate statements (and good practice for readability), the syntax 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 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 at hard to trace bugs.

Example of a not-signaled bug 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.

Back to AviSynth_Syntax.