Runtime environment

From Avisynth

(Redirected from Scripting at runtime)
Jump to: navigation, search

Contents

[edit] Definition

The runtime environment is an extension to the normal AviSynth script execution environment that is available to scripts executed by runtime filters. Its basic characteristic is that the runtime filters' scripts are evaluated (executed) at every frame. This allows for complex video processing that it would be difficult or impossible to be performed by a normal AviSynth script.

Lets now look at the above definition in a more detailed level. The runtime environment is:

  1. An environment, that is a set of available local and global variables and filters / functions to be used by the script.
  2. An extension to the normal AviSynth script execution environment; that is there are additional variables and functions available to runtime scripts.
  3. Available to scripts executed by runtime filters only, that is scripts inside it are executed only during the AviSynth "runtime" (the frame serving phase).

The later is the biggest difference. Normal script code is parsed and evaluated (executed) at the start of the script's execution (the parsing phase) in a linear fashion, from top to bottom; the result is the creation of a filter graph that is used by AviSynth to serve frames to the host video application. Runtime script code is executed after the parsing phase, when frames are served. Moreover it is executed on every frame requested and only for that specific frame, in an event-driven fashion.

Note: Audio is not handled by the runtime environment; it is passed through untouched. This also means that you cannot modify clip audio with runtime filters.

[edit] Runtime filters

The following filters are the basic set of the so-called "runtime filters":

  • ConditionalFilter: Selects, on every frame, from one of two (provided) filters based on the evaluation of a condition.
  • ScriptClip: Executes arbitrary script code on every frame and returns a clip.
  • FrameEvaluate: Executes arbitrary script code on every frame but the filter's output is ignored.
  • ConditionalReader: Loads input from an external file to a selectable variable on every frame.

In addition, the WriteFile filter -although not giving the ability to execute runtime scripts- can also be considered a runtime filter, because it sets the special variables set by all runtime filters before evaluating the expressions passed to it.

[edit] Special runtime variables and functions

All runtime filters set and make available to runtime scripts the following special variables.

  • last: The clip passed as argument to the filter
  • current_frame: The framenumber (ranging from zero to input clip's Framecount minus one) of the requested frame.

There are also a few runtime filters that set and make available to runtime scripts some additional variables.

  • current_sample: The approximate starting audio sample number of the requested frame. ScriptClip and FrameEvaluate only.

All the above variables are defined at the top-level script local scope. That is you read and write to them in a runtime script as if they where variables that you declare at the script level.

Runtime scripts can also call a rich set of special functions that provide various pieces of information for the current frame of their input clip.

[edit] How to script inside the runtime environment

Creating a runtime script is easy: you use one of the runtime filters and supply it with the needed arguments. Among them, two are the most important:

  • The input clip
  • The runtime script

The later is supplied as a string argument which contains the AviSynth script commands. Scripts can contain many statements (you can use a multiline string), local and global variables and function calls, as well as special runtime functions and variables. In general all statements of the AviSynth syntax are permitted, but attention must be paid to avoid overly complex scripts because this has a penalty on speed that is payed at every frame. See the runtime section of scripting reference's performance considerations for details.

Lets see a few examples: 

TODO...EXAMPLES
  • Runtime functions and variables, such as current_frame, AverageLuma(), etc., are available only at the runtime script's scope. To use them in a function you must pass them as arguments.
  • You can include an explicit return statement in your runtime script to return a clip that is not contained in the special last variable.
Retrieved from "http://avisynth.org/mediawiki/Runtime_environment"
Personal tools