Value Tester (updated)

Filter: PieroF_Value_Tester_v2.6.fxscript.zip: (click the link to Download)

Generator: PieroF_Value_Tester_Generator_v2.6.fxscript.zip: (click the link to Download)

What does it do ?

Value Testers are tools mainly dedicated to fxscript code developers: they display the values of many predeclared variables and functions that are made available by FCE and FCP to filters and generators. This information is a support for debugging filters and generators.

The filter version of the Value Tester returns values that FCE/FCP makes available in filters; these values may be partially different from the corresponding values returned in generators by the same fxscript variables and functions. These are returned by the generator version of the Value Tester.

This filter allows to enable or disable the display of each single parameter, and to customize the text color and size, and its background opacity.


In the above example the Value Tester filter shows that the sequence runs at 25 fps and it is processed by FCE on a field by field basis (fieldprocessing = 1) and has Field Dominance = Lower(Even); in addition the clip duration is 146 fields (= 73 frames), while the playhead is currently parked over the last frame #72 and field #145 is displayed. Its pixel aspect ratio is 1,0667 (i.e. PAL CCIR 601 for 4:3 frames), its frame resolution is 720x576, while the current internal buffer resolution is 720x288 (i.e. a single field).

TV System may display whether the movie is PAL, NTSC or HD, but only when the sequence is not rendered; when rendered (as in the figure above) the n/a info is displayed.

The Value Tester generator shows very similar parameters (see below for details) but all referred to the sequence where the generator is inserted. Clip1 parameters are not available in the generator.

Note that some of the above values can also be read in the clip property window (using -9) or deduced from them, while other parameters are only available, or get different values, in the plugin code: AspectOf (a compound value of pixel aspect and fieldprocessing info), renderRes (ratio between final output buffer width and internal buffer width), GetPixelFormat (color space for video processing in use), srcType1, etc. provide very fundamental information for coding a plugin, but are not visible in the property window.

In the above figure there are a few parameters displayed in the right half of the frame; these are field specific parameters and usually appear in pair: a value for the 1st field in the left half of the frame, and a value for the 2nd field in its right half. In the figure only the parameters for the 2nd field are displayed because in FCE and FCP the canvas displays only the top field (2nd field in this example where Dominance = Lower(Even)) when its zoom is different from 100%.

Instead, when the zoom is 100%, both fields are displayed simultaneously as in the figure below (and may create the “comb effect” when objects move...):


Here you can see that the field specific parameters are displayed for both fields of the the frame: on the left, the parameters for the 1st field show that this is the bottom field (topfield (F,T) = false), on the right the parameters for the 2nd field show that this is the top field (topfield (F,T) = true): this is consistent with the fact that the sequence has Field Dominance = Lower(Even). In the example the last frame is displayed including field #144 (1st field = frame #72.0) and field #145 (2nd field = frame #72.5) out of 146 fields (duration) numbered from #0 to #145. Frame numbering is from #0 to #72 for a total of 73 frames.

Compatibility, Disclaimer

This Value Tester filter has been tested in Final Cut Express 4 and Final Cut Pro 6, but it will likely work also in other versions of FCE and FCP as long as they provide support for the fxscript scripting language (see also the Disclaimer).

Version History

v2.6 - many improvements - added the generator - added previewing, input well, duration offset...

v2.3 - added Align to Bottom - minor fixes.

v2.2 - added GetNativeAspect - made GetPixelFormat field dependent.

v2.1 - bug fix fieldprocessing.

v2.0 - first release - in pf-toolkit.

Plugin Usage

After its Installation drag the filter Value Tester v2.6 from the Video Filter > pf-toolbox folder in Effects into the Viewer on the clip you want to apply it to, or (for the generator) select pf-toolbox > Value Tester Generator v2.6 from the generator menu in the Viewer window to create a new clip; then select the parameters you want to display. For a summary description of the displayed variables and their meaning, look at the following sections.

In general a single occurrence of Value Tester is sufficient to read the necessary parameters of the clip.

If you need to read the values resulting from applying any filter to a clip, position the Value Tester filter below that filter in the same clip (in the Video Filters section of the Viewer).

You can also apply this same filter twice in the same clip, before and after another filter to test: in this case make sure you set the Indent Output control on the second occurrence, to be able to read the values of both occurrences. In the example on the right the Channels v0.0 filter is packed between 2 occurrences of the Value Tester to read the parameters before and after its application.

