FFAStrans wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
======= Variables =======

Variables are used to adapt and alter your workflow jobs to fit your output needs and incoming media. A variable is represented by a text string encapsulated with the percentage (%) character:
%f_fps%, %username%, %s_original_name% etc...
FFAStrans variables are always prefixed with a "s_" (string), "i_" (integer) or "f_" (float):

%s_v_codec% ---> DNxHD120\\
%i_height% ---> 1080\\
%f_fps% ---> 29,97\\


FFAStrans has 3 kind of variables: Generic inbuilt variables, special inbuilt variables and user variables.


===== Generic Inbuilt Variables  =====

These variables are automatically populated. If variable cannot be populated, they will mostly have an empty string or a zero (0), (e.g: height or width for an audio file, number of audio channels for a video file, mxf version for a quicktime file, etc). 
FFAStrans has 5 types of generic inbuilt variables :

  - Media Variables
  - File Variables
  - Time Variables
  - OS Variables
  - FFAStrans Variable

{{:variables:extraction_general.jpg?nolink&550|}}


Variables are generally populated on the fly when needed.

{{:variables:populated_variable_1.2.png?nolink&1000|}}

You can call all these generic inbuilt variables when you want and insert it by pressing the arrow-button next to a text field. All fields that has an arrow next to it supports variables.


{{:variables:delivery_variable.jpg?nolink&600|}}

==== 1.Media Variables ====

Media properties are derived from the original input file. Different types of media can contain different kind of properties

=== Video And Audio Variables ===
{{:variables:oeil.jpg?nolink&50 |}}{{ :variables:oreille.jpg?nolink&50 |}}


|< 100% 17% 33%>|

|**%i_v_streams%**|Number of video streams (1).|**%i_a_streams%**|Number of audio streams (4).|
|**%i_v_bitrate%**|Video bitrate of first video stream (50000).|**%i_a_bitrate%**|Audio bitrate of first audio stream (128).|
|**%i_frames%**|Media length in frames (2600).|**%i_a_bit_depth%**|Bit depth of first audio stream (16).|
|**%s_pixel_format%**|Pixel format of first video stream (yuv422p).|**%i_a_channels%**|Total number of audio channels (2).|
|**%f_frame_rate%**|Frames per second (29.97).|**%i_a_sample_rate%**|Audio sample rate of first audio stream(48000).|
|**%s_frame_rate%**|Frames per second represented as num/den (30000/1001).|**%s_dbe_layout%**|Json formatted audio layout including Dolby E after full decode.|
|**%s_v_codec%**|Codec of first video stream (mpeg2video).|**%s_a_codec%**|Codec of first audio stream (pcm_s16le).|
|**%s_v_profile%**|The profile of the first video stream.|**%s_a_codec_long%**|Long codec name of first audio stream (Advanced Audio Codec).|
|**%i_v_first%**|Stream number of the first video stream.|**%i_a_first%**|Stream number of the first audio stream.|
|**%s_pix_aspect%**|Pixel aspect of the first video stream (1:1).|**%i_tot_channels%**|The total number of audio channels.|
|**%f_duration%**|Media length in seconds (137.48).|**%f_duration%**|Media length in seconds (137.48).|
|**%i_interlace%**|Field domination(0=Progressive, 1=Upper, 2=Lower (1)).|**%s_a_layout%**|Return audio layout as array. First instance is number of channels in first audio stream, etc.|
|**%s_date_created%**|Creation date of media (2015-15-11 21:16:33).|**%s_date_created%**|Creation date of media (2015-15-11 21:16:33).|
|**%i_v_bit_depth%**|Bit depth of first video stream (10).|**%s_a_profile%**|The profile of the first audio stream.|
|**%i_dheight**|Display height of the codec video.|**%i_has_cover**|Return 1 if audio file has cover image.|
|**%i_dwidth**|Display width of the codec video.|**%i_has_dolbye**|Checks if source media has Dolby E content.|

{{:variables:oeil.jpg?nolink&50 |}}\\

Video Variables Only\\

