FaceFX Support

FaceFX Documentation and support

Python Functions

Table of Contents

  1. Phoneme and Mapping Info
  2. Face Graph Info
  3. Animation, Time and Keys
  4. GUI
  5. Miscellaneous
  6. Render Asset
  7. Avoiding Catastrophe

Below is a list of commands available for getting information from FaceFX Studio.  They can be called like so:

FxStudio.getCurrentTime()

-or-

getCurrentTime()

Check the Scripts directory for wrapper functions, example implementations, and additional information.

You can also get the most up-to-date information by using the Python shell in Studio. Open the shell and type:

help FxStudio

Phoneme and Mapping Info

FUNCTION Arguments Returns Description
getPhonemeRegistry - tuple Returns a tuple for each phoneme containing (enum,  FaceFX, SAMPA, IPA).
getPhonemeClass enum unicode string Returns the class of the phoneme.  (plosive, fricative, etc)
getPhonemeSampleWords enum unicode string Returns a sample word for the phoneme.
getPhonemeClassification enum unicode string Returns the classification string for the phoneme.
getPhonemeMap - tuple Returns the current phoneme to target mapping with an array of (phoneme enum, target name, value) tuples.
getPhonemeList string, string tuple Returns the phoneme list for the given animation as an array of phoneme tuples:(enum, starTime, endTime).  Takes the animation group name and animation name as input.
getWordList string, string tuple Returns the word list for the given animation as an array of word tuples:(word, startTime, endTime).  Takes the animation group name and animation name as input.
getPhonemesInWord string, string, index tuple Returns the phonemes contained in the specified word.  Takes the animation group name, the animation name, and the word index as input.

Face Graph Info

FUNCTION Arguments Returns Description
getBoneFrame - tuple Returns bone transforms in parent space for all bones in the actor at the current frame.  Used by FrameData. Prefer FrameData.BoneFrame() or FrameData.AnimationFrame()
getBoneNames - tuple Returns an array of bone names for all bones in the actor.
getBonePoseBoneNames string tuple Takes the name of a bone pose as input.  Returns an array of bone names for all bones in the bone pose.
getBonePoseFrame string tuple Takes the name of a bone pose as input.  Returns bone transforms in parent space for all bones in the bone pose.  Used by FxBone. Prefer FxBone.BonePose()
getRestPose - tuple Returns bone transforms in parent space for all bones in the FaceFX rest pose.  Used by FxBone. Prefer FxBone.RestPose()
getFaceGraphFrame - tuple Returns the node values for all nodes in the Face Graph at the current frame.   Used by FrameData. Prefer FrameData.FaceGraphFrame() or FrameData.AnimationFrame()
getFaceGraphNodeNames - tuple Returns face graph node names.
getFaceGraphNodeProperties string tuple Returns the specified face graph node’s properties. (type, min/max, input operation, input links, user properties)
getFaceGraphNodeSliderValue string value Returns the value of the specified Face Graph Node’s slider
getSelectedFaceGraphNodeGroup - string Returns the currently selected Face Graph node group.
getSelectedFaceGraphNodeLink - tuple Returns the currently selected Face Graph node link, or the first selected if there are multiple.
getSelectedFaceGraphNodes - tuple Returns the currently selected Face Graph nodes.
getSkeletonFrame - tuple Returns bone transforms in parent space for all bones in Skeleton at the current frame.  Used by FrameData. Prefer FrameData.SkeletonFrame()
getBindPose - tuple Returns bone transforms in parent space for all bones in Skeleton in the bind pose.  Used by FrameData. Prefer FrameData.SkeletonBindPose()

Animation, Time and Keys

