Post by nic on May 3, 2019 18:49:21 GMT
Customising the Controls Box
The controls box is customised using SET rules. Each control is referred to using the 'Q' variable array which has 16 elements of signed 16 bit values. Q0 refers to the 1st control on the 1st page and QF (or Q$15) is the last control on the second page. Remember, the second controls page is invisible unless referred to in a script.
The first thing you will want to set is the name of the control (from the defaults of Q0 to QF)
set Q0 mySlider
which will tell StreamByter that Q0 is a slider control and has the name 'mySlider'. If you would like to use more than one word in a slider name (or a block label for that matter) then you put an underscore in the name and when it is displayed the underscore will be replaced by a space:
set Q0 Max_Level_%
will show 'Max Level %; as the slider name.
When setting up a control, the name is mandatory (except for a hidden control, see below).
The next thing you can change about a control is the type of control. You do this by specifying a flag in the set rule:
set Q1 Push_Me +button # a momentary pushbutton
set Q2 Toggle_Me +toggle # a latched pushbutton
set Q3 CC_Number +menu # a dropdown menu (0-127)
set Q4 Boolean_Option +yesno # a boolean dropdown menu
set Q5 Note +note # a note name dropdown (yamaha C-2-G8 convention)
set Q6 +hide # control is hidden from the control box
set Q7 Delay +slider # control is a slider
If there is no flag, the control defaults to a slider.
set rules can be called from anywhere in the script so you can change a control's appearance, name or range dynamically. See the Channel Switcher tutorial for an example of this. If the control configuration is static in your script, for efficiency, enclose your set rule inside an if load block.
Setting a Control's Range
By default the range that the control can have is 0-127 (slider, menu and note) or 0-1 (button, toggle and yesno).
If you wish to change the range of a 0-127 control, you include the range in the set rule:
set Q0 Octave $-4 $4 +slider
Which will create a slider which will range in whole numbers between -4 and +4.
If you wish to configure a note dropdown control's range, you can do this too with either MIDI note numbers or note literals (or both)
set Q5 Note ^C3 ^G8 +note
set Q6 Note 0 $64
Finally, you can use short 1 character flags if you prefer conciseness: +s, +t, +b, +m, +n, +y, +h
Naming a Script
In some hosts (AUM definitely does) you can tell the host that you want your Audio Unit instance to have a (short) name. The host will then display the name with the icon. To set a name do:
set name Looper
which will display 'Looper' in the host (if it supports that). AUM supports max 6 character names, BTW. You can change your script name dynamically, but again, if it is static I suggest you put your set name inside an if load block.
Exposing/Hiding the controls box
You can expose or hide the controls box from code too, so you could have the controls box automatically displayed when the script is loaded:
set slider_display 1 # exposes the 1st controls box
set slider_display 2 # exposes the 2nd controls box
set slider_display 0 # hides the control box.
Again, this can be done dynamically in your script, but if only being done once at startup put it in the if load block.
Block Labels
The other UI elements that can be customised are the two black labels at the bottom of the StreamByter interface (always displayed). The left label is called 'LB0' and the right label is 'LB1'. You can display numbers in hex or decimal, note names (C-2-G8) or text strings of your own choosing:
set LB0 I0 # display current value of I0 in hex
set LB0 I0 +decimal # display I0 as decimal number
set LB1 ^Bb2 +note # display as note
set LB1 SHello # display the string 'Hello'
The controls box is customised using SET rules. Each control is referred to using the 'Q' variable array which has 16 elements of signed 16 bit values. Q0 refers to the 1st control on the 1st page and QF (or Q$15) is the last control on the second page. Remember, the second controls page is invisible unless referred to in a script.
The first thing you will want to set is the name of the control (from the defaults of Q0 to QF)
set Q0 mySlider
which will tell StreamByter that Q0 is a slider control and has the name 'mySlider'. If you would like to use more than one word in a slider name (or a block label for that matter) then you put an underscore in the name and when it is displayed the underscore will be replaced by a space:
set Q0 Max_Level_%
will show 'Max Level %; as the slider name.
When setting up a control, the name is mandatory (except for a hidden control, see below).
The next thing you can change about a control is the type of control. You do this by specifying a flag in the set rule:
set Q1 Push_Me +button # a momentary pushbutton
set Q2 Toggle_Me +toggle # a latched pushbutton
set Q3 CC_Number +menu # a dropdown menu (0-127)
set Q4 Boolean_Option +yesno # a boolean dropdown menu
set Q5 Note +note # a note name dropdown (yamaha C-2-G8 convention)
set Q6 +hide # control is hidden from the control box
set Q7 Delay +slider # control is a slider
If there is no flag, the control defaults to a slider.
set rules can be called from anywhere in the script so you can change a control's appearance, name or range dynamically. See the Channel Switcher tutorial for an example of this. If the control configuration is static in your script, for efficiency, enclose your set rule inside an if load block.
Setting a Control's Range
By default the range that the control can have is 0-127 (slider, menu and note) or 0-1 (button, toggle and yesno).
If you wish to change the range of a 0-127 control, you include the range in the set rule:
set Q0 Octave $-4 $4 +slider
Which will create a slider which will range in whole numbers between -4 and +4.
If you wish to configure a note dropdown control's range, you can do this too with either MIDI note numbers or note literals (or both)
set Q5 Note ^C3 ^G8 +note
set Q6 Note 0 $64
Finally, you can use short 1 character flags if you prefer conciseness: +s, +t, +b, +m, +n, +y, +h
Naming a Script
In some hosts (AUM definitely does) you can tell the host that you want your Audio Unit instance to have a (short) name. The host will then display the name with the icon. To set a name do:
set name Looper
which will display 'Looper' in the host (if it supports that). AUM supports max 6 character names, BTW. You can change your script name dynamically, but again, if it is static I suggest you put your set name inside an if load block.
Exposing/Hiding the controls box
You can expose or hide the controls box from code too, so you could have the controls box automatically displayed when the script is loaded:
set slider_display 1 # exposes the 1st controls box
set slider_display 2 # exposes the 2nd controls box
set slider_display 0 # hides the control box.
Again, this can be done dynamically in your script, but if only being done once at startup put it in the if load block.
Block Labels
The other UI elements that can be customised are the two black labels at the bottom of the StreamByter interface (always displayed). The left label is called 'LB0' and the right label is 'LB1'. You can display numbers in hex or decimal, note names (C-2-G8) or text strings of your own choosing:
set LB0 I0 # display current value of I0 in hex
set LB0 I0 +decimal # display I0 as decimal number
set LB1 ^Bb2 +note # display as note
set LB1 SHello # display the string 'Hello'