The purpose of the Musika programming language is to provide a quick and easy way of writing music ideas and listening to them. Musika takes a file containing Musika code in the form of text (".ka" file extension) and uses a 2-step conversion process to turn code into an audible sound file (".wav"), playable in any audio player that accepts ".wav".
The following indicate the key features of the Musika programming language:
Use "compiler.exe" in a command line in order to use the compiler by itself. The binary receives 1 or 2 arguments
Be sure to specify the file extension in the file argument! This will be the file to compile. If the file is of extension ".ka", the binary will convert the text in that file into a note sheet binary. This binary will be stored in the same directory with the same file name and a ".mkc" file extension. All files specified as arguments are assumed to be in the same directory.
If a note sheet is passed in as an argument (".mkc" file extension), the compiler binary will convert that note sheet into an audible ".wav" file. It will store this file in the same directory with the same name and an extension of ".wav". This wav file can be played in any ".wav" audio player.
The "-d" flag can be added before or after the file argument. This can only be used for ".ka" files. If this flag is set, the specified file will first be converted into a ".mkc" note sheet binary, and that binary will then immediately be converted into an audible ".wav" file (both files will be available after the operation). This essentially combines the two compilation steps into one.
Single-line comments are specified with an & and multi-line comments begin with a => and end with <=
& This is a single-line comment! & ... Code before multi-line comment ... => Everything between the arrows is part of the multi-line comment! <= & ... Code after multi-line comment ...
These comments are ignored by the compiler, so you can add them for specification/clarification within your Musika code anywhere you like!
Every Musika file is divided into 4 sections:
Each of these sections are separated by three dashes (---) on a new line. The accompaniment section is optional, but the other three are required.
The following is an example of an accompaniment (another Musika file):
accompany [musika_file] name new_accompaniment
You specify a Musika file within your directory (or as a part of the Musika library) solely by the name and/or relative path (NO FILE EXTENSION).
To accompany any created Musika files, specify the filename/relative path in between brackets ([]). Note that relative paths can only go forward, not backward (e.g. [dir1/file] is okay, but [../file] is NOT accepted).
To accompany a file from Musika's standard library, specify the standard library name in between brackets AND underscores (e.g. [_filename_]). This means that any custom Musika files which begin AND end in underscores cannot be accompanied in other files, as they will be mistaken for standard library files.
This statement will import the specified Musika file and it can be referenced later in the file using the name specified after the name keyword.
Each accompaniment specification must be specified on its own line. After that, place three dashes (---) at the bottom line to enter the info section:
accompany [file1] name one accompany [file2] name two --- title: "Song Title" author: "Song Author" coauthors: "Song coauthors" key: Cmaj & The info section is here time: 4 / 4 tempo: 4 = 60 octave: 4 ---
Note the bottom three dashes used to enter the patterns section afterwards.
The following are specified in the info section:
The title of the song/piece. This is specified by either a literal string:
title: "Song Title"
Or by a reference from an accompaniment:
title: accompaniment_ref_Name
The title has no effect on the output of a song.
Name of the author of the song. This is specified by either a literal string:
author: "Song Author"
Or by a reference from an accompaniment:
author: accompaniment_ref_Name
The author has no effect on the output of a song.
This is an optional section that specifies any extra authors of the piece. This is specified by either a literal string:
coauthors: "Author 1, Author 2, Author 3"
Or by a reference from an accompaniment:
coauthors: accompaniment_ref_Name
Note that each coauthor is separated by a space and a comma (", "). If the coauthors are not listed this way, the names of each coauthor may be split or conjoined in an undesired fashion. The coauthors have no effect on the output of a song.
Key signature of the song/piece. This is specified by either a key signature keyword:
key: Cmaj
Or by a reference from an accompaniment:
key: accompaniment_ref_Name
Supported key signatures:
The time signature of the piece. This is specified literally:
time: 6 / 8
Using common (4/4) or cut (2/2) as a shorthand:
time: common
Or by a reference from an accompaniment:
time: accompaniment_ref_Name
If specified literally, the first number specifies the beats per measure and the second number is the base beat. So 6 / 8 means that there are 6 8th notes per measure and 4 / 4 specifies that there are 4 quarter notes per measure. Because Musika does not specify time signatures, the top number of the time signature has no effect on the output of the song. It should be used solely to inform other users of the number of beats per measure. The bottom number does have an effect on the output of the song, as it changes the base beat of the song, affecting the type of note each "dot" represents. More on that later.
The tempo of the piece. This is specified literally:
tempo: 4 = 144
Or by a reference from an accompaniment:
tempo: accompaniment_ref_Name
If specified literally, the first number specifies the base beat and the second number specifies the base beats per minute. So 4 = 144 means that there are 144 quarter notes per minute, and 2 = 60 means that there are 60 half notes per minute.
The base octave This is specified literally:
octave: 4
Or by a reference from an accompaniment:
octave: accompaniment_ref_Name
If specified literally, this is the default octave for each note specified in patterns and in the main music sheet. Knowing this, be careful with the octaves of each written note. C is the lowest note in all octaves; therefore, all notes specified in the piece will be higher in pitch than the C of the same octave by default.
This means that an A minor scale
& octave: 4 A. B. C. D. E. F. G. A.
Will not continuously increase in pitch because the C will be lower than the B and A before it. The octave must be set to 1 higher than the base from the C on:
& octave: 4 A. B. ! octave: 5 ! C. D. E. F. G. A.
or
& octave: 4 A. B. C'. D'. E'. F'. G'. A'.
Octave values are supported from 0 to 8 inclusive.
Details on note specification later
The pattern section comes directly after the info section. It allows you to write named repeatable patterns that can be referenced in the music section. Patterns are analogous to functions in normal programming (however, there are no parameters in patterns).
The pattern section also allows you to define chords, which are groups of notes played at the same time. The chords you define in the pattern section (or that are defined in an accompanied file) can be used in the music section.
This is the basic anatomy of a pattern definition:
pattern [pattern_name]:
...Music code...
The code that goes into a pattern is written exactly the same way as the music section, which is discussed later.
The pattern naming convention is the same as the accompaniment naming convention.
You can define as many patterns as you like. However, in order for one pattern to reference another, it must be defined first. For example:
...Accompaniment Section...
---
...Info Section...
---
pattern [p2]:
...Music Code...
p1
pattern [p1]:
...Music Code...
---
...Music Section...
---
This code will result in a contextual error because the p1 pattern is called before it is defined. Musika reads and compiles patterns one at a time in the order they were specified. Therefore, in order to reference a pattern, it must have been fully defined first.
Switching the definition order will result in the code successfully compiling.
...Accompaniment Section...
---
...Info Section...
---
pattern [p1]:
...Music Code...
pattern [p2]:
...Music Code...
p1
---
...Music Section...
---
Because accompaniments are always defined before patterns, any pattern stored in an accompanied file can be referenced from any pattern in the current file.
A chord is defined in the pattern section in the following way:
chord chord_name is A;B'';C,
Note that the chord body consists of individual notes followed by an optional set of , or '.
Each note by default is set to the octave specified in the info section. However, you can change each note's octave using , and '.
Every , represents 1 octave lower than the base octave.
Every ' represents 1 octave higher than the base octave.
The note F''' will be 3 octaves higher than the base.
The note G,, will be 2 octaves lower than the base.
The note C','',',,,' will be the same octave as the base. This is because there is one ' for each ,. These all cancel each other out. If there were one more ', then the note would be 1 octave higher than the base.
Each individual note in the chord is separated by a semicolon (;).
The music section is the heart of a Musika program, and is also the most complex.
For each accompanied file, the music section can be considered its own pattern that can be referenced.
For the main file, the notes generated will come from the music section of that file.
The contents of a pattern definition follows the same anatomy as the music section.
The simplest music section is a blank line:
...Accompaniment Section... --- ...Info Section... --- ...Pattern Section... --- & There is nothing here but a comment (no comment required) ---
All accompaniments, info, patterns, and chords will be saved, but no notes will be generated to play. This can be done for files that are made solely to contain a library of patterns and chords (files that are always meant to be accompaniments). However, files with no music in the music section cannot be converted into ".wav" files.
The music section is just a set of music elements. These music elements make up the actual notes of the song.
There are 2 types of music elements:
functions are built-in Musika commands that accept a piece of music as input and manipulate the music as output. Sometimes literal music can be passed in and sometimes it must be in the form of a pattern.
Currently, there are 2 Musika functions:
repeat can be used in the following form:
repeat(4) {
pattern_in_repeat
}
Everything inside of the braces ({}) is another section of music (much like a pattern).
The number within the parenthesis can be any integer. It represents the number of times you would like to repeat the section of music within the braces.
In the example above, the music contained in the pattern_in_repeat section will be repeated back-to-back 4 times.
layer can be used in the following form:
layer(pattern_in_layer)
The layer function requires its argument to be in pattern form (not a chord). It can also be the main music of an accompanied section.
The pattern passed in layer function will be played over the music that comes after it. This means that it will be played at the same time.
A useful way to think about this is that if you wanted a harmony to be played (for example, a G major scale and an E minor scale played together in harmony), you could define the E minor scale in a pattern and then call the pattern:
...Info Section...
---
pattern [e_minor]:
...Music Code...
---
part_1
layer(e_minor)
...G Major Scale Code...
---
This code will play the harmony.
Remember, position is important. If the layer reference were called after the G Major Scale Code, then the E minor pattern will not be played until after the G Major Scale Code is completed. In this case, you would get one after the other instead of the harmony played together.
In the below example:
accompany [file] name acc
---
...Info Section...
---
pattern [part_1]:
...Music Code...
---
part_1
layer(acc)
...Rest of Music Section...
---
The main music of the acc file will play on top of the rest of the music in the music section immediately after all of the music in part_1 is played. If the layer were written before the part_1 call, it would be played over part_1 music.
Much like music is made up of music elements, a riff is made up of riff elements.
A riff element can be any of the following:
A note represents a frequency value. This table was used to determine the frequencies of each note. A note is any of the following letters: A, B, C, D, E, F, G.
A note can contain an accidental: A# (A sharp), Bb (B flat), C* (C double sharp), Dbb (D double flat), E$ (E natural).
A note can also be assumed to be sharp or flat by default based on the current key signature. For example, if the key signature is Emaj, then both D and D# will play the same note. However, in Em, D will play a D natural while a D# will play a D sharp.
The accidentals add "rigidity" to your notes (i.e. make them independent of key signature). For example, to get a D natural in a key with a D sharp, an accidental must be set (D$ will always play a D natural regardless of the key signature, whereas a D will give you a D, D#, or Db depending on the key).
A note's octave can be changed much like in a chord (see chord definition) where the , lowers the note from the base octave by 1 and the ' raises the note from the base octave by 1. For example, G''',',,,, is 1 octave lower than the base. With no , or ', the note will play at the base octave by default.
A note must also be followed by a series of dots (.). The dots represent the number of base beats to play the note. In 4 / 4 time, each dot represents a quarter note; in 2 / 2 time, each dot represents a half note; and in 6 / 8 time, each dot represents an eight note.
If the time is set to common, (4/4) time, then A... will be played for 3 quarter notes long. If the time is set to 8 / 8, then that same note specification will be played for 3 eighth notes instead of quarter notes. Each dot represents one base beat of the song. You can change the base beat of the song as much as desired to get the proper subdivision whenever necessary; more on that later.
A callback is a reference to a local pattern or chord (within the file), a pattern or chord from an accompaniment file, or the main music from an accompaniment file.
A callback to a local pattern, local chord, or accompaniment main music is simply the name of the pattern, chord, or accompaniment name respectively. To access a specific pattern or chord from an accompanied file, use the > operator. Examples are shown here:
accompany [song] name song
...more accompaniments if desired...
---
...Info Section...
---
chord chord_name is A;B'';C,
pattern [p1]:
...Music Code...
---
p1
chord_name....
song
song>riff
song>song_chord....
---
In this example, the main music section is first calling back the p1 pattern. Therefore, the music section of the p1 pattern will be played.
Next, the chord_name chord is called back, so it will be played next. Unlike a pattern or accompaniment main music section, a chord does not have a set length. Therefore, just like a note, a set of dots must follow the chord callback to specify the number of main beats the chord should be played for.
After that, the "song" accompaniment was referenced directly. Therefore, the main music specified in the "song.ka" file will be played. Then the song's "riff" pattern is referenced using the > operator. This indicates that you are playing the "riff" pattern from the "song" accompaniment. Finally, the song's "songchord" chord is referenced using the >_ operator. This indicates that you are playing the "song_chord" chord coming from the "song" accompaniment. Just like local chords, you must specify the length of the chord with dots.
In the above example, if the time is set to cut, then the chord_name chord will be played for 4 half notes.
The caret (^) is a shorthand repeat symbol. It cannot be the first riff element of any music section (including patterns). The caret is followed by an integer, and it repeats the most recently played note that number of times.
For example:
& the time was set to common A. ^ 4 E.... d_minor_chord.. ^ 2 pattern_call ^ 3
This code will play the A note 1 quarter note long 4 times. After that, it will play an E note 4 quarter notes long. Then it will play the d_minor_chord chord for 2 quarter notes long 2 times. Finally, it will play the last note in the pattern_call pattern however long it played last 2 additional times (3 times total).
You can see why the caret cannot begin a section. It must have a note or chord to repeat, which is set to the last note to play before the caret appears.
Also note that the spacing is optional, all examples in this document represent the conventions. However, the following section...
& the time was set to common
A.
^ 4
E....
d_minor_chord..^2
... or any other spacing format is valid.
Within a riff, you can change the base music information that was specified in the info section.
To do this, begin with a bang symbol (!). Then enter the name of the info to change followed by a colon (:):
Note that the title, author, and coauthors cannot be changed in the middle of the music section like this.
And then make your change
Changing the key signature works the same way as setting it in the first place:
! key: Gm !
This will change the key signature from its current key to G minor for all music code below the change. If the key is the same, this statement will do nothing.
Changing the time signature can be done just like setting it in the first place:
! time: common !
This will change the time signature from the current one to common time. If the base beat does not change, this statement will do nothing.
On top of this, the base beat can be changed directly inputting a single positive number:
! time: 8 !
If the original time signature was common, then the above statement will set the base beat to the eighth note while automatically adjusting the beats per measure to keep the same relative time signature. In this case, it will convert 4 / 4 to 8 / 8. This means that all of the "dots" above this change will still be quarter notes, because the original time signature was common. After ! time: 8 !, each dot will now represent an eight note. This is how subdivisions can change as necessary.
Keep in mind that the base beat value is a subdivision of a whole note. In other words, a base beat value of 1 represents 1 / 1 whole notes (i.e. a whole note); a base beat value of 4 represents 1 / 4 of a whole note (i.e. a quarter note); a base beat value of 3 represents 1 / 3 of a whole note (i.e. a whole note triplet). In order to determine the proper base beat value, think of the number of beats that go into a whole note. For example, to get quarter note triplets, know that a quarter note triplet is one third of a quarter note, and there are 4 quarter notes in a whole note. Therefore, the number of quarter note triplets in a whole note is 3 triplets per quarter note * 4 quarter notes per whole note = 12 quarter note triplets per whole note. This means that setting time: 12 will yield quarter note triplets.
Changing the tempo can be done just like setting it in the first place:
! tempo: 2 = 66 !
This will change the tempo from the current one to the tempo of half note equals 66 beats per measure. If the tempo is the same, this statement will do nothing.
On top of this, the tempo can be changed relatively to the original tempo by inputting a single integer:
! tempo: 3 !
This statement will make the current tempo 3 times slower than the original tempo. If the number were negative (e.g. -3), then the statement will make the current tempo 3 times faster than the original tempo.
Changing the octave can be done just like setting it in the first place:
! octave: 4 !
This will change the octave from the current one to 4.
On top of this, the octave can be changed relative to the original octave by inputting a single integer with a preceding sign:
! octave: -1 !
This statement will decrement the current octave by 1. Setting it to +1 will increase the current octave by 1.
As stated previously, accompaniments can be custom files, or standard library imports. To make a standard library import, the accompaniment name must be in between _underscores_. The following files are supported for the Musika standard library:
accompany [_scale_] name scale --- title: scale & You can put your own title, author, and other metadata in here instead of referencing the library for that information, author: scale & but keep in mind that the core metadata that plays the notes (key signature, time, tempo, and octave) will not affect the output of the actual pattern. coauthors: scale key: scale time: scale tempo: scale octave: scale ---
note that "scale" does not have to the be the name of the accompaniment; this is an example of a name
This library only contains the C major scale. Use it as a pattern if you want to!
accompany [_doublestops_] name ds
note that "ds" does not have to the be the name of the accompaniment; this is an example of a name
This file contains typical double stops formed as Musika chords. It supports the following base notes from the Circle of Fifths:
The following types of double stops are supported for each of these notes:
To specify an octave, use an underscore and an octave value (supported 0 - 8). Keep in mind that 8 is the highest octave supported in the language, so if a doublestop requires an octave value higher than 8, it is not supported. For example, C major 8 at octave 8 is NOT supported because it requires C9, which is not a supported frequency.
Examples:
_Note: Ab and G# are paired together. Ab double stops are supported for major intervals and G# is supported for minor intervals. For example, AbM6_5 is supported but Abm6_5 is not supported. Conversely, Gsm7_4 is supported by GsM74 is not supported. Perfect, octave, and triad intervals are supported for both notes.
accompany [_powerchords_] name pc
note that "pc" does not have to the be the name of the accompaniment; this is an example of a name
This file contains "power chords" in the form of Musika chords. "Power chords" for the sake of this library is defined as the root note, perfect 5th, and octave (e.g. C 4 power chord is C4, G4, C5). It supports the following base notes from the Circle of Fifths:
Examples:
accompany [_c_chords_] name c accompany [_gsab_chords_] name gsab accompany [_bb_chords_] name bb accompany [_a_chords_] name a
note that each of the names do not have to the be the names of the accompaniments; these are examples of names
These library files are used to add more complex chords to the song.
Supported files:
The following chord types are supported for each of these files:
Note that G# and Ab chords are in the same file.
Add octave modifiers (this is required) to specify the base octave of each chord with an underscore (_) and an octave number.
The following examples comply with this accompaniment section:
accompany [_c_chords_] name c accompany [_cs_chords_] name cs accompany [_d_chords_] name d accompany [_eb_chords_] name eb accompany [_e_chords_] name e accompany [_f_chords_] name f accompany [_fs_chords_] name fs accompany [_g_chords_] name g accompany [_gsab_chords_] name gsab accompany [_a_chords_] name a accompany [_bb_chords_] name bb accompany [_b_chords_] name b
Examples:
ALL Musika files must end in a newline character!
There you have it! A Musika program is simply a collection of these components. Below are some sample programs so you can see collections of the components put together.
title: "Example 1"
author: "Musika"
key: Cmaj
time: common
tempo: 4 = 144
octave: 4
---
& Simple song: no patterns needed!
---
! time: 8 !
repeat(2) {
C. E. G. C'. G. E. C. G,.
}
! octave: -1 !
repeat(2) {
A. C'. E'. A'. E'. C'. A. E.
}
! octave: +1 !
! key: Gmaj !
G. A. B. ! octave: +1 ! C. D. E. F. G. B. G. D. G. B,. D. B,. G,.
! key: Fmaj !
! octave: -1 !
F. A. C'. F'. C'. A. F. D.
! key: Emaj !
E. G. B. E'. B. G. E. B,.
! key: Am !
! time: 1 !
! octave: -1 !
A.
---
accompany [_powerchords_] name pc
---
title: "Example 2"
author: "Musika"
coauthors: "Coauth1, coauth2, coauth3"
key: Cmaj
time: common
tempo: 4 = 120
octave: 4
=>
This is a collection of patterns. No main music here, so it is used for accompaniments!
<=
---
pattern [scale_chords]:
! time: 1 !
pc>CP_3.
pc>GP_3.
pc>CP_4.
pc>GP_4.
pc>CP_5.
pc>GP_4.
pc>CP_4.
pc>GP_3.
pc>CP_3.
pattern [scale_harmony]:
E.. F. G. A. B. C'. D'.
! octave: +1 !
E.. F. G. A. B. C'. D'. E'..
D'. C'. B. A. G. F. E.. D. C.
! octave: -1 !
B. A. G. F. E..
---
---
accompany [_scale_] name scale & This references the standard library file "scale.ka" accompany [example2] name ex2 & This references a file in the same directory "example2.ka" --- title: "Example 3" author: "Musika" key: scale time: scale tempo: scale octave: scale --- --- scale & This is the main music from the "scale" standard library file! Let's first play it by itself layer(ex2>scale_chords) & Play example 2's "scale_chords" pattern on top of the scale scale layer(ex2>scale_harmony) & Now let's play the scale again, but give it a harmony! scale ---
title: "Example 4" author: "Musika" key: Cmaj time: common tempo: 4 = 90 octave: 4 --- chord Cmajguitar is C,;E,;G,;C;E chord Dmajguitar is D,;A,;D;F# chord Gmajguitar is G,,;B,,;D,;G,;B,;G pattern [rhythm]: ! time: 8 ! Cmajguitar. ^ 8 ! time: 8 ! Gmajguitar. ^ 8 ! time: 8 ! Dmajguitar. ^ 8 ! time: 1 ! Cmajguitar. pattern [lead]: ! time: 16 ! ! octave: +1 ! C. D. E. F. G. C'. E. C'. E. C'. D. B. A. B. C'. F'. ! key: Gmaj ! G'. B. D'. B. A. B. E. F. G. F. G. D,. E. F. G. F. ! key: Dmaj ! D. A,. D. A,. F. A,. E. A,. D. C,. D. F. D. A. F,. A. ! key: Cmaj ! C. E. G. E. C. E. G. C'. E'. G'. E'. B. D'. C'. A. B. ! time: 1 ! C. pattern [main]: layer(rhythm) lead --- main main ---
The following shows the basic features of the Musika IDE and how it can be used to create and manage Musika files.
At its core, the Musika IDE behaves as a basic editor specific for Musika files. The "File" menu item provides basic features including:
By default, the Musika IDE does not do any kind of styling to Musika code. However, syntax highlighting can be toggled on and off using View -> Toggle Syntax Highlighting. It should be noted, however, that syntax highlighting takes a significant performance drain on the editor, and it is recommended to avoid use of this feature for any file that is not small.
Musika code undergoes a 2-step compilation process:
In order to turn Musika code into a playable .wav file, it must first be saved and stored somewhere in a .ka file. You can use the IDE to create, edit, and save a .ka file or you can use a separate text editor.
To build a Musika file, it must first be opened in the Musika IDE. The Build -> Build Note Sheet menu item will compile the file into a note sheet binary. A file with an identical name and an extension of .mkc will be created and stored in the same directory as your .ka file. This will only happen if the code is free of any syntax or contextual errors. If there are any present, you must fix them before a note sheet can be generated.
To turn a note sheet binary into a playable .wav file, first make sure you have the corresponding .ka file open in the Musika IDE if it is not already open. Then the Build -> Build WAV File menu item will convert that note sheet binary into an audible .wav file. This file can be opened in any media player that supports .wav. However, you can also play the song directly in the Musika IDE using the Play -> Play Song menu item. This will play the .wav representation of the .ka file you are currently viewing in the editor, if there is one. You can stop playing a song that is playing using the Play -> Stop Song menu item; and Play Song will play the song back from the beginning.
Note that if you select Build -> Build WAV File before Build -> Build Note Sheet, the build wave file operation will build the note sheet binary first, and then build the .wav file; but it will cancel the process if there are any syntax or contextual errors in the Musika code. Be careful bypassing the Build Note Sheet option though; because if a .mkc file corresponding to your .ka file is present, the Build WAV File will create a .wav file based on that binary without rebuilding it, potentially using an out-of-date binary (i.e. it only builds a note sheet binary if there is not one already present). If you have a note sheet binary present, but you've updated your Musika code, be sure to either delete the existing binary or use the Build -> Build Note Sheet option first before building the *.wav file.