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
<!-- Audio paths can be stored relative to the actor path -->
path CDATA #IMPLIED>
<!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>
<!ATTLIST property
name CDATA #
REQUIRED
<!-- An enum representing the FxFaceGraphNodeUserPropertyType: int, bool, real, string, choice -->
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 (entry*)>
<!ELEMENT entry>
<!ATTLIST entry
<!-- the phoneme should be on of the phonemes in FaceFX format
supported by FaceFX (i.e "P", "B", "T", "D", etc.) -->
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.

Version Number: 
2010