Script variables

From Avisynth wiki
Jump to: navigation, search

"String" redirects here. For the String() conversion function, see Internal functions: String

"Val" redirects here. For the Value() conversion function, see Internal functions: Value


In computer programming, a variable is a storage location, which contains some information referred to as a value, paired with an associated symbolic name.(1)  This page shows how to use variables in a script. It also describes the types of data that scripts can manipulate, and how literals (constants) of those types are written.

Variable Names

A variable name may be made of (English) letters, digits, and underscores (_), but no other characters. The name cannot start with a digit. The name can be of practically any length – more than 4000 characters. Variable names are not case-sensitive.

You may use characters from your language system code page (ANSI 8 bit only, not Unicode) in string literals (see below) and file names, but variable names are restricted to the ASCII characters A-Z, a-z, 0-9 and _ (underscore).

A variable's placement in an expression is determined by the AviSynth Syntax.

Variable Types

Variables can have a value of one of the following types:

  • clip
A clip holds the video and/or audio content; all frameserving scripts (there are other types, such as function library scripts) must return a value of type clip. Clips also have properties, such as Width, Height and FrameRate.
  • string
A sequence of characters representing text. String literals are written as text surrounded either by "quotation marks" or by """triple quotes""". The text can contain any characters (including line breaks) except the terminating quotation mark or triple-quote sequence.
\ align=5)
Subtitle("Current frame = " + String(current_frame), 
\ align=5)
  • To put a quotation mark inside a string, you need to use the triple-quote form as shown above.
  • Alternatively, you can use curly-quotes to get around this limitation.
  • Embedded quotes may also be included with Chr(34).
  • int
An integer (32 bits, signed). An integer literal is entered as a sequence of digits, optionally with a + or - at the beginning. The value can be given in hexadecimal (often used for color values) by preceding it with a $ character. For example $FF as well as $ff (case does not matter) are equal to 255. See also: Numeric Functions.
  • float
A single-precision, floating-point number. Literals are entered as a sequence of digits with a decimal point (.) somewhere in it and an optional + or -. For example, +1. is treated as a floating-point number. Note that exponent-style notation is not supported. See Also: Numeric Functions.
  • bool
Boolean values must be either true or false. In addition they can be written as yes or no, but you should avoid using these in your scripts (they remain for compatibility purposes only). See also: Boolean Functions.
  • val
A generic type name. It is applicable only inside a user defined script function's argument list, in order to be able to declare an argument variable to be of any type (int, float, bool, string, or clip). You must then explicitly test for its type (using the boolean functions) and take appropriate actions.

There is another type which is used internally by Avisynth - the void or 'undefined' type. Its principal use is in conjunction with optional function arguments. See the Defined() function.

Declaring a New Variable

To declare a variable, simply type the variable name, followed by '=' (an equals sign), followed by its initial value. The type must not be declared; it is inferred by the value assigned to it (and can actually be changed by subsequent assignments). The only place where it is allowed to declare a variable's type (though not strictly required) is in user defined script function's argument lists. Examples:

b = false      ## declare a variable 'b' of type 'bool' and initialize it to 'false'
x = $100       ## type int (initial value is in hexadecimal)
y = 256        ## type int (initial value is in decimal)
global f = 0.0 ## type float declared globally (see Global Variables below)

## declaring function arguments (last one is optional):
function MyFilter(clip c, int new_color, float amount, val "userdata") { ... }
Global Variables

Variables can be either local (bound to the local scope of the executing script block) or global. Global variables are bound to the global script environment's scope and can be accessed by all Internal functions, User defined script functions, runtime environment scripts and the main script also.

To declare and/or assign a value to a global variable you must precede its name with the keyword global at the left side of the assignment. The keyword is not needed (or allowed) in order to read the value of a global variable. Examples:

## declaring global variables
global canvas = BlankClip(length=200, pixel_type="yv12")
global stroke_intensity = 0.7
global canvas = Overlay(canvas, pen, opacity=stroke_intensity, mask=brush)
## using a global variable inside a user function
function MyFunction(clip c)
    (testbool ) ? FlipHorizontal : FlipVertical
    return Last

Subtitle("ABCDEFG", size=Height/8, align=5)

testbool = true ## wrong - not global
return MyFunction
## "Error: I don't know what 'testbool' means"

global testbool = true ## right 
return MyFunction
## works as expected

1. Variable (computer science) (wikipedia)

Back to AviSynth Syntax.

Personal tools