Handel

Handel is a procedural programming language for writting songs in browser.

The Handel Interpreter interprets Handel programs and plays compositions in browser, thanks to Tone.js.

Try the Handel Web Editor here: Handel Web Editor

See the language documentation (including latest features): Handel Documentation

Join the Handel forum to ask questions and showcase compositions. Also check out the Contributing guidelines.

soli deo gloria

Installation

Add the below to your html document:

<script src="https://unpkg.com/handel-pl"></script>

You're all set!

Alternatively

Install Handel with the following:

npm i handel-pl

And import Handel with the following:

import * as Handel from 'handel-pl';

Usage

Example Handel Snippet

start
    chunk example 
        play E3, C3, G3 for 2b
    endchunk
    run example with sound piano, loop for 5 
finish

See the Examples folder here for example Handel programs and inspiration.

Example Using Handel In Browser

function clicked(){
    Handel.RunHandel(`
        start
            chunk example using somePlayable 
                play somePlayable 
                rest for 1b
            endchunk
            save myPlayable = Eb3 for 1b
            run example using myPlayable with sound piano, loop for 5 
        finish
    `)
}
document.addEventListener("click", clicked);

Note that you pass the Handel code into the RunHandel function Handel.RunHandel(someHandelCode).

To compile to midi, pass a config object to the RunHandel function with outputMidi set to true.

const config = {outputMidi: true};
Handel.RunHandel(`start play E4 for 1b finish`, config);

Additionally, you can use the StopHandel function to stop a running Handel program. Handel.StopHandel()

Getting started

Handel programs are contained within the start and finish keywords. Below is a complete Handel program:

start
    play E4 for 1b
finish

The program above only plays 1 note. But it's a start!

Let's play something

You can be play notes and chords using the play command. Below is an example program that plays a note, then a chord:

start
    play C#3 for 1b
    play E3, G3, A4 for 1b
finish

Note the syntax above. A play command begins with the play keyword, then a note or chord (a list of notes separated by commas) follows.

Lastly play commands need a duration. The play commands above end with 'for 1b'. This states how long the particular note or notelist (chord) should be held.

Phew! We're getting somewhere.

Let's rest

Similar to the play command, a rest can played using the rest command. Below is an example program that rests for 1 beat then plays a note for 2 beats.

start
    rest for 1b
    play G5 for 2b
finish

But are there Variables?

tl;dr Here is a code snippet showing variables in Handel

start
save mynotelist = Cb3, D3
save myduration = for 1b
save myplayable = E4, F4, G3 for 3b

save myotherplayable = mynotelist for myduration

play myplayable
rest myduration
play myotherplayable
finish

You can declare Variables in Handel. Variables store three builtin types in Handel: Notelists, Notegroups, Durations, Playables.

A Digit is a positive or negative integer.

A Notelist is a single note name, or a list of note names separated by commas.

For example:

Bb3
G#2, A2

A Notegroup is a group of notelists (or conceptually an array of notelists). Each notelist is separated by a vertical line.

For example:

Bb3|G#2, A2

A Duration is the keyword for followed by a beat.

Here are some example durations:

for 1b
for 2b
for 16b
for 32b

Lastly, we've already seen Playables above. Playables are a note or notelist (chord) followed by a duration. Here are some example playables.

Bb3 for 1b
D#6, E#6, G3 for 1b

no promises that the above chord sounds pleasing to the ear :p

Finally variables!

To store a notelist, playable or a duration use the save keyword, followed by a variable name, an equal sign and a notelist, playable, duration (or another variable which stores on of these values).

Variable names must contain only lowercase letters, and no numbers. Variable names must also not be any of the reserved keywords in Handel. eSee the Reserved Keywords).

Below is an example program using variables.

start
    save mynote = E2
    save myplayablenote = mynote for 2b
    save myrest = for 2b

    play myplayablenote
    rest myrest
    play myplayablenote
    rest myrest
finish

When saving variables, Handel now also provides expressions for generating random numbers and for evaluating expressions.

To generate a random number when setting a variable, use the randint keyword, followed by a range start to end