Mode controls:

  1. •Select (default: manual): it helps in selecting the parameters to be displayed.

  2. ‣manual: the following list of checkboxes determines whether a parameter is displayed or not;

  3. ‣Frame Timing: all Frame Timing (t-type) parameters are displayed and all Frame Format (a-type) parameters are not displayed, independent of the their checkbox settings; the General Parameters (TV System, fieldprocessing and Field Dominance) are also displayed;

  4. ‣Frame Timing Plus: all Frame Timing (t-type) parameters are displayed, independent of the their checkbox settings; the General Parameters (TV System, fieldprocessing and Field Dominance) and the Frame Format (a-type) parameters are also displayed if selected;

  5. ‣Frame Format: all Frame Format (a-type) parameters are displayed and all Frame Timing (t-type) parameters are not displayed, independent of the their checkbox settings; the General Parameters (TV System, fieldprocessing and Field Dominance) are also displayed;

  6. ‣Frame Format Plus: all Frame Format (a-type) parameters are displayed, independent of the their checkbox settings; the General Parameters (TV System, fieldprocessing and Field Dominance) and the Frame Timing (t-type) parameters are also displayed if selected;

  7. ‣System Info: only TV System and Field Dominance are displayed; no fieldprocessing, no Frame Timing (t-type) and no Frame Format (a-type) parameters is displayed;

  8. ‣System Info Plus: TV System and Field Dominance are always displayed; fieldprocessing, Frame Timing (t-type) and Frame Format (a-type) parameters also displayed if selected.

  9. •Indent Output (default: OFF): when ON the output lines are shifted both right and down to allow to display 2 different occurrences of this filter applied to the same clip; one occurrence must have the Indent Output OFF and the other ON. Using 2 different Font Colors may also help in identifying the 2 different displays in the same frame.

  10. •Align to bottom (default: OFF): when ON the output lines are aligned to the bottom of the frame; otherwise they are aligned to the top of the frame.

General Parameters Selection:

  1. •TV System (default: ON): when ON the TV System (seq): aaa and previewing: n on the same line are displayed based on the clip or sequence format.

  2. If the sequence is rendered TV System (seq): n/a is displayed, otherwise aaa returns info about the hosting sequence: NTSC, PAL or HD followed by the frame aspect and its frame rate (i50, i60, p24, p25, p30, p50, or p60) depending on the sequence pixel aspect, buffer size and fps.

  3. n for previewing may be 0 (RENDERED) after the clip is rendered, or during playback of an unrendered section (Unlimited RT); 1 (unrendered) when the clip is paused and not rendered. Note that TV System is meaningful only when previewing = 1 (unrendered).

  4. •fieldprocessing (default: ON): when ON the line fieldprocessing (AspectOf(dest)): n(m) is displayed. The 2 values n and m (both in the range 0, 1) indicate: n = the value of the predefined internal variable fieldprocessing, m = lnAspect as evaluated from the predeclared function AspectOf(dest). In filters the 2 values should always be equal, while in generators may be different (namely when rendered in an interlaced sequence).

  5. •Field Dominance (default: ON): when ON the line Field Dominance: aaa is displayed, where aaa may be “Lower(Even) - 2nd field is topfield”,  “Upper(Odd) - 1st field is topfield” if the sequence is interlaced, or “None” if the sequence is progressive; this depends on the predeclared variables fieldnumber and topfield.

