======= 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)|
: %%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"%%
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.
: 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
__**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.
------------------------------------------
[[variables:inbuilt_variables|Back to top]]