New 'Launch Exclusively' Option for Clip Sections

[todd-gochenour]

A new option LE (Launch Exclusively), isolates the arming of a Clip Section from all other launch activity. This option is found to the left of option LNE (Launch Non-Exclusively) when selecting the section's number of repetitions:
AUDITION-HOLD-->SELECT-ENC-->TURN-LEFT

All section launch events leave untouched the launch status of LE sections. In contrast, LNE sections arm and turn off when a new section launches. LNE sections armed with another section will have that section repeat infinitely and ignore its set number of repetitions.

TEST PLAN: A link to the song XML used in this test plan can be found in a comment link below.

SETUP:
Section 3, Launch Exclusively, Clip 7
Section 4, Launch Non-exclusively, Clip 6
Section 1, repeat 2, Clips 4 and 5, Fill 3
Section 2, repeat 2, Clips 1 and 2, Fill 0

START: Several ways to start. One way is to arm section (3) and press PLAY, or alternatively section (1) or section (2) can be armed or PLAY can start with no clips active. Note the difference between arming a clip versus arming a section. If any tracks are armed individually or the song is loaded from disk with clips already armed, then these clips will loop infinitely and not queue the transition to the next section.

LAUNCH: Launch (3). After play starts, launch section (1). Drums in (3) continue. FILL Instrument in section (1) does a walk-up bass line. Section (1) begins. Drum track (3) still ON. Instrument fill played once and now is OFF. Section (2) is flashing red and Section (1) is flashing green. OLED is reporting 2 Bars Remaining. Instrument Fill on Section (2) plays during the last bar of the repeat before (2) launches.

STOP: After section (2) launches, the 'exclusive' section (3) is NOT flashing green. The section (2) instruments are flashing green. If left to complete 2 repetitions, then all clips will stop.

REPEAT: However, if section (1) is armed to launch again, the non-exclusive section (3) button becomes solid green and continues to play. The section (1) flashes green. This effectively repeats step number 4) above.

TEST NON-EXCLUSIVELY: Launch section (4) after (1) has launched. Section (1) is flashing green while playing for its two-bar repeat. Section (4) flashes red for one bar and green for the second. It turns off when section (2) launches.

TEST SONG FILE SAVE: When song saveed to disk, a section's numRepeats values allows numbers in the range -2 to 9999.

The same behavior was observed to occur in Session Grid View.

[github-actions]

Test Results

107 tests  ±0   107 ✅ ±0   0s ⏱️ -1s
 16 suites ±0     0 💤 ±0 
 16 files   ±0     0 ❌ ±0 

Results for commit 9ef8cc4. ± Comparison against base commit c91a932.

♻️ This comment has been updated with latest results.

[todd-gochenour]

Here is the song used in testing.

Testing song example.zip

[todd-gochenour]

Open Issues:

1. Would this feature be better named 'Launch Independence'?
2. Should the final flashing queue before song stops be flashing red instead of green?
3. I'd like to see a different flashing style, a slower gradient fade, while more than one bar remains in the queue before launch. Then when the last 4 beats occur the current flashing makes it obvious that a launch is about to happen.

[m-m-adams]

Yeah maybe change it to "plan non exclusively"? I think that makes it clearer that it doesn't only refer to launches. Additionally I think this should be a new mode rather than a change of the existing mode since this removes the ability to have a clip which starts on its own and ends on section switch

For your open issues 2 and 3 both sound good to me!

[todd-gochenour]

Open Issue (1): Left existing label for 'Launch Non-exclusively' alone. Added new mode 'Launch Exclusively'.
Open Issue (2): Not implemented. I was wrong about the colors. Flashing green means 'currenly playing but about to stop' and flashing red means 'not playing but about to start'.
Open Issue (3): Not implemented.

[todd-gochenour]

Updated test song configuration with added 'Launch Exclusively' mode.
Testing song example xml.txt

[todd-gochenour]

Video playback of testing song:

https://www.youtube.com/watch?v=3DqX7K1BLNY

[m-m-adams]

Code lgtm. Before we merge it needs user facing docs under community features to explain what it's for and how to use it effectively though!

[todd-gochenour]

Retested and found defect that I'm currently trying to resolve. Clips that 'Launch Exclusively' will not shut off except at the end of the song.

