Show Internal Structures

These data structures are used internally by Beat Link Trigger to implement shows. Because some of the elements can be useful when writing your own expressions, they are made available to those expressions.

The Show

This map contains everything Beat Link Trigger needs to know about a show in order to be able to display and run it. Some of the elements are not suitable for use by expressions, but some can be quite useful. It is passed to all show expressions as the value show.

Track Signatures

The discussion below often mentions track signatures. These are strings that uniquely identify a track that can be loaded on a player. They are calculated using things like the track’s title, artist, length, and beat grid, so the same track can be recognized when found on different media. An example signature looks like "6c8139bd531a417999317a9d024d6d8ea6993507". While you will never need to compute one directly yourself, you can compare them to see if two different structures are referring to the same track, or use a signature to look up other details about a track using the show’s :tracks map, described below.

Here’s a list of some of the more useful values present in the show map, and the keywords under which each can be found.

:block-tracks?: Normally absent, but will have a true value if your show expressions have called show/block-tracks to suppress the normal display of tracks that makes up the user interface of the Show window, or set up your own custom UI as described in the Wireshark debugging section and the Xone:96 Channels on Air and QLC+ Lighting Cues integration examples.
:contents: The basic configuration information for the show, described below.
:cueing: A map from player numbers to track signatures if the specified player is currently cue-playing (rather than normally playing) the specified track.
:default-ui: The Swing JPanel holding the normal show interface displayed by Beat Link Trigger inside the Show window (the Enabled Default, Filter, and scrolling list of tracks). This can be replaced by calling show/block-tracks as described above, but is kept here in case you later call (show/block-tracks nil) to restore the normal show interface.
:file: The Java File object holding the show.
:frame: The Swing JFrame holding the show window.
:last-beat: A map from player number to the timestamp of the last beat packet that was received from that player.
:loaded: A map from player numbers to the track signature of the track, if any, currently loaded in that player.
:master: A map from player numbers to the track signature of the track, if any, currently loaded in that player, as long as that player is the current Tempo Master.
:on-air: A map from player numbers to track signatures showing which tracks are currently loaded into players that are on the air according to the mixer. (Requires a DJM mixer, and the players and mixer must be configured to offer the on-air feature.)

:phrases: A map holding runtime (not saved) information about all phrase triggers in the show, such as the user interface panels which display them. The keys are UUIDs randomly assigned to the phrase triggers when they are created. The values that are more likely to be useful to you are in the corresponding map within the show contents section.
:playing: A map from player numbers to the track signature of the track, if any, currently playing on that player.
:playing-phrases: A map of player numbers to the currently-playing phrase triggers that were chosen for the phrase playing on that player, if any. This value is itself a map, whose keys are the UUIDs of the active phrase triggers (only the ones from this show), and whose values identify how the sections of the phrase trigger map to beats in the track in order to make it fit.

:tracks: A map holding information about all tracks in the show. The keys are the track’s signatures, and the values are the track maps described in the Track section.