|< 100% 50% 50%>|
|**%i_height%**|Media video height of first video stream (1080).|
|**%i_width%**|Media video width of first video stream (1920).|
|**%s_v_codec_long%**|Long codec name of first video stream (Windows Media Video 2).|
|**%s_disp_aspect%**|Display aspect of the first video stream (16:9).|
|**%s_chroma_loc%**|Location of the first chroma sample (Upper left).|
|**%s_color_space%**|Color space of the first video.|
|**%s_color_trans%**|Color transfer of the first video.|
|**%s_color_prim%**|Color primaries of the first video.|
|**%s_color_range%**|Color range of the first video.|
|**%i_intra%**|Checks if media is intra frame based. Return 1 if true, 0 otherwise.|
|**%i_gamma%**|Gamma curve applied during encoding (Slog3).|
|**%i_rotation%**|Find the rotation/orientation of the source media.|
|**%s_duration_tc%**|Media duration as time code (00:05:10:12).|
|**%s_date_created%**|Creation date of media (2015-15-11 21:16:33).|
|**%f_start_sec%**|Start TC converted to seconds (2591.96).|
|**%i_stc_hh%**|Start hour from TC.|
|**%i_stc_mm%**|Start minute from TC.|
|**%i_stc_ss%**|Start second from TC.|
|**%i_stc_ff%**|Start frame from TC.|
|**%s_start_tc%**|Start TC of Media (01:13:48:20).|
|**%s_start_tc_alt%**|Alternative start TC based on creation time. NOT frame accurate.|
|**%f_pix_aspect%**|The calculated aspect from denum/num (1.4222).|
|**%f_v_tbase%**|The time base of the source video returned as float.|
|**%i_xoffset%**|Start position of display width.|
|**%i_yoffset%**|Start position of display height.|
|**%i_v_precharge%**|Return number of pre-charge frames if available.|

**%s_last_enc_cmd%**

The latest calculated 

Metadata Variables
{{:variables:valise.jpg?nolink&50|}}

|< 100% 15% 75% >|
|**%s_format%**|Format name of the container.|
|**%s_mxf_version%**|Checks the mxf version used in the MXF source.|
|**%s_mxf_op%**|Find the operational pattern used in the MXF source.|
|**%s_format_long%**|Long format name of the container.|
|**%s_master_display%**|Master display info if present on PQ/HDR10 video.|
|**%s_info_ffprobe%**|Complete media info from ffprobe in JSON format.|
|**%s_info_exiftool%**|Complete media info from exiftool in JSON format.|
|**%s_info_mediainfo%**|Complete media info from mediainfo in JSON format.|
|**%i_max_fall%**|Maximum program average frame light level in nits.|
|**%i_max_cll%**|Maximum program light level in nits.|

----


==== 2.File Variables ====

File properties are derived from the original input file. ALL files has these properties so they will allways be populated with data.

{{:variables:file.jpg?nolink&50|}}

|< 100% 15% 75% >|
|**%s_original_attrib%**|Attributes of the original file (RASH).|
|**%s_original_ext%**|Original extension.|
|**%s_original_name%**|Original filename without extension and path.|
|**%s_original_path%**|Path of original file.|
|**%s_original_path~n%**|Folder name n-steps backwards.|
|**%s_original_folder%**|Path of original without drive or UNC.|
|**%i_original_size%**|File size of original in bytes.|
|**%s_original_date%**|Creation date of original file (YYYY-MM-DD_hh-mm-ss).|
|**%i_original_year%**|Creation year of original file, e.g. 2020|
|**%i_original_mon%**|Creation month of original file. [1-12]|
|**%i_original_day%**|Creation day of original file. [1-31]|
|**%i_original_hour%**|Creation hour of original file.|
|**%i_original_min%**|Creation minute of original file.|
|**%i_original_sec%**|Creation second of original file.|
|**%s_original_root%**|Valid drive or UNC server path of the original file.|
|**%s_original_drive%**|Drive or UNC server of the original file.|
|**%s_recursed_path%**|Path of original without drive/UNC, monitored path and filename.|
|**%i_source_size%**|File size of current source in bytes.|
|**%s_pickup_file%**|Full path to the original file picked up by the monitors. 1'st level source. Full remote or local path of file picked up by def_runner based on individual monitor settings. Can be any binary or non-binary reference files like .lnk, .url, .xml, .json.'(*Note)|
|**%s_original_full%**|Full path original file name as picket up by monitor or manually submitted. 2'nd level source. Full remote or local path to binary file discovered by monitor'(*Note)|


<note> : %%The %s_pickup_file% is ALWAYS the file that's being picked up by monitors, hence its name. But, this might be just a link to another file. Consider the case of for example a "c:\shortcut.lnk" file. This file just point to another file, say "\\server\share\cool.mp4"%%</note>

This gives us the following different contents of the two variables:\\
%s_pickup_file% = c:\shortcut.lnk\\
%%%s_original_full% = \\server\share\cool.mp4%%


------------

==== 3.OS Variables ====

