-----------------------------------------------------------------------------
Ascore-HOWTO

(Includes enhancements to Ascore ver. 4.3)
 Copyright 2009  Alfred Steffens Jr.
-----------------------------------------------------------------------



----------------
--- Contents ---
----------------

    How to Create a Basic Score

    How to make a comment line

    How to define a variable

    How to create a pattern

    How to make chords and simultaneous notes

    How to set the number of pattern tracks

    How to skip specific tracks in the score

    How to skip a section of the score

    How to shift the MIDI note numbers on a given channel

    How to send MIDI data to multiple ports

    How to program aplaymidi to send MIDI data to multiple ports

    How to set a MIDI voice patch

    How to set the voice patch with a bank switch

    How to insert conditional _IFDEF_ statements

    How to change voice effects on a Yamaha ES-6

    What is the Yamaha ES6 MSB and LSB in terms of MIDI commands?

    How to use System Exclusive MIDI messages

    How to change tempo within a pattern

    How to insert MIDI control inside a pattern

    How to suppress all MIDI channels but one with a single statement

    How to Set Bank Switch Statements for Different Synthesizers

    How to Ramp (fade) a Midi Control Parameter

-----------------------------------------------------------------------------
-----------------------------------------------------------------------------


---------------------
--- Howto Section ---
---------------------



----------------------------
How to Create a Basic Score
----------------------------

The basic score must have these elements:

    1.  A "BEGIN" statement

    2.  One or more pattern definitions

    3.  One or more score lines

    4.  An "END" statement

~end~



---------------------------
How to make a comment line
---------------------------

Any line that starts with a "#" symbol is ignored as a comment.

~end~



------------------------
How to define a variable
------------------------

An ascore "variable" is a simple word that holds a number or text string
for later use in a pattern or a score line.

    set Amp 1.0

creates a variable called "Amp", case sensitive, that holds the value of
1.0.

    set     aval1   2.5

creates a variable called "aval1" with a value of 2.5.

    set amp_bb_1     0.1    1.102  2.1

creates a variable called "amp_bb_1" that is an array of values 0.1, 1.102,
and 2.1.

    set pan_gt    $aval1 $aval2 $aval1 $aval6

creates a variable called "pan_gt" with references to the eval operations
in aval1, aval2, aval6.

A variable can be created that is the result of an arithmetic operation on
another variable by using the "eval" keyword:

    eval hamp020      $Amp * 0.020

creates a variable called "hamp020" whose value is the value previously
stored in "Amp" multiplied by 0.020.  The operator can be *, /, +, -.
The second value can also be a reference to a variable, for example,

    eval hamp020      $Amp * $bFactor

Also, the variable references appearing in the eval statement may themselves
be the result of eval definitions: the values are not resolved until the
matrix is dumped to the Csound score.

Performing variable operations with ASCORE is very limited--this is not a
full-blown programming language.  It is just a set of simple rules that get
parsed by an AWK script.  The ascore.awk file was initially written in about
three days as a quick-and-dirty means of creating Csound scores.  The fact
that it is based upon a modular software design has made ascore.awk a
powerful, very easy to improve utility.  But we must remember to manage our
expectations in regards to its programability.

~end~



-----------------------
How to create a pattern
-----------------------

A "pattern" is a variable that ascore.awk turns into a sequence of Csound-like
score lines.  If you are unfamiliar with Csound, the following description
will help understand an ASCORE pattern.

A musical note in a Csound score is given as a line (a row) in the score file
in which each element (each column) controls some aspect of the note, such
as pitch, duration, amplitude, velocity, effect depth, etc.  In Csound
nomenclature each control element is referred-to with the letter "p" and a
number giving its sequential location on the line.  For example,

    i4  0.41  2.0  8.01  0.75  101  0.92

is discussed in the literature as

    p1 p2 p3 p4 p5 p6 ..... pN

where p1 = "i4" would mean instrument 4;  p2 = 0.41 would mean the start time
in the score is at 0.41 seconds after the beginning; p3 = 2.0 would mean the
duration of the note is 2.0 seconds; p4 = 8.01 would mean a pitch
corresponding to the C# just above middle C, etc.  Since a Csound score can
be written only with numbers, as in the score line above, we can see how hard
it would be to write music with Csound without using a "front-end" to write
the score.  The ascore.awk tool is a "front-end" for writing a Csound score.