FUNCTION Arguments Returns Description
getVisibleTimeRange - tuple Returns the current time range in Studio.
setVisibleTimeRange float, float bool Sets the minimum and maximum visible time range in Studio.
getCurrentTime - value If there is no animation selected, or there is no actor / valid session, the Python value None is returned. Otherwise the current session time is returned as a floating point number in seconds (always as seconds; never frames or any other time value).
getAnimationNames - tuple Returns an array of (group name, anim names) tuples
getCurveNames string, string tuple Returns an array of curve names when passed in the group and anim name of the animation.
isCurveOwnedByAnalysis string, string, string bool Returns if the specified curve is owned by analysis.  Takes the group name, animation name, and curve name as input.
getKeys string, string, string tuple Returns the keys. Takes the group name, animation name, and curve name as input.
getAnimationGroupMountStatus string tuple Tells you if a group is mounted, and where the external file is.  Takes the name of the group as input.  Returns a tuple (bool, string) with the mount status and path to external file (the second argument is an empty string if the first argument is False) 
getAnimationProperties string, string tuple Returns the animation properties (start time, end time, curve start time, curve end time, absolute audio asset path, asset path, language, analysis actor, analysis text). Takes the animation group name and animation name as input.  Used by FxAnimation. Prefer FxAnimation.Animation()
getSelectedAnimation - tuple Returns the currently selected animation group name and animation name.
getSelectedCurves - tuple Returns the currently selected curve names.
getSelectedKeys string tuple Returns the key indices of the currently selected keys for the specified curve.
unlockSelectedKeyTangents - bool Unlocks the selected key tangents.
lockSelectedKeyTangents - bool Locks the selected key tangents.
hasAnimationBeenEdited string, string bool Returns if the animation has been hand edited
hasAnimationAudioChanged string, string bool Returns if the audio file has changed since the animation was created with it
hasAnimationTextChanged string, string bool Returns if the text file has changed since the animation was created with it
markAnimationAudioUnchanged string, string - Makes it as if the current audio file was used to generate the animation
markAnimationTextUnchanged string, string - Makes it as if the current text file was used to generate the aniamtion

GUI

Function Arguments Returns Description
createStyledButton wx.Window, int, string, wx.Point/tuple, wx.Size/tuple, int styled button Creates and returns a FaceFX Studio styled button. Throws an exception on failure. Takes the following:(parent window, button ID, label, button’s position, button’s size, style.)
createStyledChoice wx.Window, int, wx.Point/tuple, wx.Size/tuple, list styled choice Creates and returns a FaceFX Studio styled choice control. Throws an exception on failure.  Takes the following:(parent window, button ID, label, button’s position, button’s size, choices.)
dingBell - - Dings the system bell to get the user’s attention
displayAnimationSelectionDialog msg, default_path tuple Displays the animation selection dialog and returns the selected group and animation name in a tuple, or an empty tuple if the user pressed cancel.
displayDirectorySelectionDialog msg, default_path string Allows users to browse for a directory.  Returns empty string on cancel or the selected directory.  displayDirectorySelectionDialog(default_path=”C:\Temp”, msg=”Select a folder for temporary files.”).  Note: this function will cause scripts run from the command line to fail.
displayFileOpenDialog msg, default_path, default_filename, default_extension, wildcard, file_must_exist string Displays a file open dialog.  This command uses named Arguments that can be used in any order.  default_extension will select the extension if you give a wildcard, and wildcard is the same as in windows e.g. “All Files (.)|.|Config Files (.ini)|.ini” and setting default_extension to “*.ini” will display the dialog with the Conifg Files extension selected.  Note: this function will cause scripts run from the command line to fail.
displayFileSaveDialog msg, default_path, default_filename, default_extension, wildcard, confirm_overwrite  string Displays a file save dialog.  takes the same parameters as displayFileOpenDialog() except file_must_exist is relaced with confirm_overwrite and that defaults to True.  Note: this function will cause scripts run from the command line to fail.
displayMessageBox string, string - The first argument is the message to be displayed.  The second should be “info”, “warning”, or “error”.  Note: this function will cause scripts run from the command line to fail.  Prefer msgBox, warnBox, errorBox.
displayNodeSelectionDialog - list Displays the node selection dialog and returns the list of selected nodes, or an empty list if the user pressed cancel. Note that the user is free to type in a name that isn’t a node and it will be returned.
displayYesNoBox string string Returns ‘yes’ or ‘no’.  Takes the message to display as an argument.  Note: this function will cause scripts run from the command line to fail.
displayYesNoCancelBox string string Returns ‘yes’ or ‘no’ or ‘cancel’.  Takes the message to display as an argument.  Note: this function will cause scripts run from the command line to fail.
dockInMainWindowNotebook window, string bool Docks the window in the application as a new tab.  Takes the window and the caption as Arguments.  Pass select=True to select the tab
errorBox string - Displays a message box with the specified message and an “Error” title, or a console error in from the command line.
getAppIconPath - string returns the full path to the FaceFX Studio icon.
getColorPalette - dict Returns the current Studio color palette as a Python dictionary.
getMainWindowNotebook - wx.Window Returns the main application window’s notebook window.
getMultipleChoicesFromUser string, string, list list Like getSingleChoiceFromUser, but a list is returned of all selected entries.  Note: this function will cause scripts run from the command line to fail.
getPasswordFromUser msg, caption, default_value string Same as getTextFromUser, but the text box is a password box that displays * characters instead of what was typed. Note: this function will cause scripts run from the command line to fail.
getSelectedTabInMainWindowNotebook - string returns the caption of the selected tab in the FaceFX Studio notebook.
getSingleChoiceFromUser string, string, list string returns the selected (only single selection) string or empty string if user pressed cancel.  getSingleChoiceFromUser(“Here’s the list”, “Pick one”, [“one”, “two”, “three”]) Note: this function will cause scripts run from the command line to fail.
getTabsInMainWindowNotebook - list returns a list of tab captions From Studio’s notebook.
getTabWindowInMainWindowNotebook - wx.Window* returns the wxPython window pointer for the tab with the given caption.  Generates a runtime error if the tab doesn’t exist.
getTextFromUser msg, caption, default_value string Gets text from the user.  Use named Arguments in any order: getTextFromUser(default_value=”29”, caption=”Input your age”, msg=”What’s your age?”).  Note: this function will cause scripts run from the command line to fail.
msgBox string - Displays a message box with the specified message and an “Information” title, or a console information message from the command line.
selectTabInMainWindowNotebook string - Selects the tab from Studio’s notebook based on the provided caption.
styledButtonGetToggleValue styledButton bool Returns the toggle value of the specified styled button. Throws an exception on failure.
styledButtonSetIconByPath styledButton, string, string - Sets the icon for the specified styled button via a path to the icon files. Throws an exception on failure.  Takes the button, the path to the enabled icon and the path to the disabled icon as input.
styledButtonSetToggleValue styledButton, bool - Sets the toggle value of the specified styled button. Throws an exception on failure.
styledButtonMakeToggle styledButton - Makes the specified styled button a toggle button. Throws an exception on failure.
styledButtonSetIcon styledButton, wx.Icon, wx.Icon   Sets the icon for the specified styled button via the icons. Throws an exception on failure.takes the button, the enabled icon, and the disabled icon as input.
undockFromMainWindowNotebook wx.Window bool Undocks the given window from the main window notebook. Returns True if successful.
warnBox string - Displays a message box with the specified message and an “Warning” title, or a console warningin from the command line.

