ConditionalReader

Import information from a text file and assign a per-frame value to a script variable.

Syntax and Parameters

ConditionalReader(clip clip, string filename, string variablename [, bool show ] )

clip  clip =

Source clip. Not touched, unless you specify show=true.

string  filename =

Path to the file with the per-frame values you want to set. See File format below.

string  variablename =

Name of the variable you want the filename values assigned to.

bool  show = false

If true, show the variablename value at the current frame (as determined by the file values) as a text overlay.

File format

• The file is plain text. It is not case sensitive. Each line stands alone. There are several different line types, as explained below.

• The file may begin with one or more optional comment lines:

Any line is ignored if the first non-whitespace character is '#' (hash), ';' (semicolon) or '%' (percent).

#this line is a comment
;so is this line
     %and this one too.

• The first non-comment line must be a type line, being one of the following:

TYPE int

(ints are the digits 0-9, optionally preceded with a '+' or '-' sign)

TYPE float

(like int but containing a '.' decimal separator, and optionally followed by an 'e' or 'E' character plus an int exponent)

TYPE bool

('true' or 'false')

TYPE string (from v2.60)

(any sequence of characters representing text)

The type line defines the data type to be parsed from this file and assigned to the variable variablename. You must have one, and only one, type line per file, and it must come before any other lines, except for optional comments.

• The header comes next, and consists of the following lines in any order:

Optional default line:

DEFAULT <value>

This specifies the default value to be assigned to the script variable if there is no data line defining a value for a given frame. If you do not define a default, you must be sure to specify a setting for all frames; or you will get unexpected results.

Optional offset line:

OFFSET <value> (from v2.60)

When specified, this will add an offset to all frame numbers in the data lines below.

Optional comment and empty line(s)

• Next come the data line(s), which set the per-frame value(s) to be assigned to the script variable. There are three styles:

Single-frame data line:

<framenumber> <value>

Set value for frame framenumber only.

Range data line:

R <startframe> <endframe> <value>

Apply value to a range of frames.

Note that both startframe and endframe are included.

Interpolated data line:

I <startframe> <endframe> <startvalue> <stopvalue>

Interpolate between two values over a range of frames. This only works on int and float types.

Note that both startframe and endframe are included.

Values must be valid for the defined type, as defined above, or file parsing will fail and an error will be raised.

To sum up the file format in approximate BNF-style:

input_file:
    comment_line*   /* asterisk means zero or more */
    WS* 'TYPE' WS ( 'int' | 'float' | 'bool' | 'string' ) /* choose one */
    header
    data_line+      /* plus sign means one or more */

comment_line:
    WS* ( '#' | ';' | '%' ) <ignore any characters to end of line>

WS: 
    ( ' ' | '\t' )+ /* WS = one or more spaces or tabs */

header:             /* header = zero or more of the following in any order */
(
    WS* 'DEFAULT' WS <type value>       /* legal value for TYPE */
  | WS* 'OFFSET' WS <int offset_value>
  | WS*
  | comment_line
)*

data_line:          /* data = one or more of the following in any order */
(
    WS* <int framenumber> WS <type value>
  | WS* 'R' WS <int startframe> WS <int endframe> WS <type value>
  | WS* 'I' WS <int startframe> WS <int endframe> WS <type startvalue> WS <type endvalue>
)

Examples

Basic usage

Example file File.txt:

Type float
Default 3.45567

R 45 300 76.5654
2 -671.454
72 -671.454

The file above will return values of type float. It will return 3.45567 by default, but at frames 45-300 it will return 76.5654, and at frames 2 and 72 it will return -671.454.

Later lines in the file overrule earlier ones. This is illustrated by the '72' line: even though frame 72 is inside the range of 45-300, frame 72 will use the value -671.454, not 76.5654. If the 'R' line had been placed after the '72' line, the range value would have had priority.

A script to invoke this file could be:

ColorBars(512,512)
Trim(0,500)
ScriptClip("subtitle(string(myvar))")
ConditionalReader("file.txt", "myvar", false)

This will put the values into the variable called myvar, which is displayed with Subtitle. Subtitle must be invoked by ScriptClip to display the conditional value.

Adjusting Overlay

Script:

ColorBars(512,256)
a1 = Trim(0,600)
a2 = MessageClip("Text clip")
Overlay(a1,a2, y = 100, x = 110, mode="subtract", opacity=0, pc_range=true)
ConditionalReader("opacity.txt", "ol_opacity_offset", false)
ConditionalReader("xoffset.txt", "ol_x_offset", false)

File xoffset.txt:

Type int
Default -50

I 25 50 -50 100
R 50 250 100
I 250 275 100 250

File opacity.txt:

Type float
Default 0.0

I 25 50 0.0 1.0
R 50 250 1.0
I 250 275 1.0 0.0

Basically this example defines keyframes for an Overlay x-offset and opacity. For frames 25-50 the opacity is scaled from 0.0 to 1.0, while the text is moving from left to right. The text is then kept steady from frame 50-250, and thereafter it moves further to the right while fading out. It is easier to watch the clip above than completely describe what it does.

Complicated ApplyRange

As you may have noticed, using a large number of ApplyRange calls in a script can lead to resource issues. Using ConditionalReader together with ConditionalFilter can lead to an efficient solution:

File File.txt:

Type Bool
Default False

2 True
R 45 60 True
72 True
R 200 220 True
210 False
315 True

The file above will return boolean values. It will by default return False. However frames 2, 45 to 60, 72, 200 to 220 and 315 except for 210 it will return True. As you might notice, later changes overrule settings done earlier in the file. This is illustrated by frame '210' - even though it is inside the range of 200-220, the later value, False, will be returned.

A script to make use of this file could be:

ColorBars(512,512)
Trim(0,500)
A = Last
FlipHorizontal # Add a complex filter chain
B = Last
ConditionalFilter(A, B, "MyVar", "==", "False", false)
ConditionalReader("File.txt", "MyVar", false)

This will put the values into the variable called MyVar, which is used by ConditionalFilter to select between the unprocessed and flipped version of the source.

Note! The ConditionalReader line comes after any use of MyVar in the script.

Returning Strings

ConditionalReader cannot return strings prior to v2.60, but one solution is to create a list of variables with corresponding string assignments, and Eval the indexed solution. For example:

Import("strings.txt")
ScriptClip("""subtitle(Eval("n"+string(mystringindex)))""")
ConditionalReader("range_string.txt", "mystringindex")

File strings.txt

n0=""
n1="Intro"
n2="Main"
n3="Credits"

File range_string.txt

Type int
Default 0

R 10 1000 1
R 1005 3000 2
R 3200 3800 3

Obviously strings.txt does not need to be a separate file, but this solution is sometimes appropriate in e.g., multilingual applications:

language="spanish" 
Import(language + "_strings.txt")

Changelog

v2.60

Added OFFSET, Added Type=string.