These variables, also called system enviroments, are the ones that resides within the OS independent of FFAStrans. But all can be utilized within FFAStrans. F.ex. the variable %username% is a part of the OS variables. OS variables are in fact statics(see [[variables:inbuilt_variables#User Variables|user variable/statics]]) that don't change from job to job, or workflow to workflow.

{{:variables:os.jpg?nolink&50|}}

These variables are specific and depend of each system. You can find the list of all variables here :
https://en.wikipedia.org/wiki/Environment_variable#Windows

We can find for example %APPDATA% -->C:\Users\Share\AppData\Roaming.\\
Or %windir% --> C:\Windows\\
Etc.
-------

==== 4.Time Variables ====

These are a selection of time variables read from the system time.

{{:variables:time.jpg?nolink&50|}}

|< 100% 15% 75% >|
|**%i_gmt_bias%**|Returns the local GMT bias (-1).|
|**%i_year%**|Full year (2020).|
|**%i_yr%**|Short year (20).|
|**%i_mon%**|Month (01-12).|
|**%s_mon%**|Abbrevated month name going Jan. to Dec.|
|**%s_month%**|Month name going January to December.|
|**%i_mday%**|Day of month (01-31).|
|**%i_wday%**|Numeric day of week. Starting on Sunday (1) through Saturday (7).|
|**%i_yday%**|Current day of year. Range is 001 to 366 (or 001 to 365 if not a leap year).|
|**%i_hour%**|Hour (23).|
|**%i_min%**|Minute (59).|
|**%i_sec%**|Second (59).|
|**%s_week_day%**|Weekday name going Sunday to Saturday.|
|**%s_w_day%**|Abbrevated weekday name going Sun. to Sat.|
|**%i_week%**|Week number of the year.|
|**%i_msec%**|Millisecond (346).|

-------

==== 5.FFAStrans Variables ====

These are variables generated by FFAStrans. F.ex. %s_wf_name% holds the name of the workflow on where the job runs. 

{{:variables:newlogo.png?nolink&50|}}

|< 100% 15% 75% >|
|**%s_job_id%**|GUID identifier for the current job (20160219-202314-181-4693BFCC0A72).|
|**%s_job_work%**|Work folder for the current job (D:\_ffas_workroot\2015052120481\20160219-202314-181-4693BFCC0A72).|
|**%i_job_priority%**|Priority of the current running job.|
|**%s_wf_id%**|Identifier for the current workflow (20150521204819).|
|**%s_wf_name%**|Name of the current workflow (Untitled).|
|**%s_wf_folder%**|Folder name of the current workflow.|
|**%s_split_id%**|Split/branch id of the current running job.|
|**%s_node_name%**|Name of the current working processor node (XDCAM-HD).|
|[[variables:Inbuilt_variables#special_variables|%s_source%]] |Full path to the file work file passed by FFAStrans processors. 4'th level source. Any file set as current input/output source for processors'|
|**%s_root_work%**|Path to the global root work directory.|
|**%s_ffastrans_dir%**|Path to the local FFAStrans.exe file.|
|**%s_ffmpeg%**|Full path to the ffmpeg.exe file.|
|**%s_ffmpegx64%**|Full path to the ffmpegx64.exe file.|
|**%s_prev_node%**|Name of the previous processor node.|
|**%s_error%**|Current error message/state.|
|**%s_cache_record%**|Full path to the cache history record file created by the monitors.|
|**%s_source_dir%**|Path to the files passed by some FFAStrans processors.|
|**%s_version%**|Version of the current running FFAStrans.|
|**%s_last_error%**|Retrieve last viable error message.|

----


===== Special Variables  =====

There is currently one variable that behave a bit different than others:

**%s_original_path~n%** = Folder name n-steps backwards. (This variable supports minus notation for retrieving path names from the right side.)

{{variables:ffastrans_original_path_v2.png?nolink&800|}}


**%s_source%** represent the input file for any processor. It can be altered using the "Populate variables"-node.

{{:variables:source_tutorial_m1.png?nolink&1200|}}

**%s_success%** represent the success message upon job completion. It can be altered using the "Populate variables"-node.\\

In this example, the objective is to ensure that the input file has a video stream to perform the H264 encoding. Otherwise a message in the status monitor and in Webinterface's jobs list will appear. In this particular workflow, each branch leads to a success(but "no video" node isn't one for the user). The trick is to turn that success into "error" for user. Don't forget to use "//execute on success//"(conditional "TRUE") to continue to H264 node OR "//execute on error//"(conditional "FALSE") to continue to another node.\\
You just have to finish your branch by populated the %s_success% variable to a message of your choice e.g: "error" or "failed" or for the example "No video in input file".

{{:variables:success_variable.png?nolink&800|}}


**%s_options%** (since FFAStrans 1.4) advanced users can force special behaviour. 

Mostly used by advanced users to change the encoding commands of internal encode processors to specific needs.
You can enable/disable options by setting %s_options% to some value using a populate vars processor. Setting one a single option will not change possible existing options.

Note that **skip_encoding=True|save_enc_cmd=True** can be used to "not encode" but just calculate some encoding command string which you can change to your needs.


^ Heading 1      ^ Heading 2      ^   
|skip_encoding	|Option to skip encoding in encoding nodes - used to retrieve the calculated encoding cmd in combination with save_enc_cmd|
|proc_execute	|Don't execute procs when false|
|save_enc_cmd	|Option to save ffmpeg processing and filter chains to variables|
|allow_text_source	|Option to turn the string in s_source into a text file|
|end_branch	|Option to end the current branch even if there are subsequent nodes|
|dispel_branch	|Option to end the current branch even if there are subsequent nodes and hide from history|
|emulate_crash	|none,mem,bounds,var,obj,halt,recurse,stress, null, Option to emulate node crash. For testing purpose only!|
|allow_afuncs	|Allow using native AutoIT functions in the populate and conditional node.|
|encode_errors	|Stop and error on known encoding andomalies resulting in a complete but incompatible file.|
|afilters	|Add extra ffmpeg audio filters at the end of filter chain per stream.|
|apre_filters	|Add extra ffmpeg audio filters at the start of filter chain per stream.|
|apost_filters	|Add extra ffmpeg audio filters at the end of filter chain per stream.|
|vfilters	|Add extra ffmpeg video filters at the end of filter chain.|
|vpre_filters	 |Add extra ffmpeg video filters at the start of filter chain.|
|vpost_filters	|Add extra ffmpeg video filters at the end of filter chain.|
|enc_pre_input	|Add extra ffmpeg arguments before input specifier.|
|enc_pre_output	|Add extra ffmpeg arguments before output specifier.|


**%s_last_enc_cmd%**

Read only variable for retrieving the latest internally ffmpeg encoding command (after some encode processor)

-----

===== User Variables  =====
\\

__**Normal User Variable**__ : User variables can be populated using the "Populate variables" node within a workflow, a number of other processors like the Loudness Analyzer and via API\\ [[processors:operation_populate|Populate Variables help]] \\

Scope : \\

User Variable Values are valid only for the current Branch and it's Child-branches. User Variables cannot be passed directly from one Branch to another.


How to create and set : 
    * Press the arrow-button next to a text field,variables window appears. 
    * Select "user" category.
    * Right-click into variables window and choose "new".

{{:variables:variables_window_400.jpg?nolink&400|}}


  * **Set "//variable//" **: Creates a normal user variable. 
    * **Field 1**:  Enter your variable name, this will always be lower case and spaces are not allowed.
    * **Field 2**: Here you can just write a description for the variable and its usage.
    * **Set "//variable//"** and **as "//string//"**: Sets the variable as a text string. This is default.
    * **Set "//variable//"** and **as "//integer//"**: Sets the variable as an integer: whole number. Use this type if you need ffastrans to "guarantee" the value is of type integer. E.g. Spaces are removed and if the original value is a float, it will be rounded down. If the value is too big to fit into 64bit Int, it will be the maximum number an Int can be on your System. 
    * **Set "//variable//"** and **as "//float//"**: Sets the variable as floating point number. Same automatic internal value conversion as int above





  * **Set "//static//" **: This is a static that can not be populated dynamically in workflows. 
    * **Field 1**:  Enter your variable name, this will always be upper case and spaces are not allowed.
    * **Field 2**: this option will read "Content". Here you set the content of the static.
    * **Set "//static//"** and **as "//string//"**: Sets the variable as a text string.
    * **Set "//static//"** and **as "//integer//"**: Sets the variable as an integer: whole number.
    * **Set "//static//"** and **as "//float//"**: Sets the variable as floating point number.
    

 <note> : Each time you create or modify a user variable, an archive file is created. You can retrieve the history of your variables from the folder : \\ 
 %FFAStrans install directory%\Processors\db\configs\archive\user_variables</note>


__**Static User Variable**__ : This is another kind of variable. Unlike other variables, static variables are always written with upper case.Creating statics are very handy for example representing a very long path in a short static.\\

Example 1:\\
%S_MS_OUTPUT% = D:\Media\Customer previews\Huge important company\720p\Windows Media Video\500k bitrate with watermark

Example 2 :\\

{{variables:static_variable.png?nolink&500|}}

In this example we have several monitor folder nodes with the same input folder.Only accept files or deny files are different.\\
If a full path is entered, it will work but all paths will have to be changed if the input folder is changed.\\
Static variables are handy to avoid this.\\

  *Create a static variable like "%S_INGEST_PATH%"
  *Enter the appropriate content (the full path of monitored folder)
  *Enter your new static variable instead of the full path into all your monitor nodes

If your input path change, just edit and modify the content of %S_INGEST_PATH% and all the paths will be changed at the same time. 

------------------------------------------

<html>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</html>[[variables:inbuilt_variables|Back to top]]