FaceFX Support

FaceFX Documentation and support

Python Functions

Table of Contents

Phoneme and Mapping Info
Face Graph Info
Animation, Time and Keys
GUI
Miscellaneous
Render Asset
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.
setAnimPythonDictionary	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)

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()