UE4 Sequencer Python Cookbook

[RudyTriplett]

Article written by Euan C.

UE4 Sequencer Python Cookbook

Fundamentals

Sequencer is a cinematic editing tool that uses various specialized tracks which are used to define the makeup of scenes.

This document will be focusing on common practices/examples with general Sequencer Scripting.

Sequencer uses the following terminology:

• World: An object that represents a map in which actors and components can exist and be rendered (commonly referred to as Level)
• LevelSequence: An asset that is a container for cinematics scenes. Level Sequences hold data and tracks that can be bound to manipulate different objects to be animated (commonly referred to as Sequence)
• SequencerBindingProxy: A struct defining the actor or component that is bound by a Level Sequence (commonly referred to as Binding)
• Possessable: A type of binding describing an actor or component that exists in a Level, in which the Level Sequence can own any animatable properties
• Spawnable: A type of binding describing an actor or component that exists only while the Sequence is playing
• MovieSceneTrack: An object that lives under a Binding, which contains all sections of edits for a specific typed property (ex: MovieScene3DTransformTrack → Actor/Component Transform)
• MovieSceneSection: An object that lives under a Track, which contains all channels, length, and parameters for a specific typed property (ex: MovieScene3DTransformSection → Pre/Post Roll, When Finished State, Active/Muted, Additive )
• MovieSceneScriptingChannel: An object that lives under a Section which contains all keys that would animate a specific typed property or sub-property (ex: MovieSceneScriptingFloatChannel → Location.X)
• MovieSceneScriptingKey: An object that represents a keyframe in the specifically typed channel (ex: MovieSceneScriptingFloatKey)
• FrameNumber: A struct that represents a frame
• FrameRate: A struct that represents a fraction of 2 integers: # of frames/seconds (ex: 30 fps = 30/1)

Accessing the Level Sequence

The first step when scripting against any Sequences is to gain access to the main object you’ll interact with: The LevelSequence. There are several ways to do that depending on your situation.

Opening an Existing Level Sequence

To access an existing rig you can simply load the asset (an example asset created at the root Content folder).

import unreal

Get a level sequence asset…

level_sequence = unreal.load_asset("/Game/Test_LS")

…Then open it in Sequencer

unreal.LevelSequenceEditorBlueprintLibrary.open_level_sequence(level_sequence)

Getting the currently opened Level Sequence

Luckily there’s a function to access the currently opened sequence.

import unreal

Grab the current level sequence

level_sequence = unreal.LevelSequenceEditorBlueprintLibrary.get_current_level_sequence()

Creating a Level Sequence

To create a level sequence asset from scratch you can get the existing editor AssetTools and the LevelSeqeunceFactoryNew factory.

import unreal

Get asset tools

asset_tools = unreal.AssetToolsHelpers.get_asset_tools()

Creates a Level Sequence - /Game/Test_LS

level_sequence = unreal.AssetTools.create_asset(asset_tools, asset_name = "Test_LS", package_path = "/Game/", asset_class = unreal.LevelSequence, factory = unreal.LevelSequenceFactoryNew())

Editing the Level Sequence

Once you have access to a Level Sequence in Python, you can perform changes to it. There are a lot of ways to change the Sequence, we’ll focus on the most common ones in the examples below including:

• Changing the frame rate
• Setting the playback range
• Adding a Possessable/Spawnable Actor
• Adding Tracks and Sections
• Adding an Animation Sequence

Change the frame rate

By default, Level Sequences are set to 30 fps. Depending on the usage, you may want to change it. To do so, change the display rate.

Create a frame rate object, change the numerator to the desired fps number

frame_rate = unreal.FrameRate(numerator = 60, denominator = 1)

Set the display rate

level_sequence.set_display_rate(frame_rate)

Extending the range of Level Sequence

By default, A Sequence’s playback range is set to start at frame 0 and end at frame 150. This can be easily edited.

Set the playback range to 20-200

level_sequence.set_playback_start(20)
level_sequence.set_playback_end(200)

Adding a Possessable Actor

To add an actor from your current Level for Sequencer to possess, grab the current Sequence, and use add_possesable.

Get the selected actor

actor = unreal.EditorLevelLibrary.get_selected_level_actors()[0]

Add actor to level as a spawnable

actor_binding = level_sequence.add_possessable(actor)

Refresh to visually see the new binding added

unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()

Adding a Spawnable Actor

