Kunquat – Getting Started

This page de­scribes some of the ba­sic con­cepts of Kunquat to help get you start­ed. This is not a step-by-step tu­to­ri­al: rather, my aim is to give you some ideas to try out so that you are bet­ter equipped to learn things on your own. At any giv­en point, I en­cour­age you to try out things dif­fer­ent from what I sug­gest. If Kunquat crash­es, let the au­thors know by following in­struc­tions in the crash dialog.

WARNING: Kunquat of­fers many flex­i­ble ways to con­trol sounds. As a re­sult, you may some­times ac­ci­den­tal­ly cre­ate sounds much loud­er than you ex­pect. Please keep your volume levels mod­er­ate, es­pe­cial­ly when edit­ing in­stru­ments.


  1. Ba­sic no­ta­tion
    1. Con­trols, notes and rests
    2. Long­er com­po­si­tions
    3. Tempo, time axis and grids
  2. Ba­sic in­stru­ment con­fig­u­ra­tion
    1. Main con­nec­tion graph
    2. In­stru­ment con­nec­tion graph
    3. Force en­ve­lopes
    4. Ad­di­tive syn­the­sis
    5. Chan­nel de­fault in­stru­ments
  3. Mu­si­cal ex­pres­sion
    1. Force con­trol and add­ing event trig­gers
    2. Force and pitch slides
    3. Vi­bra­to
    4. Force car­ry­ing
  4. More topics to be introduced later

1. Ba­sic no­ta­tion

This sec­tion de­scribes the ba­sics of writ­ing no­ta­tion in Kunquat Tracker.

1.1. Con­trols, notes and rests

Lo­ca­tion of the in­put view.

When you first start Kunquat Tracker, you will see an in­put view at the bot­tom of the main win­dow. The four rows of large but­tons rep­re­sent your key­board, and you can press ei­ther the but­tons on the screen or the cor­re­spond­ing keys on your key­board to play notes.

Lo­ca­tion of the sheet tool­bar.

Take a look at the sheet tool­bar above the no­ta­tion view in the main win­dow. This tool­bar con­tains most of the tools re­quired for edit­ing your mu­si­cal score. Hov­er your mouse over the tool but­tons and you will find that many of them have key­board short­cuts that you will prob­a­bly find use­ful.

Press­ing the Edit but­ton ac­ti­vates the edit­ing mode, which al­lows you to en­ter notes in­to the sheet. After you have en­tered some notes, press the play but­ton to hear what you en­tered. You can add rests by press­ing 1 (on most key­boards; the rest key is al­ways lo­cat­ed at the top left-hand cor­ner of the note in­put keys).

If you need to re­move any­thing you add into the sheet, you can use Delete and Backspace like in typ­i­cal text edi­tors. Al­so, you will find the Re­place mode very use­ful, as it al­lows you to re­place ex­ist­ing notes with new ones di­rect­ly.

1.2. Long­er com­po­si­tions

Af­ter play­ing around with adding notes for a while, you will soon reach the end of com­po­si­tion space. Ini­tial­ly, the de­fault emp­ty com­po­si­tion con­tains one pat­tern, which is a short sec­tion of mu­sic in­tend­ed to con­tain a few bars of music, usual­ly enough for a mu­si­cal phrase or two.

Adding pat­terns to com­po­si­tion.

While you can in­crease the pat­tern length above the top right-hand cor­ner of the sheet, it is usual­ly more ap­pro­pri­ate to or­ga­nise your com­po­si­tion into sev­er­al pat­terns. This al­lows you to freely change the or­der in which pat­terns are played, and you can al­so reuse ex­ist­ing pat­terns. Open the Songs & chan­nels win­dow from the top of the main win­dow and take a look at the Or­der list sec­tion on the left. This is where you can man­age your set of pat­terns.

1.3. Tempo, time axis and grids

Take a look at the time axis on the left side of the sheet. The num­bers along the axis rep­re­sent beats. By de­fault, the tem­po of a Kunquat com­po­si­tion is 120 beats per minute; there­fore, the play­back cur­sor moves for­wards two beats ev­ery sec­ond. You can ad­just the de­fault tem­po in the Songs & chan­nels win­dow.

Location of the default tempo setting.

