[Up: CAL home page]
[Previous: CAL Edit Menu Commands]
[Next: CAL programs for downloading]
Bikexprt.com Web
Site
| [Top: John
S. Allen's Home Page] [Up: CAL home page] [Previous: CAL Edit Menu Commands] [Next: CAL programs for downloading] |
|
Preview the table which is the centerpiece of this article
The table which is the centerpiece of this article shows all of the Cakewalk event types (through version 9) and how they can be manipulated in the Cakewalk Application Language, CAL. The table assembles and summarizes the contents of several CAL help screens. Also, the table describes a number of undocumented event types and parameters, indicated with asterisks (*). Cakewalk is an event-driven sequencer. It stores and transmits MIDI events such as note-on and note-off messages, controller messages and tempo changes. Cakewalk lets you edit events using familiar Windows commands such as Cut, Copy and Paste. The main use of the CAL programming language is to automate a series of these editing functions. Some Cakewalk events -- markers, meter and key settings and tempos -- do not exist as event types in CAL. CAL is completely blind to markers, though it can cut copy, paste and delete them without knowing they are present. Through programming tricks, CAL can identify, insert and modify meter/key settings and tempos (and in some versions, there are undocumented procedures to modify them. How it can do that is fodder for another article, though. The clickable event type table The table you will see next as you scroll down this page is a clickable image map. Click on the column numbers above the table, or anywhere in the table, to go to an explanation of that part. If a click brings you back here, that is because you clicked on the border between two regions. Try again after moving the mouse pointer slightly one way or another. The width of the table will fit on a 640-pixel-wide computer monitor, but 800 x 600 or greater resolution will let you see more of the table's height at once. If you remove some of the toolbars at the top of your browser window, that will help, too. This article is best used by saving it, along with its graphics, and viewing it in your browser as you work in CAL. The article should be in a directory named cakewalk, and images in a directory named images (case-sensitive names!, both under the same higher-level directory. You might also print the article out, preferably in color. The event types are listed in the order in which they appear in the Cakewalk Event Filter, and to let you construct an insert command by scanning down the table from the top. Color Coding; Accessibility The table makes heavy use of text and background color. I have provided an explanation of the color coding. Please read it! I also have some suggestions which I hope will be helpful for people without normal color vision. The Microsoft Excel '97 spreadsheet from which the graphic was copied is also available for downloading. |
CAKEWALK EVENT TYPES AND
THEIR PARAMETERS
Click
anywhere inside the graphic to go to an explanation of that part!
Usage (to right) -- Event, variable or parameter (down)
Column 1 of this table lists the 17 types of Cakewalk and CAL events, with their parameters. Columns 2 through 7 (to the right) give more information about each type of event, and show the different ways in which these may be used in Cakewalk and in CAL. Table column headings "Classic" MIDI events (column 1, near top) The official data type list for Cakewalk includes only the familiar Cakewalk MIDI events, in the categories NOTE (actually a pair of events, note on and note off) , PATCH, CONTROL, CHANAFT, KEYAFT, WHEEL, SYSX. (See the help screen CAL | CAL data types). The SYSX event works differently from the others(see below). Table column headings RPNs and NRPNs (column 1, middle) RPNs (registered parameter numbers) and NRPNs (non-registered parameter numbers) -- are clusters of 4 controller messages which Cakewalk 6.x and higher and many synthesizers read as single messages.. Earlier Cakewalk versions can send and receive RPNs and NRPNs, but they appear as clusters of controller messages. There are 16384 possible RPNs and 16384 possible NRPNs. Each may have 16384 possible values. These numbers follow from the fact that a single controller message can transmit 128 possible values. 16384 is 128 squared -- each RPN or NRPN uses two controller messages to transmit the RPN or NRPN number, and two more to transmit the value. The controller numbers for an RPN are 101,100, 6, 38. The controller numbers for an NRPN are 99, 98, 6, 38. Controllers 98, 99 or 101, 100 establish the RPN or NRPN number. Once it has been established, any number of data messages on controllers 6 and 38 may be sent, each time changing the data values. The Controller 38 message may be omitted entirely if the high order byte provides enough precision. Repeated controller 38 messages can change the value of the low-order byte without the need to resend an unchanged high order byte. There is more detail on page190 of the CPA 6 manual, on page 6-33 of the CPA 7 manual, on page 6-34 of the CPA 8 manual, and on the Cakewalk Web site at http://www.cakewalk.com. Table column headings SYSX and SYSXDATA (column 1, middle) The SYSX event in Cakewalk sends MIDI data, but unlike the other MIDI events, it does not unleash one note or one change in an instrument's settings. Instead, it is a call to Cakewalk to transmit one of 256 banks of device configuration data which are stored using Cakewalk's Sysex View. Each bank of configuration data may have many different effects on the MIDI device. Different makes and models of MIDI devices use different Sysex commands, so the data will only work with the one type of device for which it is intended. Other devices will ignore it. SYSXDATA, introduced in CPA 6, provides a second way to transmit System Exclusive data, as strings embedded directly into a MIDI track. This allows more flexibility in transmitting such data, for example in connection with the position of a slider in Cakewalk's Panel View. . Table column headings Additional event types in CAL 3.0 (column 1, middle) The Event Filter commands in CAL versions 3.0 and later support four additional "kind of event constants": TEXT -- comments that appear in the Event list. Notice that TEXT and LYRIC have no audible effect. TEXT simply provides a way to leave cues or comments in the Event List. Each LYRIC event con - sists of a sin - gle syl - la - ble. These events are intended for Staff View and printed notation, and are also visible in the Event List. Table column headings additional event types in CAL 4.0 (column 1, bottom) CAL version 4.0 introduced three more types of event which, like LYRIC, affect the Staff View display and are visible in the Event List: EXPRESSION -- expression text such as p, mf and fff, Table column headings SetFilterKind, event kind constants (column 2) szKind stands for one of the 17 event kinds, or "kind of event constants" -- NOTE, KEYAFT, CONTROL...etc., listed in Column 3. Each of these corresponds to one of the kinds of events in column 1. Cakewalk's CAL recorder writes expressions in the form (SetFilterKind nFilter szKind bInclude) when you invoke the Event Filter. For more details on event types, see the Cakewalk help screen for CAL | CAL Function Reference | Edit Menu | SetFilterKind. Also check out what happens when you invoke the Event Filter with the CAL Recorder running. CAL uses exactly the same 17 event kinds -- NOTE, KEYAFT, CONTROL...etc. -- in conditionals like (if (== Event.Kind NOTE)....) or (if (!= Event.Kind WAVE)....). The event kinds I have shown with asterisks, such as (*HAIRPIN) are UNDOCUMENTED, but the CAL recorder invokes them in the SetFilterKind expression, and they also work with Event.Kind conditionals. The asterisk is not part of the actual name of the event kind. You may read how I discovered the undocumented event kinds, if you are interested. The discussion may give you some ideas about how to discover other useful things using the CAL Recorder. I have written a CAL program (downloadable on this site) which you may use to determine which types of events your version of Cakewalk supports. A way to demonstrate this for yourself is to invoke Event Filter with the CAL recorder on, and deselect all types of events. The CAL recorder will generate a CAL command for each kind of event which your version supports. The undocumented event types in CAL are a very powerful tool. For example, you can move audio clips from one time or channel to another using CAL. The official documentation gives the impression that this is not possible, or at least not possible without moving other types of events. Table column headings Inserting events using CAL (column 3, top half) The insert command in CAL may be used to insert any of the 6 types of events it supports. The form of the command is as shown at the top of the column, (insert time chan kind params). Every (insert..) command must include a time, a chan, a kind and the params of that kind. To construct an insert command, read down the column from the top. Pick up the time and channel, then skip down to the event type you want, its (indented) parameters and the closing parenthesis, as in this example:
With values assigned to the parameters, this example might give you: (insert (makeTime 2 1 0) CONTROL 7 64), which would insert a controller 7 (volume) setting of 64 at the start of measure 2. Notice that a parameter need not be a number -- it can be a variable or an expression which returns a number, such as the (makeTime 2 1 0) I used. Allowable values for the params are given in columns 6 and 7 of the table. For more about the (insert...) command, see the CAL help screen under CAL | CAL Function Reference | Buffer functions (or in v. 7 and 8, Reference Material | CAL Function Reference | Buffer functions). Table column headings When CAL insertion doesn't work (column 3, bottom) (insert...) is not available for newer event types, because CAL has not yet been extended to support the parameters of these event types. I have indicated [in square brackets, like this] common ways of inserting such event types outside of CAL. An approach that does work in CAL with any type of events is to store them in .wrk files and to paste them in using the CAL FileMerge command. RPNs and NRPNs can be inserted in CAL as groups of 4 controller events. However, Cakewalk 6 does not identify these as RPNs and NRPNs until you reopen the .wrk file. I have written a CAL program to insert RPNs and NRPNs. It forces Cakewalk 6 to recognize them, and it is available for downloading on this site. I don't yet have a version that works under Cakewalk 7 or 8. Table column headings Reading and changing parameters of events in CAL (column 4, top half) Parameter variables are used directly to read or change the values of parameters, as in the example:
This example checks all controller 64 (sustain pedal) events and sets them to 127 or to 0 depending on whether their original value was 64 or greater. This is actually a practical example -- some MIDI devices support "half-pedaling" like a real piano. These MIDI devices can generate any sustain pedal value from 0 to 127. Some other MIDI devices want either a 0 or a 127. This CAL routine will make all of the needed changes for you. (A more sophisticated version of this routine would also delete repeated pedal down or pedal up events. Could you upgrade the routine here to do that?) Table column headings Events without parameter variables (column 4, bottom) The newer event types, RPN, NRPN, SYSX, SYSXDATA, TEXT, LYRIC, WAVE, MCI, EXPRESSION, CHORD and HAIRPIN do have parameters (see pages 187 and following of the CPA 6 user manual, 6-41 and 6-42 in the CPA 7 manual, or 6-43 and following in the CPA 8 manual) -- but these event types do not have parameter variables in CAL, or if there are any such variables, I do not know their names. (I tried some obvious possibilities such as Hairpin.Dur, and they returned syntax errors). For this reason, it is not yet possible to make internal changes to these newer types of events inside a (forEachEvent...) loop. It is possible to change the starting times and channel assignments of the newer event kinds using Event.Time and Event.Chan, parameter variables which are available for all events. Since all events have Event.Kind constants, it is possible as well to include or exclude any type of event from processing in the (forEachEvent....) loop. It is possible to change all parameters of RPNs and NRPNs (as with all the "classic" MIDI events as well) using the EditInterpolate40 command in CAL under Cakewalk 6 and higher, which use the SetFilterKind and SetFilterRange commands described in our table. . Table column headings SetFilterRange, parameter ranges (columns 5-7) The command (SetFilterRange nFilter nRange bInRange wMin wMax) sets limits for filtering using the Event Filter. This type of selective filtering is available for all parameters for which numbers are given in column 5 of my table. These include not only the parameters of the "classic" MIDI events, but also times, RPNs and NRPNs. The nFilter parameter is set to 0 for event filtering, to 1 for Interpolate input filtering or to 2 for Interpolate output filtering. The CAL help screen on the Interpolate command provides more information. The nRange parameter corresponds to the numbers 1 through 17 in column 5 of our table. This parameter determines what is to be filtered. For the From and Thru times, there is no SetFilterKind command and so, no nRange parameter. These times may be established inside the filter dialog box or directly in CAL -- for example, (= From 480). There are nRange parameters (nFilter values 11 and 12) for Beat and Tick. Changing these does not change the From and Thru times, but rather determines which beats and ticks in each measure are included in filtering. I have marked the nRange numbers 14 through 17, for RPNs and NRPNs, with asterisks (*) because they are UNDOCUMENTED -- though the CAL recorder invokes them under CPA 6. The bInRange parameter determines whether the range between the two filtering limits is to be what the filter leaves in, or what it cuts out. wMin and wMax set the limits of the range. The number in column 6 for each parameter is the lowest possible value for wMin and the number in column 7 is the highest possible value for wMax. Table column headings Values of wMin and wMax (columns 6 and 7) The values of wMin and wMax are generally the lowest and highest possible values for the parameters they represent -- but there are some special cases, noted in red: 16777215 (2^24 - 1) is the highest possible raw time in Cakewalk. Some commands, and notably the Retrograde commands, do not seem to work right with very high tick numbers, so take care. Unless you are planning to write a piece of music several hours long and include it in one Cakewalk file, this should not be a problem. MIDI channel numbers (parameter unlucky 13) can be confusing, for two reasons. 1) We commonly refer to channel numbers as "1 through 16," but computers like to start counting at zero, so in MIDI and in Cakewalk (and so in wMin and wMax), channel numbers are actually 0 through 15. Remember to subtract 1 from the channel number when using wMin and wMax. 2) Cakewalk's user interface lets us use -1 to refer to "all channels" or "do not force to a channel" -- for example, when setting the channel number in Track view. When we want the Event Filter to pass all channels, though, we set wMin to 0 and wMax to 15. In the literature of some MIDI equipment manufacturers, patch numbers are referred to as 1 through 128. In CAL, they are 0 through 127. Subtract or add 1 as necessary... The patch bank number may be set to -1 in the Track view to indicate bank number pass-through. The Event Filter shows a highest value of 16384 for the patch bank number, though the highest value that it will actually set is 16383. Pitch wheel values are -8192 through 8191 everywhere except in the SetFilterKind command, where (O, joyous inconsistency!) they are 0 through 16383. Add or subtract 8192 as necessary... Table column headings Event Kinds without wMin and Wmax (columns 5-7 bottom) Since SYSX, SYSXDATA, TEXT, LYRIC, WAVE, MCI, EXPRESSION, CHORD and HAIRPIN have no (publicly known ???) nRange assignments, they have no wMin and wMax values for use in the Event Filter. The Event Filter is an all-or-nothing proposition with these kinds of events: it can exclude or include each kind of event, and that is all. The parameter values in columns 6 and 7 for these event types are used only outside CAL. Values for SYSXDATA (F0 xx [xx....] F7) are shown in RED to point out that these must include the beginning F0 and terminal F7, and that they need not include any special symbols to indicate that they are hexadecimal numbers. Velocity for audio data is shown in RED to point out that it uses a quasi decibel-linear scale (see CPA 6 manual, Appendix J, p. 533 and CPA 7 manual, p. 7-12., bottom). (But the scale is different under CPA 5 and there is none under CPA 3). The velocity setting may not bear the same relationship to loudness as in your synthesizer. Table column headings Colors used in the table Text colors are: violet, blue, green and orange to indicate items (constants, variables or parameters) to be inserted into a CAL expression. Red indicates items that require your special attention. These items are accompanied by comments in red in the text linked to the table. Background colors in the table are:
Back to text preceding table | Table column headings Suggestions to readers without normal color vision I express my regrets to readers who do not have normal color vision, but the 5 dimensions of the data in the 2-dimensional table would be hard to represent without color coding. You might try saving the table (it is a GIF file) and changing the color palette in an image editing program. A useful trick is to view the table through eyeglasses with lenses of different colors (as used for 3-D movies and comic books) so the colors will look different to each eye. For the common inability to distinguish red from green, I would imagine that purple and green lenses would work best, so you could also distinguish blue from green. Ordinary red/green 3D lenses might also work well if the green lens transmits enough blue. Back to text preceding table | Table column headings |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| [Top:
John S. Allen's Home Page] [Up: CAL home page] [Previous: CAL Edit Menu Commands] [Next: CAL programs for downloading] |
Contents © 1998 John S.
Allen
Last revised 28 May 2008 |
