Track and Sequencing Python Samples

This guide demonstrates how to use the Disguise Python API to work with the Track system, including tracks, layers, field sequences, and key sequences. These concepts are central to timeline-based animation, automation, and show control in Disguise.

Track Operations

Cues

Direct access to cues is possible via track.cues, which returns a list of all Cue objects on the track. However, it is often easier to work with the Track methods for sections, tags and notes directly.

Cues are unnamed Resources.

Tags

• Tags are markers placed at specific beats on the track. They are useful for navigation, triggering externally, or marking important events.
• There are special tag types:
  • CUE is used for specific cue numbering, and follows the schema X, X.Y or X.Y.Z (eg CUE 1.2.3)
  • TC is used to represent a Timecode reference, in the format HH:MM
    .ff - refer to the track frame rate to ensure you set this appropriately (eg TC 12:34:56.00)
  • MIDI indicates external trigger from a MIDI “note on” event. Supports a dotted notation (<channel>.<note>) to specify a specific MIDI note on a specific channel (eg MIDI 1.60 for channel 1, note 60).
• Tags can be added, removed, or queried. Each tag typically has a beat position and a string label.
• The list of all tags is accessible via the track.tags property.

Notes

• Notes are text annotations that can be attached to specific beats or sections. They are useful for adding comments, reminders, or cues for operators and programmers.
• Notes can be set or retrieved using the appropriate methods on the track or section objects.

Layer Operations

A Layer represents a composable element on the Track. Layers are unnamed Resources.

Layer time extents

The most important Layer properties are their time extents: tStart, tEnd and tLength (which is tEnd - tStart). All of these values are in track beats.

The time extents determine when a Layer is active on the Track. When creating or modifying layers, it’s important to set the time extents carefully to avoid unexpected behavior.

Best practices for time extents:

• Match related content: When creating layers that work together (e.g., a blur effect for specific video layers), match their time extents to the content they affect
• Avoid arbitrary full-track layers: Creating a layer that spans the entire track makes it difficult to understand what’s active at any given time
• No unnecessary gaps: Don’t create gaps between related layers unless there’s a specific reason, as this can cause unintended pauses
• Context matters: Consider what the layer is doing and how it relates to other timeline elements when setting its duration

Example - Creating a layer that matches existing layers:

# Find the time range of target layers
target_layers = [l for l in track.layers if l.name.startswith("Video")]
layer_start_beats = min(l.tStart for l in target_layers)
layer_end_beats = max(l.tEnd for l in target_layers)
layer_length_beats = layer_end_beats - layer_start_beats

# Create a new layer with matching time extents
blur_layer = track.addNewLayer(BlurModule, layer_start_beats, layer_length_beats, "Blur Effect")

Example - Creating a timed layer:

# Create a 30-second layer starting at the current playhead
current_time = trackTime()
duration_seconds = 30
duration_beats = track.timeToBeat(current_time + duration_seconds) - track.timeToBeat(current_time)

video_layer = track.addNewLayer(VideoModule, track.timeToBeat(current_time), duration_beats, "Video")

Layer composition

Layers which occupy the same time range (tStart/tEnd) and use mappings which target the same screens compose on top of each other according to the blend modes the layers are set to. To control the blending order of the Layers, the order they appear in their parent (track or container).

The earlier in their parent, the higher in the composition stack the Layer is used, and a layer’s blend mode affects layers “below” it.

If the user references multiple layers, there are 2 scenarios to consider:

1. The content has some known relationship (e.g. they target different mappings and are used together, or should be blended together): the layers should share some overlap in tStart/tEnd.
2. The content is independent: the layers should be arranged separately on the track.

Note the above means that there is NO relationship between track position and position in the parent’s layer list! The first layer in the track can be the last item in the list.

Modules

Modules define the different types of layers and their behaviors within a track. Each module defines the specific properties and methods accessible to the Layer.

Do not access the Module object directly. It may be absent or change. Use ModuleConfig and FieldSequence on the Layer instead.

ModuleConfig

The ModuleConfig is accessible via layer.moduleConfig. For certain Module types, this can include specific settings or parameters that control the behavior of the layer. For example, OpenModule has a corresponding OpenModuleConfig which allows for customization of which system properties the Layer can access. The majority of Module types do not use ModuleConfig. It is used for modules that are very generic in nature and require additional configuration to provide dynamic FieldSequence properties on the Layer instance. ModuleConfigs are unnamed Resources.

FieldSequence & KeySequence

Layers are unnamed Resources. They contain field sequences, which represent the sequencable properties on the layer. This is the only way to apply values to Layers.

A KeySequence stores the actual keyframes for a property. All KeySequences have at least 1 keyframe.

Important: Keyframes have a time (t) value that represents a specific beat on the Track, not within the Layer. When setting keyframe times, always use Track time. For example: field_sequence.sequence.setResource(layer.tStart, <resource>).

In the examples below, fseq is a FieldSequence and keyseq is a KeySequence:

Working with KeySequence in more detail:

An example of setting a float sequence to a constant value:

brightness_fseq = my_layer.findSequence("brightness")
assert(brightness_fseq is not None)
# Disable sequencing - value not animating
brightness_fseq.disableSequencing = True
# Set the brightness value on the KeySequence
brightness_fseq.sequence.setFloat(my_layer.tStart, 25.0)

Searching for Media

You can find and reference media assets (like images, videos, or audio files) within your projects using the resource manager.

Finding Media by Name

The examples below show common patterns for finding media. Replace MediaType with the appropriate type (e.g., VideoClip, ImageResource, AudioFile).