Instead of possessing a level Actor, you may want to have Sequencer spawn one when a Sequence plays. In that case, you would want to use either add_spawnable_from_instance, which will take in an Object or you can use add_spawnable_from_class and give it a Class.

Get the selected actor

actor = unreal.EditorLevelLibrary.get_selected_level_actors()[0]

Add actor to level as a spawnable

actor_binding = level_sequence.add_spawnable_from_instance(actor)

Refresh to visually see the new binding added

unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()

Adding Tracks and Sections

Now that we have our bindings in bear, let’s add some tracks and sections. Each track and section has a different type. Sections are used to house different parameters and the frame range that would be active.

For Transforms, it will be unreal.MovieScene3DTransformTrack and unreal.MovieScene3DTransformSection.

For Skeletal animations, it will be unreal.MovieSceneSkeletalAnimationTrack and unreal.MovieSceneSkeletalAnimationSection.

Use the binding to add tracks into sequencer - specified by track type

transform_track = actor_binding.add_track(unreal.MovieScene3DTransformTrack)

anim_track = actor_binding.add_track(unreal.MovieSceneSkeletalAnimationTrack)

Add section to track to be able to manipulate range, parameters, or properties

transform_section = transform_track.add_section() 
anim_section = anim_track.add_section()

Get level sequence start and end frame

start_frame = level_sequence.get_playback_start()
end_frame = level_sequence.get_playback_end()

Set section range to level sequence start and end frame

transform_section.set_range(start_frame, end_frame)
anim_section.set_range(start_frame, end_frame)

Refresh to visually see the new tracks and sections added

unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()

Adding Animation

Once an animation track and section is created, we can simply add an animation by setting the section’s parameters

Get the animation sequence asset

anim_seq = unreal.load_asset("/Game/Mannequin/Animations/ThirdPersonWalk")

Get the section, get the parameters, set animation to anim sequence asset

anim_section.params.animation = anim_seq

Additional Sequencer Scripting Resources

For more resources on Sequencer Scripting in general, look at the Sequencer Scripting examples located in your local engine path:

*\Engine\Plugins\MovieScene\SequencerScripting\Content\Python

[scottunreal]

Hopefully, all of this will make it somewhere in the documentation. More examples and coverage of making/using unreal tools in your documentation and/or learning center would be very useful.

[geordiem]

with Python, how does one add a Geometry Cache (alembic) section pointing to the proper alembic cache?

[geordiem]

Found some answers.
Here is how to add a geom cache to a sequence:

cache_asset = unreal.load_asset("/Game/path/to/cache_asset")
cache_actor = unreal.EditorLevelLibrary.spawn_actor_from_object(cache_asset,unreal.Vector(x=0.0, y=0.0, z=0.0))

actor_binding = level_sequence.add_spawnable_from_instance(cache_actor)
# adding a geom cache
cache_track = actor_binding.add_track(unreal.MovieSceneGeometryCacheTrack)
anim_section = cache_track.add_section()
anim_section.set_range(start_frame,end_frame) # start and end frames

# add the cache asset 
params = anim_section.get_editor_property("params")
params.set_editor_property("geometry_cache_asset",cache_asset)
unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence()

And this is of use to others who may be looking for it.
Adding sub sequences to another sequence:

 # this adds an empty subscenes track to add something too
master_track = top_sequence.add_master_track(unreal.MovieSceneSubTrack)
subseq = unreal.load_asset("/Game/path/to/subsequence" )
subsequence_section = master_track.add_section()
subsequence_section.set_sequence(subseq)
# shift to proper location in timeline
subsequence_section.set_range(start_frame,end_frame)

[SkyOHorizon]

Excuse me, How to create a morph target sequence using python? I have imported a fbx with morph targets of face, and I could using ui to set a level sequence, how to implement it with python? Thank you

[SkyOHorizon]

Also，I have got another problem, when I first open the project(without opening the sequence), and using section.get_channels() to get the Face’s channels, it will return None, but if I once open the level sequence, it could work, I have tested the metahuman’s control rig sequence, the issue didn’t occur. So does anything else I need to set with morph target or the sequence? Maybe it’s a bug(I have meet it both in 4.26.2 and 5.0.3)

[nksoo7371]

Did you find a solution?

[q92ie83ir8]

I also found that I must open the sequence manually (after creating it) in the editor before any further manipulation was possible through python -
OR
I have to call unreal.LevelSequenceEditorBlueprintLibrary.refresh_current_level_sequence() which also allows further python commands