Track

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

Categories: [‘Sockpuppet’, ‘Track and Sequencing’]

Base class: SuperTrack

Properties

cues : TimeSequence[Cue]

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

defaultTransitionInfo : TrackTransitionInfo

Default transition settings for the track.

tc_adjust : float

This value will be added to timecode chase time, in seconds

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) -> 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: int, 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, 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

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: int, startOrEnd: int) -> 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.

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: int, 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: int)

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.

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)

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 = 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: int) -> 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]

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.

transitionInfoAtBeat(self, beat: float) -> 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

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).