:vis-phrases: A vector of the UUIDs of all the phrase triggers that are currently visible inthe show window, in the order in which they appear. This can be affected by the Filter text field at the top of the window (filtering on the phrase triggers' comments), as well as the Loaded Only checkbox next to it (showing only currently-active phrase triggers).
:visible: A vector of the signatures of all the tracks that are currently visible in the show window, in the order in which they appear. This can be affected by the Filter text field at the top of the window as well as the Loaded Only checkbox next to it.

Show Contents

The :contents map contains information that can be directly saved into the show file to represent the configuration the user has chosen. Some elements that might be useful include:

:cue-library: Holds the definitions of any cues that have been added to the show’s library.
:enabled: The value chosen in the show’s Enabled Default menu, one of "Never", "On-Air", "Master", "Custom", or "Always".
:expressions: A map holding the source text of any show-level expressions that have been created, indexed by the keyword identifying the expression type.
:filter: The filter text that has been entered at the top of the show window, if any, causing only matching tracks to be visible.
:loaded-only: Indicates whether the Loaded Only checkbox at the top of the show window has been checked, causing only tracks that are currently loaded in a player to be visible in the window.
:phrase-order: A vector of UUIDs that maintains the order in which the phrase triggers should appear in the window, regardless of their current visibility.

:phrases: A map holding persistent (saved) information about all phrase triggers in the show. The keys are UUIDs randomly assigned to the phrase triggers when they are created, and the values are the phrase trigger contents maps described in the Phrase Trigger Contents section.
:window: The left and right coordinates of the show window on the screen, and its height and width, for use in restoring the window when the show is opened again.

Tracks

Each track map contains everything Beat Link Trigger needs to know about a track in a show in order to be able to display it and run cues in it. Some of the elements are not suitable for use by expressions, but some can be quite useful. It is passed to all track expressions as the value track, and all tracks in the show can be found in the show map under the keyword :tracks, further indexed by their signatures.

Here’s a list of some of the more useful values present in a track map, and the keywords under which each can be found.

:contents: The basic configuration information for the track, described below.
:cues: Holds working information about the current state of the cues in the track, for convenient and efficient display and tracking of entry/exit. The information you are more likely to use is found inside the :contents map, described below.
:cues-editor: The Swing JFrame holding the cues editor window for the track, if one has been opened.
:entered: A map from player numbers to the set of cue UUIDs of the cues, if any, that player is currently positioned inside of.
:file: The Java File object holding the show to which the track belongs.
:filter: A string containing all of the track-related text which can be matched by the Filter text field at the top of the show window, so filtering can be performed efficiently.
:grid: The Beat Link Beat Grid object that lists where each beat in the track falls.
:metadata: A map containing useful information about the track, described below.
:panel: The Swing JPanel holding user interface of the track row.
:preview: An on-demand loader for the graphical waveform preview that shows the track waveform, cues, and current playback position of any players that have loaded the track when it is visible in the show window.
:preview-canvas: The Swing JPanel in which the track’s graphical waveform preview, cues, and current playback positions are drawn.
:signature: The unique string that identifies this track, regardless of what media it was loaded from, so it can be recognized in the lists of which players have it loaded, playing, and so on, or looked up in the show’s :tracks map.
:song-structure: If there is phrase analysis information available for the track, this holds the SongStructureTag that describes it.
:tripped: Will be true when the track is currently enabled and loaded on at least one player (the same conditions under which there will be a green dot showing in the Loaded Status indicator of the track row).

Track Contents

The :contents map contains information that can be directly saved into the show file to represent the track configuration the user has chosen. Some elements that might be useful include:

:comment: The comment text, if any, entered to describe the track. This can be used to filter visible tracks.
:cues: Holds information about the Cues Editor associated with the track, as described below.
:enabled: The Enabled setting for the track, as configured with the track’s Enabled Menu.
:expressions: A map holding the source text of any track-level expressions that have been created, indexed by the keyword identifying the expression type.
:loaded-channel: The MIDI channel on which Loaded and Unloaded messages are sent, as configured with the track’s Loaded Channel Spinner.
:loaded-message: The type of message that will be sent for Loaded and Unloaded events, as configured with the track’s Loaded Message Menu.
:loaded-note: The MIDI note (or controller number) used to send Loaded and Unloaded messages, as configured with the track’s Loaded Note/Controller Spinner.
:midi-device: The MIDI device to which track messages will be sent, as configured with the track’s MIDI Output Menu.
:phrase-unlocked: A boolean flag indicating whether phrase triggers are allowed to run for this track. By default tracks do not allow this, because their custom cues will likely be more meaningful.
:playing-channel: The MIDI channel on which Playing and Stopped messages are sent, as configured with the track’s Playing Channel Spinner.
:playing-message: The type of message that will be sent for Playing and Stopped events, as configured with the track’s Playing Message Menu.
:playing-note: The MIDI note (or controller number) used to send Playing and Stopped messages, as configured with the track’s Playing Note/Controller Spinner.

Track Metadata

The :metadata map contains information obtained from the Beat Link TrackMetadata object describing the track. Note that few DJs fill in all this information in rekordbox, so values are often nil. Available keys and values are:

:album: A string naming the album the track is part of, if any.
:artist: A string naming the artist who performed the track.
:comment: A string entered by the DJ in rekordbox to make notes about the track, if any.
:date-added: A string holding a date in "YYYY-MM-DD" format reporting when the track was imported into rekordbox.
:duration: An integer holding the playback length of the track, in seconds, at normal speed (100% pitch).
:genre: A string describing the musical genre of the track.
:key: A string describing the dominant musical key of the track.
:label: A string naming the record label that issued the track.
:original-artist: A string naming the artist who originally performed the track, if any.
:rating: An integer the number of stars (0--5) the DJ assigned the track in rekordbox.
:remixer: A string naming the person who remixed the track, if any.
:tempo: An integer holding the starting tempo of the track when played at normal speed (100% pitch). Units are beats per hundred minutes, so a track that begins at 128.5 BPM would have the value 12850.
:title: A string identifying the title of the track.

Track Cues Editor Information

The track’s cues editor information map contains the information needed to manage the Cues Editor window that can be opened for a track. Its keys and values are:

:auto-scroll: Will be true when the Auto-Scroll checkbox at the top of the window is checked.

:cues: A map holding information about all cues in the track. The keys are the cues' UUIDs, and the values are the cue maps described in the Cue section.
:entered-only: Will be true when the Entered-Only checkbox at the top of the window is checked.
:hue: A floating-point number representing the angle around the color wheel that was chosen for the last cue created; used to assign each new cue a visibly distinct hue.
:filter: The filter text that has been entered at the top of the cues editor window, if any, causing only matching cues to be visible.
:visible: A vector of the UUIDs of all the cues that are currently visible in the cues editor window, in the order in which they appear. This can be affected by the Filter text field at the top of the window, as well as the Entered Only checkbox next to it.
:window: The left and right coordinates of the cues editor window on the screen, and its height and width, for use in restoring the window when it is opened again.
:zoom: An integer reporting how far out the waveform view has been zoomed. The value 1 shows the full detail of the waveform, 2 compresses two columns into one, and so on.

Cues

Each cue map contains everything Beat Link Trigger needs to know about a cue in a show track or phrase trigger in order to be able to display and run it. Some of the elements are not suitable for use by expressions, but some can be quite useful. It is passed to all cue expressions as the value cue.

Here’s a list of some of the more useful values present in a cue map, and the keywords under which each can be found.

:comment

The comment text, if any, entered to describe the cue. This shows up as a tooltip to help identify the cue on the track waveforms, and can also be used to filter visible cues.

:end

An integer that specifies the beat number within the track’s beat grid, or phrase trigger section, at which the cue ends. Must always be at least one greater than :start, and can be no greater than the largest beat number within the track or section.

:events

A map containing the cue’s event configuration. It has three keys, :entered, :started-on-beat, and started-late, and each of those hold inner maps with keys :message, :note, and :channel. Jointly these record the choices the user has made in the cue’s Entered Message Menu, Entered Note/Controller Spinner, Entered Channel Spinner, Started On-Beat Message Menu, Started On-Beat Note/Controller Spinner, Started On-Beat Channel Spinner, Started Late Message Menu, Started Late Note/Controller Spinner, and Started Late Channel Spinner respectively.

To make this concrete, here is an example :events map:

{:entered         {:message "Note", :note 1, :channel 1}
 :started-on-beat {:message "Note", :note 2, :channel 1}
 :started-late    {:message "None", :note 3, :channel 1}}

:expressions

A map holding the source text of any cue-level expressions that have been created, indexed by the keyword identifying the expression type.

:hue

An floating point value that specifies the angle (in degrees) around the color wheel that is used when drawing this cue.

:section

Present only for cues which are in a phrase trigger, identifies the section of the phrase trigger in which the cue exists (will be one of :start, :loop, :end, or :fill).

:start

An integer that specifies the beat number within the track beat grid, or phrase trigger section, at which the cue begins. Must be positive (non-zero: in the DJ Link protocol, beat numbers start with 1) and less than :end.

:uuid: The unique identifier (a Java UUID object) that identifies this cue within the show, so it can be recognized in the lists of which players are positioned inside it, playing it, and so on, or looked up in a track’s or phrase trigger’s :cues map.

Phrase Triggers

In addition to tracks, starting with version 7, shows can also contain phrase triggers, which can run cues whenever a track plays a particular kind of phrase (as analyzed by rekordbox).

The phrase information is split into two parts, both of which are indexed by the phrase UUID. This part, found under the key :phrases in the show map is computed at runtime for rapid and efficient display and processing but is not stored in the show file. The saved part is found in the show :content map, also under the key :phrases there.

:cues: Holds working information about the current state of the cues in the phrase trigger, for convenient and efficient display and tracking of entry/exit. The information you are more likely to use is found inside the :contents map, described below.
:cues-editor: The Swing JFrame holding the cues editor window for the phrase trigger, if one has been opened.
:entered: A map from player numbers to the set of cue UUIDs of the cues, if any, that player is currently positioned inside of.
:file: The Java File object holding the show to which the phrase trigger belongs.
:panel: The Swing JPanel holding user interface of the phrase trigger row.

:uuid: The unique identifier (a Java UUID object) that identifies this phrase trigger within the show, so it can be recognized in the list of which are currently visible, and referenced in other ways.
:tripped: Will be true when the phrase trigger is currently enabled and was chosen in response to a phrase playing on at least one player (the same conditions under which there will be a green dot showing in the Playing Status indicator of the phrase trigger row).

Phrase Trigger Contents

Each phrase trigger contents map contains everything Beat Link Trigger needs to know about a phrase trigger in a show in order to be able to display it and run cues in it. Some of the elements are not suitable for use by expressions, but some can be quite useful. It is passed to all phrase trigger expressions as the value trigger. Note that phrase triggers also have a runtime information map, which is found directly in the show map, and not saved as part of the show file.

The phrase trigger contents map, found within the show :contents map, contains information that can be directly saved into the show file to represent the phrase trigger configuration the user has chosen. Some elements that might be useful include:

:channel: The MIDI channel on which Playing and Stopped messages are sent, as configured with the phrase trigger’s Channel Spinner.
:comment: The comment text, if any, entered to describe the phrase trigger. This can be used to filter visible phrase triggers.
:cues: Holds information about the Cues Editor associated with the phrase trigger, as described below.
:enabled: Controls how the phrase trigger is matched against playing track phrases. Has one of two values: "See Below" means that all of the Enabling and Weighting user elements (and their associated values in this section) are used, and "Custom" means that your own Enabled Filter expression will be called instead, and its results will control what happens.
:enabled-phrase-types: The set of phrase types which will allow this phrase trigger to activate when they play. Controlled by the Phrase Types Picker, the set will contain any combination of the following elements: :low-intro, :low-verse-1, :low-verse-2, :low-bridge, :low-chorus, :low-outro, :mid-intro, :mid-verse-1, :mid-verse-2, :mid-verse-3, :mid-verse-4, :mid-verse-5, :mid-verse-6, :mid-bridge, :mid-chorus, :mid-outro, :high-intro-1, :high-intro-2, :high-up-1, :high-up-2, :high-up-3, :high-down, :high-chorus-1, :high-chorus-2, :high-outro.
:enabled-track-banks: The set of track banks which will allow this phrase trigger to activate when associated with the playing track. Controlled by the Track Banks Picker, the set will contain any combination of the following elements: :cool, :natural, :hot, :subtle, :warm, :vivid, :club-1, :club-2.
:end-bars: The number of bars long the End section of the phrase trigger is. This can be zero, meaning that the Loop section is immediately followed by the Fill section.
:expressions: A map holding the source text of any phrase trigger level expressions that have been created, indexed by the keyword identifying the expression type.
:fill-bars: The number of bars long the Fill section at the end of the phrase trigger is. This section will be repeated as many times as needed to align the size of the phrase trigger with the size of the fill-in section of the playing phrase that it matched.
:loop-bars: The number of bars long the Loop section of the phrase trigger is. This section will be repeated as many times as needed to align the size of the phrase trigger with the size of the playing phrase that it matched.
:max-bars?: A boolean value that records whether the checkbox in front of the phrase trigger’s Max Bars: Checkbox is checked, and therefore whether the value in :max-bars should be honored.
:max-bars: The maximum number of bars long a playing phrase can be in order to activate this phrase trigger, configured using the Max bars Spinner. Only used when :max-bars? is true.
:max-bpm?: A boolean value that records whether the checkbox in front of the phrase trigger’s Max BPM: Checkbox is checked, and therefore whether the value in :max-bpm should be honored.
:max-bpm: The maximum tempo, in beats per minute, for which this phrase trigger will activate, configured using the Max BPM Spinner. Only used when :max-bpm? is true.
:message: The type of message that will be sent for Playing and Stopped events, as configured with the phrase trigger’s Message Menu.
:midi-device: The MIDI device to which phrase trigger messages will be sent, as configured with the phrase trigger’s MIDI Output Menu.
:min-bars?: A boolean value that records whether the checkbox in front of the phrase trigger’s Min Bars: Checkbox is checked, and therefore whether the value in :min-bars should be honored.
:min-bars: The minimum number of bars long a playing phrase can be in order to activate this phrase trigger, configured using the Min Bars Spinner. Only used when :min-bars? is true.
:min-bpm?: A boolean value that records whether the checkbox in front of the phrase trigger’s Min BPM: Checkbox is checked, and therefore whether the value in :min-bpm should be honored.
:min-bpm: The minimum tempo, in beats per minute, for which this phrase trigger will activate, configured using the Min BPM Spinner. Only used when :min-bpm? is true.
:note: The MIDI note (or controller number) used to send Playing and Stopped messages, as configured with the phrase trigger’s Note/Controller Spinner.
:players: Controls which players will be considered when looking for phrases that match this phrase trigger, as confugred with the phrase trigger’s Players Menu. Choices are "Master", "On-Air", or "Any".
:start-bars: The number of bars long the Start section of the phrase trigger is. This can be zero, meaning that the first section is the Loop section.
:solo: Controls the Exclusivity of the phrase trigger. The default value is "Show", which means that only one such trigger will be chosen for the entire show (but other "Show" Solo triggers might be running for the same phrase in other shows). Other choices include "Global", which (as its name suggests) will only allow one such trigger to be chosen from any open show (although triggers in other exculsivity modes will still be allowed to run), and "Blend", which means this trigger will activate whenever its criteria are met, regardless of how many other triggers are activating in any show for the current phrase.
:uuid: The unique identifier (a Java UUID object) that identifies this phrase trigger within the show, so it can be recognized in the list of which are currently visible, and referenced in other ways.
:weight: Adjusts how likely this phrase trigger will be chosen if if it is configured as Solo and other Solo matches exist for a phrase that has started to play. This is configured using the Weight Spinner.

Phrase Trigger Cues Editor Information

The phrase trigger’s cues editor information map contains the information needed to manage the Cues Editor window that can be opened for a phrase trigger. Its keys and values are:

:auto-scroll: Will be true when the Auto-Scroll checkbox at the top of the window is checked.

:cues: A map holding information about all cues in the phrase trigger. The keys are the cues' UUIDs, and the values are the cue maps described in the Cue section.
:entered-only: Will be true when the Entered-Only checkbox at the top of the window is checked.
:hue: A floating-point number representing the angle around the color wheel that was chosen for the last cue created; used to assign each new cue a visibly distinct hue.
:filter: The filter text that has been entered at the top of the cues editor window, if any, causing only matching cues to be visible.
:visible: A vector of the UUIDs of all the cues that are currently visible in the cues editor window, in the order in which they appear. This can be affected by the Filter text field at the top of the window, as well as the Entered Only checkbox next to it.
:window: The left and right coordinates of the cues editor window on the screen, and its height and width, for use in restoring the window when it is opened again.
:zoom: An integer reporting how far out the cue canvas view has been zoomed. The value 1 shows the most detail available, 2 compresses two columns into one, and so on.