Miscellaneous

FUNCTION Arguments Returns Description
beginProgressDisplay string, integer [optional] - Warning: Expert use only!  Calling this without calling endProgressDisplay later in the script will cause the application be locked behind a modal dialog!  Only implement this in a well-debugged python script that also calls endProgressDisplay.  Takes a string and an optional integer as input: (string to display on the progress dialog, number of progress bars <= 3 [if the number of progress bars is omitted 1 is assumed]).  Update the progress bars with the pp_overall_progress, pp_task_name, pp_task_progress, pp_subtask_name, and pp_subtask_progress console variables.
connectSignal string, string bool Takes the signal name and python function as Arguments.  Connects the function to the signal.
createPluginLog string, bool object Creates a new log, with its own tab.  Pass the name of the log, and True if the log should have timestamps.  A log object is returned which you can pass to writeToPluginLog and destroyPluginLog.  Returns the existing log if it exists.
destroyPluginLog object bool Destroys the provided log created with createPluginLog. 
disconnectSignal string, string bool Take the signal name and python function as Arguments.  Disconnects the function from the signal.
endProgressDisplay - - Closes the progress display.
error string - prints an error message to the console.
getActorName - string Gets the current actor name.
getActorPath - string Gets the path to the currently loaded actor file.  Empty string if the file hasn’t been saved yet.
getActorPythonDictionary - dictionary returns the actor’s python dictionary that is saved in the .facefx file.
getAnimPythonDictionary string, string dictionary Takes the animation group and animation name as inputs.  Returns the python dictionary stored in the .facefx file for the specified animation.
getAppName - string Returns the name of the application (i.e. ‘FaceFX Studio Professional’)
getAppTitle - string Returns what is written in the title bar (i.e. ‘FaceFX Studio 2010 (Professional Edition)’)
getAppVersion - string Returns the version number of the applciation (i.e. ‘2010’)
getAudio - tuple Returns the audio information for the currently selected audio file.  This includes the path to the audio, number of channels, bit rate, frequency, and raw audio bytes.
getCameraNames - list(string) Returns the names of all the cameras.
getConsoleCommandHelp string string Returns the help string for the specified console command. Throws an exception if the command does not exist.
getConsoleCommandList - list(string) Returns the list of valid FaceFX Studio console commands.
getConsoleVariable string string Returns None if the console variable doesn’t exist, otherwise returns console variable. Takes the name of the console variable as input.
getConsoleVariableAsSwitch string string Returns True if the switch is enabled and False if it is not. If the console variable does not exist, a FaceFXError is raised.
getConsoleVariableDefault string string Returns None if the console variable doesn’t exist, otherwise returns the console variable’s default value. Takes the name of the console variable as input.
getConsoleVariableList - list(string) Returns the list of current FaceFX Studio console variables.
getDirectory string string Returns the specified directory.  Accepts one of [user, app, settings, logs, templates, clientspec_root]
getLastCommandResult - string returns the result of the last command issued to Studio. valid returns: Failure, Success, ArgumentFailure, InvalidCommand, InternalError, InvalidLicense, UnknownError
getLicenseeName - string Returns the licensee name that the version of FaceFX Studio is licensed to.
getLicenseeProjectName - string Returns the project name that the version of FaceFX Studio is licensed to.
getSDKVersion - string Returns the SDK version number.
getUnicodeFontName - string Returns the name of the current Unicode font the user has selected in Studio’s options.
msg string - Prints a message to the log.
hasAnalyzeCommand - bool returns id the analyze command is enabled.
issueCommand string bool Issues a FaceFX command.  Takes command string as argument.
isCommandLineMode - bool Returns if Studio is currently in command line mode.
isNoSave - bool Returns if the application is a no-save version
isRunningInRemoteDesktop - bool Returns if FaceFx Studio is running over remote desktop
isUnattended - bool Returns if the g_unattended flag is set, which prevents Studio from popping up dialog boxes.
setActorPythonDictionary dictionary bool Sets the actor’s python dictionary that is saved in the .facefx file.
setAnimationPythonDictionary string, string, dictionary bool Set’s the animation’s python dictionary that is saved in the .facefx file.  Takes the animation group and animation names as input.
setConsoleVariableFast string, string - Takes the name of the console variable and the console variable value as input.  Creates the console variable if it doesn’t exist.
warn string - prints a warning to the console.
writeToPluginLog object, string - Writes the provided string to the provided log object created with createPluginLog()