While Kunquat does not have a con­cept of time sig­na­tures, it can rep­re­sent them with grids. A grid is a set of lines that your cur­sor will snap in­to in the sheet. If you look at the sheet in its ini­tial state, you can see that the de­fault grid re­peats every 4 beats, and each beat is fur­ther di­vid­ed into 4 sub­di­vi­sions. Thus, the de­fault grid is suit­able for rep­re­sent­ing basic rhythms in 4/4 time with up to a 1/16th note in pre­ci­sion. Try zoom­ing in a step or two, and the dis­play re­veals an­oth­er set of lines, al­low­ing you to use 1/32nd notes.

Lo­ca­tion of the sheet grid con­trols.

If you need a time sig­na­ture oth­er than 4/4 or you need a dif­fer­ent sub­di­vi­sion of your bars (e.g. for en­ter­ing triplets), you have two op­tions: ei­ther dis­able the grid fea­ture en­tire­ly by uncheck­ing the Grid check­box, or cre­ate your own cus­tom grids. You can ac­cess both methods at the grid con­trols on the right side of the sheet tool­bar.

Dis­abling the grid al­lows you to en­ter your notes freely on the time axis, which can help you add a sense of human el­e­ment or groove in­to your music. If you are com­fort­able with the grid­less ed­i­tor, you can safe­ly skip the rest of this section.

The grid ed­i­tor.

If you wish to cre­ate your own grids, press the Edit grids but­ton to open the grid ed­i­tor. After cre­at­ing a new grid, you have a grid pat­tern that is equiv­a­lent to the de­fault grid. You can ad­just the length of the grid to match the num­ber of beats you want in a sin­gle bar. You can re­move any line ex­cept the first one by se­lect­ing the line and press­ing Delete. You can add new lines by sub­di­vid­ing re­gions be­tween exist­ing grid lines. Se­lect the line above the re­gion you want to di­vide, then choose how many parts you want and what line style you want to use for split­ting the re­gion. Fi­nal­ly, click Sub­di­vide (or press In­sert).

Af­ter cre­at­ing your own grid, you can use it by plac­ing the sheet cur­sor in the pat­tern of your choice and se­lect­ing your grid from the drop-down menu in the grid con­trols. This will change the de­fault grid of the pat­tern. If you only want to use your grid in a spe­cif­ic area, se­lect the area by drag­ging with your mouse (or by us­ing Shift + ar­rows on your key­board) and then se­lect the grid. This is es­pe­cial­ly use­ful if you want to add pre­cise triplets or oth­er sub­di­vi­sions of time.

Note: If you can­not see some of your grid lines in the sheet, it is like­ly be­cause they are con­sid­ered to be so close to oth­er lines that show­ing them would cause clut­tered dis­play. Take a look at the “Show lines —— when spac­ing is ≥:” set­ting in the grid ed­i­tor. Se­lect the kind of line you need to make vis­i­ble and then re­duce the val­ue (that is 0.6 by de­fault) un­til you can see the lines in the sheet.

2. Basic in­stru­ment con­fig­u­ra­tion

Soon you will prob­a­bly want sounds more in­ter­est­ing than the de­fault sine wave in­stru­ment. This sec­tion will help you add a bit of va­ri­ety in­to your in­stru­ments.

2.1. Main con­nec­tion graph

Main con­nec­tion graph with two in­stru­ments con­nect­ed to Mas­ter Out.

Open the Con­nec­tions win­dow from the top of the main win­dow. This win­dow shows your in­stru­ments (lat­er, al­so ef­fects) and the way their audio sig­nals are con­nect­ed. You can think of it as anal­o­gous to the way you con­nect elec­tric in­stru­ments to am­pli­fiers and ef­fect units with ca­bles. The Mas­ter Out box pro­duces the fi­nal au­dio out­put, and any sound you want to hear needs to reach this des­ti­na­tion ei­ther di­rect­ly or through ef­fect box­es.

If you start­ed Kunquat Tracker nor­mal­ly with­out open­ing an ex­ist­ing com­po­si­tion, you will see an in­stru­ment la­belled “Sine” that is con­nect­ed to Mas­ter Out by two ca­bles. Add a new in­stru­ment with the ap­pro­pri­ate tool but­ton at the top of the con­nec­tions view, and you will get a new in­stru­ment. The new in­stru­ment should be con­nect­ed to Mas­ter Out au­to­mat­i­cal­ly; if not, con­nect that in­stru­ment as well by drag­ging ca­bles from the in­stru­ment out­put ports to the cor­re­spond­ing ports of Mas­ter Out.