The basic idea that motivated the creation of the ascore.awk tool is that
successive lines in a Csound score form a matrix, like in matrix algebra.
The following Csound score lines,

    i4  0.41  2.0  8.01  0.75  101  0.50
    i4  0.83  1.0  8.05  0.70  121  0.61
    i4  1.27  2.0  8.03  0.72   89  0.73
    i4  1.96  1.0  8.11  0.64  111  0.87

form a "matrix" of Csound p-fields with 4 rows and 7 columns.  This matrix
can be created as an ASCORE pattern:  rows are successivre notes, and columns
are Csound p-fields.  Each column is a parameter that defines that instrument's
sound.

A pattern, in ASCORE, is created by defining a variable that holds an array
of columns.  For example,

    set bb_rf_11    &  ^ins_bb_11  ^stt_bb_11  ^dur_bb_11  ^key_bb_11  (con't)

                    ^vel_bb_11  pad5  ^amp_bb_11  ^pan_bb_11

The variable "bb_rf_11" is created to be a note pattern with 9 columns:

     &          =   column 1
    ^ins_bb_11  =   column 2
    ^stt_bb_11  =   column 3
    ^dur_bb_11  =   column 4
    ^key_bb_11  =   column 5
    ^vel_bb_11  =   column 6
    pad5        =   column 7
    ^amp_bb_11  =   column 8
    ^pan_bb_11  =   column 9

The variables ins_bb_11, stt_bb_11, dur_bb_11, key_bb_11, vel_bb_11, amp_bb_11,
pan_bb_11 are arrays that are interpeted as columns not rows, because they are
prepended with "^" (carat) symbols.

The variable pad5 is not interpreted as a column because it is not
prepended with a "^".  The variable pad5 will be expanded as a row.
This row will form the top of a set of columns in the pattern.  Each of
these columns formed by pad5 will have the same values in every row,
because ASCORE will back-fill any column with the last value found (in
that column) in order to make every column have the same number of rows.
This means that the "&" symbol in the first column of the pattern will be
repeated to create a column with the same number of rows as the largest
column given.

The Csound score lines shown above could be created with an ASCORE pattern,
named "pattn", whose definition is shown below:

    set instrm    4
    set start     0.41   0.83   1.27   1.96
    set dur       2.0    1.0    2.0    1.0
    set key       8.01   8.05   8.03   8.11
    set ampl      0.75   0.70   0.72   0.64
    set veloc     101    121    89     111
    set pan       0.50   0.61   0.73   0.87
    set pattn     &  ^instrm ^start ^dur ^key ^ampl ^vel ^pan

The first column in the pattern, shown with the "&" symbol above, is always
the local tempo.  Setting it to a "&" symbol just means use the default tempo
of the score.  The second column in the pattern, shown above with ^instrm,
must always be the instrument number, and it becomes the first column in the
Csound score that is output.  The next 2 columns must be start time and
duration, respectively, as mandated by the Csound program.  The remaining
columns may be in whatever order you prefer.

The above variable definitions for the columns: start, dur, key, ampl, veloc,
pan, are simplified by giving raw numbers in the definition.  Usually, you
will put variable references instead of raw numbers.  For example, the note
durations will be given with duration symbols:

    set dur       o    h   o    h

being "whole note", "half note", "whole note", "half note".  The amplitudes
are better given with variables so that whole sections can have their amplitudes
adjusted simultaneously:

    set ampl      $ja01  $ja01  $ja01  $ja01

where the variables ja01, ja02, ja03, ja04 would have been defined somewhere
above the pattern with definitions such as the following

    set  JAmp    0.95
    eval ja01    $JAmp * 0.1
    eval ja02    $JAmp * 0.2
    eval ja03    $JAmp * 0.3
    eval ja04    $JAmp * 0.4

See the section on note duration symbols and tempo symbols.

~end~



-----------------------------------------
How to make chords and simultaneous notes
-----------------------------------------

Chords are created by using a special symbol for the start time in a pattern
definition.  When a pattern is created, the start time list can be literal
times, in seconds, or start-time symbols.  There are two different start time
symbols: an "&" symbol and an "@" symbol.  The ampersand ("&") symbol is used
for sequential notes, and the "@" symbol is used for simultaneous notes.  So
you must use the "@" symbol for chords.  You must not mix these two kinds of
symbols in the same pattern.

For example:

    set stt_bb_1    & & & & & &

defines a list (named stt_bb_1) of six notes having sequential start times.
This means that the notes in this pattern will be ordered to start one after
another, sequentially.  The whole pattern starts whenever this pattern appears
in the score.  This is a sequencer style of note pattern.  It was designed to
make scoring note patterns easy--the next start time is calculated for you.
On the other hand,

    set stt_cc_1    @ @ @ @ @ @

defines a list (named stt_cc_1) of simultaneous notes.  The "@" symbol can be
adjusted so that the simultaneous notes can be staggered to imitate real-world
variations (nothing is really simultaneous).  This is done by adding delays to
the "@" symbols in the start time list.  For example,

    set stt_cc_1    @ @+[!] @+[q] @+[h] @+[o] @+[2o]

makes the simultaneous pattern into a sequential pattern with the second note
delayed by a sixteenth note (!), the third note delayed by a quarter note (q),
the fourth note delayed by a half note (h), the fifth note delayed by a whole
note (o), and the last note delayed by two whole notes.

Here is how I get the effect of a guitar chord strummed:

    set stt_ff_1    @ @+[0.1!] @+[0.15!] @+[0.2!] @+[0.25!] @+[0.3!]

~end~




---------------------------------------
How to set the number of pattern tracks
---------------------------------------

The "TRACKS" variable must be set before any score lines are read.  This is
just a simple mechanism to tell the parser how many tracks to expect.  For
example,

    TRACKS 3
    7*          my_pattern_1        drums_4         horns_2b
    o               |                   %           horns_1
    5*          my_pattern_1        drums_5         horns_3

Whatever the "TRACKS" variable is set to, there must be TRACKS+1 fields
on the line (the left-hand time column plus the track columns).  The
"TRACKS" variable can be set as often as needed.  For example, each line
may be preceded by a "TRACKS" statement:

    TRACKS 3
    7*          my_pattern_1        drums_4         horns_2b
    TRACKS 2
    o               |               horns_1
    TRACKS 4
    5*          my_pattern_1        drums_5             %           horns_3

(Programmers may complain that I didn't have to make a TRACKS variable--the
code could have been written so that the number of columns are automatically
detected and processed--and I agree, but this is a "consistent coding
enforcement" B.S. that I am imposing on you because I can--it keeps the score
section well organized.)

~end~



----------------------------------
How to skip a section of the score
----------------------------------

In the score section, which specifies the columns of tracks and a left
hand timing column,

    q           guitar_part 1       sax_part1
    3*              |               sax_part2
    *           guitar_note_1           |
    2q              %                   %
    o           hold_guitar_note    sax_run_1

lines of the score may be temporarily "disabled", or skipped so that you don't
have to replay the whole score each time you work on one little pattern.
Place the statement SKIPSCORE on a line by itself, and every score line that
follows will be skipped until a line containing STARTSCORE is found.  In the
example above, let's say we want to work on the last line:

    o           hold_guitar_note    sax_run_1

Then we would use the SKIPSCORE, STARTSCORE keywords as in the example below,

    SKIPSCORE
    q           guitar_part 1       sax_part1
    3*              |               sax_part2
    *           guitar_note_1           |
    2q              %                   %
    STARTSCORE
    o           hold_guitar_note    sax_run_1

These key words may be used as often as is needed in the score to select
specific section to "blank out" of the score.  Also, repeated occurrences of
STARTSCORE are ignored until another SKIPSCORE is found.  Likewise, repeated
occurrences of SKIPSCORE are ignored until the next STARTSCORE is found, so
that sloppy score editing will not break the score(!).

~end~



----------------------------------------
How to skip specific tracks in the score
----------------------------------------

In order to "comment out" certain tracks use the "SKIPTRACK" statement.
On the line immediately above the score section where the tracks are to be
skipped, insert the statement

    SKIPTRACK <list of track numbers>

and when you want to turn those tracks back on, use the SKIPTRACK statement
but without any track numbers.  For example,

    TRACKS 3
    q           guitar_part 1       sax_part1       flute_part_7
    3*              |               sax_part2               |
    *           guitar_note_1           |           piano_run_4
    2q              %                   %                   %
    o           hold_guitar_note    sax_run_1               %

If we want to "comment out", say, the last two tracks to here what the
first track sounds like by itself we would use the following syntax:

    TRACKS 3
    #
    #   turn of the second and third tracks
    #
    SKIPTRACK 2 3
    #
    q           guitar_part 1       sax_part1       flute_part_7
    3*              |               sax_part2               |
    *           guitar_note_1           |           piano_run_4
    2q              %                   %                   %
    o           hold_guitar_note    sax_run_1               %
    #
    #   restore all tracks
    #
    SKIPTRACK

~end~



-----------------------------------------------------
How to shift the MIDI note numbers on a given channel
-----------------------------------------------------

In the code block that assigns MIDI channel to instrument number, specify
an "nshift" paramemter.  It specifies the number of MIDI note numbers (half
tones) to offset the note number given in the Ascore score.  For example, the
following code is used to assign your Csound instrument number 11 to midi
channel 2.

    CS2MTX midi_channel 2 instrument 11

now use the following line to cause all notes sent to this channel to be offset
(down) by an octave:

    CS2MTX midi_channel 2 nshift -12

~end~



---------------------------------------
How to send MIDI data to multiple ports
---------------------------------------

Use MIDI channels greater than 16.  MIDI channels 1-16 correspond to MIDI port
0, channels 17-32 correspond to MIDI port 1, etc.

~end~



------------------------------------------------------------
How to program aplaymidi to send MIDI data to multiple ports
------------------------------------------------------------

    aplaymidi -p 16:0,20:0  midi_file

will make Alsa midi port 16:0 the "port 0" and Alsa midi port 20:0 the "port 1"
port.

~end~


-----------------------------
How to set a MIDI voice patch
-----------------------------

For a general instrument, the following line issues a program change
midi command at the start of the playback (in the header of the midi
file):

    CS2MTX midi_channel 5 program 93

where the command is issued to midi channel 5 (numbered 1-16) and to
program (voice) number 93 (numbered 0-127).

To issue a program change command after the playback has already begun,
insert a line like the following line into the score section where you
want the change:

    PROGRAM 7  5

where the command is issued to midi channel 5 and program (voice) number
7 (numbered (0-127).

~end~


---------------------------------------------
How to set the voice patch with a bank switch
---------------------------------------------

Bank switching typically requires one or more midi control messages
just prior to the program change message.  Consult your synthesizer
midi reference.  The following explanation uses the Yamaha ES6 as
the example instrument. (see also, How to Set Bank Switch Statements
for Different Synthesizers).

In the code block that assigns MIDI channel to instrument number, specify
an the "bank" and "program" paramemters.  For example, to set the "GnarlyBs"
voice (bank pre 2, group F, number 14 ==> voice 094), use the following
code lines in the same code block that assigns midi channel to the Csound
instrument number.

    CS2MTX midi_channel 5 bank 1
    CS2MTX midi_channel 5 program 93

notice that bank numbers and program numbers are 1 less than what they are
on the keyboard control panel.

To issue a program change command after the playback has already begun,
insert a line like the following line into the score section where you
want the change:

    CONTROL BANK_MSB 63 5
    CONTROL BANK_LSB 1 5
    PROGRAM 93  5

where the command is issued to midi channel 5 and program (voice) number
93 (numbered (0-127).  The two CONTROL statements issue the bank switch
command.  The BANK_MSB is always 63 for voice banks, and BANK_LSB is
0=PRE1, 1=PRE2, 2=PRE3, 3=PRE4, 4=PRE5, 5=PRE6, 8=USR1, 9=USR2.  For
drums BANK_LSB will be 32.  To select the ES6 General Midi patches use
BANK_MSB=0, BANK_LSB=0.  For the General Midi drums: BANK_MSB=127,
BANK_LSB=0.

~end~


--------------------------------------------
How to insert conditional _IFDEF_ statements
--------------------------------------------

Sections of the Ascore file may be wrapped in "conditional compilation"
statements (like #ifdef in the C language).  The following psuedo code
illustrates how they are used:

    _IFDEF_ Mode1
    .
    code lines
    .
    _ELSE_
    .
    code lines
    .
    _ENDIF_

The lines between "_IFDEF_ Mode1" are included in the macro variable "Mode1"
is defined somewhere above it with the special syntax,

    _DEFINE_ Mode1

If no "_DEFINE_ Mode1" is found in the preceding code, then the code between
_ELSE_ and _ENDIF_ is included.

~end~


--------------------------------------------
How to change voice effects on a Yamaha ES-6
--------------------------------------------

Reverb Send:

    CONTROL  YM_EF1  <value>  <ch>
or
    CONTROL  91      <value>  <ch>

changes the Reverb Send (effect1) where value=0-127.

Chorus Send:

    CONTROL  YM_EF3  <value>  <ch>
or
    CONTROL  93      <value>  <ch>

changes the Chorus Send (effect3) where value=0-127.

~end~



-------------------------------------------------------------
What is the Yamaha ES6 MSB and LSB in terms of MIDI commands?
-------------------------------------------------------------

MSB is a CONTROL 0 command, and LSB is a CONTROL 32 command.  For example,
sending a BANK_MSB command could be done in either of the following two ways:

    CONTROL BANK_MSB  63  7
or
    CONTROL 0         63  7

and the BANK_LSB command could be done as follows:

    CONTROL BANK_LSB   2  7
or
    CONTROL 32         2  7

~end~



------------------------------------------
How to use System Exclusive MIDI messages
------------------------------------------

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Warning: system exclusive messages require a user agent (i.e., your midi
playback program) that supports system exclusive.  For example, on Linux
the the ALSA driver "sequencer" interface, which is what aplaymidi and
pmidi are built upon, does not support system exclusive messages.  Since
the ASCORE/MSCORE system basically creates a midi file, it requires you
run your "midi player" program to control your midi instruments.  That
midi player must support system exclusive messages (good luck).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use

    SYSEX <ch>  d0 d1 d2 ... dn

where d0 d1 ...  are upper-case, 2-digit hexidecimal numbers.

Warning:  this feature is experimental.  If it does not work on your
synthesizer, that is because this feature is untested.

~end~



------------------------------------
How to change tempo within a pattern
------------------------------------

Normally, tempo is changed with the TEMPO keyword in the score section.  But
this methos only changes the tempo for all notes that follow.  Within an
individual pattern the tempo can be changed so that only that particular
pattern is affected.  Recall, in "How to Create a Pattern," that the first
column in an ascore pattern definition is the "&" symbol, then the instrument
number.  This first column is the local tempo, and the "&" symbol by itself
means just use the tempo that was set with the last TEMPO keyword.

The local tempo is adjusted by supplying a separate "&" and modifier for
each note, for example

    set tmp_bb_1    1.1& 1.1& 1.1& 1.1& 1.1& 1.1&

corresponds to six notes at 1.1 times the tempo of the other patterns in the
section (1.1 times the value of the last TEMPO statement).

    set tmp_bb_1    & 0.9& 0.8& 0.7& 0.6& 0.5&

is a pattern whose tempo slows down.

~end~



-------------------------------------------------
How to insert MIDI control inside a pattern
-------------------------------------------------

The most general way to insert MIDI CONTROL changes into a score is with the

    CONTROL  <type>  <value>  <ch>

statement in the score (see above).  However, to associate a MIDI control
change with an individual note you can put the control change into a pattern
definition.  Then ASCORE will not only put a parameter value into the
Csound note line, but will issue a CONTROL statement into the Csound score
so that cs2mtx will convert it into a midi command.

Use the "%" (percent sign) symbol prefix in a parameter array to designate
a midi control parameter.

    set amp_xx_21    %7_45  %7_55  %7_65  %7_75

means control type 7 (volume control) with midi values 45, 55, 65, 75.

~end~



------------------------------------------------------------------
How to suppress all MIDI channels but one with a single statement
------------------------------------------------------------------

The MIDI_MASTER statement allows you to mute all but one MIDI channel.  This
feature was introduced for the sake of recording only one MIDI channel at a
time.  The necessity for this command may not seem obvious.  Most midi
keyboards can be set to a single voice mode in which all midi channels are
ignored but one.  And there are other ways, using Ascore commands, to select
only one channel for playback.

The MIDI_MASTER statement allows you to hold certain MIDI control messages
at a flat level (volume, pan, effects, etc) to be tweaked later in the
mastering process.  The most important consideration underlying the
MIDI_MASTER statement is the effort to keep the total number of MIDI messages
in the score constant.  Adding or removing MIDI messages in the score may
have slight effects on the synchronization of the voices.  This adverse effect
may not be noticable until the voices are recorded separately and mixed as
audio files.  If whole sections of the score file are removed (commented out)
for the sake of muting channels the MIDI message queue in your sequencer
will have a lighter burden and may speed up the message transmission slightly.

The syntax is as follows:

    MIDI_MASTER ch=<channel> ctrl###=nnn ctrl###=nnn ... ctrl###=nnn

There must be a "ch" parameter and at least one "ctrl###" parameter.  Channel
numbers must be given in the range 1--128 (ch 17 is the first channel on the
second midi port, ch 33 is the first channel on the third midi port, etc).

The syntax of the "ctrl###=nnn" argument is as follows:  the "###" is a three
digit control ID number in the range 0--127.  For example, ctrl001 is the midi
modulation wheel message;  ctrl007 is the midi volume message;  ctrl010 is the
midi stereo pan message.  The "nnn" is a three-digit control value number in
the range 0--127.

Example:

    MIDI_MASTER ch=5 ctrl007=80

will mute all MIDI channels but channel 5 and hold the volume of channel 5 to
80, regardless of any volume control messages in the score.  But any other
control messages for channel 5 will be passed through, unchanged.

Example:

    MIDI_MASTER ch=5 ctrl007=80 ctrl010=64

also suppresses all but channel 5, holding the volume constant at 80.  But
now any MIDI pan messages (control ID 10) will be intercepted and reset to
64 (center).

Every volume message encountered for one of the ignored channels will be
intercepted and its volume value set to zero.  Any MIDI control messages
encountered that are not specified on the MIDI_MASTER command line will be
passed through unchanged.

One or more channels may be made exempt from being blocked by MIDI_MASTER
with the "ignore" option.  Using

    ignore=8

for example, would allow midi channel 8 to be passed through, that is,
"ignored".  So in the above example we would put

    MIDI_MASTER ch=5 ctrl007=80 ctrl010=64 ignore=8

to the option line.

The opposite of MIDI_MASTER mode is MIDI_MUTE mode.  With MIDI_MUTE mode
you can suppress one or more channels.  This allows you to record most of
the channels simultaneously, leaving out a few that need to be recorded
separately for special effects.  The syntax of the MIDI_MUTE statement is
similar to the MIDI_MASTER statement:

    MIDI_MUTE ch=<chA> ch=<chB> ...

where each of the channels (numbered 1 to 128) listed will be muted.

~end~



-------------------------------------------------------------
How to Set Bank Switch Statements for Different Synthesizers
-------------------------------------------------------------

The musical instrument industry standard for bank switch MIDI messages is
a set of two control messages followed by the program (instrument patch)
MIDI message.  For example, the Yamaha Motif synthesizers would use the
following sequence of MIDI messages to set the bank to BANK 3:

    control 0,  value 63
    control 32, value 2

The first control message value (63) is called the "MSB", and the second
control message value (2) is called the "LSB."  However, the values used
for the MSB and LSB are not industry standards.  Each musical instrument
manufacturer will use different values for the MSB and LSB for bank
switching.  Although the control numbers 0 and 32 are probably common to
most synthesizers, it is like that there will be some exceptions.  In fact,
it may be that some devices do not use two control messages but one.

The ASCORE interpreter allows any sequence of one or more control messages
to be defined as a bank switch.  Bank switch definitions are like preset
settings that assign a sequential number to a bank on your instrument.  If
you had, hypothetically, some instrument that required three control
statements (I'm making this up) to switch to bank "2",

    control 0,  value 80
    control 20, value 81
    control 32, value 1

You could define a bank definition in your ASCORE score like this:

    BANKDEF   0 80 20 81 32 1

The numbers are all on the same line alternating between the successive
control numbers and control values that comprise the three MIDI messages.
To see how this works for multiple bank definitions, consider the definitions
for banks 1-6 and the drums bank on the Yamaha ES synthesizer:

    BANKDEF   0 63 32 0
    BANKDEF   0 63 32 1
    BANKDEF   0 63 32 2
    BANKDEF   0 63 32 3
    BANKDEF   0 63 32 4
    BANKDEF   0 63 32 5
    BANKDEF   0 63 32 32

The first "bank number", is 0 in the ASCORE score and corresponds to the
instrument's bank 1.  The second statement defines the ASCORE bank number 1
and corresponds to bank 2 on the instrument.  The last, seventh, statement
defines the ASCORE bank number 6 and corresponds to the instrument drum
bank.

It is important to understand that the ASCORE bank number is just the
sequential index of the bank definition statement.  If you want to assign
bank 0 to the drum bank you could just list the drum definition first.  The
ASCORE bank number will be the number that is entered in the CS2MTX script
line in your score.  In the above example the drum bank was the last
statement and received the assignment to number 6.  This number would be
used in the ASCORE script according to the following format:

    CS2MTX  midi_channel 10  bank 6

~end~



-------------------------------------------
How to Ramp (fade) a Midi Control Parameter
-------------------------------------------

Use either individual midi control statements, or use the automatic ramping
feature.

To manually send control messages use the CONTROL statement.  For example,
to ramp up (fade in) the volume (control number 7) for the instrument on,
say, channel 5 you would use the following commands in your Ascore score file:

    CONTROL   7   0   5
    CONTROL   7   5   5
    CONTROL   7  10   5
    CONTROL   7  15   5
    CONTROL   7  20   5
    CONTROL   7  25   5
        .
        .
        .
    CONTROL   7 127   5

Note, however, that the above example leaves out the necessary time intervals
(all the commands above would be sent simultaneously before any note messages).
The CONTROL message actually must be interleaved in the score lines so that
there are time intervals between the midi messages.  Let's say that pattern
"MakeMeSmile" has a duration of 13* (thirteen eighth notes), and you want
this channel to fade in over that duration.  Assuming (arbitrarily) that there
are three tracks at this score position, the command sequence would be changed
from

    TRACKS 3
    13*     MakeMeSmile     other_pattern     yet_another
to

    CONTROL     7     0     5
    TRACKS 3
    0.64!   MakeMeSmile     other_pattern     yet_another
    CONTROL     7     5     5
    0.64!       |                 |               |
    CONTROL     7    10     5
    0.64!       |                 |               |
    CONTROL     7    15     5
    0.64!       |                 |               |
        .
        .
        .
    0.64!       |                 |               |
    CONTROL     7   127     5

where all the 0.64! duration intervals are meant to sum to 13*.


The automatic control ramp is used with the following syntax in the Ascore
score file,

    CTRLRAMP <control>  <range>  <duration>  <increment> <channel>

For example, to fade in the volume (control number 7) on channel 5 over a
duration of 32* at intervals of * (eigthth note intervals), the following
command would be used:

    CTRLRAMP   7  0,127  32*   *   5

The syntax of this command requires that the control value range be two
numbers separated by a comma, no spaces or tabs between them.  The control
number (7 in the above example) must be a number between 0 and 127.  The
control value range numbers must also lie within 0 and 127.  The duration
over which the ramp is executed (32* above) must be a duration symbol
having an optional multiplier, no spaces or tabs between the multiplier
and symbol.  The time increment (time between messages) must adhere to the
same syntax as the duration.  The duration and time increment parameters
are not allowed to be pure numbers (cannot be absolute time).

The CTRLRAMP command should be inserted just above the score line where
the ramping should begin.  That way, the first score line will be rendered
with the starting control parameter--the first number in the value range.
After the last command parameter (the sixth field, that is, the midi
channel) a string of comments may be optionally appended.

~end~

-----------------------------------------------------------------------------
END of File
-----------------------------------------------------------------------------

September 10, 2009
alsteffe at netwood dot net

