Event Text Tags

Text tags can be used to insert an event into an animation.  The event will be inserted at the start time of the word following the tag.  If the tag is after the last word, it will be inserted at the end time of the last word.


  • Tags are encapsulated with brackets: {}
  • The group and animation name are separated with a pipe character: |
  • The combined group and animation names are enclosed with quotes: ""
  • Event parameter names (other than persist and payload) are followed by an equals character and a numerical value.
  • The persist parameter, when present, makes the animation persistent. It does not accept a value after the parameter.
  • The payload parameter accepts a string value.  For multiple words, enclose in quotation marks.


The following parameters are part of the text tag syntax and can optionally follow the animation and group name to modify the event.
  • start, minstart, maxstart - Sets the event start time.  The time is relative to the start time of the word after the tag. 
  • duration, minduration, maxduration - Sets the duration of the event.  
  • magnitude, minmagnitude, maxmagnitude - Sets the magnitude of the event.
  • blendin, minblendin, maxblendin - Sets the blend in time of the event.
  • blendout, minblendout, maxblendout - Sets the blend out time of the event.
  • probability - The probability that an event will be fired in a given take.
  • persist - When present, sets the event as persistent.  Unlike other parameters, the persist tag is not followed by a value.
  • payload - Can be used to store game-specific information that can be accessed with the FaceFX SDK. 
    • Follow with a string.  For multiple words, enclose in quotation marks.
    • Including one or more of the following character sequences will change how the text tag is interpreted:
      • _!p - influence the events probability with the stress value of the following vowel.  The probability for the event must be set because a probablility of 1 will always be fired regardless of the stress.  At probabilities less than 1,  higher stress values will result in higher probabilities for the event.  A probability of 0 specifies that the event will only have non zero probability if the following vowel is stressed. 
      • _!d - influence the duration of the event with the current rate of speech.  Fast speech will result in a faster gesture, and slow speech will result in a slower gesture.
      • _!s - influence the start time by adding the following words duration.  This places the tag at the end of the word as opposed to the beginning.  Text tags are timed in accordance with the following word's start time, so if there is a silence, this tag can be used to ensure a tag will always be placed at the end of a word.
      • _!m - influence the magnitude by the stress value.  This will multiply the magnitude scale by the stress value of the following vowel.  A minimum of 0.5 and maximum of 2.0 are observed.
      • _!r - ensure that the influences applied above by the _!m and _!d flags will not result in an overly strong and fast gesture.  Specifically, _!m is decreased if necessary such that ( _!m / _!d ) == 1.

Note:  Specifying a minimum and a maximum value for a parameter (i.e. with minstart and maxstart), will create a range of possible values that will be randomly picked every time a new take is created.


The below example will insert a text tag for the "smile" animation in the "group1" group when the word "Aren't" is spoken.

Knock Knock! {"group1|smile"} Aren't you going to ask me who's there?

Below is a slightly more complicated tag that inserts the smile animation event -.75 seconds before the word "Aren't" is spoken.  The magnitude will be a random number between .5 and 1.5 each time you generate a new take. Also the event will persist and it will store the following string in its payload for use in other in-game systems: "Data for your game"

Knock Knock {"group1|smile" start=-.75 minmagnitude=.5 maxmagnitude=1.5 persist payload="Data for your game"} Aren't you going to ask me who's there?

See also

Python Callbacks - you can insert tags automatically based upon the contents of the analysis text with the analysistextpreprocessor callback.

Version Number: