Python API

Used to enable or disable the new Add to Workspace button available in the Write File node.

One of the following must be set as an argument:

• True
• False

Enable the Add to Workspace option in a Write File node

wf = flame.batch.create_node("Write File")
wf.add_to_workspace = True

Used to set the in_mark and out_mark on a Render node.

A frame or timecode information must be passed as an argument. This can be done by passing the information from another node or using a PyTime.

Set the Render node In Mark based on a Clip's In Mark

Enable the Add to Workspace option in a Write File node

clip = flame.batch.get_node("clip100")
wf = flame.batch.create_node("Write File")
wf.in_mark = clip.in_mark

Set the Render node Out Mark using a PyTime

time = flame.PyTime(10)
wf = flame.batch.create_node("Write File")
wf.out_mark = time

Used to get only the number part of a Batch Iteration name.

Get the current iteration number of the current Batch Group

iteration = flame.batch.current_iteration_number
print(iteration)

Used to get the media path of a write file node with resolved tokens. Three arguments can be set:

• show_extension
• True or False must be passed.
• Used to display or not the part with the frame range and filename extension.
• translate_path
• True or False must be passed.
• Used to apply the Media Location Path Translation.
• frame
• A number must be passed.
• Used to get the path of a specific frame.

Get the system disk path set in a selected Write File node

wf = flame.batch.current_node.get_value()
path = get_resolved_media_path(show_extension = False, translate_path = True)
print(path)

Used to set the name of a channel in the Render and Write File nodes.

The following must be passed as arguments:

• The channel to be modified. Either the channel index or current name can be used.
• The new channel name.
• For the Render node, the name of the Matte channel must be specified as well.

Change the first two channels of a Write File node

wf = flame.batch.get_node("writefile")
wf.set_channel_name(0, "Beauty")
wf.set_channel_name("rgb2", "Z")

Change the first two channels of a Render node

rn = flame.batch.get_node("render")
rn.set_channel_name(0, ("Beauty","Beauty_alpha"))

Used to print a tuple of the current channels present in a Render and Write File nodes.

Print the name of channels present in a Write File node

wf = flame.batch.get_node("writefile")
print(wf.channels) 

Used to open a message dialog box and offer options to users. The following arguments can be passed:

• title (mandatory)
  • The title of the message window. A string must be passed.
• message (mandatory)
  • The message body. A string must be passed.
• type (mandatory)
  • The message window's type. One of the following must be passed:
    • info
    • error
    • warning
    • question
• buttons (optional)
  • Up to three user defined options in the form of buttons can be offered. The right most option is displayed in blue and can be selected using the Enter shortcut.
  • An additional option can be defined outside of the first list of buttons. That option is displayed on the left and can be selected the ESC (Flame) or ~ (Smoke Classic) shortcut.

Example:

Display a Dialog offering default colours for a new Reel.

reelgroup = flame.projects.current_project.current_workspace.desktop.reel_groups[0]

dialog = flame.messages.show_in_dialog(
title ="Create Coloured Reel",
message = "Which colour coding do you want to apply to your new Reel?",
type = "question",
buttons = ["Red", "Green", "Blue"],
cancel_button = "Cancel")
if dialog == "Red":
    red = reelgroup.create_reel("red")
    red.colour = (0.75, 0.0, 0.0)
if dialog == "Green":
    green = reelgroup.create_reel("green")
    green.colour = (0.0, 0.75, 0.0)
if dialog == "Blue":
    blue = reelgroup.create_reel("blue")
    blue.colour = (0.0, 0.0, 0.75)
if dialog == "Cancel":
    pass

Used to print a message in the message console at the bottom left of the screen. The following arguments can be passed:

• message (Mandatory)
  • The message to be printed in the console.
• type
  • The message type. Must be one of:
    • error
    • warning
    • info
• time
  • The amount of time (in seconds) the message must remain displayed on screen.

An example of how to use these functions are available in /opt/Autodesk/<version>/python_examples.

Used to clear the content of the message console.

Allow to import multiple clips at once, as opposed to flame.batch.import_clip() which always imports the frames found in a path as a single clip node.

Used to open a <PyBrowser> window. The Resolution dropdown is set to Same as Source by default. The Width, Height, and Ratio settings are disabled when the resolution is set to Same as Source. In this scenario None is returned for Width, Height, and Ratio.

The following arguments can be passed:

• title
  • The title of the Browser window. A string must be passed.
• default_path
  • The path set in the Browser. A string must be passed.
