Use available Python hooks are there to help you integrate Flame Premium into a shot management system, monitor archives, or just specify how batch setups are named.
All Python hook files are located in /usr/discreet/<application>/python/.
To provide more flexibility in how hook implementations are deployed, Flame Premium loads modules, searching for supported methods until all supported hooks are found. This allows you to separate hook implementations into multiple files, making allowance for better organization. Module specific hooks are part of specific files:
- archiveHook.py: archiveRestored, archiveComplete, archiveSegmentComplete, archiveSelectionUpdated
- batchHook.py: batchSetupLoaded, batchSetupSaved, batchExportBegin, batchExportEnd, batchDefaultIterationName, batchDefaultRenderNodeName, batchDefaultWriteFileNodeName
- projectHook.py: projectChanged, appInitialized, projectSaved
- hook.py: renderEnded, playbackEnded, previewWindowConfigChanged
- exportHook.py: preCustomExport, postCustomExport, preExport, postExport, preExportSequence, postExportSequence, preExportAsset, postExportAsset, useBackBurnerPostExportAsset, getCustomProfiles
Environment Variables
- DL_PYTHON_HOOK_PATH
- Allows you to set the path to the Python hooks files. It behaves similar to other PATH variables.
- export DL_PYTHON_HOOK_PATH=/share1/dev/flame_hooks/test:/share1/dev/flame_hooks/production
- In this case, Flame loads the hooks from test first, and then for any undefined hooks, continue to scan production.
- DL_DEBUG_PYTHON_HOOKS
- Enable to get verbose output from hooks, which should simplify the debugging process. Outputs to the shell about:
- Which hooks are loaded from which files
- The data sent to each hook that is triggered
- export DL_DEBUG_PYTHON_HOOKS=1
Reloading Hooks From Within the Application
A new hotkey has been added to re-scan hook files while the application is running. This is useful to iteratively test changes during implementation.
By default, this is mapped to Ctrl+Shift+P+H, but can be found in the hotkey editor under the name Scan for python hooks.
Archive Hooks
archiveRestored
Called when a restore operation from an archive successfully completes. A restore operation can be as simple as a partial restore (restoring a single clip) or as long as a full Project restore.
def archiveRestored( archiveName ): print 'This archive was successfully restored: %s' % archiveName
- archiveName
- String. Name of the archive that was entered when the archive was first created, and from which an element was successfully restored.
archiveComplete
Called when an archive operation successfully completes. This can be archiving individual clips, Archive Project, or Archive Setups. The archive need not be closed (Close Archive from the application UI) for archiveComplete to be called.
def archiveComplete( archiveName ): print 'This archive was successfully created: %s' % archiveName
- archiveName
- String. Name of the archive to which elements were successfully archived.
archiveSegmentComplete
Called each time an archive segment is successfully written.
def archiveSegmentComplete( segmentPath, archiveName, archivePath, status,
statusMessage, archiveComplete ):
pass
- segmentPath
- String. Path to the archive segment file that successfully completed. segmentPath is empty for non-file archives such as VTR archives.
- archiveName
- String. Name of the archive that the segment is part of.
- archivePath
- String. Path to the location where the segment was written to disk.
- status
- Integer. Zero if successful, non-zero if there was an error.
- statusMessage
- String. Description of the error, if any. Empty string if status is zero.
- archiveComplete
- Boolean. True if all the segments of the archive successfully complete.
archiveSelectionUpdated
archiveSelectionUpdated is blocking. The application waits for it to return.
Called when the user updates the information on the currently selected element in an opened archive (either through the U keyboard shortcut, or through the .) Update selection information tells the user which segments are needed to bring the selection back online.
def archiveSelectionUpdated( segmentInfo, numFrames, numClips,
dataSize, metadataSize ):
pass
- segmentInfo
- Dictionary{ Integer, String }. Map of segment ID to file path . If this is a non-file based archive, indicates the device type.
- numFrames
- Long. Number of frames of the selection.
- numClips
- Integer. Number of clips in the selection.
- dataSize
- Float. Size of the selection, in MB.
- metadataSize
- Float. Size of the metadata for the selection, in MB.
Batch Hooks
batchSetupLoaded.func_dict[ "async" ] = True #Runs in its own interepreter separate from the application batchSetupSaved.func_dict[ "async" ] = False #Uses the same thread as the application
batchSetupLoaded and batchSetupSaved can be run synchronously, or asynchronously in its own interpreter, by setting their respective func_dict["async"] true or false.
batchSetupLoaded
Called whenever a batch setup is successfully loaded.
def batchSetupLoaded( setupPath ): pass
- setupPath
- String. File path to the location of the loaded setup.
batchSetupSaved
Called whenever a batch setup is successfully saved.
def batchSetupSaved( setupPath ):
pass
- setupPath
- String. File path to the location of the saved setup.
batchExportBegin
This hook is called before the Write File node starts rendering and writing files to disk. batchExportBegin blocks the export until it returns. This allows it to update the paths to the media even before it is created.
def batchExportBegin( info, userData ): pass
- info
- Dictionary. Information about the export. Some of this information can be modified by the script as it executes.
Key Description Data Type nodeName Name of the export node String exportPath Editable. Export path as entered in the export node from within application. Can be modified by the hook to change the written file's destination. String namePattern List of optional naming tokens as entered in the application UI. String resolvedPath Full path to the first frame that will be exported, with all the tokens resolved. String firstFrame Frame number of the first frame that will be exported. Integer lastFrame Frame number of the last frame that will be exported. Integer versionNumber Current version number of this export. Zero there is no version.
Integer openClipNamePattern List of the tokens used in the UI to name the Open Clip XML that will be created by the export node. Only available if Clip Version (versionning) is enabled in the UI.
String openClipResolvedPath Full path to the open clip that will be created, with all the tokens resolved. Only available if Clip Version (versionning) is enabled in the UI.
String setupNamePattern List of the tokens used in the UI to name the batch setup that will be created by the export node. Only available if Clip Version (versionning) is enabled in the UI.
String setupResolvedPath Full path to the batch setup that will be created, with all the tokens resolved. Only available if Clip Version (versionning) is enabled in the UI.
String - userData
- Dictionary. User-defined. Empty Dictionary that will be carried over into the batchExportEnd hook. This can be used by the hook to pass black box data around.
batchExportEnd
This hook is called whenever a Write File node in Batch finished its render. Use it, amongst other things, to publish renders to shot tracking systems, or to perform post-processing on successful renders.
def batchExportEnd( info, userData ): pass
- info
- Dictionary. Information about the export. Some of this information can be modified by the script as it executes.
Key Description Data Type nodeName Name of the export node. String exportPath Export path either entered in the export node from within application, or edited by batchExportBegin. String namePattern List of the naming tokens as entered in the application UI. String resolvedPath Full path to the first frame that was exported, with all the tokens resolved. String firstFrame Frame number of the first frame that was exported. Integer lastFrame Frame number of the last frame that was exported. Integer versionNumber Current version number of this export. Zero if there is no version.
Integer versionName Current version name of this export. Empty if unversionned. String fps Frame width of the exported frames. Double scanFormat Scan format of the exported asset. Possible values: - FIELD_1
- FIELD_2
- PROGRESSIVE
String depth Bit depth of the exported asset. Possible values: - 8-bits
- 10-bits
- 12-bits
- 16 fp
String height Frame height of the exported asset. Long width Frame width of the exported asset. Long aspectRatio Frame aspect ratio of the exported asset. Double openClipNamePattern List of the tokens used in the UI to name the Open Clip XML that was created by the export node. Only available if Clip Version (versionning) is enabled in the UI.
String openClipResolvedPath Full path to the open clip that was created, with all the tokens resolved. Only available if Clip Version (versionning) is enabled in the UI.
String setupNamePattern List of the tokens used in the UI to name the batch setup that was created by the export node. Only available if Clip Version (versionning) is enabled in the UI.
String setupResolvedPath Full path to the batch setup that was created, with all the tokens resolved. Only available if Clip Version (versionning) is enabled in the UI.
String - userData
- Dictionary. User-defined. Empty Dictionary that is carried over from the batchExportBegin hook. This can be used by the hook to pass black box data around.
batchDefaultIterationName
Called at application startup, and whenever the user switches project. Use it to define the default name given to new Batches created by the user in the Media Panel. Overrides the preferences defined in . The returned value can use any of the tokens available in the UI such as <user nickname> (note the lack of underscore).
def batchDefaultIterationName( project ): return ""
- project
- String. Usually called with the current project. If a project name is specified, the default batch iteration name for this project will be returned. For example:
if project == "project_name": return "<batch name>_<iteration###>_project" return "<batch name>_<iteration###>_global"
batchDefaultRenderNodeName
Called at application startup, and whenever the user switches project. Use it to define the default node name given to new render nodes. Overrides the preferences defined in . The returned value can use any of the tokens available in the UI such as <user nickname> (note the lack of underscore).
def batchDefaultRenderNodeName( project ): return ""
- project
- String. Usually called with the current project. If a project name is specified, the default render node name for this project will be returned. For example:
if project == "project_name": return "<batch name>_render_project" return "<batch name>_render_global"
batchDefaultWriteFileNodeName
Called at application startup, and whenever the user switches project. Use it to define the default node name given to new write file nodes. Overrides the preferences defined in . The returned value can use any of the tokens available in the UI such as <user nickname> (note the lack of underscore).
def batchDefaultWriteFileNodeName( project ): return ""
- project
- String. Usually called with the current project. If a project name is specified, the default write file node name for this project will be returned. For example:
if project == "project_name": return "<batch name>_write_file_project" return "<batch name>_write_file_global"
Project Hooks
projectChanged.func_dict[ "async" ] = True #Runs in its own interepreter separate from the application appInitialized.func_dict[ "async" ] = False #Uses the same thread as the application
projectChanged, appInitialized, and projectSaved can all be run synchronously or asynchronously in its own interpreter, by setting their respective func_dict["async"] true or false.
projectChanged
Called every time the project is changed in the application. This includes the project selection on launch.
def projectChanged(projectName): pass
- projectName
- String. Name of the loaded project.
appInitialized
Called when the application is done loading (from to the Start screen to the actual tab-based UI).
def appInitialized( projectName ): pass
- projectName
- String. Name of the loaded project.
projectSaved
Called whenever a project save is performed by the application. Can be an auto-save, or a user-initiated one.
def projectSaved( projectName, saveTime, isAutoSave ): pass
- projectName
- String. Name of the project saved. This is the project currently open in the UI.
- saveTime
- Float. Time it took to save the project (in seconds).
- isAutoSave
- Boolean. True if the save was automatically initiated. False if the user initiated it.
Generic Hooks
Located in the hook.py.
renderEnded
Called when a sequence finishes rendering, even if the render was unsuccessful due to factors such as a manual abort.
def renderEnded(sequenceName, elapsedTimeInSeconds): pass
- sequenceName
- String. Name of the rendered sequence.
- elapsedTimeInSeconds
- Float. Number of seconds it took to render the sequence named sequenceName.
playbackEnded
Called when a sequence finishes playback, successfully or not.
def playbackEnded(sequenceName, fps): pass
- sequenceName
- String. Name of the sequence that was played back.
- fps
- Float. The frames per second rate at which the sequence was played back.
previewWindowConfigChanged
Called when the user changes the video preview device. The parameters for previewWindowConfigChanged are actually read from the init.cfg VideoPreviewDevice keyword.
def previewWindowConfigChanged(description,width,height,bitDepth, rateString,syncString): pass
- description
- String. Description of the video preview device, such as 1920x1080@5994i_free.
- width
- Integer. Width of the selected preview device.
- height
- Integer. Height of the selected preview device.
- bitDepth
- Integer. Integer of the selected preview device.
- rateString
- String. Rate of the selected preview device, such as 6000i.
- syncString
- String. Sync source of the selected preview device, such as freesync.
Export Hooks
Located in the exportHook.py.
These hooks are used when the user exports from the application.
Export hooks are called in the following order:
- preCustomExport Optional: called if required by getCustomExportProfiles. Called when the contextual menu item defined by getCustomExportProfiles is selected by the user.
- preExport Always called. In a regular export, preExport is called as the Export window is displayed to the user. In a custom export, called after preCustomExport.
- preExportSequence Always called. Called before writing the sequence.
- preExportAsset Always called. When it is called depends on the export option. With Foreground Export, all preExportAsset are called for each assets immediately in one go. With Background Export, each preExportAsset is called as each asset job is submitted to Backburner.
- postExportAsset Always called. Called after an asset is written. Can be done in backburner as determined by use BackburnerPostExportAsset.
- postExportSequence Always called. Called after postExportAsset.
- postExport Always called. Called after postExportSequence.
- preCustomExport Optional: called if required by getCustomExportProfiles. Called after preCustomExport.
Export Hook Example
The info dictionary contains the information set by the selected preset, be that by the contextual menu defined by getCustomExportProfiles, or by the preset selected by the user in the Export window.
This means that for regular exports, the user either uses one of the presets, or inputs the required information in the Export dialog box. For custom exports, the getCustomExportProfiles get the actual profile use, based on the contextual menu defined within.
def getCustomExportProfiles( profiles ): profiles['Create Stuff']= '/usr/discreet/flamepremium_2015.2.pr45/export/presets/CustomExport.xml'
When performing a regular export through the Export window, use preExport to validate or overwrite settings that the user might have changed. This ensures the exported information is correctly output, to the correct directory.
def postExportAsset( info, userData ): # These processes are performed here because the postExportAsset is called # each time an asset is done being written. # # Make sure that the written asset is something we actually went to process # assetType = info.get( "assetType" ) if ( assetType not in [ "video", "batch", "openClip", "batchOpenClip" ] ): return # If the export is foreground, accumulate the asset and update the asset # management system at the end of the export process to increase performace # if ( not info.get( "isBackground", False ) ): userData[ "assetList" ][ assetType ].append( info ) else: if ( assetType == "video" ): createVersions # Create a new version in the asset management elif ( assetType == "batch" ): createBatchAssets # Create an entry for the Batch setup elif ( assetType == "openClip" ): createOpenClipAsset # Create and insert the Open Clip XML file elif ( assetType == "batchOpenClip" ): createBatchOpenClip # Create the batch Open Clip XML file
preCustomExport
Called before a custom export begins, just after the user clicks the Export button. The export is blocked until the function returns.
def preCustomExport( info, userData ): pass
- info
- Dictionary. Information about the export. Some of this information can be modified by the script as it executes and is marked as Editable.
Key Description Data Type destinationHost Editable. Name of the host where the exported files will be written. Defaults to localhost. String destinationPath Editable. Export path root. This path will probably be added to by the actual Preset path. Defaults to /tmp. String presetPath Editable. Path to the preset used for the Export. String useTopVideoTrack Editable. Use only the top video track and ignore the other ones. False if not defined. Boolean exportBetweenMarks Editable. Export between the In and Out marks, excluding the marked frames. Without In, export from start of sequence to Out; without Out, export from the In to the end of the sequence. False if not defined. Boolean isBackground Editable. Perform the export in background. True if not defined. Boolean abort Editable. Set abort to True to abort the export process. Boolean abortMessage Editable. The error message to be displayed to the user when the export process has been aborted. String - userData
- Dictionary. User-defined. Dictionary that could have been populated by previous export hooks and that will be carried over into the subsequent export hooks. This can be used by the hook to pass black box data around.
postCustomExport
Called after a custom export ends. The export is blocked until postCustomExport returns.
def postCustomExport( info, userData ): pass
- info
- Dictionary. Information about the export.
Key Description Data Type destinationHost Name of the host where the exported files were written to. String destinationPath Root of the export path. String presetPath Path to the preset used for the Export. String - userData
- Dictionary. User-defined. Dictionary that could have been populated by previous export hooks and that will be carried over into the subsequent export hooks. This can be used by the hook to pass black box data around.
preExport
Called before an export begins
def preExport( info, userData ): pass
- info
- Dictionary. Information about the export.
Key Description Data Type destinationHost Name of the host where the exported files will be written to. String destinationPath Root of the export path. String abort Editable. Set abort to True to abort the export process. Boolean abortMessage Editable. The error message to be displayed to the user when the export process has been aborted. String - userData
- Dictionary. User-defined. Dictionary that could have been populated by previous export hooks and that will be carried over into the subsequent export hooks. This can be used by the hook to pass black box data around.
postExport
Called before an export begins
def postExport( info, userData ): pass
- info
- Dictionary. Information about the export.
Key Description Data Type destinationHost Name of the host where the exported files were written to. String destinationPath Root of the export path. String - userData
- Dictionary. User-defined. Dictionary that could have been populated by previous export hooks and that will be carried over into the subsequent export hooks. This can be used by the hook to pass black box data around.
preExportSequence
Called before an sequence export begins. The export is blocked until this function returns.
def preExportSequence( info, userData ): pass
- info
- Dictionary. Information about the export.
Key Description Data Type destinationHost Name of the host where the exported files were written to. String destinationPath Root of the export path. String sequenceName Name of the exported sequence. String shotNames Tuple of every shot name in the exported sequence. Note that multiple segments can use the same shot name: segments sharing shot names are part of the same shot. String abort Editable. Set abort to True to abort the export process. Boolean abortMessage Editable. The error message to be displayed to the user when the export process has been aborted. String - userData
- Dictionary. User-defined. Dictionary that could have been populated by previous export hooks and that will be carried over into the subsequent export hooks. This can be used by the hook to pass black box data around.
postExportSequence
Called after a sequence export ends. The export is blocked until this function returns.
def postExportSequence( info, userData ): pass
- info
- Dictionary. Information about the export.
Key Description Data Type destinationHost Name of the host where the exported files were written to. String destinationPath Root of the export path. String sequenceName Name of the exported sequence. String shotNames Tuple of every shot name in the exported sequence. Note that multiple segments can use the same shot name: segments sharing shot names are part of the same shot. String - userData
- Dictionary. User-defined. Dictionary that could have been populated by previous export hooks and that will be carried over into the subsequent export hooks. This can be used by the hook to pass black box data around.
preExportAsset
Called before an asset export begins. The export is blocked until this function returns.
def preExportAsset( info, userData ): pass
- info
- Dictionary. Information about the export.
Key Description Data Type destinationHost Name of the host where the exported files were written to. String destinationPath Root of the export path. String namePattern List of optional naming tokens as entered in the application UI. String resolvedPath Editable.Path (relative to destinationPath) with the tokens resolved. String name Name of the exported asset. String sequenceName Name of the sequence to which this asset belongs. String shotNames Name of the shot to which this asset belongs. String assetType Type of the exported asset. Possible values: - video
- audio
- batch
- openClip
- batchOpenClip
String width Frame width of the exported asset. Long height Frame height of the exported asset. Long aspectRatio Frame aspect ratio of the exported asset. Double depth Bit depth of the exported asset. Possible values: - 8-bits
- 10-bits
- 12-bits
- 16 fp
String scanFormat Scan format of the exported asset. Possible values: - FIELD_1
- FIELD_2
- PROGRESSIVE
String fps Frame rate of the exported asset. Double sequenceFps Frame rate of the sequence to which this asset belongs. Double sourceIn The source In point as a frame, using the asset frame rate (the fps key). Integer sourceOut The source Out point as a frame, using the asset frame rate (the fps key). Integer recordIn The record In point as frame, using the sequence frame rate (the sequenceFps key). Integer recordOut The record Out point as a frame, using the sequence frame rate (the sequenceFps key). Integer track ID of the sequence's track that contains the asset. String trackName Name of the sequence's track that contains the asset. String segmentIndex Asset index (1 based) in the track. Integer versionName Current version name of this export. Empty if unversionned. String versionNumber Current version number of this export. Zero if unversionned. String - userData
- Dictionary. User-defined. Dictionary that could have been populated by previous export hooks and that will be carried over into the subsequent export hooks. This can be used by the hook to pass black box data around.
postExportAsset
Called after an asset export ends. The export is blocked until this function returns.
def postExportAsset( info, userData ): pass
- info
- Dictionary. Information about the export.
Key Description Data Type destinationHost Name of the host where the exported files were written to. String destinationPath Root of the export path. String namePattern List of optional naming tokens as entered in the application UI. String resolvedPath Editable.Path (relative to destinationPath) with the tokens resolved. String name Name of the exported asset. String sequenceName Name of the sequence to which this asset belongs. String shotNames Name of the shot to which this asset belongs. String assetType Type of the exported asset. Possible values: - video
- audio
- batch
- openClip
- batchOpenClip
String width Frame width of the exported asset. Long height Frame height of the exported asset. Long aspectRatio Frame aspect ratio of the exported asset. Double depth Bit depth of the exported asset. Possible values: - 8-bits
- 10-bits
- 12-bits
- 16 fp
String scanFormat Scan format of the exported asset. Possible values: - FIELD_1
- FIELD_2
- PROGRESSIVE
String fps Frame rate of the exported asset. Double sequenceFps Frame rate of the sequence to which this asset belongs. Double sourceIn The source In point as a frame, using the asset frame rate (the fps key). Integer sourceOut The source Out point as a frame, using the asset frame rate (the fps key). Integer recordIn The record In point as frame, using the sequence frame rate (the sequenceFps key). Integer recordOut The record Out point as a frame, using the sequence frame rate (the sequenceFps key). Integer track ID of the sequence's track that contains the asset. String trackName Name of the sequence's track that contains the asset. String segmentIndex Asset index (1 based) in the track. Integer versionName Current version name of this export. Empty if unversionned. String versionNumber Current version number of this export. Zero if unversionned. String - userData
- Dictionary. User-defined. Dictionary that could have been populated by previous export hooks and that will be carried over into the subsequent export hooks. This can be used by the hook to pass black box data around.
useBackburnerPostExportAsset
Indicates whether postExportAsset should be called from a backburner job or directly from the application.
Not generating a postExportAsset backburner job for exports that are using backburner could result in postExportAsset being called before the export job is complete.
def useBackburnerPostExportAsset(): return True
getCustomExportProfiles
Returns the custom export profiles to show to the user in the contextual menu that is displayed when right-clicking a clip in the application. These custome export profiles are displayed after the Export... menu item, and are expected to trigger an export.
def getCustomExportProfiles( profiles ): pass
- profiles
- Dictionary. User-Defined. A dictionary of userData dictionaries where the keys are also used as the name of the profiles displayed in the contextual menu.