Syntaxe avisynth

Revision as of 23:46, 15 February 2008

La syntaxe d'une ligne de commande d'un script AviSynth peut se présenter sous l'une de ces trois formes :

1. nom_de_la_variable = expression
2. expression
3. return expression

Dans le premier cas, expression est exécuté et le résultat de l'expression est assigné à nom_de_la_variable. Dans le second cas expression est exécuté et le résultat est assigné à la variable spéciale last. En fin dans le troisième cas, expression est évalué et le résultat de expression est la valeur du bloc courant (que le bloc en question soit une fonction ou le script en lui même) qui sera retournée. Dans le cas ou la valeur retournée est celle du script, la valeur retournée sera typiquement le clip vidéo envoyé à l'application qui ouvre le script AviSynth.

La plupart du temps, le résultat d'une expression sera un clip vidéo; Cependant AviSynth supporte plusieurs types de valeurs (clip, entiers / int, flottant / float, booléen / bool et chaîne de caractère / string ) qui peuvent être traitées par les fonctions internes d'AviSynth.

Une expression peut se présenter sous l'une de ces formes :

1. constante_numérique ou constante_string
2. nom_de_variable or propriété_du_clip
3. Fonction(argument)
4. expression.Fonction(argument)
5. expression1 opérateur expression2
6. expression_booléenne ? expression1 : expression2

Dans le premier cas, la valeur d'expression prend la valeur de la constante. Dans le second cas, expression prend la valeur correspondante à une propriété du clip ou d'une variable (dont la valeur doit avoir été préalablement définie). Dans le troisième cas, expression prend la valeur retournée par la fonction (voir ci-dessous). Le quatrième cas est une alternative à la forme fonction(expression,argument).

Les deux derniers cas montrent la syntaxe employée pour effectuer une opération arithmétique ou logique (via des opérateurs dérivés du langage C). Le premier permet de manipuler int, float, variable générique (val - voir Script variables) ou booléen. Le second permet de mettre en place des actions conditionnelles. Les chaînes de caractères peuvent être concaténées avec '+'. L'opérateur '+' peut être aussi utilisé pour assembler des vidéos : a + b est équivalent à UnalignedSplice(a, b) tandis que a ++ b est équivalent à AlignedSplice(a, b).

La majeure partie des fonctions utilisées dans AviSynth sont des filtres vidéo. Cependant une fonction peut retourner tout type de variable (ce qui peut être utile dans le cas de scripting de fonction complexe - voir script functions). Il faut cependant noter que la dernière fonction d'un script doit retourner un clip comme variable finale.

Une fonction peut avoir jusqu'à 60 arguments (vous en aurez assez?), et la valeur retournée peut être de n'importe quel type supporté par AviSynth (clip, int, float, bool, string). Functions can take up to sixty arguments (hope that's enough), and the return value can be of any type supported by the scripting language (clip, int, float, bool, string). 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 script language you must assign to it a new value.

To see the syntax of the function call for each built-in filter, view the internal filters. There are also built-in internal functions that perform common operations on non-clip variables.

Args is a list of function arguments separated by commas. The list can be empty. Each argument must be a text string, an integer, a floating-point number, a boolean value or a video clip (that is, an expression). If the filter function expects a video clip as its first argument, and that argument is not supplied, then the clip in the special last variable will be used.

AviSynth filters can take named arguments. The named arguments can be specified in any order, and the filter will choose default values for any that you leave off. 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). Colors can be specified in hexadecimal as in the example above or in decimal. In both cases it should be specified as RGB value, even if the clip itself is YUV.

You can also make function calls without parentheses, e.g. FilterName arg1, arg2. The primary reason for this is to retain compatibility with old scripts. However, it's sometimes convenient to leave off the parentheses when there's no possibility of confusion.

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

# comment

In v2.58 it is possible to add block and nested block comments in the following way:

# block comment:
/* 
comment 1
comment 2
*/

# nested block comments:
[* [* a meaningful example will follow later :) *] *]

Avisynth ignores anything from an __END__ keyword (with double underscores) to the end of the script file. This can be used to disable some last commands of script.

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

Avisynth ignores case: aViSouRCe is just as good as AVISource.

Multiple Avisynth statements on a single line can only be achieved in the context of OOP notation or embedding filters as parameters of another function such as:

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

Avisynth 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 accross 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.