---
title: "Track"
description: "API documentation for Track"
url: https://developer.disguise.one/python-api/docs/track/
---

# Track

A SuperTrack derived class which expands functionality to include control over Cues, containing Sections, Tags and Notes.

See also: [Track & Sequencing Guide](/plugins/guides/track-and-sequencing)

Base class (inherits properties and methods): _[SuperTrack](/python-api/docs/supertrack#supertrack)_

## Properties

#### **cues** : _[TimeSequence](/python-api/docs/timesequence#timesequence)\[[Cue](/python-api/docs/cue#cue)\]_

All cues (containing Sections, Tags, Notes, and transition settings) in the track

#### **defaultTransitionInfo** : _[TrackTransitionInfo](/python-api/docs/tracktransitioninfo#tracktransitioninfo)_

Default transition settings for the track.

#### **tc\_adjust** : _float_

Positive values make the track play earlier relative to the chased input (use this if the track is running late); negative values make it play later

_UserName: TC Adjust_

#### **trigger\_note** : _str_

Numerical identifier for the track, used to trigger the track from MIDI or ArtNet.

## Methods

#### **adjustCurrentTimecodeTag**(self, t: _float_, dFrames: _int_)

Add frames to the closest timecode tag found preceding the given time.

**Parameters**:

-   t: The time at which to locate the timecode tag.
-   dFrames: The number of frames to add to the timecode tag.

#### **beatOfCue**(self, cue: _[Cue](/python-api/docs/cue#cue)_) -> _float_

Returns the beat of a given cue in the Track.

**Parameters**:

-   cue: The cue to get the beat for.

**Returns** The beat of the cue, or -1 if not found.

#### **beatToGlobalTime**(self, tBeat: _float_, clockType: _[SMPTEClockType](/python-api/docs/smpteclocktype#smpteclocktype)_, tcTagsLimitedToSection: _bool_) -> _float_

Convert timeline beat to SMPTE timecode time.

**Parameters**:

-   tBeat: The beat to convert.
-   clockType: The SMPTE clock type used in the track.
-   tcTagsLimitedToSection: Whether the input beat and nearest preceding timecode tag have to be part of the same section or not.

**Returns** The global time value corresponding to the given beat.

#### **beatToSection**(self, beat: _float_) -> _int_

Returns the index of the section containing the given beat.

**Parameters**:

-   beat: The beat to find the section for.

**Returns** The section index (0-based).

#### **beatToSectionCue**(self, iBeat: _float_) -> _int_

Returns the index of the closest section cue preceding the given beat.

This represents the index into the list of Cues, which includes not only Sections but also Tags and Notes. Each entry is positioned according to its beat on the timeline, and a single entry can contain multiple of these elements.

**Parameters**:

-   iBeat: The beat to search for a section cue.

**Returns** The index of the section cue.

#### **contains**(self, arg0: _[SuperLayer](/python-api/docs/superlayer#superlayer)_, arg1: _bool_ = True) -> _bool_

Whether the track contains the layer sl

**Parameters**:

-   sl: The superlayer to search for
-   searchLeafOnly: If true, only leaf layers will be searched, otherwise all layers (including GroupLayer instances) will be searched.

return: Whether the superlayer is found in the track

#### **cueAtBeat**(self, iBeat: _float_) -> _[Cue](/python-api/docs/cue#cue)_

Returns the cue at a given beat.

**Parameters**:

-   iBeat: The beat to search for.

**Returns** The cue at the specified beat, or None if no cue was found.

#### **cueBeats**(self) -> _List\[float\]_

Returns the times of all cues on the track.

**Returns** A list of beat values indicating the position of each cue.

#### **distanceToSection**(self, iBeat: _float_, prevOrNext: _[Direction](/python-api/docs/direction#direction)_, startOrEnd: _[LayerEdit](/python-api/docs/layeredit#layeredit)_) -> _float_

Computes the distance to or from the section containing the given time.

**Parameters**:

-   iBeat: Beat used to locate section.
-   prevOrNext: Direction in which to look for the section (Prev or Next).
-   startOrEnd: Edit type (EditStart or EditEnd) when used to change layer extents or position.  
    If you pass in EditStart as the value, and the newly computed beat for the start of the layer equals the end of the track,  
    it will use the start time of the last section on the track as the new start beat for the layer to prevent a zero-length layer.

**Returns** The distance in beats.

#### **findBeatOfLastNote**(self, tBeats: _float_) -> _float_

Finds the beat of the note at the specified time, or the nearest note occurring before it.

**Parameters**:

-   tBeats The time in beats from which to begin the search.

**Returns** The beat of the located note, or -1 if no note is found.

#### **findBeatOfLastSection**(self, tBeats: _float_) -> _float_

Finds the beat of the last section before a given time in beats.

**Parameters**:

-   tBeats: The time in beats to search for the last section.

**Returns** The beat of the last section before the given time, or 0 if no sections exist before the given time.

#### **findBeatOfLastTag**(self, tBeats: _float_) -> _float_

Finds the beat of the tag at the specified time, or the nearest tag occurring before it.

**Parameters**:

-   tBeats The time in beats from which to begin the search.

**Returns** The beat of the located tag, or -1 if no tag is found.

#### **findBeatOfNextNote**(self, tBeats: _float_) -> _float_

Find the beat position of the next note after a given time in beats.

**Parameters**:

-   tBeats: The time in beats from which to start searching for the next note.

**Returns** The beat position of the next note, or DBL\_MAX (1.7976931348623158e+308) if no more notes are found.

#### **findBeatOfNextSection**(self, tBeats: _float_) -> _float_

Finds the beat of the next section after a given position.

**Parameters**:

-   tBeats: The position in beats to start searching from.

**Returns** The beat of the next section, or the length of the track if no more sections are found.

#### **findBeatOfNextTag**(self, tBeats: _float_) -> _float_

Find the beat position of the next tag after a given time in beats.

**Parameters**:

-   tBeats: The time in beats from which to search for the next tag.

**Returns** The beat position of the next tag, or DBL\_MAX (1.7976931348623158e+308) if no more tags are found.

#### **findTagBeat**(self, tag: _[Tag](/python-api/docs/tag#tag)_) -> _float_

Find the beat for a tag of given type with given text.

**Parameters**:

-   tag: A Tag object describing the tag to search for.

**Returns** The beat of the tag, or -1 if not found.

#### **formatNoteForBeat**(self, beatOfNote: _float_, tCurrentBeats: _float_) -> _str_

Format a note for a given beat.

If the note is ahead of the current section, the description is suffixed with ”.”, where indicates how many sections ahead it is.

**Parameters**:

-   iBeatNote: The beat to format the note for.
-   tCurrentBeats: The current position of the playhead in beats.

**Returns** A string representation of the note, optionally including the section offset.

#### **globalTimeToBeat**(self, tGlobal: _float_, clockType: _[SMPTEClockType](/python-api/docs/smpteclocktype#smpteclocktype)_, tDiff: _float_, tcTagsLimitedToSection: _bool_) -> _float_

Convert SMPTE timecode time to timeline beats.

**Parameters**:

-   tGlobal: Global time value to convert.
-   clockType: SMPTE clock type of the track.
-   tDiff: Difference between the input global time and the nearest preceding timecode tag.
-   tcTagsLimitedToSection: Whether the input global time and nearest preceding timecode tag have to be part of the same section or not.

**Returns** Beat value corresponding to the given global time, or -1 if not found.

#### **layerByName**(self, name) -> _Any_

Access layers by a (hopefully) unique name

#### **mergeSectionAtBeat**(self, iBeat: _float_)

Merge the section at a given beat with the previous section.

This method finds the closest section cue before the one at the specified beat and removes the section indicator from it. If the resulting cue is empty, it is removed entirely.

**Parameters**:

-   iBeat: The beat to merge the section at.

#### **nSections**(self) -> _int_

Get the number of sections in the track.

**Returns** The number of sections in the track.

#### **noteAtBeat**(self, iBeat: _float_) -> _str_

Returns the note at a given beat.

**Parameters**:

-   iBeat: The beat to search for.

**Returns** The note at the specified beat, or an empty string if no note is found.

#### **readCueTable**(self)

Reads a cue table and updates the track’s cues.

The table should consist of two header rows (table path and column header list), followed by data rows in the format of \[Beat, Tag, Note, Track Time, Timecode Time, Section Break\]. These rows are converted into cues and inserted on the current track, replacing existing cues at matching beats.  
The cue table is read from disk using file pattern: objects/table/\_cue\_table.txt

#### **removeNoteAtBeat**(self, iBeat: _float_)

Removes a note at the specified beat.

**Parameters**:

-   iBeat: The beat where the note should be removed.

#### **removeNotes**(self, iBeat: _float_, nBeats: _float_)

Removes notes on the interval \[iBeat, iBeat + nBeats) and removes corresponding cues from the track if empty.

**Parameters**:

-   iBeat: The starting beat of the interval.
-   nBeats: The number of beats in the interval.

#### **removeTagAtBeat**(self, iBeat: _float_, tagType: _[TagType](/python-api/docs/tagtype#tagtype)_)

Removes a tag from the track at the specified beat.

**Parameters**:

-   iBeat: The beat where the tag should be removed.
-   tagType: The type of tag to remove.

#### **removeTags**(self, iBeat: _float_, nBeats: _float_)

Removes all tags on the interval \[iBeat, iBeat + nBeats) and removes corresponding cues from the track if empty.

**Parameters**:

-   iBeat: The starting beat of the interval.
-   nBeats: The number of beats in the interval.

#### **sectionAtBeat**(self, iBeat: _float_) -> _bool_

Checks whether a section is located at the given beat.

**Parameters**:

-   iBeat: The beat to check for sections.

**Returns** True if a section is located at the given beat, false otherwise.

#### **sectionCueToBeat**(self, iSection: _int_) -> _float_

Convert cue index to its beat if the cue is a section.

**Parameters**:

-   iSection: The index of the cue to be converted.

**Returns** The beat value of the section, or -1 if the given index is not a section.

#### **sectionInfo**(self, iSection: _int_) -> _[SectionInfo](/python-api/docs/sectioninfo#sectioninfo)_

Get info on a given section of the track.

**Parameters**:

-   iSection: The index of the section (0-based).

**Returns** A SectionInfo object pertaining to the specified section,  
or the end of the track if no such section exists.

#### **sectionLengthBeats**(self, iSection: _int_) -> _float_

Returns the duration of a section defined by its cue index.

**Parameters**:

-   iSection: The cue index of the section.

**Returns** The duration of the section in beats.

#### **sectionToBeat**(self, iSection: _int_) -> _float_

Returns the beat of the section matching the given index.

**Parameters**:

-   iSection: The index of the section to get the beat for (0-based).

**Returns** The start beat of the section.

#### **setNoteAtBeat**(self, iBeat: _float_, note: _str_)

Sets the note at a specific beat in the track.

Overrides the current note on the cue at the given beat, if one is present, otherwise creates a new cue with the provided note.

**Parameters**:

-   iBeat: The beat to set the note for.
-   note: The note to set.

#### **setTagAtBeat**(self, iBeat: _float_, tag: _[Tag](/python-api/docs/tag#tag)_)

Sets a tag at the specified beat.

Overrides the current tag of the same type on the cue at the given beat, if one is present, otherwise creates a new cue with the provided tag.

**Parameters**:

-   iBeat: The beat where the tag should be set.
-   tag: The tag to set.

#### **splitSectionAtBeat**(self, iBeat: _float_, sectionTransitionInfo: _[TrackTransitionInfo](/python-api/docs/tracktransitioninfo#tracktransitioninfo)_ = TrackTransitionInfo())

Split a Section (i.e. create a new Section) at the given beat.

If there is already a Cue at the specified beat, it will be marked as a Section. Otherwise, a new Cue will be created and marked as a Section with no section transition.

**Parameters**:

-   iBeat: The beat to split the section at.
-   sectionTransitionInfo: Optional transition settings for the new section. If not provided, the new section will have no section-specific transition, defaulting to the track or global transition.

#### **tLastBeatInSection**(self, t: _float_) -> _float_

Returns the last beat in the section containing the given beat.

**Parameters**:

-   t: Beat used to locate section.

**Returns** The last beat in the section.

#### **tagAtBeat**(self, iBeat: _float_, tagType: _[TagType](/python-api/docs/tagtype#tagtype)_) -> _[Tag](/python-api/docs/tag#tag)_

Returns the tag at a given beat.

**Parameters**:

-   iBeat: The beat to search for.
-   tagType: The type of tag to return.

**Returns** The tag at the given beat, or None if none is found.

#### **tagsAtBeat**(self, iBeat: _float_) -> _List\[[Tag](/python-api/docs/tag#tag)\]_

Returns a list of tags at the given beat.

**Parameters**:

-   iBeat: The beat to get the tags for.

**Returns** A list of tags. List is empty if there are no tags at the given beat.

#### **timeOfNoteContainingBeat**(self, iBeat: _float_) -> _float_

Returns the time of the note at the given beat.

**Parameters**:

-   iBeat: The beat to check.

**Returns** The time in seconds corresponding to the given beat.

#### **transitionInfoAtBeat**(self, beat: _float_) -> _[TrackTransitionInfo](/python-api/docs/tracktransitioninfo#tracktransitioninfo)_

Returns the transition information of the last section before the given beat.

This method takes into account section, track and project default transition information.

**Parameters**:

-   beat: The beat to get the transition information for.

**Returns** The effective transition information.

#### **transitionInfoAtSection**(self, iSection: _int_) -> _[TrackTransitionInfo](/python-api/docs/tracktransitioninfo#tracktransitioninfo)_

Get the transition information for a specific section.

This function returns the effective transition information for a section cue, taking into account default track or global transitions. If no transition is found, an empty `TrackTransitionInfo` object is returned.

**Parameters**:

-   iSection: The index of the section cue for which to get the transition information.

**Returns** The effective transition information for the given section cue.

#### **writeCueTable**(self)

Write a cue table for the track.

Creates a file in the ‘objects/table’ folder of the project, containing information of all the cues in the track. For each cue, it writes out its beat, tag, note, track time, timecode time and whether or not the cue corresponds to a section break. Cues consisting of multiple tags are split over separate rows (one per tag).