Python Functions

Contents Phoneme and Mapping Info Face Graph Info Animation, Time and Keys GUI Miscellaneous Avoiding Catastrophe

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

>>> %FxStudio.getCurrentTime()

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

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 int he reference pose at the current frame.
getBoneNames	-	tuple	Returns an array of bone names for all bones in the reference pose.
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.
getBoneRefFrame	-	tuple	Returns bone transforms in parent space for all bones in the reference pose.
getFaceGraphFrame	-	tuple	Returns the node values for all nodes in the Face Graph at the current frame.
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)
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.

Animation, Time and Keys

FUNCTION	ArgUments	Returns	Description
getVisibleTimeRange	-	tuple	Returns the current 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.
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.
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.

GUI

Function	Arguments	Returns	Description
dingBell	-	-	Dings the system bell to get the user's attention
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	default_path, wildcard default_filename, default_extension, 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	default_path, wildcard, default_filename, default_extension, 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.
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.
errorBox	string	-	Displays a message box with the specified message and an "Error" title, or a console error in from the command line.
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.
getSingleChoiceFromUser	string, string, list		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.
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.
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.
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.
getAppDirectory	-	string	Returns the application directory (where the .exe file is located).
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.
getCallback	string	tuple	Gets the callback function.  Takes callback name as argument.
getConsoleVariableDefaultImpl	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.
getConsoleVariableImpl	string	string	Returns None if the console variable doesn't exist, otherwise returns console variable. Takes the name of the console variable as input.
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.
getUserDirectory		string	Returns the User documents folder path.
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.
registerCallback	string	bool	Registers a callback.  Takes callback name as argument.
setConsoleVariableFastImpl	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.
unregisterCallback	string	bool	Unregisters a callback.  Takes callback name as argument.
warn	string	-	prints a warning to the console.

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