Frame Timing Parameters Selection:

  1. With the exception of systime (a system wide info) and fps (a sequence info), the following controls refer only to the clip (and not the hosting sequence) both in the filter and the generator version of the Value Tester.

  2. t-clip1 glDuration/glOffset (as any other control, referring to clip1/src1) is available only in the filter version, and not in the generator version.

  3. Note: in all the following description for Timing and Format parameters lnAspect(dest) it’s a shorthand for Integer(AspectOf(dest)+0.7) and lnAspect(clip1) it’s a shorthand for Integer(GetNativeAspect(clip1)+0.7): their value is either 1 or 2 depending whether the dest or clip1 buffer is a frame (1) or field (2) buffer.

  4. •t-systime (default: ON): when ON the line systime: nnn.nnnn is displayed, where nnn.nnnn is the predeclared variable systime. Since this value is different in each field, 2 values are displayed on the same line: for the 1st field on the left, and for the 2nd field on the right (only when the canvas zoom = 100%, else only the 2nd field value is displayed).

  5. •t-fieldnumber (default: ON): when ON the line fieldnumber (1,2): n is displayed, where n is the predeclared variable fieldnumber. Since this value is different in each field, 2 values are displayed on the same line: fieldnumber (1,2): 1 on the left, and fieldnumber (1,2): 2 on the right (only when the canvas zoom = 100%, else only the right value is displayed).

  6. •t-topfield (default: ON): when ON the line topfield (F,T): a is displayed, where a is True if the predeclared variable topfield=1 or False if topfield=0. Since this value is different in each field, 2 values are displayed on the same line: for the 1st field on the left, and for the 2nd field on the right (only when the canvas zoom = 100%, else only the right value is displayed).

  7. •t-ratio (default: ON): when ON the line ratio: nnn.nn% is displayed, where nnn.nn% is the predeclared variable ratio. Since this value is different in each field, 2 values are displayed on the same line: for the 1st field on the left, and for the 2nd field on the right (only when the canvas zoom = 100%, else only the right value is displayed).

  8. •t-frame (default: ON): when ON the line frame (frames): nnn.nn (mmm.mm) is displayed, where nnn.nn is the predeclared variable frame, and mmm.mm = frame / lnAspect. The first value is the number of fields or frames for the current position, depending on the fieldprocessing and previewing value. The second value is usually a number of frames for the current position. Since this value is different in each field, 2 pairs of values are displayed on the same line: for the 1st field on the left, and for the 2nd field on the right (only when the canvas zoom = 100%, else only the 2nd field value is displayed).

  9. •t-duration (default: ON): when ON the line duration (frames): nnn (mmm.mm) is displayed, where nnn is the predeclared variable duration, and mmm.mm = duration / lnAspect. The first value is the total number of fields or frames in the clip (from IN to OUT), depending on the fieldprocessing value. The second value is always the total number of frames; so, if fieldprocessing=0 nnn = mmm.00.

  10. •t-clip1 glDuration/glOffset (default: ON): when ON the line clip1 glDuration-glOffset (frames): nnn - mmm is displayed where nnn = clip1Duration and mmm = clip1Offset are the values returned by the predeclared function GetLimits (clip1, clip1Duration, clip1Offset)

  11. •t-fps (default: ON): when ON the line fps (seq)(frames): nn.nn is displayed, where nn.nn is the predeclared variable fps, which returns the frames per second for the sequence hosting the clip.

Frame Format Parameters Selection:

  1. Among the following controls a-srcType1 and a-clip1 buffer W x H are available only in the filter version, and not in the generator version.

  2. In addition the generator version does not display info about clip1 and src1, that are instead available in the a-lnAspect, a-pxAspect, a-renderRes, and a-src1/dest buffer W x H.

  3. •a-srcType1 (default: ON): when ON the line srcType1: aaa is displayed, where aaa is based on the predeclared variable srcType1. kNone is displayed if srcType1 = -2, kAlpha if -1, kBlack if 0, kWhite if 1. Since this value might be different in each field (even if this case is meaningless...), 2 values are displayed on the same line: for the 1st field on the left, and for the 2nd field on the right (only when the canvas zoom = 100%, else only the right value is displayed). (only in the filter version).

  4. •a-GetPixelFormat(dest) (default: ON): when ON the line GetPixelFormat(dest): aaa is displayed, where aaa shows the color space used for video processing, and is based on the value returned by the predeclared function GetPixelFormat. RGB255 is displayed if GetPixelFormat = 1, RGB219 if it is 2, YUV219 if it is 3. Since this value might be different in each field (even if this case is not really clear...), 2 values are displayed on the same line: for the 1st field on the left, and for the 2nd field on the right (only when the canvas zoom = 100%, else only the right value is displayed).

  5. •a-AspectOf(dest) (default: ON): when ON the line

  6. AspectOf(clip1 - dest) = lnAspect / pxAspect: n.nnnn - m.mmmm is displayed, where:

  7. n.nnnn is returned by the predeclared function GetNativeAspect(clip1) (only in the filter version)

  8. m.mmmm is returned by the predeclared function AspectOf(dest).

  9. •a-lnAspect (default: ON): when ON the line

  10. lnAspect(clip1 - dest) = fields per frame: n.nnnn - m.mmmm is displayed, where:

  11. n.nnnn = lnAspect(clip1) = integer(GetNativeAspect(clip1)+0.7) (only in the filter version)

  12. m.mmmm = lnAspect(dest) = integer(AspectOf(dest)+0.7).

  13. Note: usually if fieldprocessing=0 then lnAspect = 1 (1 field per frame = frame-by-frame processing = all frame lines are in the dest buffer), if fieldprocessing=1 then lnAspect = 2 (2 fields per frame = field-by-field processing = only half number of lines in the dest buffer). But this is not always true in generators, so the best way to count the number of fields per frame is integer(aspect+0.6), as used in this filter

  14. •a-pxAspect (default: ON): when ON the line

  15. pxAspect(clip1 - dest) = pixel width / pixel height: n.nnnn - m.mmmm is displayed, where:

  16. n.nnnn = lnAspect(clip1) / GetNativeAspect(clip1). The value represents the pixel aspect for the clip1 buffer. (only in the filter version)

  17. m.mmmm = lnAspect(dest) / AspectOf(dest). The value represents the pixel aspect for the dest buffer.

  18. •a-renderRes (default: ON): when ON 3 lines are displayed in the filter version and 2 in the generator version:

  19. renderRes = rendW/destW: n.nnnn, where n.nnnn is the predeclared variable renderRes.

  20. zoom = 1/renderRes = destW/rendW: n.nnnn, where n.nnnn = 1 / renderRes and represents the scaling factor for adapting absolute dimensions of objects to the dest buffer.

  21. zoom2 = clip1W/rendW: n.nnnn is displayed, where n.nnnn = clip1W / (destW * renderRes). Note that clip1W and destW are defined below. (only in the filter version).

  22. •a-clip1 buffer W x H (default: ON): when ON the line clip1 native buffer clip1W x clip1H: nnn x mmm is displayed, where nnn = clip1W and mmm = clip1H are the values returned by the predeclared function GetNativeSize(clip1, clip1W, clip1H). (only in the filter version)

  23. •a-src1/dest buffer W x H (default: ON): when ON the line src1/dest buffer destW x destH: nnn x mmm is displayed, where nnn = destW and mmm = destH are the values returned by the predeclared function DimensionsOf(dest, destW, destH).

  24. •a-rendered buffer W x H (default: ON): when ON the line rendered buffer (seq) rendW x rendH: nnn x mmm is displayed, where nnn = destW * renderRes and mmm = destH * renderRes * lnAspect.

  25. •Input Well (default: <empty>): if you drag a clip into it the following parameters will be displayed:

  26. well native buffer wellW x wellH - aspect: nnn x mmm - o.oooo, where nnn = wellW and mmm = wellH are the values returned by the predeclared function GetNativeSize(Input Well, wellW, wellH), and o.oooo = GetNativeAspect(Input Well)

  27. well glDuration - glOffest (frames): nnn - mmm, where nnn = wellDuration and mmm = wellOffset are the values returned by the predeclared function GetLimits (Input Well, wellDuration, wellOffset)