• extension
  • Used to display only files with a defined extension. A string must be passed.
• select_directory
  • Allows a directory to be selected, not only Files. One of the following must be passed:
    • True
    • False
• multi_selection
  • Allows multiple files/directories to be selected. One of the following must be passed:
    • True
    • False
• include_resolution
  • Enables the display of the resizing controls. One of the following must be passed:
    • True
    • False

Returns a list of the selected files/directories.

Returns a resolution preset name.

Returns the width set in the Resolution controls.

Returns the height set in the Resolution controls.

Returns the bit depth set in the Resolution controls.

Returns the frame ratio set in the Resolution controls.

Returns the scan mode set in the Resolution controls.

Returns the colour space set in the Resolution controls.

Returns the resizing mode set in the Resolution controls.

Returns the resizing filter set in the Resolution controls.

Returns the state of the Sequences / Frames button in the file browser.

Used to set the MediaHub's Colour Space to Tag Only with the defined colour space.

Used to get or set the MediaHub's Resizing mode.

One of the following value must be passed as an argument when the attribute is set:

• Fill
• Crop Edges
• Letterbox
• Centre/Crop

Used to get or set the MediaHub's Resizing filter.

One of the following value must be passed as an argument when the attribute is set:

• Lanczos
• Shannon
• Gaussian
• Quadratic
• Bicubic
• Mitchell
• Triangle
• Impulse

Used to get or set the MediaHub's Resolution.

One of the following value must be passed as an argument when the attribute is set:

• Same as Source
• Project Resolution
• Custom Resolution
• Any resolution presets available.
  • Example: "RED 4.5K 16x9 (4224 x 2376)"

Used to get or set the MediaHub's Resolution width.

An integer value between 24 and 16384 must be passed when the attribute is set.

Used to get or set the MediaHub's Resolution height.

An integer value between 24 and 16384 must be passed when the attribute is set.

Used to get or set the MediaHub's frame ratio.

A float value between 0.01 and 100.00 must be passed when the attribute is set.

Used to get or set the MediaHub's pixel ratio. This attribute is only used when the Resolution is set to "Same as Source"

One of the following value must be passed as an argument when the attribute is set.

• From Source
• A float value between 0.01 and 100.00 must be passed when the attribute is set.

Used to get or set the MediaHub's Bit Depth.

One of the following value must be passed as an argument when the attribute is set.

• 8
• 10
• 12
• 16
• 32
• From Source

Used to get or set the MediaHub's Scan Mode.

One of the following value must be passed as an argument when the attribute is set.

• F1
• F2
• P
• From Source

Used to set the MediaHub's sequence mode to File Sequence or Frame. One of the following must be passed as an argument:

• True.
  • Sets the option to "File Sequence"
• False
  • Sets the option to "Frames"

Use one of the following to import a file sequence as a single clip:

• flame.import_clips( [ "file.0001.exr", "file.0002.exr", "file.0003.exr" ], destination )
• flame.import_clips( [ "file.[0001-0003].exr" ], destination )
• flame.import_clips( "file.[0001-0003].exr", destination )

Used to get the colour space of a frame in time. A PyTime can be passed as an argument to get the colour space at a specific time.

If no PyTime is specified the positioner is used fo the PyClip and the first frame is used for the PySegment.

Used to transform a dissolve into a To/From Colour transition.

RGB values must be passed as an argument.

Used to transform an audio fade into a To/From Silence transition.

Used to get or set the RGB Slope values.

A float number must be passed as an argument when the attribute is set.

Used to get or set the RGB Offset values.

A float number must be passed as an argument when the attribute is set.

Used to get or set the RGB Power values.

A float number must be passed as an argument when the attribute is set.

Used to get or set the Saturation value.

A float number must be passed as an argument when the attribute is set.

Used to get or set the Style value.

One of these must be passed as an argument when the attribute is set:

• No Clamping
• ASC v1.2

Used to get or set the Invert value.

One of these must be passed as an argument when the attribute is set:

• True
• False

Used to remove the colour coding on every entry of the Media Panel that can be colour coded.

Used to create a cut on one or all tracks of a clip.

Example:

Create a cut on all tracks on the 10th frame

time = flame.PyTime(10)
.cut(time)

Create a cut on a single track at 10:00:01:00

time = flame.PyTime("10:00:01:00", "23.976 fps")
.cut(time)

Used to create a Container. The following methods are used in order:

