12/*! \mainpage CFugue, The C++ Music Programming Library
13
14\section mainPageContents Contents
15 - \ref overview
16 - \ref features
17 - \ref pageExamples "Examples"
18 - \ref pageMusicString "CFugue MusicString"
19 - \ref download "Download CFugue"
20 - \ref copyright "Contact us"
21
22\section overview Overview
23
24CFugue, meaning Carnatic Fugue or the C/C++ replacement of JFugue, is a high level Music Programming Library.
25
26CFugue makes it possible to play music notes directly from C/C++ programs,
27without ever having to deal with the low-level MIDI complexities. This library
28provides a beautiful abstraction that lets you concetrate on programming the <i>Music</i> rather
29than worry about the MIDI nuances.
30
31CFugue has numerous features that make it possible to use it directly from many
32platforms, including but not limited to ASP pages, .Net applications and even non-Windows
33based systems.
34
35\section usage Usage
36
37Using CFugue to play music is as easy as writing plain music notes. Just create
38a Player object and call the Play method on it, supplying the Music notes to be played. Simple.
39<pre class="fragment">
40 \#include "CFugueLib.h"
41 void main()
42 {
43 CFugue::Player player; <span class="comment">// Create the Player Object</span>
44 player.Play("C D E F G A B"); <span class="comment">// Play the Music Notes on the default MIDI output port</span>
45 }
46</pre>
47And the music notes are not restricted to be of just Western sytle either. CFugue fully
48supports both Western and Carnatic Music notations - with a simple hint from the \ref subKeySignatures "KeySignature"
49directive, one should be able to switch between them seemlessly.
50
51For more usage demonstrations, please refer to \ref pageExamples "CFugue examples".
52
53\section features Features
54CFugue is a C++ runtime environment for music note programming with below features:
55 - Highlevel music programming library with direct support for C++ bindings and .Net P/Invoke calls
56 - Provides COM interfaces to enable easy integration with ASP clients and COM compatible clients, such as Delphi, VB etc.
57 - Easy to use notation. Writing music for CFugue is as easy as writing plain music notes.
58 - Event subscription model allows easy extension of the library to allow advanced features such as customized music renderers and parsers.
59 - Platform compatible code to make the library accessible from a veriety of platforms such as Windows and multiple variants of Linux: OpenSuse, Ubuntu etc.
60 - Fully compatible with both Western style of music and Carnatic music. Offers below capabilities:
61 - Specifying simples notes (such as C, D, E .. for Western and S, R, G .. for Carnatic)
62 - Specifying note durations
63 - Specifying ties, chords, sequential notes and parallel notes
64 - Specifying Raga, Tala and Speed directives
65 - Specifying MIDI Instruments and tracks
66 - and more...
67
68For further details on CFugue music note specifications, please refer to \ref pageMusicString "CFugue MusicString".
69
70\section download Download
71
72CFugue is ready to be used in your applications. It can be found at the downloads section of http://sourceforge.net/projects/cfugue/
73
74\section limitations Limitations
75
76CFugue is under active development, with much of the features, such as rendering to sheet music, etc.
77pending. By the time the development completes, we hope to have this Limitations section to be empty.
78
79\section copyright Copyright
80
81This is a product of CineFx Research Labs, made available free of charge for personal and research use.
82For commercial usage, please contact the author.
83
84CFugue is distributed with the hope that it will be useful.
85No warranty of what-so-ever is implied, including MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
104 - \ref ancCExampleSaveMIDI "Saving to MIDI file"
105 - \ref ancCExamplePlayOptions "Configuring Play Options"
106 - \ref ancCExampleParserEvents "Accessing the Parser events"
107 - \ref secCplusCplusExamples
108 - \ref ancPlay "Playing the Notes"
109 - \ref ancSaveMIDI "Saving to MIDI file"
110 - \ref ancAsynchPlay "Playing Asynchronously"
111 - \ref ancParserEvents "Accessing the Parser events"
112 - \ref secPInvokeUsage
113 - \ref subsecPInvokePlay "Playing the Notes"
114 - \ref subsecPInvokeSave "Saving to MIDI file"
115 - \ref ancPInvokeExampleParserEvents "Accessing the Parser events"
116 - \ref index "Back to main page"
117
118\section secCExamples C Examples
119\subsection ancCExamplePlay Playing the Notes
120<pre class="fragment">
121 \#include "CFugueLib.h"
122 void main()
123 {
124 CFugue::PlayMusicString("C D E F G A B"); <span class="comment">// Play the Music Notes on the default MIDI output port</span>
125 }
126</pre>
127Playing them Carnatic style:
128<pre class="fragment">
129 \#include "CFugueLib.h"
130 void main()
131 {
132 CFugue::PlayMusicString("K[MELA_DEFAULT] S R G M P D N"); <span class="comment">// Play the Music Notes on the default MIDI output port</span>
133 }
134</pre>
135
136\subsection ancCExampleSaveMIDI Saving Music Notes to MIDI output file
137<pre class="fragment">
138 \#include "CFugueLib.h"
139 void main()
140 {
141 CFugue::SaveAsMidiFile("Cq Dw Ex", "MidiOutput.midi"); <span class="comment">// Save the Music Notes to Midi file directly, without playing</span>
142 }
143</pre>
144
145\subsection ancCExamplePlayOptions Configuring the Play Options
146
147The <tt>PlayMusicString()</tt> method plays the music notes on default MIDI output port with default MIDI timer resolution. However, if you would like to configure these options, use the <tt>PlayMusicStringWithOpts()</tt> method. It works similar to the <tt>PlayMusicString()</tt> method, but directs the output based on the input options.
148
149<pre class="fragment">
150 \#include "CFugueLib.h"
151 void main()
152 {
153 CFugue::PlayMusicStringWithOpts(_T("Cq Dw Ex"), <span class="comment">// CFugue MusicString to be played</span>
428One of the capabilities of CFugue that makes it so elegant and easy to use is the concept of Music Note Strings
429(or simply <i>MusicString</i>s, as referred to by JFugue). MusicStrings provide the ability to specify
430Music Notes and MIDI instructions as a sequence of characters (and tokens) in human readable form,
431as opposed to the usual complex binary data byte form. This makes it easy to learn and master. Below is an example of a MusicString supplied to the <i>Play()</i> method to play a Mid-C note and a C-Major chord. (Please refer \ref pageExamples "CFugue API examples" for more such examples.)
432<pre class="fragment">
433 \#include "CFugueLib.h"
434 void main()
435 {
436 CFugue::Player player; <span class="comment">// Create the Player Object</span>
437 player.Play("C CMaj"); <span class="comment">// Play a Mid-C followed by C-Major Chord </span>
438 }
439</pre>
440Few more examples of MusicStrings:
441<pre class="fragment">
442 CFugue::Player player; <span class="comment">// Create the Player Object</span>
443 player.Play("I[FLUTE] FMaj"); <span class="comment">// Play the F-Major chord with Flute </span>
444 player.Play("C D E F G A B"); <span class="comment">// Play all the mid octave notes </span>
445 player.Play("K[MELA] S R G M P D N"); <span class="comment">// Play all the mid octave (madhya sthayi) notes in Carnatic Music </span>
446 player.Play("C+D+E+F+G+A+B"); <span class="comment">// Play all the mid octave notes in parallel</span>
447 player.Play("CI CI CI GI FI GI D#I. FI. G#I GI. RI"); <span class="comment">// Notes with durations</span>
448 player.Play("K[HAMSADHWANI]T8S2 ( S' GA' R' S' R' S' N PA N S' RI' RI' )"); <span class="comment">// A piece of Vatapi Ganapathim in double speed </span>
449</pre>
450In the following we discuss at length the details of what constitues a MusicString and how it can be used for creating music with CFugue.
451
452\section secMusicString Components of MusicString
453In CFugue, a valid MusicString is formed out of a series of music tokens. Tokens are nothing but sequences of alpha numeric charaters. Seperated with whitespace, each of them represents either a music note related data or a CFugue related command. The first character of a token usually determines if the token should be considered as a note token or a command token.
454
455Typical examples of note tokens are notes, chords, ties and so on, while MIDI instructions, such as instrument change, voice command etc. are few examples of CFugue related commands.
456
457When CFugue parses a MusicString, it uses the first character of the tokens to identify the notes and commands. If no decision can be made about a token, CFugue will simply ignore the token and moves on (observe that this is unlike any typical parser behavior, where an unrecognized token will halt the parsing).
458
459Below are the first characters and their associated token classifications for CFugue MusicStrings:
478Each of these will be explained in detail in later parts of this discussion. For now, when a token starts with a character that is different from all of these shown above, CFugue tries to read that token as a note token. If it succeeds in that, it will generate note events for further processing. And if it fails, it will ignore the token and moves on.
479
480CFugue MusicStrings are case-insensitive. That is, the characters can be used in any case, either upper or lower, while creating the MusicStrings. CFugue will internally convert all the supplied MusicStrings to upper case before processing them. Use this fact to your advantage by mixing the case for your MusicString tokens and making them more readable and easy to understand. Examples of few valid MusicStrings that showcase this advantage are:
487 player.Play("I[XyloPhone] K[Mela_29] S R G M P D N S'");
488</pre>
489
490\subsection subsecNotes Specifying Notes
491Specifying music notes in CFugue MusicStrings is simple and straight forward. Just indicate the root of the note followed by its optional attributes, such as octave, duration, any additional connectors etc. and you are done. Thus the structure of a valid note token is:
498Except for the Root, all others in the above are optional. And when they are present, they have to be in the order specified above. Changing the order will cause incorrect results.
499
500\subsubsection subsubRoot Root
501The root is specified either by a note name or by its MIDI numeric value. Alphabets such as C, D, E .. indicate the names for the Western style and S, R, G .. indicate the names for the Carnatic style. The complete list is as shown below for the two systems:
520In addition, CFugue allows <i>#</i> and <i>b</i> modifiers for the Western style of notes to access one halfstep up or down the given note. Thus, one can use <i>D#</i> to indicate the note <i>Eb</i>, <i>Fb</i> to indicate the note <i>E</i> and so on. Repeating a modifier more than once is also supported. For example, <i>C##</i> signifies <i>D</i> and <i>Bbb</i> signifies <i>A</i>. However, it is advised to refrain from mixing <i>#</i> and <i>b</i> in the same token. For example, do not try something like <i>C\#b</i> to get back to <i>C</i>. Though CFugue understands such notation correctly, it is not always guaranteed to work.
521
522Similarily, for Carnatic music, CFugue allows <i>R3</i>, <i>G1</i>, <i>D3</i> and <i>N1</i> Swaras, which essentially are the same as <i>G2</i>, <i>R2</i>, <i>N2</i> and <i>D2</i> from the above, respectively.
523
524\note Before we can pass any Carnatic music notes to CFugue for parsing, it need to be informed that we are indeed passing Carnatic style of notes and not Western style of notes. That is, we need to tell CFugue to use Carnatic note parser and not the default Western note parser for the notes we are about to supply. We do this by using the \ref subKeySignatures "Key Signature" directive as shown below:
525<pre class="fragment">
526 <span class="comment">// Switch to Carnatic mode and play some notes</span>
527 player.Play("K[MELA] S R G M P D N");
528</pre> The K[MELA] directive informs the parser to switch to Carnatic mode of parsing and to interpret the subsequent notes in that mode. For further discussion on this, please refer \ref secInteroperation.
529
530Music notes can also be specified using their MIDI numeric value directly. Usually, when a note is specified using its name, such as C, D, E .. or S, R, G.., it is treated as a relative note. Its absolute position will be internally re-computed based on the Octave specifiers and the Scale/Raga settings. On the otherhand, when a note is specified with its MIDI numeric value directly, it is treated as an absolute note and will not be affected by the current Scale or Octave settings. An example of such numeric note is:
531<pre class="fragment">
532 <span class="comment">// Play a Mid-C </span>
533 player.Play("[60]");
534</pre>
535Observe that we need to enclose the numeric value in square brackets []. Failing to do so might result in CFugue ignoring the token. Below is the complete listing of MIDI numeric values for all the notes.
692Be informed that when you specify a note using its MIDI numeric value, you cannot use the Octave field in the token anymore. Octave fields are only applicable for notes specified using their names.
693
694\subsubsection subsubOctave Octave
695For Western music, CFugue supports octaves in the range [0, 10]. You can specify an octave for a non-numeric note by appending the octave number to it, such as <i>C2</i> to signify C note in 2nd octave or <i>Bb8</i> to signify B-flat note in 8th octave. Observe that CFugue starts the octave numbering at 0 (instead of -1 used by some other representations). Middle-C in CFugue is C5, which is MIDI note value 60.
696
697Octaves are optional. If you do not specify any octave value for a note, a default value of Octave 5 will be used for that note (unless it is a chord note, in which case a default value of 3 will be used).
698
699For Carnatic music, there is no concept of absolute octaves. Instead it supports the concept of <i>Sthayis</i>, which is a relative value that changes from instrument to instrument and from person to person. Typically each singer will be having his/her own base <i>Sthayi</i>, which is usually referred to as medium sthayi, and varies above and below it, leading to upper sthayi notes and lower sthayi notes.
700
701In CFugue's Carnatic music notation, a plain note indicates a medium sthayi note. One can append the character <i>'</i> to get an upper sthayi note of it, and the character <i>.</i> to get a lower sthayi note of it. For example, <i>S'</i> is the upper sthayi note of the medium note <i>S</i>, with <i>S.</i> being its lower sthayi correspondent.
702
703Multiple <i>'</i> and <i>.</i> can be appended to a note to get more upper and lower sthayis, such as <i>P'''</i> or <i>D...</i>. However, do not mix <i>'</i> and <i>.</i> in a single token. For example, usage such as <i>S'.</i> is not valid. <i>S'.</i> is not same as <i>S</i> in CFugue.
704
705Below are few valid examples of notes with Octaves and Sthayis.
706<pre class="fragment">
707 player.Play(" C4 D4 E4 F4 G4 A4 B4 C D E F G A B C6 C#6 E6 F#6 G6 Ab6 B6 ");
708 player.Play(" S. R. G. M. P. D. N. S R G M P D N S' R1' G' M2' P' D1' N' ");
709</pre>
710For compatibility between Western and Carnatic music, CFugue defines the default medium sthayi as Octave 5. Thus, both of the above two lines produce the same results. For further details on how to interoperate between Western and Carnatic style of music, refer \ref secInteroperation.
759In the above haflstep intervals, zero indicates the root note. Other values are relative haflstep values from it, which will be adjusted based on the root note.
760
761To specify a chord in CFugue, specify the root and append it with the chord name from the above table. For example, <tt>CMAJ</tt> signifies the C-major chord, which, based on the above halfstep intervals {0, 4, 7}, will automatically expand to <tt>C+E+G</tt> notes (C=0, E=4, G=7).
762
763The default octave for the chord notes is 3. To specify an explicit octave value for a chord, append the chord root with the octave number. For example, a B-Flat, 7th Octave, major chord will be <tt>Bb7Maj</tt>.
767A chord inversion indicates a different way of playing a chord. The degree of inversion indicates how many notes in the chord that need be shifted in the octave. A first degree inversion indicates that one note (the root note) should be moved up an octave, while the second degree inversion indicates that two notes (the root note and the second note) should be moved to one octave heigherr. When the note is moved up an octave heigher, the remaining notes in the chord become the new bass notes. Typically a chord with <i>n</i> number of notes can have atmost <i>n</i> degree inversions.
768
769The character <tt>^</tt> indicates an inversion in CFugue. There are two ways to use it. The first is to specify <tt>^</tt> as many times as the degree of inversion after the chord name, and the second is to specify <tt>^</tt> after the chord name followed by the new bass note. For example, <tt>Cmaj^^</tt> and <tt>Cmaj^G</tt> are two ways of indicating the same: a second degree inversion for C-Major chord (that makes the <tt>G</tt> as the new bass note).
770
771
772\subsubsection subsubDuration Duration
773Duration in Western music indicates how long a note should be played. CFugue supports below durations for the Western music notes.
789These characters can be combined to form any aribtrary lengths of durations as required. For example, the token <tt>Bb6www</tt> indicates a B-Flat note in 6th octave for a duration of three whole notes, and the token <tt>F\#MajH</tt> indicates an F-sharp Major chord for a duration of half-note.
790
791CFugue also supports dotted durations. For example, a dotted quarter note would be a <tt>q</tt> followed by a dot (<tt>q.</tt>). Dotted durations indicate an addendum of extra half to the original duration. Thus a dotted quarter note = quarter note + 1/8th note;
792
793Further, CFugue supports numeric durations also. Use the slash character followed by the decimal portion of whole note to indicate a numeric duration. For example, the token <tt>F#8/0.25</tt> signifies an F-sharp note in eight octave for a duration of quarter note (<tt>0.25</tt> is the quarter note portion of whole note). Similarily <tt>0.5</tt> signifies half-note and <tt>1.0</tt> signifies a while note. Values greater than <tt>1.0</tt> indicate a note that spans multiple measures. For example, the <tt>Bb6www</tt> token discussed above can be represeted numerically as <tt>Bb6/3.0</tt>.
794
795Below are few valid examples of duration specification:
796<pre class="fragment">
797 player.Play("Gh"); <span class="comment">// G note in default octave for a half-note duration </span>
798 player.Play("[65]wq"); <span class="comment">// Middle-F (F5) for a whote+quarter note duration </span>
801For Western music, if no duration is specified, a default duration of quarter note is assumed.
802
803In Carnatic music, durations for the notes are determined automatically based on the <i>Talam</i>. A <i>Talam</i> specifies the duration for a group of notes instead of an individual note. CFugue supports below Talams.
804
805\subsubsection subsubVelocity Velocity
806CFugue supports attack and decay velocities for notes. These values indicate how a note should be played in terms of its "take off" and "landing" volumes. For example, a note with long attack will sound like being built over a period of time, while a note with long decay sounds like a bell or a string that continues to resonate long after it has been struck.
807
808In CFugue, attack and decay velocities can be specified using a pair of <tt>V</tt> followed by a numeric value in the range [0, 127] duo. The first <tt>V</tt> number pair stands for attack velocity, followed by the optional second <tt>V</tt> number pair that stand for decay velocity. Both are optional and are independent of each other. Low numeric values indicate quicker attack (or decay), while high values signify longer attack (or decay). And the default value, if unspecified, is 64. Below are few examples of valid usage:
809<pre class="fragment">
810 player.Play("C6V2V124"); <span class="comment">// C6 note with sharp attack 2 and longer decay 124. The first V stands for attack, second V for decay. </span>
811 player.Play("Bb3qhVV3"); <span class="comment">// B-Flat 3rd octave quarter+half duration with default Attack and sharp decay 3. First V value left unspecified, so attack takes default value </span>
812 player.Play("Bb3qhV1"); <span class="comment">// B-Flat 3rd octave quarter+half duration with sharp Attack 1 and default decay. Second V left unspecified, so decay takes default value</span>
813 player.Play("Bb3qh"); <span class="comment">// B-Flat 3rd octave quarter+half duration with default Attack and default decay - No V at all, so both attack and decay take default values</span>
814</pre>
815
816\subsubsection subsubConnectors Connectors
817
818\subsection subRestNotes Specifying Rests
819Apart from the regular notes, CFugue also supports <i>Rest</i> notes. Rest notes are nothing but periods of silence. Their use is similar to that of sounded notes, except that Rest notes do not support anything other than a Duration. That is, Rest notes do not have Octaves or Velocities or Connectors. And the durations specifications for Rest notes are same as that of the usual notes. Refer to \ref subsubDuration for details on durations.
820
821Use the symbol <i>R</i> to specify a Rest note in Western music. The usual duration specificiers can be appended as usual. Below are few examples:
822<pre class="fragment">
823 player.Play("R"); <span class="comment">// Rest note for the detault duration</span>
824 player.Play("Rw"); <span class="comment">// Rest note for a whole duration</span>
825</pre>
826Obviously, you would not be listening any sound being output when you run the above lines of code. Rest notes are designed to be used in conjunct with other regular notes. Usually it is rare that you would want to program MusicStrings made of only rest notes. Place them amidst of regular music notes to actually listen them, such as shown in the below example.
827<pre class="fragment">
828 player.Play("Cw Rh Dw"); <span class="comment">// Can you "listen" the Rest note ?</span>
829</pre>
830For Carnatic music, the symbols <tt>,</tt> and <tt>;</tt> signify the Rest notes. The durations are based on the currently selected Talam. The <tt>,</tt> specifies a Rest note for one duration, while the <tt>;</tt> specifies a Rest note for two durations.
831
832These <tt>,</tt> and <tt>;</tt> can also be used in Western music notation, in which case they both act as the default Rest note with no explicit duration. For more details on mixing the Western and Carnatic music notations, please refer \ref secInteroperation.
835Instrument tokens in MusicStrings indicates which instrument should be used to play the subsequent notes in the strings. In CFugue, instrument tokens are identified with character <b>I</b> at their beginning. Below are few examples of valid instrument tokens:
836<pre class="fragment">
837 player.Play("I[PIANO]");
838 player.Play("I10");
839 player.Play("I[RAIN]");
840</pre>
841Ofcourse, the above does not produce any music output since there are no notes specified in the input. Usually one supplies a series of note tokens after an instrument token for generting music using the specified instrument. Examples are as shown below:
842<pre class="fragment">
843 player.Play("I[Piano] C D E F G A B"); <span class="comment">// Play an Octave using Piano instrument </span>
844 player.Play("I0 C D E I40 F G A B"); <span class="comment">// I0 is Piano and I40 is Violin</span>
845 player.Play("I[Flute] K[Kalyani] S R G M P D N"); <span class="comment">// Play an Octave in Kalyani Ragam with Flute</span>
846</pre>
847
848Complete list of intruments supported by CFugue is as shown below. In the MusicStrings these instruments can be specified either by their name or their MIDI instrument number indicated.
1025KeySignature specification is one of the powerful features of CFugue MusicStrings that makes it easy to write music notes and keep them simple and clean. A KeySignature essentially indicates how CFugue should interpret the notes it encouters during the MusicString parsing.
1026
1027In CFugue, KeySignature tokens are identified with character <b>K</b> at their beginning. Below are few examples of valid KeySignature tokens:
1028<pre class="fragment">
1029 player.Play("K[CMAJ]");
1030 player.Play("K[F#MAJ]");
1031 player.Play("K[KANAKANGI]");
1032</pre>
1033Ofcourse, the above does not produce any music output since there are no notes specified in the input. Usually one supplies a series of note tokens after a KeySignature token for generting music as per the supplied Key. Examples are as shown below:
1034<pre class="fragment">
1035 player.Play("K[CMaj] C D E F G A B"); <span class="comment">// Play an Octave in CMajor Scale </span>
1036 player.Play("K[FMaj] C D E F G A B"); <span class="comment">// Play an Octave in FMajor Scale </span>
1037 player.Play("K[Kalyani] S R G M P D N"); <span class="comment">// Play an Octave in Kalyani Ragam</span>
1038 player.Play("K[Kanakangi] S R G M P D N"); <span class="comment">// Play an Octave in Kanakangi Ragam</span>
1039</pre>
1040
1041When a note is specified using its name, CFugue considers it as a relative half-step value within an octave. The KeySignature directive helps CFugue compute the absolute MIDI numeric value of the note based on the selected Scale/Ragam value. When one specifies tokens such as K[CMaj] or K[Kalyani] in the MusicStrings, CFugue starts interpreting the named notes C, D, E.. S, R, G.. according to their values in CMajor Scale or Kalyani Raga.
1042
1043For example, in the above, when K[FMaj] is specified, the B note in the octave will be treated as B<i>b</i> automatically. Similarily, for K[Kalyani], the M note will be treated as M2 automatically.
1044
1045When no KeySignature is specified, CFugue assumes these default Values: K[CMaj] for Western and K[Shankarabharanam] for Carnatic.
1046
1047When a KeySignature is specified, it will be applied for all subsequent notes. However, if you do not want the KeySignature to be applied to any specific note, you have to either use the MIDI numeric value directly or use the note modifier <i>n</i> to declare it as a natural note. (Note modifiers are not applicable for Carnatic music. You have to explicitly specify the complete name, such as R1, R2 etc. to make it a natural note.) Natural notes are not affected by KeySignature. By definition, all MIDI numeric notes are natural notes. Thus, the below all five produce the same result.
1048<pre class="fragment">
1049 player.Play("K[CMaj] C D E F G A B"); <span class="comment">// Play an Octave in CMajor Scale </span>
1050 player.Play("K[FMaj] C D E F G A Bn"); <span class="comment">// B is declared as natural. FMaj is ignored for B</span>
1051 player.Play("K[Shankarabharanam] S R G M P D N"); <span class="comment">// Play an Octave in Shankarabharanam Ragam</span>
1052 player.Play("K[Kalyani] S R G M1 P D N"); <span class="comment">// M1 declared explicitly. Kalyani is ignored for M</span>
1053 player.Play("K[FMaj] C D E F G A [71]"); <span class="comment">// [71] is numeric note. FMaj is ignored for it</span>
1054</pre>
1055 KeySignatures are applicable for the whole song, independent of tracks. They can be redefined as many times as one wants throughout the song. CFugue will use the latest definition that precedes a note to process the note.
1056
1057 KeySignatures support both Carnatic and Western music modes. In Western mode, a total of 15 KeySignatures are present. These are accessible through their names, such as CMAJ, DMAJ, F\#MIN etc. Complete list of the names is given in the \ref KeySignatureTable "KeySignatures table".
1058
1059 In Carnatic mode, all the basic 72 KeySignatures, known as Melakartha Janya Ragas, are supported. These are accessible through MELA_x macro, where x specifies a number in the range [1, 72]. In addition, for convenience, MELA_0 and MELA_DEFAULT are available, that map to Melakartha 29 (Shankarabharanam). Further, numerous ragas are accessible directly through their names, such as KALYANI, MOHANA etc. Thus one can either use the MELA_x macro or the raga name for the KeySignature. For example, K[Mela_65] and K[Kalyani] both give same results. Refer to the below listing for complete set of mappings between raga names and their associated Melakartha janyas. Note that when using an incomplete raga (one that does not use all the seven swaras), the missing notes in the raga will default to their corresponding values in the Melakartha janya of the raga.
1060
1061 \anchor KeySignatureTable \htmlonly
1062 <table align="center" border="1">
1063 <caption ALIGN=bottom><br/>KeySignatures supported by CFugue</caption>
1210For CFugue, Western is the default mode, and CMajor is the default KeySignature. All Parsers start in Western mode with CMajor scale set to their default. If you rather want the Parser to use a Carnatic mode, then you should explicitly supply a KeySignature token with an appropriate value before passing on any Carnatic music notes.
1211
1212For further details on how to interoperate between Western and Carnatic style of music, refer \ref secInteroperation.
1215Channels / Tracks are referred to as <i>voices</i> in CFugue. The tokens that start with character <b>V</b> are considered as voice tokens.
1216
1217CFugue supports all the 16 channels of MIDI, which are accessible through V0 to 15. Whenever CFugue encounters a voice token in the MusicString, it changes the current track to the specified one in the token, inserting all the subsequent notes into this newly set track. When you want to switch back to your old track to insert notes into it, you simply supply another voice token with the corresponding track number.
1218
1219By default, <i>V0</i> is implied at the beginning.
1220
1221Be noted that channels/tracks/voices play in parallel. For example, the MusicString <tt>CMAJ V1 CMIN</tt> plays CMAJ chord on channel 0 in <i>parallel</i> with CMIN chord on channel 1. Just because <tt>V1 CMIN</tt> comes <i>after</i> CMAJ in the Music String does not make it wait till CMAJ completes playing. Channels play independent of each other and certain MIDI players allow you to turn off selective tracks, so that you can listen only few tracks of your choice.
1222
1223In CFugue, if you would like to sync the channels, you have to use the Rest notes. For example, to make CMIN chord on channel 1 play <i>after</i> the CMAJ chord completes playing on channel 0, you need to insert a Rest note with sufficient duration on channel 1, something like <tt>CMAJ V1 R CMIN</tt>. This makes the Rest note play in parallel with CMAJ, effectively making CMIN play after CMAJ is completed.
1224
1225\section secInteroperation Interoperating Western and Carnatic Music
1226A powerful feature of CFugue's MusicString is its ability to work with both Western and Carnatic music with same ease. For the first time in the music world, it is now not only possible to specify
1227Carnatic music Swaras side by side with Western Notes, it is also possible to transform between
1228the two notations with same ease.
1229
1230\note In addition, the same principles can be adapted for Hindustani music also to make it work side by side with Western music.
1231
1232By default CFugue starts parsing the notes in Western mode. However, when it encounters the K[] signature token with Carnatic music mela as key, it switches to Carnatic music parsing mode.