To evaluate an expression use the eval keyword followed by a mathematical expression (note division is integer division).

Here is an example of the syntax:

save somerandomdigit = randint -5 to 5
save someint = eval 5 * 5 / (1 + 1) % 6

OK! So far so good!

Variable Reassignment

Handel now supports variable reassignment. Variables can be reassigned using the update keyword.

For example:

save mynotelist = B3
update mynotelist = Bb3

Reassignment and Shifting values

All variables in Handel can be shifted using the rshift and lshift keywords. You can think of this as the equivalent of += and -= respectively.

For variables storing digits, this shifting is exactly the equivalent of addition and subtraction.

For variables storing notelists and notegroups, shifting changes the notes, left or right by a number of semitones.

The following example reassigns (or shifts) ```mynotelist`` left by one semitone. Then right by two semitones.

start
    save mynotelist = B3 

    update mynotelist lshift 1
    play mynotelist for 1b

    save somenum = randint 1 to 5
    update mynotelist rshift somenum 
    play mynotelist for 1b
finish

Variables storing Durations and Playables can also be shifted.

Shifting a duration increases or decreases its beat value.

Shifting a playable (which contains a notelist) increases or decreass its notelist.

For example:

start
    save duration = for 1b
    save playable = E3, G3 for 2b
    
    update duration rshift 1 
    update playable lshift 2 

    play playable
    rest duration
    play playable
finish

Blocks loops

Handel supports block loops. Block loops begin with the block keyword and end with the endblock keyword and a loop for digit or loop while condition customization.

Here is an example two block loops in Handel.

start
    block 
        play C3, E3, G3 for 1b 
        play D3, F3, A3 for 1b 
    endblock loop for 2 

    save note = C2
    block 
        play note for 1b 
        update note rshift 1
    endblock loop while note lessthan C3
finish

Block loops are blocking (no pun intended), and should not be confused with Handel's procedures (chunks).

More on procedures below.

Conditionals (if - else blocks)

Though booleans are not built in types in Handel, Handel now supports conditonals. > < >= <= ==

The syntax for an if - else block is as follows.

start
    if E4 > Cb3 then
        play E4 for 1b 
    else
        play Cb3 for 1b
    endif

    save mydigit = 5
    if mydigit == 5 then
        play C2 for 5b
    endif
finish

The above plays E4 for 1 beat. Note that else blocks are optional.

Procedures (I thought this was a procedural programming language?)

Procedures in Handel are called chunks. You can conceptualize a chunk as a song track. When ran, chunks play at the same time as other run chunks and the global track. Chunks must begin with the chunk keyword and end with the endchunk keyword.

Below is an example program with a kick drum and a piano, playing together.

start
    chunk backbeat using myplayable
        play myplayable 
    endchunk

    chunk mykeys 
        play E3, G3, A3 for 1b
        play G3, A2, C3 for 1b
        play F3, A3, C3 for 1b
        play D3, F2, A3 for 1b
    endchunk

    run mykeys with sound piano, loop for 2

    save myplayable = A1 for 1b

    run backbeat using myplayable with sound kick, loop for 8
finish

Both the 'backbeat' chunk and the 'mykeys' chunk above play together (not one after the other). This behavior allows multitrack songs to be created with Handel.

Note that each chunk has its own scope.

More on procedures (chunks) and their syntax

Procedure declaration (creating chunks)

As noted above you can create chunks with the chunk keyword. The name of the chunk (the chunk name) follows the keyword.

This chunk name must be all lowercase letters, no numbers and cannot be one of Handel's reserved keywords. (See the Reserved Keywords).

After the chunk name, you can optionally add parameters. A list of comma separated parameters can follow the using keyword.

Together you get the following: chunk somechunkname using someparam, anotherparam

After the optional parameter list, you can add a body to the chunk. This is a function body (what you would like to happen when the chunk is ran).

Lastly the chunk must be ended with the endchunk keyword.

Running Procedures

There are two ways to run a chunk in Handel.

You can run a chunk using the run keyword. This conceptually creates a new song track, and plays the chunk synchronously with all running chunks.

You can also run a chunk using the call keyword. This run