.. transmogrifier.py command line interface documentation transmogrifier.py (Command line interface) ========================================== 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. Syntax ++++++++++++++++++++++++++++++++++++++++++ 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 Example Usage ++++++++++++++++++++++++++++++++++++++++++ The following section discusses some common use-cases for transmogrifier.py. Basic Metadata Operations ------------------------------------------ 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 .. note: By default, FCS operates on UTC time code (shown in the first example). Thus, it is recommended that you submit all datetime strings in UTC. However, you can provide the date using time based on your current time zone and the system will automatically convert this to UTC time. This operation is reliant on the static variable ``timezoneOffset`` as set in :class:`fcsxml.FCSBaseObject`, you will need to adjust it to match your current time zone. 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. .. note: The above command assumes that the fields ``Review History``, ``Current Reviewer``, and ``Reviewer's Comments`` have been configured. 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 Production and Project Operations ------------------------------------------ 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 .. note: ``--assetsFromProjectID`` should be provided the asset id of a Final Cut Pro Project file 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 .. note: When using ``--filterMDSet``, we must specify the FCS ID for the metadata set, *not* it's display name (i.e. 'pa_asset_media' instead of 'Media') 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 Working with Modules ++++++++++++++++++++++++++++++++++++++++++