Display Controls:

  1. •Font Color (default: (255, 234,234, 234)): is the color used for the output text.

  2. •Font Size (line height %) (default: 70%, range: 20-150%): is the size of the output text measured on the line height.

  3. •Lines per page (0 = all) (default: 22 in filter and 18 in generator, range: 0-30): is the number of lines to display, the fewer the lines the larger the fontsize; 0 shows all selected parameters.

  4. •Background Opacity (default: 25%, range: 0-100%): is the opacity of the background black color. This allows to completely hide the background (Opacity = 100%).

Technical Notes

The following table describes in details the range of values displayed by the filter. To better understand them you need to know the meaning of the fxscript predeclared variables and functions, that are described in the next section.


For all above settings:

lnAspect(buffer) = integer(AspectOf(buffer)+0.7) or

lnAspect(clip) = integer(GetNativeAspect(clip)+0.7)

DimensionsOf (dest, destW, destH)

GetNativeSize (clip1, clip1W, clip1H)

GetNativeSize (input well, wellW, wellH)

GetLimits (clip1, clip1Duration, clip1Offset)

GetLimits (input well, wellDuration, wellOffset)

In the above tables for each plugin control (Parameter) the Display message is shown together with the possible values for each output (Where); the F/G column indicates whether the filter (F) and/or the generator (G) provides the parameter; the Info column indicates the context for the parameter: sys is system wide, S is referred to the hosting Sequence, C to the hosting Clip, and W to the Input Well clip.

(fp) means that t-fieldnumber and t-topfield are meaningful only when fieldprocessing = 1; [W] means that while returned by the predeclared functions, input well width, height and aspect are actually meaningless (and identical to the corresponding dest values, independent of the Input Well clip).

Predeclared fxscript Variables and Functions

This section describes a summary of some fxscript predeclared variables and functions that can be used in a filter or generator. Their extensive description is in the Apple document FCP 4 Using FXScript.

