transmogrifer.py is the primary command line interface for the Transmogrifier framework. This file, located at /usr/local/bin/transmogrifier.py, provides a means to interface with Final Cut Server assets and productions. It provides functionality for programatically reading and writing asset and production metadata, creating or deleting assets and productions, modifying production membership, or triggering archive and restore operations. Assets and productions can be referenced by their unique FCS ID, by their title, or in the case of assets, by their file system path. In addition to this, transmogrifier allows assets to be mass modified at the production or FCP project level.
Lastly, transmogrifier.py provides a module interface that allows for integration with various delivery services, such as YouTube, BrightCove, or ThePlatform.
All of this functionality significantly expands the types of automation that can be triggered in Final Cut Server.
The transmogrifier.py script has the following usage:
FCS transmogrifier
Version: .95beta Build: 2011032802
Framework Version: .96beta Build: 2011041301
Copyright (C) 2011 Beau Hunter, 318 Inc.
transmogrifier.py [options] [target]
transmogrifier.py [-f configfile] [-d supportdir] [-a action] [-t mediatitle]
Working with assets:
transmogrifier.py --setField="Keywords" --value="MyAsset" -t MyAsset
transmogrifier.py --setField="Keywords" --value="MyAsset" -i /fcsxmlinfile.xml
transmogrifier.py --appendField="Status" --value="Update!" -i /fcsxmlinfile.xml
transmogrifier.py --getAssetID --assetPath="/FCS/Media/myfile.mpg"
transmogrifier.py --getEntityPath --assetID=1
transmogrifier.py --getThumbnailPath --assetID=1
transmogrifier.py --getProxyPath --assetID=1
transmogrifier.py --getPosterFramePath --assetID=1
transmogrifier.py --archive --assetID=1
transmogrifier.py --restore --assetID=1
transmogrifier.py --analyze --assetID=1
Working with productions:
transmogrifier.py --setField="Owner" --value="Calvin" --assetsWithProductionID=1
transmogrifier.py --restore --productionID=1
Working with devices:
transmogrifier.py --getDeviceName --deviceID=1
transmogrifier.py --getDeviceName --devicePath="/FCS/Media"
transmogrifier.py --getDevicePath --deviceName="Media"
transmogrifier.py --getDevicePath --deviceID=1
transmogrifier.py --getDeviceID --deviceName="Media"
transmogrifier.py --getDeviceID --devicePath="/FCS/Media"
Working with Modules:
transmogrifier.py --module=BrightCove -t MyAsset [-a action]
transmogrifier.py --module=BrightCove -a preflightCheck|upload -t MyAsset
transmogrifier.py -a createSupportFolders [-m BrightCove] [-d supportdir]
transmogrifier.py --module=BrightCove -a listFCSFields
Options:
-h, --help Displays this help message
-v, --version Display version number
-f configfilepath Use specified config file
-d supportdir Path to support folder
--debug Run in debug mode
--xmlout= Specify a FCS XML file to write out.
-m,--module=MODULE Delivery Target: 'BrightCove', 'YouTube',etc..
-a action Perform the requested action.
--fcsvr_client Utilise fcsvr_client for FCS I/O operations
This defaults to yes by default on certain operations
--nofcsvr_client Under no circumstances utilize fcsvr_client for
operations
--getField=FIELD Method to retrieve the value of FIELD
--getDBField=FIELD Method to retriev the value of FIELD using the
Final Cut Server database field name.
--setField=FIELD Method to specify FIELD to set with --value
--appendField=FIELD Append the specified field FIELD with --value
--value=value Data to append to set or import to --field
--withtimestamp Prepends a time stamp to STRING
--notimestamp Omits timestamp, if specified in config file
--getAssetID Outputs the assetID for specified target asset
--getAssetPath Outputs the asset's filesystem path
--getEntityPath Outputs the FCS address for specified target asset
--getEntityMetadataSet Outputs the metadata set associated with entity
--getProxyPath Outputs the asset's proxy path
--getEditProxyPath Outputs the asset's edit proxy path
--getThumbnailPath Outputs the asset's thumbnail path
--getPosterFramePath Outputs the asset's posterframe path
--getDeviceName Outputs the deviceName for specified target
--getDevicePath Outputs the device path for specified target
--getDeviceID Outputs the device id for the specified target
--getProductionTitle Outputs the production name of the specified target
--getProductionID Outputs the production id of the specified target
--addToProduction Adds the specified asset to the specified production
--archive Archive the specified target
--restore Restore the specified target
--filterMDSet=mdset Filters objects to only those with the provided
metadataset (experimental)
Targets:
-t title,--title= Title of the XML file to read in, useful when
using WriteXML response in FCS.
Utilizes paths set in transmogrifier.conf
--xmlin="/myfile.xml" Specify a FCS XML file to read in. Overwrites -t
--assetID=1 Asset with ID 1
--assetPath="/myfile" Asset residing at "/myfile"
--assetTitle="title" Asset with title "title"
--productionID=1 Production with ID 1
--productionTitle='title' Production with title 'title'
--productionTitleLike='title' Production with title matching substring 'title'
--assetsFromProductionID=1 All assets from the specified production.
--assetsFromProjectID= All assets linked from the provided FCP project file
--deviceID=1 Device with ID 1
--deviceName="Media" Device with name "Media"
Return Codes:
0 Clean Execution
1 Syntax Error
2 Syntax Error: parameter missing
4 Invalid target
5 Ambiguous/Conflicting Target
6 Invalid Action
7 fcsvr_client unavailable
8 Error reading from source (bad XML, fcsvr_client error)
9 Target(s) is(are) offline
99 Unknown Error
The following section discusses some common use-cases for transmogrifier.py.
Update the value for field Description for an asset with id: 10
Modify a string field
>>> transmogrifier.py --setField='Description' --value='My new description' --assetID=10
Modify a boolean field
>>> transmogrifier.py --setField='IsGood' --value=1 --assetID=10
Modify a date field:
>>> transmogrifier.py --setField='Simulation Date' --value="$(date -u +'%Y-%m-%d %H:%M:%SZ')" --assetID=10>>> transmogrifier.py --setField='Simulation Date' --value="$(date +'%Y-%m-%d %H:%M:%S')" --assetID=10>>> transmogrifier.py --setField='Simulation Date' --value="now()" --assetID=10
Retrieve the value for field Owner and the device name for an asset that resides at path /Users/Shared/FCSStore/Media/Library/myfile.mov
>>> transmogrifier.py --getField='Owner' --getDeviceName --assetPath='/Users/Shared/FCSStore/Media/Library/myfile.mov'
Owner: Beau Hunter
DEVICE_NAME: Media
Retrieve asset id, asset path, thumbnail path, posterframe path, and proxy path, value for field Owner and field Status for an asset with title Test Movie
>>> transmogrifier.py --getAssetID --getAssetPath --getThumbnailPath --getPosterFramePath \
--getProxyPath --getField=Owner --getField=Status --assetTitle="Test Movie"
ASSET_ID: 24
ASSET_PATH: /Users/Shared/FCSStore/Media/Library/Test Movie.mov
THUMBNAIL_PATH: /Users/Shared/FCSStore/Proxy/Proxies.bundle/00/00/0000000000000087/Test Movie.jpg
POSTERFRAME_PATH: /Users/Shared/FCSStore/Proxy/Proxies.bundle/00/00/0000000000000092/Test Movie.jpg
PROXY_PATH: /Users/Shared/FCSStore/Proxy/Proxies.bundle/00/00/0000000000000098/Test Movie.mov
Owner: Beau Hunter
Status: Ready for Review
Transmogrifier also has the capability to append a field, inserting a timestamp, which is pretty usefull for history-based fields. We can achieve this through the syntax below.
>>> transmogrifier.py --appendField='Review History' --value='My new comment' --withtimestamp --assetID=24
On the first run of the above command, the Review History field will have the following content:
2011-04-14 12:19: My new comment
On a subsequent run, the field value will be:
2011-04-14 12:19: My new comment
2011-04-14 12:20: My new comment
To take this further: say that we want to keep a record of all review comments, approvals, and rejections performed on an asset. In Final Cut Server, we would add a subscription to monitor the Status field for changes. This subscription would then trigger an external script response configured with the following:
Command: /usr/local/bin/transmogrifier.py
Parameters: '--appendField=Review History' "--value=[Current Reviewer] \
Set status to: [Status] \\nComments: [Reviewer's Comments]" \
--withtimestamp '--assetID=[Asset ID]'
When triggered, the asset’s Review History field will resemble the following:
2011-04-14 12:19: Beau Hunter Set status to: Rejected
Comments: Please fix the lower third.
2011-04-16 11:45: Beau Hunter Set status to: Approved
Comments: Looks better, approved.
The --appendField can also be used to increment integer fields:
>>> transmogrifier.py --getField='Test Int' --assetID=24
Test Int: 1000
>>> transmogrifier.py --appendField='Test Int' --value=30 --assetID=24
>>> transmogrifier.py --getField='Test Int' --assetID=24
Test Int: 1030
It is important to note that the vast majority of the above operations can be applied to a production target instead of an asset target:
>>> transmogrifier.py --getField='Title' --getField='Test Int' --productionID=10
Title: "My Great Production"
Test Int: 1
>>> transmogrifier.py --getProductionID --getField='Test Int' --productionWithTitle="My Great Production"
PRODUCTION_ID: 10
Test Int: 1
As we mentioned earlier, it is possible to mass-modify assets based upon production or project membership. This can be leveraged to implement extremely powerful workflows that otherwise wouldn’t be possible using native Final Cut Server functionality.
For example, using Transmogrifier, it is extremely easy to archive all assets of a given production:
>>> transmogrifier.py --archive --assetsFromProductionID=10
Archiving Asset: /asset/40
Archiving Asset: /asset/43
Archiving Asset: /asset/46
And we can do the same thing on a specific project:
>>> transmogrifier.py --archive --assetsFromProjectID=24
Archiving Asset: /asset/2
Archiving Asset: /asset/14
We can also mass edit assets:
>>> transmogrifier.py --setField=Owner --value="Beau" --assetsFromProductionID=10
We can also filter any of the above commands using the --filterMDSet argument, which will force the specified actions to operate solely on assets matching the specific metadata set provided:
>>> transmogrifier.py --setField=Owner --value="Beau" --filterMDSet='asset_graphic' --assetsFromProductionID=10
This functionality opens the door to a lot of automation possibilities. Say that we want to be able to populate a field, Assigned Editor on a production, and have that same field value be populated to any FCP project files that reside in the production, without having to manually modify each record.
To accomplish this in Final Cut Server, we would add a production subscription to monitor the Assigned Editor field for changes. This subscription would then trigger an external script response configured with the following:
Command: /usr/local/bin/transmogrifier.py
Parameters: '--setField=Assigned Editor' '--value=[Assigned Editor]' \
'--filterMDSet=asset_project' '--assetsFromProductionID=[Production ID]'
Another important production-based function is found in the --addToProduction flag. This function does what it says it does, and can be applied either to assets or productions using standard targets:
## Add asset ID 38 to production with title ``My Production``
>>> transmogrifier.py --addToProduction --assetID=38 --productionTitle="Mar-2011"
## Add production 10 to production 11
>>> transmogrifier.py --addToProduction --productionID=10 --productionID=11
## Add assets linked in FCP project file with asset id: 24 to production 11
>>> transmogrifier.py --addToProduction --assetsFromProjectID=24 --productionID=11