If you need to re­move a con­nec­tion ca­ble, click the ca­ble and se­lect Re­move from the con­text menu.

2.2. In­stru­ment con­nec­tion graph

In­strument con­nec­tion graph with a sim­ple set-up of an os­cil­la­tor (“Base“) cre­at­ing an au­dio sig­nal based on pitch and force in­put.

If you press the Edit but­ton of the new in­stru­ment you cre­at­ed, you will find an­oth­er con­nec­tion view. These are the in­ter­nal com­po­nents your in­stru­ment uses to make its sound. The in­stru­ment also has a Mas­ter Out box, and any sound that the in­stru­ment makes needs to trav­el to this des­ti­na­tion one way or an­oth­er. The ba­sic com­po­nents that gen­er­ate and/or ma­nip­u­late sound in­side in­stru­ments are called pro­ces­sors.

The struc­ture of the con­nec­tion graph in­side the in­stru­ment is sim­i­lar to the one in the high­er lev­el. How­ev­er, not all the com­po­nents han­dle au­dio sig­nals. Take the pro­ces­sor la­belled “Pitch”, for in­stance: its out­put is the pitch of what­ev­er note is play­ing. The out­put of the Pitch pro­ces­sor is con­nect­ed to the pitch in­put of the pro­ces­sor la­belled “Base”, which is the com­po­nent re­spon­si­ble for creat­ing the au­dio wave­form. Try dis­con­nect­ing the ca­ble that con­nects to the pitch input of Base, and you will no­tice that all the notes that come out of the in­stru­ment now have the same pitch (Re­con­nect the pitch sig­nal by drag­ging a ca­ble from the source port to the des­ti­na­tion port with your mouse).

2.3. Force en­ve­lopes

Force ed­i­tor.

The pro­ces­sor la­belled “Force” is re­spon­si­ble for con­trol­ling the vol­ume of the notes pro­duced by the in­stru­ment. It is al­so re­spon­si­ble for keep­ing the notes alive, so all in­stru­ments need a force pro­ces­sor. Try dis­con­nect­ing the sig­nal trav­el­ling in­to the force in­put of Base, and you will no­tice that the in­stru­ment no longer makes a sound.

If you press the Edit but­ton of the Force pro­ces­sor, you will find a num­ber of con­trols for the force sig­nal out­put. The Glob­al force is the base con­trol of force out­put, and you can use it to ad­just the over­all loud­ness of your in­stru­ment.

You can use the Force en­ve­lope to con­trol how the force changes for each note over time. Tap the En­abled check­box to en­able the en­ve­lope. You can move en­ve­lope nodes by drag­ging with your mouse, cre­ate new nodes by click­ing some­where be­tween ex­ist­ing nodes, and re­move nodes by drag­ging them out­side the en­ve­lope area (oth­er than the right edge – that will sim­ply give you more space to work with).

If you en­able the Force re­lease en­ve­lope, you can con­trol how your note fades out when you re­lease the key (or add a rest in the no­ta­tion).

2.4. Ad­di­tive syn­the­sis

Ad­di­tive syn­the­sis ed­i­tor.

The Force pro­ces­sor al­lows you to add a bit of char­ac­ter to your in­stru­ment, but hav­ing the sine wave­form as your base will not take you very far. Click the Edit but­ton of the pro­ces­sor la­belled “Base” to get some ba­sic con­trols for tim­bre. The bot­tom of the ed­i­tor con­tains ba­sic con­trols for edit­ing the over­tone se­ries of the sound. Next to the wave­form dis­play, how­ev­er, you can change the base wave­form to some­thing oth­er than sine wave.

2.5. Chan­nel de­fault in­stru­ments

Set­ting a de­fault in­stru­ment for a chan­nel.

At this point you have a new in­stru­ment that you can play in the in­stru­ment ed­i­tor, but it is not eas­i­ly ac­ces­si­ble in the com­po­si­tion sheet yet. Go to the Songs & chan­nels win­dow again and take a look at the Chan­nel de­faults sec­tion on the right. You can set the de­fault in­stru­ment for each chan­nel here. Once you change the de­fault in­stru­ment in a chan­nel, you can see that the cor­re­spond­ing col­umn in the sheet edit­or dis­plays the name of the de­fault in­stru­ment in the col­umn head­er.

3. Mu­si­cal ex­pres­sion

