Batch Processing with Time Shaper
Time Shaper's user interface provides an easy way to set up and process one clip at a time, but for production, it is usually necessary to process many, many clips in a way that provides consistency and high throughput.
To aid in this, Time Shaper includes a command-line version which can be easily scripted, and the settings produced in the graphical user interface can be exported to run the command line version.
The command line version is located in the application bundle for Time Shaper:
/Applications/Time Shaper.app/Contents/Helpers/timeshaper
Running this utility without any arguments in the OS X terminal will display the full help for the program.
The command line version of Time Shaper provides all the processing capability of the full graphical version, including all the synthetic shutters and speed ramps.
The easiest way to set up the command line version is to use the graphical interface to configure all the settings, then use the "File/Copy Command Line" menu item to copy the full command with all settings to the clipboard. This command can be immediately pasted into the terminal, or it can be pasted into a script file that can be later executed.
SYNOPSIS
timeshaper [-h | -? | -help]
timeshaper -gpulist
timeshaper [<options>] inputfilename outputpath outputclipname
Following are the options broken up into sections:
[-usegpu#]
[<filename.json>]
[-csLinear | -cs"Rec-709" | -cs"DCI P3" | -cs"ARRI Log-C" | -cs"Sony SLog2" | -cs"Sony S-Log3" | -cs"GoProColor" | -cs"GoPro Flat"]
[-ifr###.##]
[-f]
[-ost"ProRes 422 (Proxy)" | -ost"ProRes 422 (LT)" | -ost"ProRes-422" | -ost"ProRes 422 (HQ)" | -ost"ProRes 4444" | -ost"Uncompressed" | -ost"PIZ Lossless" | -ost"B44A Lossy"]
[-ofr23.976 | -ofr24 | -ofr25 | -ofr29.97 | -ofr30 | -ofr50 | -ofr59.94 | -ofr60]
[-fi###] [-fo###]
[-sf##.## | -st"(###,##.#)(###,##.#)..."]
[-sh<shuttername>]
[-sa###.#]
[-i0 | -i1]
[-log<logfilename>] [-btc] [-tc0] [-clg] [-ar###]DESCRIPTION
The timeshaper utility can read ProRes, EXR, and ARRIRAW footage and downsample the high frame rate footage to desired project frame rates. This downsampling can be tuned to yield optimal motion representation.
Specifying some of the timeshaper options can be tricky depending on the specific input and output frame rates in use. The Time Shaper graphical application makes selection of options much easier and interactive, and has the ability to save the selected options as command options for this timeshaper utility.
OPTIONS
-h | -help | -? Show this help file
Displays the utility help. Ignores all other arguments.
-gpulist List available GPUs
Lists the available GPUs on the system with their corresponding selection IDs for use with -usegpu. Ignores all other arguments.
-usegpu Specify the GPU (or CPU) to use for processing
Indicates the GPU device to use as a zero-based value into the items listed in -gpulist. Defaults to 1 on systems with a GPU, 0 if no GPU is present. A value of 0 indicates no GPU will be used.
Example:
-usegpu1-cf Load a configuration json file
The Time Shaper GUI can save json settings files with all the settings specified. If it exists, the timeshaper utility will first load any json file with the same name as the clip in the clip directory. Then, if this option is specified, any settings will be changed to by the file specified here. Finally, any other command line options will override settings set by the json files.
-cs Color Space
For ProRes, one of:
-cs"Rec-709" (default for ProRes)
-cs"DCI P3"
-cs"ARRI Log-C"
-cs"Sony S-Log2"
-cs"Sony S-Log3"
-cs"GoProColor"
-cs"GoPro Flat"
-csLinearFor others, only -csLinear is allowed (which is the default)
-ifr Incoming Frame Rate
The incoming footage frame rate represented as a floating point number. For instance: -ifr120.0
If unspecified, the Incoming frame rate is determined as well as possible from the source footage. This is only available if metadata in the source footage indicates the acquisition (rather than project) frame rate. OutputPath
-f Force Overwrite
If specified, will overwrite the output file if it exists. By default, timeshaper will not overwrite the output file and an error will be generated if the output already exists.
-ost Output SubType
For ProRes output files only, is one of:
-ost"ProRes 422 (Proxy)"
-ost"ProRes 422 (LT)"
-ost"ProRes 422"
-ost"ProRes 422 (HQ)"
-ost"ProRes 4444"If unspecified, the output file type will match the input file type.
For EXR, is one of:
-ost"Uncompressed"
-ost"PIZ Lossless"
-ost"B44A Lossy"If unspecified, the output file will be uncompressed.
-ofr Output Frame Rate
Specifies the output project frame rate. This is one of:
-ofr23.976 (default)
-ofr24
-ofr25
-ofr29.97
-ofr30
-ofr50
-ofr59.94
-ofr60-fi In Frame Number
The "in" frame for generating the output. Defaults to 51 (first possible input frame). This value must be less than or equal to the OutFrameNumber and greater than 0.
-fo Out Frame Number
The "out" frame for the output. Defaults to the length of the input clip minus 50. This value must be greater than or equal to the InFrameNumber and less than or equal to the length of the input clip minus 50 frames.
-sf Speed Factor
The speed factor for resampling. A value of 1 will represent the live action as real-time in the output clip. Values less than 1 will cause action to appear slowed (overcranked). Values greater than 1 will cause action to appear sped-up (undercranked) in the output footage.
See the discussion on binning, speed factors, and shutter selection on how to compute a speed factor.
By default, the speed factor is specified as 1.0, meaning that for the provided input and output frame rates, the available speed factor nearest to 1.0 will be used.
The "-sf" argument cannot be used with the "-st" argument. Specifying both will cause an error.
Examples:
-sf1.0
-sf0.99-st Speed Table
A table of speed factors to use in speed ramping during over the clip. The speed factor table is specified with position/value pairs consisting of an input frame number as a keyframe and a speed factor.
Input frame numbers are 1-based, and the first usable frame of the input clip is 51, and the last usable frame is 51 before the end of the clip. Timeshaper will move any keyframes specified before or after these points to the end of the usable range.
The speed factor at each input frame number is specified as a floating point number, with 1.0 indicating realtime playback. Values greater than 1 will result in fast playback, and values less than 1 will result in slow motion (overcranked) playback.
Timeshaper only permits integer upsampling or downsampling at the keyframes, and will round to the nearest valid value. For instance, if the resample is from 120 to 24 fps, the only valid speed factors would be 0.2, 0.4, 0.6, 0.8, 1, 1.2 and so on (corresponding to 1/5, 2/5, 3/5, 4/5, 5/5, 6/5, etc.)
The pairs are specified as paren-grouped pairs, with an input frame number followed by a comma and then followed by a floating point speed factor.
Start and end clip keyframe/speedfactor pairs can be specified. If not specified, the first and last pair will be used as constant speed values to the extents of the clip.
For instance, if an input clip is 500 frames in length, and the following argument is used:
-st"(100,1.0)(150,0.4)(300,1.0)"it would be equivalent to specifying:
-st"(51,1.0)(100,1.0)(150,0.4)(300,1.0)(450,1.0)"The order in which the keyframe/speedfactor pairs are specified is not important.
The argument values must be surrounded with double quotes.
The speed table is independent of the "in" and "out" points specified.
The "-sf" argument cannot be used with the "-st" argument. Specifying both will cause an error.
-sh Shutter
The type of synthetic shutter to apply. This is one of the
supported shutters:
-shTessive_Os
-shTessive_C
-shTessive_Be
-shTessive_Ag
-shTessive_Mg
-shTessive_Np
-shTessive_Ga
-shTessive_X
-shTessive_Y
-shSquare-sa Desired Shutter Angle
The desired shutter angle for square-wave shutters. If any shutter type other than "Square" is specified in the "-sh"command, this will be ignored. For square-wave shutters, the nearest possible shutter angle to the specified value will be used.
-i0 | -i1 Shutter Interpolation
For setups where there is not integer frame alignment, indicates if the shutter waveform should be interpolated (if possible). -i0 disables interpolation, while -i1 enables interpolation.
-log Log File
The name of the running log file. If specified, this file will be created if it does not exist, or appended to if it does exist. For each clip processed, a tab-delimited line of information will be added to the log.
-btc Burn-in timecode info string
If specified, will burn in the timecode and the clip info, including shutter setting, on the output frames.
-tc0 Zero output timecode
If specified, the output timecode will begin at 00:00:00:00
-clg Create a per-clip log file
If specified, will create a log file per clip (distinct from the running log). The clip log will have the same name as the output clip, with the extension ".log".
-ar### Add black rows to the top and bottom of the frame
Will add a total of ### black rows to the frame, splitting evenly between top and bottom. This can be useful for burnin. The value can be a number from 0 to 1000, and must be even (if not even, will be rounded to nearest even number.)
inputfilename
The fully-qualified path and filename of the input file. For ARRIRAW or EXR, this is one of the files in an ARRIRAW or EXR set.
outputpath
The path to the desired output directory for the created file to be written.
outputclipname
The name of the output clip. For ProRes files, this will become the filename, for ARRIRAW clips it will become the name of the created output directory and be the prefix of all created files. This clip name does not include the file extension (but can have any legal file character, including period). This is just the name of the clip.