[todd-gochenour]

I've completed a refactor of the strategy for implementing this LE (Launch Exclusively) section. I've done a better job contrasting the functionality between an LE section with the original LNE (Launch Non-Exclusively) section.

The strategy I had before where the code would ignore clips with numRepetitions=-2 during traversal across the song's list of clips meant that the LE clip could never be launched or stopped, yielding the wrong interpretation of the word 'Exclusively'.

Starting over.

I've concentrated the focus around when and how the variable lastSectionArmed is set. This variable is left untouched when the launch event being processed is from an LE section or clip. A clip in an LE section will launch or stop without affecting the arming of other sections. In the opposite direction any other launch event will launch and stop without affecting the status of the LE section. Contrast this behavior with LNE clips after launch that cause other clips to repeat infinitely or LNE clips that arm and stop playing when another section launches.

The second change made to code is the logic that gets the next section to arm. With SONG ROW VIEW the clips are ordered bottom to top and the next section to launch after n number of repeats is c - 1. With SONG GRID VIEW the clips are ordered top to bottom by section number and the next section to launch is c + 1. When either of these next sections is an LE section, the code now skips over that section to find one not an LE section.

A new testing plan includes launching and muting the LE clip. Tests conducted against an LNE section are included to contrast results between the two options. Tests using the SONG GRID VIEW are also included.

[todd-gochenour]

Testing Plan

• FR stands for Flashing Red and FG stands for Flashing Green.
• In the tests below, change section 2 to repeat infinitely and the flashing goes away when section 2 is playing. This helps to distinguish flashing launch events that start when section 1 is armed.
• The order of clips is significant. In SONG ROW VIEW clip 7 is top and clip 0 is at the bottom. In SONG GRID VIEW the sections are rows ordered top to bottom by section #). Changing the order of clips in SONG ROW VIEW will be part of the test plan. The order of sections in SONG GRID VIEW cannot be changed.

Setup (Using same song as above, all test results above are still valid)
Section 3, Launch Exclusively, Clip 7
Section 4, Launch Non-exclusively, Clip 6
Section 1, repeat 2, Clips 4 and 5, Fill 3
Section 2, repeat 2, Clips 1 and 2, Fill 0

• Before Launch
  Play is off. All clips are muted. Arm section 4. Arm section 3 (4 stays on). Arm section 1 (3 is on and 4 is off). The difference between launch non-exclusively and launch exclusively is how they are affected by the launch of other sections.

• At Launch
  Play is on. (3 is on, 1 is FG, 2 is FR). Play continues to section 2 (3 is FG and 2 is FG as no next section follows so play is about to end).

• Interrupt final countdown
  Play is on. Arm section 1 (3 is on, 1 is FR and 2 is FG). Play continues to section 1 (3 is on, 1 is FG and 2 is FR). Play continues to section 2 (3 is FG and 2 is FG as no next section follows so play is about to end). Play continues and stops. (Note that Section 2 clips are on and will play infinitely if play is pressed again. Arming section 2 before pressing play will implement the section repeat of 2.)

• Arm Section 3 immediately after Section 1 (Launch Exclusively)
  Play is off. Section 3 is off. Arm Section 2. Play is on (2 is FG). Arm section 1 (1 is FR). Arm section 3 (Both 1 and 3 are FR). Play continues to section 1 (3 is on, 1 is FG and 2 is FR).

• Arm Clip 7 immediately after Section 1 (Launch Exclusively)
  Play is off. Section 3 and 4 is off. Arm Section 2. Play is on (2 is FG). Arm section 1 (1 is FR). Arm clip 6 (Both 1 and 3 are FR). Play continues to section 1 (3 is on, 1 is FG and 2 is FR).

• Arm Section 4 immediately after Section 1 (Launch Non-exclusively)
  Play is off. Section 3 and 4 is off. Arm Section 2. Play is on (2 is FG). Arm section 1 (1 is FR). Arm section 4 (Both 1 and 4 are FR). Play continues to section 1 (4 is on, 1 is on and 2 is off). Play repeats infinitely.