1. Contain selected segments, if any.
2. If there is no selected segment, contain what is between the in and out marks.
3. If there is only one mark, contain from start to out or from in to end.
4. If there is no selection and no marks then all segments are contained.

Returns the content of a container in the form of a PyClip object so some modifications normally made on a PyClip are accessible.

Used to add a gap before or after the first/last Timeline segment of a Sequence.

A PyTime defined up to which frame the gap must be extended must be passed as an argument.

Example:

Add a gap from 09:59:00:00 to 10:00:00:00 for a clip starting at 10:00:00:00

time = flame.PyTime("09:59:00:00", "23.976 fps")
<PySequence>.padding_start = time

Used to turn a Gap into an unlinked media segment. The following arguments can be passed:

• source_name
  • A string must be passed.
• tape_name
  • A string must be passed.
• start_time
  • A PyTime or an integer number must be passed.
• source_duration
  • A PyTime, a number of frames, or "Infinite" must be passed.
• head
  • An integer number must be passed.
• file_path
  • A string must be passed.
• source_audio_track
  • An integer number must be passed.
• width
  • An integer number must be passed. 0 can be used to set it to the sequence's width.
• height
  • An integer number must be passed. 0 can be used to set it to the sequence's height.
• ratio
  • A float number must be passed. 0.0 can be used to set it to the sequence's frame ratio.
• bit_depth
  • One of 8, 10t, 12, 16, or 32 must be passed. 0 can be used to set it to the sequence's bit depth.
• scan_mode
  • One of P, F1, F2, or Same As Sequence must be passed.
• frame_rate
  • One of 60 fps, 59.54 NDF, 59.94 DF, 50 fps, 30 fps, 29.97 NDF, 29.97 DF, 25 fps, 24 fps, 23.976 fps, or Same As Sequence must be passed.

Used to create a transition on a <PyTrack>. The following arguments can be passed:

• record_time
  • At what frame the transition is added. A PyTime must be passed.
• type
  • The transition type. One of the following must be passed.
    • Dissolve
    • Cut
    • Wipe
    • Action
    • OpenFX
    • Matchbox
    • Fade
• duration
  • The transition duration. An integer number must be passed.
• alignment
  • The transition alignment. One of the following must be passed.
    • Centered
    • From Cut
    • Up To Cut
    • Custom
• in_offset
  • The offset between the record_time (cut point) and the start time of the transition. An integer number must be passed.
• sync
  • Used to apply changes to all transitions part of a sync group (only available for Dissolve or Fade). One of the following must be passed:
    
    
    • True
    • False

Example:

Create a new up to cut transition at frame 24 in a Sequence

time = flame.PyTime(24)
track = flame.timeline.clip.versions[0].tracks[0]
track.insert_transition(record_time = time, type = "Dissolve", duration = 10, alignment = "Centred")

Used to set attributes on an existing transition. The following arguments can be passed:

• type
  • The transition type. One of the following must be passed.
    • Dissolve
    • Cut
    • Wipe
    • Action
    • OpenFX
    • Matchbox
    • Fade
• duration
  • The transition duration. An integer number must be passed.
• alignment
  • The transition alignment. One of the following must be passed.
    • Centered
    • From Cut
    • Up To Cut
    • Custom
• in_offset
  • The offset between the record_time (cut point) and the start time of the transition. An integer number must be passed.

Example:

Change an existing cut into a dissolve

cut = flame.timeline.clip.versions[0].tracks[0].transitions[5]
cut.set_transition(type = "Dissolve", duration = 10, alignment = "Centred")

Used to slide a transition. The following arguments can be passed:

• offset
  • The amount number of frame to slide the transition by. An integer number must be passed.
• sync
  • Used to apply changes to all transitions part of a sync group (only available for Dissolve or Fade). One of the following must be passed:
    
    
    • True
    • False

Used to get or set the transition name.

A string must be passed as an argument when the attribute is set.

Used to get or set the transition duration.

An integer number must be passed as an argument when the attribute is set.

Used to get or set the transition alignment.

One of the following value must be passed as an argument when the attribute is set.

• Centered
• From Cut
• Up To Cut
• Custom

Sets the Multi-Channel mode in the MediaHub. The possible modes are:

• Multi-Channel Clip
• Include Alpha Clip
• Ignore Alpha Channel
• Create Matte Container
• Matte Container With Comp
• Matte Container (Full)

Example:

Set the multi-channel mode

flame.mediahub.files.options.multi_channel_mode = "Multi-Channel Clip"