Render Asset

FUNCTION Arguments Returns Description
getPreviewAnimationSettings - tuple Returns the blend mode, name, length, start time, blendin and blendout times, and looping state for the preview animation.
getRenderAssetAnimationInfo - tuple Returns a tuple containg all of the Ogre animations and their durations.
getRenderAssetname - string Gets the render asset name.
getSkeletalAnimationTreeAnims - tuple Returns a list of tuples each containing the name and attributes of an animation contained in the skeletal animation tree.
getSkeletalAnimationTreeAnimsContainingTime - tuple Returns a list of tuples each containing the name and attributes of an animation contained in the skeletal animation tree whose bounds contain the specified time.
getSkeletalAnimationTreeAnimsInTimeRange - tuple Returns a list of tuples each containing the name and attributes of an animation contained in the skeletal animation tree whose bounds intersect the specified time range.
isRenderAssetValid - bool Returns true if the Render Asset is valid (a .Mesh or .Scene file was found and loaded).
renderAssetHasSkeletalAnimationTree - bool eturns True if the render asset associated with the current actor has a skeletal animation tree, False if not, or throws an exception.
setRenderAssetname string - Returns the class of the phoneme.  (plosive, fricative, etc)

Avoiding Catastrophe

If you’re going to use a progress bar from script, it’s very important to ensure your script is properly debugged before adding the progress bar. If the script throws an exception for any reason and does not call endProgressDisplay(), Studio will be irrecoverably locked. The best way to ensure that this never happens is to always use the following idiom when using progress displays from Python:

try:
	beginProgressDisplay()
	# all code that requires progress here
finally:
	endProgressDisplay()