• Arm Clip 6 immediately after Section 1 (Launch Non-exclusively)
  Play is off. Section 3 is off. Arm Section 2. Play is on (2 is FG). Arm section 1 (1 is FR). Arm clip 6 (Both 1 and 4 are FR). Play continues to section 1 (4 is on, 1 is on and 2 is off). Play repeats infinitely.

• Move Section 3 in between Sections 1 and 2 (Launch Exclusively)
  Play is off. Section 3 is off. Arm Section 2. Play is on (2 is FG). Arm section 1 (1 is FR). Play continues to section 1 (3 is off, 1 is FG and 2 is FR).

• Move Section 4 after Section 1 and before Section 3 (Launch Non-exclusively)
  Play is off. Section 3 and 4 is off. Arm Section 2. Play is on (2 is FG). Arm section 1 (1 is FR). Play continues to section 1 (3 is off, 1 is FG and 4 is FR). Play continues to section 4 and repeats infinitely.

• Test SONG GRID view
  Play is off, mode is green (not blue). Arm section 1 (first row). Play is on (first row FG, second row FR). Play continues to second 2 row (second row FG, fourth row (the launch non-exclusively section) is FR). Play continues to fourth row and then repeats infinitely.

• SONG GRID view arm third row clip (Launch Exclusively)
  Play is off. Third Row clip is off. Arm first row. Play is on (first row FG, second row FR). Launch clip on third row (third row FR, second row FR). Play continues to row 2 (second row FG, third row is on, fourth row FR). Arm first row (second row FG, first row FR, fourth row is off). Arm third row clip (second row FG, first row FR, third row FR). Play continues to first row (first row FG, second row FR, third row is off).

• SONG GRID view arm fourth row clip (Launch Non-exclusively)
  Play is off. Both Third and fourth row clips are off. Arm first row. Play is on (first row FG, second row FR). Launch clip on fourth row (fourth row FR, second row FR). Play continues to row 2 (second row on, fourth row is on). Play repeats infinitely.

• Test SOLO with section 3 in SONG ROW view (Launch Exclusively)
  Section 3 and 4 in original position. Play is off. Section 3 is on. Arm Section 1. Play is on (1 is FG, section 2 is FR, section 3 is on). SHIFT-LAUNCH any clip. (The clip is flashing blue, 1 is FG, section 2 is FR, section 3 is on). Play continues to SOLO (clip is solid blue). Press clip's LAUNCH button to disable SOLO (clip is on, section 3 is on, the same instrument in Section 2 is off, the other instrument in section 2 is on).

• Test SOLO with section 4 in SONG ROW view (Launch Non-exclusively)
  Section 3 and 4 in original position. Play is off. Section 3 is on. Arm Section 1. Play is on (1 is on, section 2 is off, section 4 is on). SHIFT-LAUNCH any clip. (The clip is on). Press clip's LAUNCH button to disable SOLO (section 1 is on, section 4 is on).

[todd-gochenour]

In all the tests cases above, section 2 is set to repeat twice and end the song, as there are no more normal sections that follow in SONG ROW view. Both Section 2 and section 3 are FG signaling they are about to stop. If I change section 2 to repeat infinitely the flashing goes away. Section 2 and 3 are solid green. Then when section 1 is armed the flashing begins and then stops once section 2 is launched. This makes testing the visual UI slightly easier to comprehend.

New test case:

• Arm Section 3 immediately BEFORE Section 1 (Launch Exclusively)
  Play is off. Section 3 is off. Change section 2 to repeat infinitely. Arm Section 2. Play is on (2 is on). Arm section 3 (2 is on, 3 is FR). Arm section 1 (2 is FG, 1 is FR, 3 is FR). Play continues to section 1 (3 is on, 1 is FG and 2 is FR).

• Arm Section 4 immediately BEFORE Section 1 (Launch Non-Exclusively)
  Play is off. Section 3 and 4 are off. Change section 2 to repeat infinitely. Arm Section 2. Play is on (2 is on). Arm section 4 (2 is on, 4 is FR). Arm section 1 (2 is FG, 1 is FR, 4 is off). Play continues to section 1 (4 is off, 1 is FG and 2 is FR).

[todd-gochenour]

I've completed my development and testing on this PR.

[m-m-adams]

Structure looks good, if you replace the magic numbers with constants so it's more readable then I'm good to merge it