FaceFX Support

FaceFX Documentation and support

XML Actor Files

FaceFX 20XX and version 1.7.3 support importing and exporting the XML file format defined below.  The XML format allows older versions of FaceFX Studio to load up data created with newer versions and it allows FaceFX Studio to load up animations created by external applications that support the format.

Keep in mind the following:

• Animations in the XML file will overwrite duplicate animations in the actor.
• The face graph in the XML file will not overwrite the actor’s face graph, unless the actor’s face graph is empty.

DTD specification

<!ELEMENT actor (face_graph? mapping? animation_groups? )>
<!ATTLIST actor
	name CDATA #IMPLIED
	version CDATA #IMPLIED
	path CDATA #IMPLIED> 	<!-- Audio paths can be stored relative to the actor path -->
	<!ELEMENT face_graph(refbones? nodes? links?)>
		<!-- As a child of the face graph, bones is a list of bones in the reference pose-->
		<!ELEMENT bones(bone*)>
			<!ELEMENT bone(#PCDATA)>
			<!-- The PCDATA is a space-seperated array of floats with 10 values. Position x,y,z then quaternion rotation w,x,y,z then scale x,y,z -->
			<!ATTLIST bone
				name CDATA #REQUIRED>
		<!ELEMENT nodes(node*)>
			<!ELEMENT node(bones? properties?)>
			<!-- The bones element is the same as that defined in the face_graph section. It is only valid when the node type is FxBonePose -->
			<!ATTLIST node
				name CDATA #REQUIRED
				min CDATA #IMPLIED
				max CDATA #IMPLIED
				input_op(sum|multiply|min|max) "sum"
				type(FxCombiner|FxBonePose|FxMorphTarget|FxCurrentTime|FxDelta|FUnrealFaceFXMaterialParameter|FUnrealFaceFXMorphNode) "FxCombiner">
				<!ELEMENT properties(property*)>
					<!ELEMENT property>
					<!-- property_enum represents the FxFaceGraphNodeUserPropertyType: int, bool, real, string, choice -->
					<!ATTLIST property
						name CDATA #REQUIRED
						property_enum (0|1|2|3|4) 
						value CDATA #REQUIRED>
		<!ELEMENT links(link*)>
			<!ELEMENT link(parameters?)>
			<!ATTLIST link
				function (linear|quadratic|cubic|square root|negate|inverse|oneclamp|constant|corrective|clamped linear) "linear"
				from CDATA #REQUIRED
				to CDATA #REQUIRED 
				<!ELEMENT parameters(#PCDATA)>
				<!-- The PCDATA is a space-seperated array of floats. It should have the same number of values as the parameters required for the specified link function -->
				<!ATTLIST parameters
				num_params CDATA #REQUIRED
	<!ELEMENT mapping(targets?, entry*)>
		<!ELEMENT targets(target*)>
			<!ELEMENT target>
			<!ATTLIST target
			name CDATA #REQUIRED
			type (Basic|TongueOnly|JawOnly) "Basic"
		<!ELEMENT entry>
		<!-- the phoneme should be on of the phonemes in FaceFX format supported by FaceFX (i.e "P", "B", "T", "D", etc.) -->
		<!ATTLIST entry
			phoneme CDATA #REQUIRED
			target CDATA #REQUIRED
			amount CDATA #REQUIRED>
	<!ELEMENT animation_groups (animation_group*)>
	<!-- Planing for supporting nested animation_groups. These will be ignored by versions that don't support it. -->
		<!ELEMENT animation_group (animation_group* animation*)>
		<!ATTLIST animation_group
			name CDATA #REQUIRED
			<!ELEMENT animation (curves? analysis_text? phonemes? words?)>
			<!ATTLIST animation
				name CDATA #REQUIRED
				language (American English|UK English|French|German|Italian|Spanish|Korean|Japanese) "American English"
				audio_path CDATA #IMPLIED
				coarticulation_config CDATA #IMPLIED
				gesture_config CDATA #IMPLIED
				analysis_results (on|off) "on"
				speech_gestures (on|off) "off">
				<!ELEMENT phonemes(phoneme*)>
					<!ELEMENT phoneme>
					<!ATTLIST phoneme
						phoneme CDATA #REQUIRED
						start CDATA #REQUIRED
						end CDATA #REQUIRED>
				<!ELEMENT words(word*)>
					<!ELEMENT word (#PCDATA)>
					<!ATTLIST word
					start CDATA #REQUIRED
					end CDATA #REQUIRED>
				<!ELEMENT events(event_group*)>
					<!ELEMENT event_group(event*)>
					<!ELEMENT event(#PCDATA)>
					<!ATTLIST event
						anim CDATA #REQUIRED
						group CDATA #REQUIRED
						start_min CDATA #IMPLIED
						start_max CDATA #IMPLIED
						magnitude_min CDATA #IMPLIED
						magnitude_max CDATA #IMPLIED
						duration_min CDATA #IMPLIED
						duration_max CDATA #IMPLIED
						blendin_min CDATA #IMPLIED
						blendin_max CDATA #IMPLIED
						blendout_min CDATA #IMPLIED
						blendout_max CDATA #IMPLIED
						weight CDATA #IMPLIED
						probability CDATA #IMPLIED
						persist (on|off) "off"
						magnitude_scaling (on|off) "on"
						duration_scaling (on|off) "on"
						payload CDATA #IMPLIED>
				<!ELEMENT curves (curve*)>
					<!ELEMENT curve (#PCDATA)>
					<!-- The PCDATA is a space-seperated list of key times, values, input slopes and output slopes (in that order). There are 4*num_keys values -->
					<!ATTLIST curve
						name CDATA #REQUIRED
						num_keys CDATA #REQUIRED
						owner (analysis|user) "user">

Example Files

Mapping

<actor>
  <mapping>
    <entry phoneme="B" target="BMP" amount="1.0"></entry>
    <entry phoneme="M" target="BMP" amount="1.0"></entry>
  </mapping>
</actor>

Animation

<actor name="test">
  <animation_groups>
    <animation_group name="Default">
      <animation name="anim1">
        <curves>
        <!-- The below curve has 2 keys at (0,0) and (1,1). All input and output slopes = 0 -->
          <curve name="curve1" num_keys="2"> 0 0 0 0 1 1 0 0</curve>
        </curves>
       </animation>
    </animation_group>
  </animation_groups>
</actor>

Note:  See curve evaluation for information on how FaceFX curves are evaluated.