Con­trol of mu­si­cal ex­pres­sion is the es­sence of Kunquat. In this sec­tion I will cov­er some of the ba­sic con­cepts of event trig­gers and sug­gest some ways you can use them to make your music more ex­pres­sive.

3.1. Force con­trol and adding event trig­gers

Steps for adding a trig­ger.

Go to the sheet (pat­tern ed­i­tor) and move your cur­sor to a lo­ca­tion im­me­di­ate­ly next to one of the notes you have en­tered. Make sure you are in Edit mode. Press Return to bring up a text field where you can en­ter an event name. Try writ­ing .f (note the pe­ri­od, it is part of the event name). The .f event al­lows you to set the force of the cur­rent note. After en­ter­ing the event name, you can en­ter the ac­tu­al force val­ue, which is typ­i­cal­ly a num­ber be­tween 0 and 30 (de­fault “max­i­mum” force).

The force value is in a log­a­rith­mic scale sim­i­lar to deci­bels: re­duc­ing a force value by 6 low­ers the am­pli­tude of the note by half. How­ev­er, note that, as an ex­cep­tion, the note force val­ues in the sheet are shift­ed so that the de­fault force is 30. Every­where else in the track­er, force and vol­ume pa­ra­me­ters use a deci­bel scale where 0 is the de­fault.

Steps for re­plac­ing a trig­ger pa­ra­me­ter.

If you would like to change a force val­ue of an existing trig­ger, enter Re­place mode, move your cur­sor on top of the force trig­ger you want to mod­i­fy, and press Re­turn.

3.2. Force and pitch slides

You can adjust the force of an existing note with the .f event anywhere between the note starting event and the next note or rest. However, this is usually not recommended, as the force change is instant and may cause an audible snap.

An ex­am­ple of a force slide from 25 to 10 with­in half a beat. The slide reach­es 10 at the cur­sor po­si­tion.

For smoother and more grad­ual changes in force, you need two ad­di­tion­al events: /f and /=f. The /f event starts a force slide, and its pa­ra­me­ter is the target force. The /=f event spec­i­fies the du­ra­tion of the slide, and its pa­ra­me­ter is the du­ra­tion in beats. You need to spec­i­fy both the tar­get force and the slide du­ra­tion; how­ev­er, Kunquat re­mem­bers the du­ra­tion you have pre­vi­ous­ly spec­i­fied in the col­umn so you don't need to spec­i­fy it every time un­less you want to change it.

You can slide pitch in a sim­i­lar way with the /p and /=p events. Note that you can re­place the tar­get pitch of the /p event in the Re­place mode di­rect­ly by play­ing a new note while your cur­sor is on the event.

One ex­am­ple of a use­ful ex­pres­sive de­vice is por­ta­men­to. Try the fol­low­ing pitch slide con­fig­u­ra­tion in your melody line in a suit­able spot. Ex­per­i­ment with dif­fer­ent slide du­ra­tions and start­ing points in the time axis.

A por­ta­men­to from G♯4 to A4. No­tice that we have zoomed in on the time axis.

3.3. Vibrato

An­oth­er com­mon ex­pres­sive de­vice, vi­bra­to is con­trolled with the vs and vd events, which con­trol the vi­bra­to speed and depth, re­spec­tive­ly. You prob­a­bly also want to use the v/=d event, which spec­i­fies the tran­si­tion du­ra­tion for the vi­bra­to depth sim­i­lar to the slide du­ra­tion events. (There is also v/=s, which you may find oc­ca­sion­al­ly use­ful.) Turn the vi­bra­to off by set­ting a depth of 0 with the vd event.

An ex­am­ple of a vi­bra­to with speed 5 and depth 4, with a grad­ual depth slide of 1 beat.

3.4. Force carrying

If you want to use the same force for a number of notes in succession inside a single channel, you don't need to use the same .f event with every note. Instead, you can use the ->f+ event to enable carrying of the previous note's force to the next note. This also works with force slides: with carrying enabled, you can make a force slide that spans multiple notes. To turn force carrying off, use the ->f- event.

An ex­am­ple of a force slide car­ried over sev­er­al notes. The slide reach­es the de­sti­na­tion force of 30 at the cur­sor po­si­tion.

4. More top­ics to be in­tro­duced lat­er

This in­tro­duc­to­ry doc­u­men­ta­tion does not in­clude all the top­ics I would like to cov­er yet, but I will ex­tend it lat­er. I hope that it helps you get start­ed with the ba­sics of Kunquat Tracker!