Set the Media Cache mode in the MediaHub. The possible modes are:

• True (Cache is enabled)
• False

Example:

Set the media caching mode

flame.mediahub.files.options.cache_mode = True

Set the Media Proxies mode in the MediaHub. The possible modes are:

• True (Proxies in enabled)
• False

Example:

Set the media proxies mode

flame.mediahub.files.options.proxies_mode = True

Set the Clip Version mode in the MediaHub. The possible modes are:

• True (All Versions is selected)
• False (Current Version is selected)

Example:

Set the clip version mode

flame.mediahub.files.options.cache_and_proxies_all_versions = True

Saves a PyReelGroup to the current Destination in the Library.

The function was previously available for other PyObjects present in the Desktop but was not for the PyReelGroup.

Example:

Save a Reel Group to the destination Library

library = <PyLibrary>
<PyDesktop>.destination = library
<PyReelGroup>.save()

<PyBatch>.opened

<PyLibrary>.opened

<PySequence>.insert()

<PySequence>.overwrite()

Inserts or Overwrites a source clip in a Sequence. The following arguments can be set:

• source_clip: A PyClip or a PySequence must be specified. Mandatory.
• insert_timeoroverwrite_time: A PyTime must be specified.
• destination_track: A PyTrack or a PyAudioTrack Channel must be specified.

Examples

Overwrite the selected clip inside a sequence

clip = flame.media_panel.selected_entries[0]
sequence = <PySequence>
overwrite_time = <PyTime>
track = sequence.versions[0].tracks[0]
sequence.overwrite(clip, overwrite_time, track)

Insert an Audio Track inside a sequence

clip = flame.media_panel.selected_entries[0]
sequence = <PySequence>
insert_time = <PyTime>
track = sequence.audio_tracks[0].channels[0]
sequence.insert(clip, insert_time, track)

<PySequence>.copy_selection_to_media_panel()

<PySequence>.extract_selection_to_media_panel()

<PySequence>.lift_selection_to_media_panel()

Copy the selected segments to a destination in the Media Panel. The following arguments can be set:

• destination: A PyReel, PyLibrary, or PyFolder must be specified. Mandatory.
• duplicate_action: Specify the add or replace behaviour if an object of the same name is present in the destination. Add is applied if the argument is not set.

Example:

Copy the selected segment to the Media Panel

reel = <PyReel>
<PySequence>.copy_selection_to_media_panel(reel, replace)

Deletes a Timeline segment. This call produces the same result as the Lift shortcut: the segment is deleted and the other segments are not rippled.

Example:

Delete a segment in the Timeline

flame.delete(<PySegment>)

Focuses a Timeline tab in the user interface. The possible arguments are:

• Source
• Sequence
• Container

Example:

Focus the sequence tab in the Timeline

flame.timeline.type = "Sequence"

Returns the PyClip or PySequence associated to the clip shown in the Timeline. Useful when running scripts in the Python Console.

Example:

Rename the clip currently shown in the Timeline

clip = flame.timeline.clip
   clip.name = "new name"

flame.timeline.current_segment

flame.timeline.current_marker

flame.timeline.current_effect

Returns a PySegment, PyMarker, or a PyTimelineFX depending on what is selected in the current clip. Useful when running scripts in the Python Console.

Example:

Rename the selected segment in the Timeline

segment = flame.timeline.current_segment
segment.name = "new name"

<PySegment>.set_gap_colour()

Turns a gap into a colour source segment and modifies the colour of an existing colour source segment. Red, Green, and Blue values arguments must be set.

Example:

Turn the selected gap to a colour source in the Timeline

<PySegment>.set_gap_colour(0.0,0.5,0.0)

<PySegment>.match()

Matches a segment from the current sequence to a destination. Contrary to the Match operation performed using the user interface or the keyboard shortcut a new clip is always created. 5 arguments can be set:

• destination: A PyReel, PyLibrary or PyFolder can be specified. Mandatory.
• preserve_handle: Used to enable or disable the Preserve Handle option. Must be set to True or False.
• use_sequence_info: Used to enable or disable the Use Sequence Info option. Must be set to True or False.
• include_nested_content: Used to enable or disable the Include Nested Content option. Must be set to True or False.
• include_timeline_fx: Used to enable or disable the Include Timeline FX option. Must be set to True or False.

Example:

Match a Timeline segment to a Reel

reel = <PyReel>
<PySegment>.match(reel, include_timeline_fx = False)

<PySegment>.smart_replace()

