-
Notifications
You must be signed in to change notification settings - Fork 0
Language Documentation
This documentation is a detailed description of the main syntax and characteristics of the language with examples on each section. It's designed for developers and it can be a bit tedious. If you are new with ChordScript, you should start with the tutorial and go back here if you have a specific query.
ChordScript is a dynamic, strongly typed and interpreted language, that executes code to generate sounds. In order to execute sounds on different operative systems, it needs to "connect" with different sound systems and drivers.
To simplify this communication, ChordScript uses Jack Audio Connection Kit. It works as a server mounted over current OS sound diver, and ChordScript connects to it as a client. For this reason, when you install CS you also install Jack. This architecture, does not only makes ChordScript able to run on different OS, but also offers the possibility to work with low latency audio generation.
So, CS allows you to trigger pre-recorded samples, synthesize sounds using basic functions and apply some effects on this sounds, using programming as interface.
For this reasons, ChordScript can be a good alternative for live coding, creative coding, algorithmic composition or for any musician/programmer who wants to use programming as a powerful instrument for composition, giving also the possibility to record and store it as a .wav file.
ChordScript takes some syntax rules from other popular languages. This decision was made to take it easy to learn other languages if you start your programming path here. It takes the strong rules of C/C++ and the dynamics of python.
Here is a list with the basic rules:
-
The type of a variable must be specified in assignation:
-
number myVariable = 10;
See data types section for a list of all valid data types
-
Assignations and executions lines, must end with a semicolon:
-
string name = "my name"; -
Variable names must start with a letter and can continue with more letters, numbers or the character underscore '_' :
-
MyVariable_3Valid name. -
4_aVariableInvalid name.
There are some code examples that you can copy and paste in your ChordScript IDE and then modify or play to understand or take as a base for your compositions. If you want to install the IDE go to the ChordScript Page.
This demo, shows a lot of capabilities of the language. In order to read simpler examples continue to specific sections.
Base with simple chords
** Insert example here **Synthesize using loops
** Insert example here **There are a list with all data types in ChordScript:
Basics
numberbooleanstringargument-
group(not implemented yet) -
array(not implemented yet)
Playables
soundsample
Some of this data types has defined methods that are listed and explained on each particular section.
Basic types are data types that are useful for programming but has not a particular usage for playing music. These are used as control variables in for loops, as flags in flow control or in general to simplify the algorithmic programming.
In the code, numbers are simply any kind of number, with or without decimal part.
Some examples of numbers could be number myNumber = 1; or number mySecondNumber = 4.53;
Only a dot can be used to separate decimal part, comma it's not allowed.
Valid operations with numbers are addition +, subtraction -, multiplication * and division /
Boolean values can be expressed as true or false.
It can also be expressed as numbers. A false value is 0 and any other number is considered true.
Valid boolean operations are:
-
==compare if two values are equal and return a boolean as a result of the comparison. -
<compare if the right values is bigger than the left value. -
>compare if the left values is bigger than the right value. -
>=compare if the left values is bigger or equal the right value. -
<=compare if the left values is smaller or equal the right value. -
!=compare if both values are different. -
&Works as the AND boolean operation. If both values are true, so the returned value is true. Otherwise return false. -
|Works as the OR boolean operation. If both values are false, return false, otherwise return true. -
!this operator placed before a boolean value, works as the NOT boolean operation.
Strings are text placed between double quotes "I am a string!". This is the way to introduce text inside ChordScript. All text between quotes aren't interpreted as code. So, can be used for naming an object or to specify the name of a file in the computer.
Some functions takes a string as an argument, for example: sample mySample = SAMPLE("path/to/my/file.wav");
Strings can be concatenated using the operator +
Argument is an interesting data type, that can hold values to be passed later to a function. An example could be the better explanation:
...
number a = 10;
argument myArgument = (a,1);
a = 13;
myFunction(myArgument); # Here myFunction is called with the argument (10,1)
...So, this allows you to set argument values before calling the function.
This data types allows you to synthesize sounds. This type has the following methods and operations:
play( [freqs] , duration )
As its name says, this method play the sound during a time in seconds specified in the argument duration. This value must be a number. If you call this method without a duration, the sounds play forever (until you stop it).
freqs is an array of frequencies of type number between brackets and separated by commas. All this frequencies are played passed to the sound at the same time, so this is the way to play chords for example.
# This line creates a sound using the pre defined sound called S_SIN.
# See synthesis section for more information about sounds.
sound mySound = S_SIN;
# Play a chord of A minor during one second
mySound.play( [A4, C5, E5], 1 );
# This sound is executed at the same time and holds a tone forever.
mySound.play( [A2] );play( (arguments) )
This is another way to call the play method. It consist of arguments similar to the previous play definition passed as the same time to play one after the other. This is the way to play a song for example.
# Define a sound
sound mySound = S_SIN;
# Call the method to play 3 chords one after the other.
# The total duration of this play is 4 seconds.
mySound.play(
( [A4, C5, E5], 1 ),
( [F4, A4, C5], 1 ),
( [G4, C5, E5], 2 )
);**Important**: you can't call this method as the second way and giving no duration on any argument. It throws a syntax error.
stop()
This method doesn't receive any argument. It just stops all generated sounds that are playing of a particular sound.
# Create a new sound using the base sound S_SQUARE
sound mySound = S_SQUARE;
# Play a 440 A during some time
mySound.play( [440] );
# And some seconds later...
# Stop the sound
mySound.stop();**Note**: if you copy and paste this code and run, you won't hear anything because you are playing and stopping the sound immediately after that.
This method is useful when live coding, and you want to stop some sounds that are currently playing.
loop( [freqs] , duration ), loop( (arguments) )
This method is similar to play but with the difference that when all arguments are played, starts again infinitely.
# Define a sound
sound mySound = S_SIN;
# Call the method to loop this 3 chords.
mySound.loop(
( [A4, C5, E5], 1 ),
( [F4, A4, C5], 1 ),
( [G4, C5, E5], 2 )
);This 3 chords will play in a loop indefinitely until you stop the sound.
setPanning( number )
This method receives a number between 0 and 1 representing the panning of the sound. 1 is the stereo right channel and 0 the left one. So, 0.5 is the default centered sound.
This method returns a new sound with the same characteristics of the current one but with the new panning. To understand how to use it, go to Synthesis section
# Define a sound completely panned to the right channel
sound mySound = S_SIN.setPanning(1);
# Play this chords in the right channel
mySound.play( [A4, C5, E5], 1 );setPanning( sound )
Additionally you can call this method but giving another sound as parameter. This generates a panning effect based on the sound passed as argument.
This method returns a new sound with the same characteristics of the current one but with the new panning. To understand how to use it, go to Synthesis section.
# Define a simple sound
sound mySound = S_SIN;
# Define a sound with panning controlled by the other sound
sound myPannedSound = S_SIN.setPanning(mySound);
# Play this bass with a fast panning change between channels during 1 second
mySound.play( [100], 1 );constantFreq( number )
This method receives a constant frequency number as parameter and returns a new sound with the same characteristics of the current sound, but with a constant frequency. This means that no matter the frequencies you sent when you call play or loop method, it always play the same note.
This is useful for synthesis. See Synthesis section for more interesting examples.
# Define a sound with a constant frequency
sound mySound = S_SIN.constantFreq( A4 );
# Play A4 during 1 second (instead of E3)
mySound.play( [E3], 2 );Additionally you can call this method as an anonymous method with the following syntax:
# Define a sound with a constant frequency
sound mySound = S_SIN( A4 );
# Play A4 during 1 second (instead of E3)
mySound.play( [E3], 2 );freqFactor( number )
This method set a factor number multiplying the frequency of the sound. Receives a number representing this factor, and returns a new sound with this factor set. To see more examples, see Synthesis section
It can be used to octave a sound for example.
# Define a sound with a frequency factor set
sound mySound = S_SIN.freqFactor( 2 );
# Play E4 instead of E3 during 2 seconds
mySound.play( [E3], 2 );freqModulation( sound )
This method modulates a copy of the current sound with the sound passed as argument using frequency modulation and return this copy. To see more examples, see Synthesis section
It works as a LFO controlling the frequency of the original sound.
# Define a basic sound with a constant freq of 10Hz
sound myLFO = S_SIN( 10 );
# Creates a new sound modulated using myLFO
sound mySound = S_SIN.freqModulation(myLFO);
# Play a note during 2 seconds
mySound.play( [E3], 2 );ampFactor( number )
This method receives a number that multiply the amplitude and return a new sound with this value set. For example, a factor of 0.5 will reduce the volume of the sound to the half. To see more examples, see Synthesis section.
This is the best way to set the volume of a sound.
Additionally you can call this method using the operator *:
# Define a sound that will be played 0.3 times low.
sound mySound = S_SIN.ampFactor( 0.3 );
# This line generates the same result.
mySound = S_SIN * 0.3;
# Play a note during 2 seconds
mySound.play( [E3], 2 );ampFactor( sound )
This method can be called giving a sound as a parameter and return a new sound modulated using amplitude modulation. To see more examples, see Synthesis section.
It works as a LFO controlling the amplitude of the original sound.
Additionally you can call this method using the operator *:
# Define a sound with a small constant frequency (5 Hz)
sound myLFO = S_SIN(5);
# Use this LFO to modulate a "carrier" of a higher frequency
sound mySound = S_SIN.ampFactor(myLFO);
# This line generates the same result.
mySound = S_SIN * myLFO;
# Play a note during 2 seconds
mySound.play( [E3], 2 );