In the description below R = the value can only be read (not modified), W = the value must be written, RW = the value can be read and written.

  1. •previewing (R): it returns info about the render status of the current section of the sequence; it returns 0 if the clip is rendered or if it is unrendered, but in Unlimited RT playback; it returns 1 if clip is unrendered and paused.

  2. •fps (R): (frames per second): it always returns the number of frames per second for the clip, whether the clip is processed field-by-field (fieldprocessing=1) or frame-by-frame (fieldprocessing=0). It returns 25 for PAL and 30 for NTSC (in place of 29.97...)

  3. •fieldprocessing (R): it returns 1 if the clip is processed field-by-field and the buffers contain only half of the lines in the frame, 0 if the clip is processed frame-by-frame and the buffers contain all the lines of the frame.

  4. Note: in Generators fieldprocessing always returns 1 for rendered clips and 0 for unrendered clips, so in general it is not a good idea to use it to evaluate the number of lines in dest. The “line Aspect” of dest (number of fields per frame) is better evaluated as integer(AspectOf(dest)+0.7).

  5. •dest (W): it is the destination buffer where the filter or the generator writes the new field or frame; its size (width x height in pixels) depends on fieldprocessing.

  6. •a = AspectOf(dest) (R): it returns a value that combines the parameters lnAspect (number of fields in the dest buffer) and pxAspect (pixel aspect ratio of the dest buffer):

  7. AspectOf(dest) = lnAspect / pxAspect

  8. As a result the following is a typical set of values:


  10. •fieldnumber (R): it returns 1 if the current field is the first field in time of the frame (independent of whether it is the top or the bottom field), it returns 2 if it is the second field in time of the frame.

  11. •topfield (R): it returns 1 if the current field is the top field in the frame, that is it contains its odd lines (independent of whether it is the first or the second field in time), it returns 0 if it is the bottom field in the frame, that is it contains its even lines. Note that in this case lines in the frame are numbered from 1 to max lines; so odd lines are in the top field and even lines are in the bottom field.

  12. Note that the sequence field dominance is not a predeclared variable, but may be evaluated by:

  13. Field Dominance Lower(Even) = ((fieldnumber - 1) = topfield)

  14. In fact if fieldnumber=2 and topfield=1 (or: fieldnumber=1 and topfield=0) field dominance is Lower(Even), otherwise it is Upper(Odd).

  15. •systime (R): it returns a timestamp as a decimal value.

  16. •ratio (R): it returns a value between 0 and 1 indicating the position of the playhead in the clip, In fact

  17. ratio = frame / duration

  18. •frame (R): it returns a value indicating the current position in the clip.

  19. If previewing, frame always counts a number of frames.

  20. If not previewing, frame counts the number of fields from the IN point (where frame = 0) if processed field-by-field (fieldprocessing=1), otherwise frame counts the number of frames if processed frame-by-frame (fieldprocessing=0).

  21. •duration (R): it returns the length of the clip. If this is processed field-by-field (fieldprocessing=1) duration returns the number of fields in the clip (from the IN to the OUT point), if it is processed frame-by-frame (fieldprocessing=0) duration returns the number of frames in the clip.

  22. •srcType1 (RW): it returns and sets the Alpha Type of the clip. (not available in Generators)

  23. Its value may be one of the following: -2 (kNone), -1 (kAlpha), 0 (kBlack), 1 (kWhite). This value indicates how the alpha type has been encoded for the clip: kNone = there is no alpha channel, kAlpha = Straight Alpha = the alpha channel is not premultioplied, kBlack = the alpha channel is premultioplied with black, kWhite = the alpha channel is premultioplied with white.

  24. The value read in a filter is the value left from previous filters code or by the generator code; so it does not necessarily correspond with the value read in FCE or FCP using -9.

  25. On the other hand any filter or generator my modify this value after generating the dest buffer, if appropriate (Note: for this to work you must modify the 2nd field value for srcType1...)

  26. •c = GetPixelFormat(dest) (R): it returns the color space used for the video processing. It may have the following values: 1 = kFormatRGB255, 2 = kFormatRGB219, 3 = kFormatYUV219.

  27. •renderRes (R): it returns the ratio between the size of the rendered output buffer and the size of the current dest buffer. This buffer may be smaller before rendering, thus making playback faster but with lower quality. This info is needed to scale down absolute dimensions of objects in the frame, when the output and the dest buffer have different sizes.

  28. •DimensionsOf(dest, destW, destH): it returns the width and the height of the current dest buffer (in pixels) into the user variables destW and destH.

  29. •GetNativeSize(clip1, clip1W, clip1H): it returns the width and the height of the buffer for the input native clip1 (in pixels) into the user variables clip1W and clip1H. (not available in Generators)

  30. •a = GetNativeAspect(clip1) (R): it returns a value that combines the parameters lnAspect(clip1) (number of fields in the src1 buffer) and pxAspect(clip1) (pixel aspect ratio of the input native clip1 buffer). Its meaning and usage is equivalent to that of AspectOf(dest) but applied to the input native clip1. The table described above for AspectOf is also valid for GetNativeAspect.