<PySegment>.smart_replace_media()

Replaces a Timeline segment with a source clip. A PyClip must be specified.

• smart_replace()replaces the entire segment.
• smart_replace_media()replaces only the media. Timeline FX present on the PySegment are kept.

Example:

Replace the media of a Timeline segment

clip = flame.media_panel.selected_entries[0]
<PySegment>.smart_replace_media(clip)

<PySegment>.trim_head()

<PySegment>.trim_tail()

<PySegment>.slip()

Applies Trim, Slip, and Slide editorial operations. The following arguments can be set:

• offset: The amount of frame applied to the operation. Mandatory.
• ripple: The equivalent of the Ripple button in the Timeline interface. False is applied by default if the argument is not specified.
• sync: The equivalent of the Sync button in the Timeline interface. False is applied by default if the argument is not specified.
• keyframes_move_mode: The equivalent of the Shift/Pin/PropSync drop-down button in the Timeline interface. Shift is applied by default if the argument is not specified.

Example:

Trim the head of a Timeline segment

<PySegment>.trim_head(offset = 10, ripple = False, sync = True, keyframes_move_mode = "Shift" )

<PySegment>.slide_keyframes()

<PyTimelineFX>.slide_keyframes()

Applies the Slide Keyframe editorial operation. The following arguments can be set:

• offset: The amount of frame applied to the operation. Mandatory.
• sync(only valid on a PySegment): The equivalent of the Sync button in the Timeline interface. False is applied by default if the argument is not specified.

Example:

Slide keyframes of a Timeline segment

<PySegment>.slide_keyframes(offset = 10, sync = False)

<PySegment>.copy_to_media_panel()

<PyTrack>.copy_to_media_panel()

Creates a new clip into the specified destination in the Media Panel. The following arguments can be set:

• destination: A PyReel, PyLibrary or PyFolder must be specified. Mandatory.
• duplicate_action: Specify the add or replace behaviour if an object of the same name is present in the destination. Add is applied if the argument is not set.

Example:

Copy a segment to a Reel

reel = <PyReel>
<PySegment>.copy_to_media_panel(reel, replace)

<PySegment>

The following PyClip/PySequence information can be obtained through the PySegment properties.

PySegment (source, gap, bfx):

• source_width
• source_height
• source_bit_depth
• source_ratio
• source_scan_mode
• source_colour_primaries
• source_matrix_coefficients
• source_transfer_characteristics

PySegment with source media:

• source_cached
• source_has_history
• source_unlinked
• source_essence_uid
• source_uid
• original_source_uid

PySegment on an audio track:

• source_sample_rate

Example:

Get the Width and Height of the current segment

segment = <PySegment>
print(segment.source_width, segment.source_height)

<PySegment>.rgb_channels

<PySegment>.matte_channels

Return the lists of RGB and Matte channels.

<PySegment>.rgb_channel

<PySegment>.matte_channel

Return the current RGB and Matte channels.

<PySegment>.matte_mode

Return the Matte mode. The possible values are:

• Follow RGB
• No Matte
• Custom Matte

<PySegment>.set_rgb_channels()

<PySegment>.set_matte_channels()

Set the RGB and Matte channels using the channel names or indexes.

The following arguments can be set for the RGB and Matte channels:

• channel_name: Selects a channel using its name.
• channel_index: Selects a channel using its index in the list.
• scope: Sets the scope among connected segments. The modes are:
  • No Sharing
  • Follow Preferences
  • Follow Source Sharing
  • Follow Connected Segments

Also the matte_mode can be set for the Matte channel. The modes are:

• Follow RGB
• No Matte

<PyMarker>.tokenized_name

<PyMarker>.dynamic_name

<PyMarker>.tokenized_comment

<PyMarker>.dynamic_comment

<PySegment>.tokenized_name

<PySegment>.dynamic_name

<PySegment>.tokenized_shot_name

<PySegment>.dynamic_shot_name

<PySegment>.tokenized_comment

<PySegment>.dynamic_comment

The tokenized attributes can be used to set the name and comment of a PySegment or PyMarker using tokens. A string must be passed as an argument.

The dynamic attributes can be used to enabled or disable the Dynamic button in the Rename and Comment dialog boxes. True or False must be passed as an argument.

Example:

Set the name of a timeline segment using tokens

<PySegment>.tokenized_name = "<segment>_<record frame>"

Enable the Dynamic setting in the Marker's comment field

<PyMarker>.dynamic_comment = "True"