Manual & Documentation
• • •
Noah Fishman & Dan Trueman, 2018
Table of Contents
If viewing in Google Drive, click “View > Open Document Outline” for a scrolling sidebar outline
Table of Contents
Installation and Setup
Mac (v2.3 and higher)
Windows (v2.3 and higher)
Versions 2.2 and earlier
bitKlavier Home Screen
bitKlavier Construction Site
Quitting bitKlavier (OSX)
bitKlavier for iOS
Example: Using Two Keymaps
Sustain Length Multipliers
Beat Length Multipliers
Pulse Trigger Menu
Nostalgic: General Notes
Note Length Multiplier
Edit Reverse Envelope / Edit Undertow Envelope
Synchronic Key Up/Down
Full Keyboard Tuning
Adaptive Anchored Tuning 1
Adaptive Tuning 1
About & Credits
At the heart of bitKlavier is an analogy to the acoustic piano. Press any key on a piano and it triggers a hammer, which strikes a string. From the resulting vibration, we hear a pitch. Preparing a piano is the process by which we intervene with that straightforward linear system by physically altering the motion of the piano strings. We traditionally prepare a piano by placing screws, forks, coins, or really any object in the piano strings in order to change their sound: We insert a step between the hammer strike and the acoustic sound that emerges. Through preparation, we can turn a familiar and homogenous instrument into something idiosyncratic, percussive or metallic, muted or dark. Yet under the hands, the instrument is still a piano.
If we understand the algorithm of the digital piano (key, MIDI signal, sample playback) in the same way that we understand the inner workings of the acoustic piano (key, hammer, vibrating string), we can think about altering the playback algorithm as a “digital preparation.” We’re inserting an additional step between the “hammer strike” (the MIDI signal) and the vibrating of the “string” (the playback of the sample).
The prepared acoustic piano has many limitations: A string can never vibrate without the impulse of the hammer, one string will never produce two pitches, and one pitch can never trigger another. bitKlavier provides an environment where virtual “screws” alter the behavior of the virtual hammer and string in ways that are impossible with the acoustic piano. bitKlavier is not only a sampler, effects unit, or sequencer: It is an instrument, responsive to the touch of the player, infinitely tweakable and refinable. It is an environment where performers and composers can build an instrument that takes the concept of the prepared piano into a new realm.
As a compositional playground and performance laboratory, bitKlavier can be used to explore tuning, rhythm, tonality, polyphony, and counterpoint. The instrument is designed so that preparations can be fluidly connected and tweaked, and ideas can quickly be brought to life. Here are a few ideas which could be built within minutes using bitKlavier’s preparations:
bitKlavier can also be used in educational settings, and has been used to teach students about the design of the piano keyboard as a functional interface. When combined with bitSuite, a collection of educational apps with a similar interface to bitKlavier, it can help teach about tuning, temperaments, and rhythm. Much of this musicological material is explored in Dan Trueman’s course Reinventing The Piano, available online through the Kadenze platform.
bitKlavier has also been used by musicians for whom making music on a traditional piano has insurmountable physical obstacles. Galleries in bitKlavier can be designed so triads can be played with one finger, long arpeggios can be played with a two-note gesture, and every note is doubled an octave lower. As a customizable instrument that uses the traditional piano interface, bitKlavier can largely fit the needs of the composer/performer while remaining distinctly itself.
Installation and Setup
bitKlavier is available for OSX (VST/AU and standalone), Windows (VST and standalone), and iOS devices. Individual installation instructions are below. For detailed desktop, laptop, or iOS installation instructions, visit the bitKlavier download page.
Download the installer and run it!
You may get a warning from OSX saying this is from an “unidentified developer” or some such; typically, if you control-click on the installer, you can select “open” and it will open fine, or you may need to adjust your security settings in the OSX System Preferences.
The installer will install the following:
Don’t move or rename the /Applications/bitKlavier folder or any of the folders inside of it; bitKlavier needs to have it there to find samples and galleries.
Download the installer and run it!
The installer will install the following:
Don’t move or rename the Applications\bitKlavier folder or any of the folders inside of it, or the Documents\galleries folder; bitKlavier needs to have them in those places to find samples and galleries.
To use bitKlavier on a Mac (<= v2.2) or Windows computer, follow the instructions below:
When using bitKlavier, a MIDI keyboard, headphones, and speakers are all highly recommended. A USB cable or MIDI interface from the keyboard are also required. Read more about our recommendations on the bitKlavier download page.
bitKlavier is also available on iOS (iPhone and iPad) and can be downloaded onto your device from the app store. For full iOS functionality, you’ll need:
bitKlavier can be used as a VST/AU in your DAW of choice. The implementation is not fully fleshed out – parameter automation is in the works – but bitKlavier can be used as a plugin instrument and mixed like any other plugin instrument. If you encounter any crashes or bugs while using bitKlavier with your DAW, please contact us or open a new issue on our GitHub page.
bitKlavier binaries 2.2 and newer include provisional support for SoundFonts (.sfz or .sf2), a file format used for batch-loading samples in a digital instrument. Visit a recent samples post the GitHub page for more information on SoundFonts.
In the desktop versions of bitKlavier (Mac or Windows, v2.2 and later), SoundFonts (.sfz or .sf2) that you place in /Applications/bitKlavier/soundfonts will be accessible in the sample loading menu beneath the default piano sample sets.
The iOS version of bitKlavier (v2.3 and later) is packed with a few default SoundFonts. If you would like to load more SoundFonts, you can add them through iOS File Sharing, accessible through iTunes when your mobile device is connected to your computer via USB.
Note: In the case of .sfz SoundFonts (in both the desktop and iOS versions), be sure to include the .sfz file in its parent directory along with any sample subdirectories.
bitKlavier Home Screen
bitKlavier uses an graphic interface similar to Max/MSP, Pure Data, and some digital synths such as Reaktor. Free-standing modules (the “preparations”) are added to an environment and connected to one another by drawing lines indicating signal flow through a given Piano.
The brown field in the center of the bitKlavier home screen is called the Construction Site. Preparations can be added to the Construction Site by using key commands or the Action tab. Double-click any preparation to open its corresponding settings window. Preparations can be linked (command-click and drag) and moved (click and drag). The location of a preparation has no influence on its behavior; it simply serves as an organizational way to understand the logic behind your bitKlavier Piano.
Along the bottom of the bitKlavier window is an 88-key keyboard. These keys can be used as a rudimentary MIDI keyboard. When a key is clicked, bitKlavier will behave as if it is receiving an external MIDI signal. This can be useful for exploring bitKlavier without a MIDI keyboard. When a MIDI keyboard is plugged in to your computer, the keyboard along the bottom will show which keys are being played.
A colored VU meter on the left-hand side of bitKlavier indicates the audio output level. Along the right-hand side, a discrete vertical slider controls overall gain from +12.0 to -90.0 dB.
The Gallery tab in the upper left provides global control for bitKlavier, plus controls for creating, renaming, and deleting Galleries (collections of preset Pianos).
New - create a new empty Gallery; a dialogue allows you to name your new Gallery
Save As - save a copy of the current Gallery, move it to a new location on your HD
Open - load Gallery settings from a location on your HD
Open (Legacy) - load .json file from the original bitKlavier (made in Max/ChucK) and create a new Gallery from it.
Clean - remove preparation presets not current used by any Pianos, to avoid clutter of accumulated presets when working in a Gallery. Every time you add a preparation, bitKlavier creates a UI object and a corresponding preparation under the bitKlavier hood. When you create a preparation then delete it from the Construction Site, the preparation’s settings can still be found in the dropdown preset menu of any corresponding UI preparation. “Clean” will remove any preparation that is not currently in use by a visible preparation.
Load Samples - choose from four subsets of the sample library in the resources/samples folder. Some use less memory than others, which may help performance in older computers. This option will not appear on bitKlavier binaries 2.2 or newer.
Share - send bitKlavier settings via Email, Messenger, or Facebook, with an attached Gallery file in .xml format (this will only work with custom Galleries).
A Gallery is a group of preset Pianos. To the right of the Gallery tab there is a list of pre-programmed Galleries. If you create custom Galleries, they will be saved here. By default, bitKlavier comes with a number of Gallery presets:
Basic Piano - a simple starter Piano with a Keymap, Direct, and Tuning preparation which together serve as an equal-tempered 88-key Piano.
Mike’s Gallery - a Piano with seven crazy presets designed by bitKlavier co-creator and programmer Mike Mulshine. Follow the prompts in the Piano titles for a musical adventure.
Examples - 27 preset example Galleries, most of which include detailed commentary about what the Piano does and how it works. These are categorized by preparation type, and are an excellent hands-on introduction to how bitKlavier works.
Nostalgic Synchronic - 8 Galleries for etudes written by bitKlavier creator, performer, and composer Dan Trueman for his work Nostalgic Synchronic. Visit the Nostalgic Synchronic website for more information and the accompanying score.
Mikroetudes - inspired by Béla Bartók’s Mikrokosmos, the Mikroetudes are Galleries built to be used in conjunction with short pieces written specifically for bitKlavier, with the intent of introducing users to bitKlavier’s features and preparations. Visit the Mikroetudes website for more information and the accompanying scores.
The middle “Action” button in the bitKlavier menu bar allows users to add new preparations. Click “Action>Add…” and choose from one of the many preparations. Each preparation can also be created with a corresponding key command, listed in the Action menu for reference. The preparation will be generated at an arbitrary location and can be dragged, moved, and connected within in the Construction Site.
Also under the Action menu is the “All Off” button, which stops all sound from bitKlavier, like a MIDI panic function. This can be useful if a Synchronic or Nostalgic preparation unintentionally begins cascading indefinitely and the source can’t immediately be pinpointed.
A number of different Pianos can be created within a given Gallery: These Pianos can be saved and located in a drop-down menu in the upper right of the bitKlavier Home Screen. For example, “Mike’s Gallery” is a single Gallery, but includes seven different Pianos with slightly different preparations and settings. The drop-down Pianomap menu allows you to navigate through different Pianos in a given Gallery. Using a Pianomap preparation, you can use Keymap signals to move between Pianos on the fly. More information on how this works can be found in the Preparations section of the manual, or number 27 in the Examples Gallery.
To the far right, a drop-down menu allows users to create, duplicate, rename, or remove Pianos from a given Gallery.
In the far upper-left corner, a small “Options” button leads to audio settings as well as saving or loading a bitKlavier state. In the Audio/MIDI settings, users can choose and test their audio output source, select a sample rate, (44.1Khz by default), buffer size (512 samples by default), and select from available active MIDI inputs. If your MIDI keyboard is not working properly, this menu is the first place to check.
Regarding the buffer size, different sizes will impact the feel of bitKlavier. A smaller buffer will result in a quicker response, but will create more of a CPU burden which could impact performance. Experiment with different values and find a setting that works for your computer and playing style. (Loading a lower-resolution sample set will not lighten the CPU burden, but will allow bitKlavier to open and load more quickly.)
Under “options,” users can save the current state of bitKlavier. This could potentially be useful when using bitKlavier as a plugin in a DAW. “Save state” saves a file of bitKlavier’s current audio/MIDI settings. “Reset to default state” tells bitKlavier to behave as if you just opened it for the first time, loading the Basic Piano and initial sample set (your preset Galleries and Pianos will not be deleted).
On OSX, there are two ways to quit bitKlavier and they aren’t quite identical. Clicking the red X at the top right corner of the app will close bitKlavier AND save the state of it, so that when you reopen it, the same sample set and gallery should open that you had when you closed. Command-q will also quit the application but will NOT save the state of it. This may change in the future.
bitKlavier for iOS
bitKlavier is available for iPhone and iPad and can be downloaded onto your device from the app store. bitKlavier for iOS uses the same windows, interfaces, and layout. One missing visual element is the mini keyboard, which has been hidden for economy of srceen space. Tap the colored audio level meter on the left-hand side of the screen, and a mini keyboard will appear.
For full iOS functionality, you’ll need:
The concept behind bitKlavier as a “prepared digital piano” is that we begin by making alterations to a Basic Piano. When using bitKlavier, we select keys and route them to different preparations so that samples will be processed in different ways. A bitKlavier Piano will have at least one Keymap preparation which selects a group of incoming key signals to be used by a linked preparation. That preparation may be: Direct (with minimal parameters such as gain, envelope, transposition), Tuning (traditional temperaments and adaptive, responsive systems), Synchronic (a customizable, adaptable sequenced pulse), or Nostalgic (reversed, sympathetic notes and clusters). Additional preparations control internal tempo parameters, such as Tempo, Modification, and Reset. If working in bitKlavier is entirely unfamiliar, check out our installation video and Basic Piano tutorial video, which provide step-by-step guides for getting familiar with bitKlavier.
To begin experimenting, add a Keymap (k) plus any other preparation, and control-click-drag to connect them. Add another preparation, a third, a fourth. Double-click a preparation to tweak its settings. You can copy or delete preparations with standard copy/paste key commands (command-c and -v), or by clicking “Action” while a preparation is selected.
To create a Gallery–a group of preset Pianos–select “new” under the Gallery tab on the right-hand side. Any number of new Pianos can be saved and stored in this new Gallery by selecting “Piano>New” in the upper right-hand corner.
Every time a preparation is added, bitKlavier creates a UI object and a corresponding preparation “under the hood.” You may, for example, experiment with several Keymap preparations and save both of them with different names. Even if you only end up using one preset, the others will remain in that Gallery within a given preparation’s settings window. Double-clicking any preparation will allow you to load settings from any previously saved preparation in that Gallery. These settings can build up fast: Using the “clean” function (“Gallery>Clean”), any saved preparation not currently in use by any Piano in the current Gallery will be deleted. So before you “clean” a bitKlavier Gallery, be sure that any presets you’ve created in that Gallery are currently being used by a Piano somewhere in that Gallery.
Envision the internal chain reaction of a traditional piano: Key, hammer, vibrating string, sound. The digital equivalent has the same conceptual components: keypress, MIDI signal, triggered sample, vibrating speaker. In bitKlavier, the preparations play back and manipulate pre-recorded samples, encompassing tuning, pitch, envelope, time, duration, and complex generative processes that trigger notes and rhythmic pulses.
There are four groups of preparations:
Keymap is one of bitKlavier’s essential control preparations. It is the starting point for understanding how the bitKlavier environment works, and the basis for every bitKlavier Piano. At the basic level, using a Keymap allows us to select and route signals from our MIDI keyboard pass through to our various bitKlavier preparations and modifications.
To begin experimenting with how Keymap functions, open the “Basic Piano” Gallery. Take a moment to note the signal flow of the Gallery: From MIDI input, the signal arrives at the Direct preparation via the Keymap, and the Tuning preparation provides temperament parameters.
Double click the Keymap preparation: You will see a popup window with a keyboard along the bottom. All 88 keys are highlighted yellow: This means that all 88 notes are being passed through to the next preparation, which in this case is the Direct preparation.
To test how the Keymap works, click C4 (middle C). It will turn white, indicating that it has been deselected. Play C4 on your MIDI keyboard, and it will not sound, while all other notes remain active. Now, click C3, and drag across the white keys on the keyboard until C5. You have just deselected two octaves of white keys: Play your MIDI keyboard, and note that for those two octaves, only the black keys produce any sound.
Keymap has several ways of selecting keys, since individually selecting and deselecting each desired key could quickly become tedious. Above the Keymap keyboard, hit “Clear” on the upper right to deselect all keys. Then, to the right of the “Select” button, choose “All… > B.” Every B on the keyboard will now be selected. Try it again with F.
There are many creative applications here, especially when using multiple Keymaps to process different parts of the keyboard. You could pair this F/B keyboard with another keyboard where every note is selected except for F and B: This means that we could prepare the F/B keyboard to make it behave in some unusual way. Imagine composing for a Piano where every F and B is actually pitched an octave higher, or those notes only play in reverse. Using Keymaps, we can easily route different MIDI notes to different destinations.
Deselecting keys is simple too. Choose “Select>All,” then change the “Select” dropdown to “Deselect” and choose “Octatonic 1.” The Octatonic 1 preset is a diminished scale beginning on A, so with those notes deselected, we end up with the notes outside of that scale, which are the notes of a Bº7 chord. Sweep your hands along the keyboard, or bring your hands down on random clusters: The only notes that sound are from Bº7 (B, D, F, Ab).
Another way to select and deselect keys is by using the “Edit All” field. This area uses MIDI values for each activated note. If you press “Clear,” then type 60 into the “Edit All” field, you will see C4 selected on the keyboard. MIDI values can be typed in or pasted here from other applications, as is the case with many parameters in bitKlavier.
It is easy to save and recall presets in all bitKlavier preparations. In Keymap, select “new” and a Keymap will be auto-named and saved in the menu to the left. This Keymap can be modified, renamed, and deleted. These saved Keymaps are saved along with the Gallery, and can be used with other Pianos in that Gallery. Go to “Gallery > Clean” to delete all unused presets.
Let’s look at a straightforward example of how using Keymaps can open creative possibilities. Begin by creating a duplicate of the Basic Piano layout in the bitKlavier environment. To do this quickly, hit (k) for Keymap, (d) for Direct preparation, and (t) for Tuning preparation. Arrange the preparations by dragging them, then link them by click-dragging while holding the command key.
Double-click the Keymap preparation on the left-hand side of the screen, and select all notes below C4. Then double-click the Keymap preparation on the right-hand side of the screen, and select all notes above C4. We’ve now divided the keyboard in half. One way to test this is by opening one of the Direct preparations and dragging the “gain” slider to a different position. This should make one half of the keyboard louder or softer, depending on which side you chose.
Try experimenting with your split keyboard. Here are some ideas:
There are many preset Galleries that include multiple Keymaps, including “And So…” and “Cygnet” in the Mikroetudes, “Wallumrod” in Nostalgic Synchronic, and Example 16 “Tuning 1.”
The purpose of the Direct preparation is to provide a minimal sampler interface, and to adjust the overall timbre and shape of the sampled sound while making no major rhythmic or timbral adjustments. It is one of bitKlavier’s core preparations alongside Nostalgic and Synchronic, and can be connected directly to a Keymap.
Double-clicking the Direct preparation will open the interface, which includes a number of sliders controlling various parameters:
* Hammer and Resonance gains are controlled by MIDI noteOff velocity. If your MIDI keyboard does not send noteOff signals, you can set your noteOn velocity as your noteOff velocity under “Gallery>Settings.”
The Direct preparation allows us to tune the bitKlavier keyboard by dragging the large Transposition slider, or double-clicking the transposition window and typing a value. The Direct preparation can be used as a harmonizer as well. Control-click to add additional voices to the slider window, or double-click the window to type multiple values, separated by a space. For an example, check out Example Gallery 21, “Direct 1.” Note: The unit for the transposition control is semitones, not cents.
The final parameter in the Direct preparation is the envelope control. Click the “edit envelope” button to open a separate window with controls for ADSR values. Units for attack, decay, and release are in milliseconds. Sustain by default goes from 0 to 1, with 1.0 being the current Direct gain. You can set this value to be greater than 1, in which case the attack will ramp up to 1, and decay will ramp up again to the given value.
As with all bitKlavier preparations, saving presets is easy and convenient. Simply click “Action” to save, rename, duplicate, delete, or clear any presets, and use the drop-down menu to the left to navigate the Gallery of presets. Your preparations are saved within the current Gallery, and can be used with other Pianos in the same Gallery. Go to “Gallery > Clean” to delete all unused presets.
Synchronic is one of the most tweakable and versatile core elements of bitKlavier. In essence, Synchronic uses MIDI input to trigger repeated pulses of notes. It’s like a cross between a delay module and step sequencer far greater playability and interactivity. Every element is customizable, from the phrasing and pitch of the Synchronic sequence to the cluster size and time threshold required to trigger a Synchronic reaction. In short, the Synchronic preparation can lead to deeply musical results in bitKlavier.
The easiest way to begin exploring Synchronic is to open the Basic Piano Gallery and add a Synchronic preparation (hit “s” or select it from the dropdown “Action > Add...” menu). Connect Synchronic to the Keymap (click-command-drag). Double-click the Synchronic preparation to open the settings panel:
A quick summary of Synchronic parameters: Note, the last five parameters are sequenced effects, each of which allows for up to 12 values (or more if manually added) which Synchronic will cycle through based on tempo.
How Many - number of Synchronic notes triggered by MIDI input
Cluster Threshold - window of time (in milliseconds) within which Synchronic will group incoming MIDI notes as a cluster
Cluster Min/Max - quantity of notes required to trigger a Synchronic gesture
Gain - volume of the Synchronic notes
Transpositions - sequenced pitch offset of Synchronic notes or clusters from ET. Values can be manually typed beyond an octave range, and diads can be added by using bracketed notation (such as [5 -3]) or control-clicking
Accents - sequenced gain adjustment of the Synchronic notes or clusters from 0% to 200%, or more if input manually
Sustain Length Multipliers - adjusts the duration of a note by dictating how much of the beat is “filled in,” so to speak. A value of -2.0 will both reverse and double the length of a single Synchronic note or chord; a value of 0.10 will produce a note of 1/10 the expected duration.
Beat Length Multipliers - adjusts the actual length of each beat and time between successive notes, controlling the speed at which the rest of the parameters step through their values. Technically, it divides the tempo, or multiplies the distance between consecutive downbeats. Example: If Beat Length is 0.5 the pulse will change from 120 to 240bpm; Sustain Length of 0.25 will result will be 8th notes at 240bpm.
Envelopes - using Synchronic, you can sequence through different ADSR envelope settings. The red square indicates the currently active envelope; the sequencer is synchronized with the other Synchronic parameters.
Using the default Synchronic settings, play any note and you’ll hear it repeat on a fixed metronomic pulse. Reading through the settings gives us an overall picture of what is happening: When any cluster of 1-12 notes is played within the space of 500 milliseconds, it triggers 20 Synchronic repeats, none of which are transposed, sequenced, or otherwise manipulated in any way. Start manipulating settings; notice how things change!
The “how many” slider indicates the number of Synchronic notes triggered by MIDI input. Default value is 20. Change this value to a number under 5 (by dragging the slider or double-clicking and typing into the text field), play a cluster of notes, and count while listening as the Synchronic notes play one by one. A blue bar under the “how many” slider indicates process from the first to last Synchronic pulse. The lowest possible value is 1, which produces a one-time repeat of the cluster notes. The highest value is 100, so Synchronic can essentially repeat a cluster once, semi-indefinitely, or any number of times in between.
The Cluster Threshold parameter helps differentiate Synchronic from a standard delay effect or MIDI sequencer. If notes are played within the time indicated by the Cluster Threshold, they will be grouped together as a Synchronic sequence. And as long as the time between notes remains under the Cluster Threshold, new notes will continue to be added to the cluster. For example, with the Cluster Threshold set to 2000ms, any cluster of notes played within 2 seconds becomes a Synchronic pulse. Synchronic essentially has a running timer that resets every time a note is played: If the timer runs out of time before you play a new note (ie. exceeds the cluster threshold), then a new cluster begins. Otherwise, the new note is added to the current cluster, and the timer is reset. You can observe how this is working in real time by looking at the blue progress bars under “how many” and “cluster threshold” in Synchronic.
Controlling what will and will not be included in a Synchronic cluster can be a powerful compositional tool. If you’re playing a fast phrase, they may easily be included in the same cluster. This can be done rather loosely: For example, setting the cluster to <50ms will mean that only very fast notes get clustered together, and >5000ms means most notes will be clustered together. This could also be done very deliberately: If the tempo is set to 120bpm, than any group of four eighth notes played in time will become a Synchronic cluster. Taking into account adaptive Tempo preparation, the possibilities are vast.
In Synchronic, you can choose precisely how many notes played within a certain amount of time will define a “cluster.” Default is 1-12, meaning that any number of notes up to 12 will trigger a Synchronic reaction. However, this parameter can be used to specify one or several values: With the Cluster Threshold set to 1000 (1 second), set both the min and max cluster number to 7, and play around a bit. When you play a 7-note cluster, either a chord or melodic line played within 1 second, the Synchronic pulse will be triggered. Playing any more or fewer than 7 notes within 1 second will cause the threshold counter will reset.
The Min cluster value can be greater than the Max, creating a zone within which a certain number of notes will not trigger a Synchronic sequence. For example, if Min is 4 and Max is 2, then one, two, or four notes can start a pulse, but three will not. You could use this, for example, to have a constant Synchronic pulse where any triad will bring the sequence to a stop.
bitKlavier currently caps the number of notes in a cluster at 8. Let's say Cluster Max is 10: If you play a chord or arpeggio of 9 notes, a cluster will begin, but that cluster will only have 8 notes. This limit currently exists so as not to overload bitKlavier, but this cap will soon be an adjustable parameter so users can dictate how many notes Synchronic will record.
Open Example Gallery "Synchronic 1" and play rapid (notes less than 500ms separated) scales of various lengths; a scale of 20 notes will begin playing after you stop, but only the last 8 notes you played will be included in the cluster. Now set it to First Note-On mode, and play the same ascending and descending scales; you'll hear the cluster change over time, shadowing the register of your scale.
The gain slider at the bottom left of the Synchronic preparation controls only the gain of the triggered Synchronic notes or chords. It is essentially a multiplier for the MIDI velocity. If you play a pianissimo note with a Gain value of 2.0, the Synchronic sequence will play back at twice the gain. If you play multiple notes within the cluster threshold time, each notes will retain its relative value, each independently scaled by the Gain multiplier.
One of five sequenced effects, the Transpositions sequencer determines how the Synchronic pitch will shift over time. Each column from L-R represents absolute semitone offset from the played pitch. A sequence of 0 1 2 3 4 5 6 7 8 9 10 11 12 will play an ascending chromatic scale.
To begin exploring the Transposition setting, drag the single bar on the far left up until it reads 2.0 (you can also double-click the Transposition box and manually enter the value). Play A4, and note that after the initial MIDI input, every Synchronic note will be B4 (A4 + 2.0 semitones).
In the next column to the right, click and drag a bar with value -1.0 (this can also be done by double-clicking the Transposition box and entering a second value, separated by a single space). Play A4 again, and observe that for the duration of the Synchronic repeats (20 by default), the pitch will go between B4 and G#3 (A4 + 2.0 semitones, then A4 - 1.0 semitone).
As you can probably guess, using the Transpositions sequencer can lead to some wild results. Double-click the Transposition box near the left-hand side and copy the following values:
0 12 19.02 24 27.86 31.02 33.69 36
Play a single note, and the Synchronic preparation will cycle that note through the first values of the harmonic series. Try this with chords, arpeggios, clusters. Try adding a (-) to every value to hear the undertone series. Experiment with values that go in both directions to create an oscillation: Copy the following sequence of values, then play a sustained note or cluster and listen to how pitches go in and out of phase with one another:
0 0.2 0.4 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.4 -0.2
Aside from dragging individual bars, or inputting numerical values for each step, you can click and drag more gesturally to create a shape. Here’s the result of randomly dragging the mouse from one side of the Transpositions window to the other:
Multiple transpositions can be added for each sequenced step: Any values within a set of brackets (like [-5.5 3.0] or [2 4 7]) will be interpreted as a cluster. You can control-click to add a new transposition, and can add more than 12 values (the window will automatically re-scale).
The Accents setting uses the same principle of the Transpositions setting in that we program a series of values through which bitKlavier’s Synchronic preparation can cycle. Let’s start with a blank slate: Go to the Action button near the upper-middle of the Synchronic settings window and select “clear” to return to Synchronic’s default settings. Now, draw a rough amplitude ramp by clicking in the lower-left and dragging to the upper-right:
By default the lowest value in the window will be 0.0, meaning no amplitude at all, and the highest value will be 2.0, or double the amplitude. Values for Accents are multiplied in relation to the initial MIDI velocity value and are not cumulative. If you have a value of, say, 1.0, 1.0, 1.0, you won’t end up with a final note with velocity 3.0 - instead, you’ll have three notes of the same initial velocity.
By double-clicking the Accents box, you can input values greater than 2.0, which will automatically change the visual scale of the other bars. This isn’t necessarily recommended because high amplitude values could make the samples clip during playback, but for a piece that’s largely pianissimo (MIDI velocity <15.0 or so), it could be very effective to have one periodic loud accent. You can also add more cells/steps by typing more values in the edit field.
Using the same interface as Transpositions and Accents, the Sustain Length Multipliers sequences through values for “sustain” in the ADSR envelope, with negative values reversing the note. A value of -2.0 will reverse and double the length of a given Synchronic note or chord, and a value of 0.10 will produce a note of 1/10 the expected duration. Try the following example values to hear the effect of the Sustain Length Multipliers more acutely:
Example 1: Ramp from 2.0 Reverse to 2.0 Normal
-2 -1.5 -1 -0.5 0 0.5 1 1.5 2
Example 2: Dash Dot Dot Dot, Reverse, Dash Dot Dot Dot
1 3 0.5 0.5 0.5 0.5 -3 0.25 0.25 0.25 0.25
Changing the Synchronic beat length is a drastic effect, allowing the user to deviate from the metronomic pulse of the preparation. By default the value is 1.0, which is 120bpm until we change it using a Tempo preparation (more on that soon). Any deviation from 1.0 is a multiplier of the quarter note value. Try setting the second column to 2.0, a half note, and listen to how the pulse shifts from ||: quarter-quarter :|| to ||: quarter-half :||
Copy and paste this sequence to have a Synchronic sequence of a recognizable rhythm:
1 1 2 1 1 2 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 1 1 2
Here’s a custom sequence of numbers used to simulate a sort of strumming pattern:
0.8 0.1 0.02 0.02 0.02 0.02 0.02
Note: Entering a negative value in the Synchronic beat length multiplier window will cause the Synchronic preparation to stop working. Synchronic cannot parse a beat length with value less than 0.
The “skip first” feature tells Synchronic to jump over the first value in all of the sequenced parameters on the first pass (Transposition, Accent, Sustain Length Multipliers, Beat Length Multipliers, Envelopes). This is useful for when you want the “downbeat” to be exactly what you play, rather than arriving one pulse after you play it. “On” is the more common setting and is used in most Synchronic Example Galleries. Compare Synchronic Examples 1 and 8 (Skip First on) with Examples 2 and 9 (Skip First off).
Four drop-down options determine where the Synchronic pulse begins, based on MIDI note-on and note-off signals:
When you play a series of notes within the cluster threshold, the phase (new downbeat) of the Synchronic pulse will be set by the timing of the first note-on signal recorded within the cluster.
The phase of the pulse will be set by the timing of the most recent note played within the cluster. If the cluster threshold is less than the period set by Tempo, then you won't hear a pulse until you stop playing notes. If the tempo is high (say, 250bpm, when the cluster threshold is 500ms), you will hear pulses while you are still adding to the cluster, but the phase will constantly be reset since the pulse is restarting based on the most recent note-on signal.
When you play a series of notes within the cluster threshold, the phase of the pulse will be set by the release of the last note played, regardless of whether it’s within the cluster time. In this case, the cluster threshold is still determining which notes are included in the threshold, but you’ll only hear them when you release the final held-down note. For example, if you play a single note, the Synchronic sequence won’t begin until you release that note. Try playing an arpeggio, low to high: The pulse will only begin when the highest note is released.
When you play a series of notes within the cluster threshold, the phase of the pulse will be set by the release of the most recent note played within the cluster. To test this, play a chord and release notes one by one: You’ll hear the pulse readjust as each successive note-off signal is registered.
Twelve boxes along the bottom right each include their own envelope settings. Using Synchronic, you can program and sequence various envelope settings in conjunction with other sequenced settings. Click any box to open an ADSR settings panel; when you adjust any of the sliders, they will go from greyed-out to bright, and this envelope will be toggled on. Press “close” to leave the ADSR view. Shift-click on individual boxes to turn on/off individual envelopes.
When a Synchronic reaction is triggered, bitKlavier will step through these envelope values just like any other setting. The currently active one will be in red.
• • •
Synchronic is a powerful tool and is used throughout Dan Trueman’s Nostalgic Synchronic and the Mikroetudes written specifically for bitKlavier. Synchronic is also featured in many of the lessons and examples from Dan Trueman’s “Reinventing The Piano” online Kadenze course. For more information and inspiration on using Synchronic in bitKlavier, check out the above links, as well as the Synchronic Examples in the bitKlavier Galleries.
The Tempo preparation provides control to any connected Synchronic preparation in bitKlavier, just like the Tuning preparation alters the Direct and Keymap preparations. There are two Tempo settings, Constant Tempo and Adaptive Tempo. To begin using the Tempo preparation, build the Basic Piano, add a Synchronic preparation, then create a Tempo preparation – key command (m) – and connect it to Synchronic. The Tempo preparation now controls that Synchronic preparation: If using multiple Synchronic preparations, a single Tempo preparation can control all of them, or each Synchronic preparation could use its own individual Tempo preparation. Tempo only controls the preparations to which it is connected.
A single slider controls metronome values from 40.0 to 208.0, or any higher/lower positive value can be typed into the window. Play a note to trigger a Synchronic pulse, then adjust the slider to hear how Tempo changes the Synchronic speed.
Adaptive Tempo determines the pace of a Synchronic sequence by taking a running average of the time between user-played notes. Adaptive Tempo will only work if it is attached to a Synchronic preparation and a Keymap preparation, because the input from the Keymap provides information that adapts the tempo to your playing.
Adaptive Tempo Settings:
For more information on how to use the Adaptive Tempo feature, load the corresponding example Pianos from the Examples Gallery (Adaptive Tempo 1-4, Examples 23-26) and explore how they function.
When using bitKlavier as a plugin, choosing “Host Tempo” will enable bitKlavier to follow tempo changes of the host directly.
The Nostalgic preparation is another way that the digital prepared piano looks beyond the on/off binary that a traditional acoustic piano key represents. One of bitKlavier’s core preparations, Nostalgic allows bitKlavier users to program notes that play in reverse when a key is lifted. Alongside the Synchronic preparation, bitKlavier’s Nostalgic preparation provides a feature-rich set of parameters that control the volume, swell, and precise sound of the instrument after notes have already been played.
Nostalgic, like Synchronic and Direct, can be used directly with a Keymap to produce sound. Check out Example 22, “Direct 2,” which uses Nostalgic as a Piano where all the samples are played in reverse upon lifting a key.
To dive in, add a Nostalgic preparation to the Basic Piano – key command (n) – and connect it to the Keymap preparation. Double-click on the Nostalgic preparation to open the settings panel. A brief overview of the parameters, moving clockwise from the upper-right:
Note Length Multiplier - takes value of note duration and multiplies it. A whole note at 60bpm will have a value of 4 seconds: With multiplier at 2.0, Nostalgic response will be 8 seconds.
Gain - controls the volume of the Nostalgic response. A MIDI note or chord of velocity 50 with Gain set at 1.5 will result in a Nostalgic response of 75.
Wave Distance - controls the start and end point of the Nostalgic playback, in milliseconds from the beginning of the sample. This value can be dragged from left to right or double-click to add a numerical value. Change this value to 500 and observe that the Nostalgic response, while still equal to the duration of the initial note, starts and ends .5 seconds before the head of the sample.
Undertow - provides a fixed value for a second Nostalgic response after the initial reversed sample. Units are also in milliseconds, and the undertow begins wherever the Wave distance is set. Change the undertow value to 500 and observe that after the Nostalgic response, there will be a .5 second bounceback of the sample.
Edit Reverse Envelope / Edit Undertow Envelope - provides ADSR control of both the Nostalgic response and the undertow.
Transpositions - controls the pitch of the Nostalgic response and undertow. Note, multiple values can be added to create clusters of Nostalgic notes.
The Nostalgic preparation is highly interactive and customizable. A blue tracker line in the Nostalgic waveform window provides real-time indication of how Nostalgic is moving through the sample. Other settings also provide a visual indication of how Nostalgic is altering the sound.
For every MIDI key off, a new Nostalgic note is created, and every note in the attached Keymap preparation will have a Nostalgic response. In the default mode (Note Length), a timer begins as soon as a key is pressed: When that key is lifted, that same duration is applied to the Nostalgic note. This can easily be observed by playing several notes, holding them, and lifting them one at a time. The same is true of Undertow notes too (more on that below). For more clarity while learning how Nostalgic works, adjust the Transposition to an obvious interval (such as +2.0 semitones) and listen back to how and when the Nostalgic notes occur.
In Synchronic Sync modes, as opposed to Note Length modes, the length of held notes does not matter, since the Nostalgic duration is set be the relationship between noteOn signals and the Synchronic pulse. More on that in the Synchronic Key Up/Down section below.
You can choose how long you want your Nostalgic notes to be as a function of the duration of the input note (defined as the time between MIDI key down and MIDI key up). If you strike a key and release it 1 second later, the Nostalgic response will have that same duration of 1 second. The Note Length Multiplier multiplies the note duration when applying it to a Nostalgic wave. A whole note at 60bpm will have a value of 4 seconds: With a multiplier of 2.0, the Nostalgic response will be 8 seconds. This can be used to create very short Nostalgic responses too.
Note Length Multiplier is the only parameter that controls the actual length of Nostalgic notes. Wave Distance and Undertow control the start and end points of the sample, but the duration is entirely controlled by the Note Length Multiplier when in Note Length mode.
Gain controls the volume of the Nostalgic response. A MIDI note or chord of velocity 50 with Gain set at 1.5 will result in a Nostalgic velocity of 75. This can be used to create Nostalgic notes and clusters that are faint, thunderous, and everything in between.
The slider above the Nostalgic waveform window controls the start and end point of the Nostalgic playback in milliseconds from the beginning of the sample. This value can be dragged from left to right. As usual, double-click to add a numerical value. Changing this value alters the location of the blue tracker line, which indicates the end point of the Nostalgic wave.
Change the Wave Distance value to 500 and observe that the Nostalgic response, while still equal to the duration of the initial note, starts and ends .5 seconds before the head of the sample. If you play a note of around one second in length, the blue line will travel for one second until it reaches the end point indicated by the Wave Distance parameter.
Using the Nostalgic preparation, we can have an “undertow” response as well, which provides a second, forward-motion playback of the sample after the initial Nostalgic notes. Undertow begins precisely where Nostalgic ends, as indicated by the Wave Distance parameter.
The slider for Undertow beneath the Nostalgic waveform determines the fixed length of the Undertow in milliseconds. When Undertow is set above 0, every Nostalgic note will have a corresponding Undertow. The Undertow will last only the length you indicate: It does not change with Note Length or Synchronic Sync settings. An Undertow of 1000ms will last 1 second after the Nostalgic cluster has ended, regardless of the length of the Nostalgic notes.
Set the Undertow slider to a value above 250ms, play a note, and watch the blue tracker line: At the end of the Nostalgic wave, the line will bounce back to the right as it plays through the sample again for one quarter of a second. Play a triad, release the notes one at a time, and observe how each Undertow is generated independently.
You can control ADSR values for Nostalgic and Undertow by using the bitKlavier envelope interface. For a clear example, try some fairly intense settings. With the following values, you won’t be able to discern the end of a Nostalgic wave from the beginning of the Undertow:
Reverse Envelope: Attack (700), Decay (600), Sustain (.6), Release (400)
Undertow Envelope: Attack (500), Decay (700), Sustain (.8), Release (500)
It’s important to note that envelopes always run forward in time, even when being applied to the Nostalgic note, which plays in reverse. In other words, Attack is applied as the reversed note begins, not at the “attack” of the original sample. To control the crossfade between Reverse and Undertow notes, you’d adjust the Reverse Release and the Undertow Attack times.
Nostalgic and Undertow don’t have to be the same pitchs as the notes that triggered them. Simply drag the slider to adjust the pitch of the Nostalgic note. This could be a subtle effect, such as having the Nostalgic response be pitched ever-so-slightly lower than the initial input, or a drastic effect, creating crashing chords and dense clusters.
As with many bitKlavier parameters, double-clicking the Transposition window in the Nostalgic preparation allows for additional values. Type or paste (-12 7.0 12) to have a Nostalgic cluster response of an octave lower, a fifth higher, and an octave higher from the initial pitch. Copy the following values to have Nostalgic generate the first eight overtones of the harmonic series:
0 12 19 24.02 27.86 31.02 33.69 36
The Synchronic Sync KeyDown/KeyUp modes control the length of the Nostalgic swell based on a the pulse of a linked Synchronic preparation. Nostalgic must be connected to a Synchronic preparation in the same Gallery for Sync mode to work: If Nostalgic is not connected to Synchronic, only the Undertow will play.
In KeyUp mode, the Nostalgic note or cluster begins when the key is released, as it does in Note Length mode, and peaks in tandem with the next Synchronic beat (or later, depending on “beats to skip” slider). In KeyDown mode, the Nostalgic note or cluster begins as soon as the key is pressed, and will peak at the next Synchronic beat (or later, depending on “beats to skip”).
Check out the Example Galleries Nostalgic 4-6, or “Hurra” from Mikroetudes, for examples of how to use the Sync mode between Nostalgic and Synchronic.
For more information on using Nostalgic, check out the corresponding sessions in the “Reinventing The Piano” Kadenze Course, as well as the Nostalgic Synchronic etudes.
The Tuning preparation is another of the control features which sets bitKlavier apart from both the acoustic piano and the more conventional sampler. Tuning provides a hugely flexible array of musical and compositional opportunities, from creating and manipulating a custom temperament to manually editing the precise pitch of every key on the keyboard.
To begin exploring the Tuning preparation, open the “Basic Piano” and double-click the Tuning preparation, which looks like a green tuning fork. There are a series of dropdown menus and buttons on the left-hand side that should be familiar from the other preparations. “Action” allows us to manage presets and other global actions, including saving and naming presets, clearing the settings, and duplicating the preparation.
Summary of Tuning settings:
Action menu – menu in the upper-left allows for saving and naming Tuning presets
Spiral toggle – open/close the “spiral” view for tuning relationships
Adaptive tuning menu – currently active adaptive tuning system (if any)
Temperament menu – menu in the upper-middle of screen includes many preset temperaments which will be loaded into the temperament keyboard. See Appendix for Tuning details.
Root menu – determines pitch to serve as the root from which the temperament is generated
Temperament keyboard - graphic interface where each note of the one-octave temperament can be manually adjusted or typed into the “edit all” menu
Offset – transposition from system tuning (default 440hz, can be changed in Gallery > Settings)
Semitone width and root – defines “semitone,” which by default is 100 cents. 50 will be a quarter-tone keyboard. Root tells which note to begin on - if root is A4, then A4 will be tuned to system settings (440hz by default), regardless of semitone width
Tuning Keyboard – a full 88-key keyboard along the bottom allows you to tune each note of the keyboard manually, by click-dragging or entering the values manually. The format is “MIDI note: cent value” (no quotations), so 60: -10.5 will lower C4 by 10.5 cents
Let’s start by looking at the Temperament section on the right-hand side of the Tuning preparation window. To review, a temperament is essentially a one-octave tuning scheme that adjusts certain intervals in order to prioritize consonance between them. A temperament is repeated every octave of the keyboard. The root of the temperament can be determined by the user — more on that soon.
The drop-down menu to the second-from-right contains presets for different tunings. Full charts for these tunings are located in the Appendix at the end of the manual. The default temperament is Equal Temperament: Click the drop-down menu and select “Just” temperament. Note how the temperament keyboard will visually change to reflect how each interval has been tuned from Equal Temperament. Blue means flat, Red means sharp, and the intensity of the color reflects the degree to which a pitch has been raised or lowered from ET.
Each key can be manually adjusted: Go back to Equal Temperament, click D, and begin to drag up while holding the mouse down. Notice that several things change: As the D becomes more red to indicate a rise in pitch, the temperament changes from Equal Temperament to Custom. The pitch of each key can also be changed by clicking at various locations on the surface of each key.
The “cents from ET” window at the upper end of the temperament keyboard, which shows the specific amount the pitch has been altered, changes in real time as well. Play along the keyboard, and notice that every D is now pitched quite a bit higher.
Let’s say we want to create a temperament where every G is lowered by 8 cents. Simply select G on the temperament keyboard and type -8.0 into the “scale” window. Now play C5 and G5 on your MIDI keyboard, and note that 5th doesn’t sound quite as “perfect” as it does in ET. Go along the keyboard and you will find that every G is now slightly lower.
You’ll notice an asterisk on C. This indicates that C is the root, meaning that the temperament is generated using a fixed scheme of offsets beginning on C. Try selecting Duodene from the drop-down menu. Notice that the first few notes of the temperament are slightly raised, while the last few notes of the temperament are slightly lowered. Now, change the root of the temperament to E, and notice how this pattern is translated 4 semitones higher.
For greater depth and control, all 12 notes in a temperament can be quickly edited via a text field. With Equal Temperament selected, click “Edit all” to reveal a field of 0s. Each of these corresponds to the current pitch value of each ascending note in the temperament.
Change the first few numbers and click “Edit all” again (or press the return key) to view the temperament keyboard; note the visual changes based on the values you typed.
A slider below the temperament keyboard moves the entire pitch of the keyboard up or down. To quickly raise the pitch of the keyboard, move the slider to the right, or change the “offset” pitch to a higher number (the unit is cents). Type 100 or -100 into the “offset” box to immediately raise or lower the temperament keyboard a semitone.
Changing the semitone width in bitKlavier can lead to some wild results. Semitone width simply translates to “number of cents in every semitone,” or half step. By default, this value is 100. Changing this value to 200 means that every semitone on the keyboard is now a whole step. By extreme contrast, changing this value to -100 inverts the keyboard. As you ascend the physical keyboard, the pitch becomes lower.
Of course, the “semitone width” feature can be used in more subtle ways as well. Change the value to 102, which adds 2 cents to every semitone. Over two octaves, the notes are spaced +48 cents apart, nearly a quarter-tone. This could be a subtle effect or a powerful compositional device depending on your application and intention. Note that the semitone width applies to the entire range of the keys selected in the Keymap preparation. To have a segment of the keyboard with a different semitone width, you will need to create two Keymaps with different ranges or pitches selected, and route them to different Tuning preparations.
Adjusting the semitone width while also using a non-Equal Temperament system has some wild results. For example, if you create a quarter-tone Piano using a semitone value of 50c, try setting the tuning to Just intonation. When you play C4 to Ab4, ordinarily a minor sixth, you’ll end up with a Just-tuned major third. Check out the Tuning and Temperament session from “Reinventing the Piano” for more information.
Under “semitone width” there is also a drop-down menu for “semitone root.” This sets a specific note to Equal Temperament as a starting point for a non-100-cent semitone scheme. By default, C4 will sound at ET as expected, with subsequent half-steps generated from there. But any pitch can serve as that initial reference, and can actually change the range of available notes on the keyboard.
For example, Set the semitone width to 50, creating a quarter-tone keyboard, and play some notes around middle C. Then change the root to D4. In the first case, C will actually sound a C, and in the second D will actually sound a D.
Another example: Let’s say you want to perform with a violinist who tunes to A440, but you want to use a quarter-tone Piano. If you set the semitone width to 50, simply set the root to A4, so that A4 can be used to “tune” bitKlavier. Starting on A4, the violin and bitKlavier will both be at 440hz, then the bK keyboard will be in quarter-tones above and below the new root of A4.
Note that the root is only relevant if the semitone width is significantly larger or smaller than 100. At 101 or 99, you won’t hear much of a change within the few surrounding octaves.
Along the bottom of the Tuning preparation there is a full 88-key keyboard. As in the Keymap preparation, each key corresponds to exactly one pitch, so unlike editing on the Temperament keyboard, any edits made on the lower keyboard will apply to a single pitch. Think of this as absolute tuning versus circular tuning: Tuning by temperament is circular (repeated every octave), while tuning individual notes is absolute tuning and is not translated or repeated anywhere else on the keyboard.
Any key along the bottom keyboard can be individually tuned by click-dragging, by clicking at a certain location on the surface of the key, or by adjusting the pitch in the “absolute” box to the upper right of the keyboard. Here’s the result of some random clicking:
Note that when you mouse over the lower keyboard, the note’s relative offset will appear in the “absolute” box.
IMPORTANT: any changes made to the absolute tuning of the keyboard happen in addition to the existing temperament! Example: If every E is raised 14 cents in the temperament, and E4 is lowered by 8 cents on the absolute keyboard, then E4 will still be 6 cents sharp, while every other E will still be 14 cents sharp.
For more control, each key can be individually edited in a text field. Open the “Edit All” field and type 60:-13.7 in the empty space. Press return or hit “Edit All” again to return to the keyboard view; you will see that middle C (MIDI value 60) has been lowered -13.7 cents relative to the temperament tuning. This makes it easy to edit note values. These values can be copied into bitKlavier from other programs.
The spiral provides a way to visual the tuning relationships of currently active notes. For this to work, in your Piano, Keymap must be connected to Tuning as well as Direct, so that Tuning knows what notes to display in real time.
The spiral begins inside with the lowest note on the piano and gradually circles outwards to the highest note. Active notes appear as circles near the equal-tempered references, with numbers indicating how far they diverge from ET, and lines between notes show the interval between them, in cents.
Loosely inspired by Erv Wilson’s logarithmic spiral, the motivations for having the spiral will become evident later when we look at spring tuning, but even just as a way to quickly see how notes are tuned it is quite useful.
Temperaments are fixed systems. We can pre-plan changes on the fly using Piano maps and Modifications, but conceptually, temperaments are inherently static. By contrast, adaptive tunings change in direct response to what you play. The tuning and temperament continuously regenerate based on your playing via a limited set of constraints. While these processes can be used to create “optimal” tunings–systems that minimize idiosyncratic intervals–based on your playing, they are also intended for exploration and play, and as such can yield unexpected results. bitKlavier currently has three basic flavors of adaptive tuning.
With both Adaptive Tuning 1 and Adaptive Anchored Tuning 1, the fundamental (root) of the established adaptive scale (set with the menu to the left of the Tuning window) will shift automatically, either after a certain number of notes have been played (the Maximum slider parameter) or after a certain amount of time has passed (the Threshold slider parameter). Each note is immediately re-tuned based on a moving fundamental, and various parameters determine when the fundamental should move and where it should move. In your Piano, Keymap must be connected to Tuning as well as Direct, so that Tuning knows what notes to adjust in real time.
In the Adaptive Anchored system, when either of the adaptive parameters are exceeded (Maximum or Threshold), the fundamental will change to the tuning determined by the “Anchor” scale, located in the bottom left of the Tuning window:
To begin, set Maximum to 1, meaning that the fundamental will reset with every note played. Set “Threshold” to 1000 (for reasons to be clear shortly), “Adaptive scale” to Just, and “Anchor scale” to Equal Tempered. Now, play an ascending scale. You should hear an Equal Tempered scale where the “current fundamental” changes to a new integer value with each note you play. You should also see that the “note” (to the bottom left about the big keyboard) is always an integer (Equal Tempered) value.
Now set Maximum to 2 and try playing a scale again. As long as each note is within 1000ms of the previous note, you should see the “current fundamental” change with every other note played, and that the “note” values of the in-between notes will have some fractional value; this is where the system starts to kick in. With these same settings, try this:
In (1) C4 is the fundamental, so the Bb is tuned as a 7/4 minor-7th above C, which is about 31 cents flatter than an Equal Tempered minor-7th.
In (2) D4 is the fundamental, so the Bb is tuned as a 8/5 minor-6th above D, which is about 14 cents sharp to Equal Temperament, so it sounds nearly a quarter-tone sharp to the Bb in (1).
Next, set Maximum to 4 and play this pattern over and over again: C4-Bb5-D4-Bb5; in this case the Bb should always sound the same because the fundamental (60.0) does not change to D4 mid-pattern. Play with this and other settings while monitoring the “current fundamental” and “note” values to learn more about how it is working.
Select Adaptive Tuning 1, and you’ll notice the Anchor scale menus disappear. The next adapted note will now become the new “anchor,” which will continuously change while playing. Set Maximum back to 1 and play an ascending scale; you should see that the “current fundamental” gets reset with every note played (as before) and that its value is always the same as the “note” tuning.
This is where things can get strange and fun! Play this pattern over and over again:
||: C4-D4-E4 :||
Why does the pitch drift up? Every note is being tuned with the prior note as the fundamental. We begin with two whole steps, each tuned as the first whole step in a Just scale (interval = 2.039, slightly larger than two ET half steps), followed by a descending major-third, also tuned as it would be in a Just scale (interval = -3.863, so slightly smaller than four Equal Tempered half-steps). The two just-tuned whole-steps yield a major third that is larger than the just tuned major-third, so the whole system begins to drift upwards.
Try this pattern, and hear how the pitch drifts down:
||: E4-D4-C4 :||
If the “invert” toggle is checked, the downward drift should move at the same pace as the upward drift from the prior example, because Tuning will consider both ascending and descending intervals as the same (a whole-step is a whole step, whether going up or down). But with “invert” unchecked, the second example will drift down more quickly than the first. This is because, in short, the downward Just-tuned whole step is treated like the minor-7th of the Just scale, which is a much bigger whole step than the upward whole step. For a temperament with some slight differences, try the Duodene scale. Feel free to refer to the Appendix at the end of this manual for how each pre-programmed bitKlavier interval is tuned.
To further explore the Adaptive Tuning feature, load Example Gallery 17, “Tuning 2.” Instructions for how to begin using the Adaptive Tuning settings are written directly into the Gallery. Adjust the maximum number of pitches, time threshold, and adaptive temperament, each of which helps to determine how and when the Tuning preparation will shift based on Keymap input. Also, check out the Mikroetude called Didymus, which uses Resets to manually anchor the Adaptive Tuning.
Adaptive tuning is a wide-open field of study, and these two approaches (Adaptive & Adaptive Anchored) are meant to be more exploratory than “solutions” that always yield some kind of optimal or neutral tuning. While Adaptive Tuning systems may be used to create consistent optimal tunings, systems with their own idiosyncrasies create valuable compositional opportunities, and these Adaptive Tunings can be used to satisfy either goal. We are currently exploring a range of richer systems, including the spring tuning system described next.
Some years ago, John de Laubenfels proposed an intriguing system for optimizing the tuning of sonorities. This system is detailed in William Sethares’ book Tuning Timbre Spectrum Scale, but was never to our knowledge fully implemented (though recently Stange, et al. created a similar system). Our implementation is largely inspired by de Laubenfels, though is not identical, and is also different in key ways from Stange’s system, discussion of which is beyond the scope of this manual.
As with the other adaptive systems, in your Piano, Keymap must be connected to Tuning as well as Direct, so that Tuning knows what notes to activate in the spring system.
The key concept is that intervals are modeled by virtual springs with rest lengths determined by a chosen tuning system (usually just). So, a major third would typically have a rest spring length of 386 cents, a perfect fifth a rest length of 702 cents, and so on. When more than two notes are played, springs of the appropriate length are connected between them all, and they pull on one another until they reach a condition where each is minimally stretched or compressed, optimizing the tuning. The relative strengths of the various intervals can be set, so, say, major third springs are stronger than, say, perfect fifth springs, and the system will respond accordingly.
In addition, a background set of “anchor notes” (represented by the spiral) is connected to active notes via another set of springs, which help prevent the system from drifting. In the image above, the anchor scale is equal tempered (as set by the top-most menu) and the interval scale that sets the default lengths of the interval springs is just (as set by the menu just below the anchor scale menu). The relative strengths of the springs to the anchor notes can also be set, allowing some pitches to be favored and others to be totally unmoored, if desired; in the above image, all the interval and anchor springs are set to equal strengths of 0.5, slightly distorting the tuning of the intervals, while in the following image only the C anchor spring is “on,” so the triad is more perfectly tuned:
The overall stiffness of the interval and anchor springs affects the dynamics of the system, causing the springs to vibrate more or less quickly, and the drag models a kind of friction in the system (imagine the notes being dragged through molasses), damping the spring oscillations. Finally, the rate (in Hz) determines how often the spring model runs. All four of these parameters can be adjusted to create a wide range of different responses, from slowly oscillating systems to almost inaudible and instantaneous tunings.
One of the more complex components of this system is the interval scale fundamental:
When set to “none,” the behavior is as described so far, where the resting length for a spring is set only with regards to the interval between its two pitches. So, for example, every M2nd spring will be set to 204c when using the just scale, which has a 9/8 M2nd between the root and M2nd:
In this case, if you play a C-D-E trichord, the D will be squeezed by its springs on either side, and it will in turn push the C-E M3rd a bit wide. Here is the M3rd by itself:
And now with the D inserted between:
If we set the interval scale fundamental to C, however, the D-E M2nd will use the 10/9 ratio (386 - 204 = 182c, from the table above) of that just scale (which is the ratio between the major 2nd and 3rd in that scale; 9/8 * 10/9 = 5/4), so all the springs will naturally sit at their rest lengths:
Setting the fundamental to “lowest” will use the lowest sounding note for the fundamental, and
“highest” the highest sounding note, while “last” will use the last played note; all can yield interesting behaviors with compositional possibilities.
Another example: try playing a C4 dominant 7th chord using “last” as the interval scale fundamental (and setting the anchor spring strengths to zero for the E4, G4 and Bb4), and compare the sound of the chord when arpeggiating it upwards vs downwards; can you figure out why these sound different?
Here’s what it should look like after playing the chord ascending:
Finally, when using these various fundamentals, the spring tuning system will always treat the P5, P4, and M3 as if the mode were “none.” This ensures that we never use “wolf” fifths or the really sharp “Pythagorean” thirds that crop up in these systems. So, for instance, in C-just, the D-A fifth is very small (64/45, instead of 3/2, or 884 - 204 = 680c from the table above); rather than use fifths like that (or similarly unjust fourths and major thirds), bitKlavier will use just 3/2 (702c) fifths.
We will be writing more about these design choices and tuning more generally in an upcoming paper about bitKlavier. We recommend exploring the example galleries for spring tuning to get a sense of how it might be used.
We can make temporary changes to preparations based on Keymap input. Creating a Modification generates a neutral gray triangle, which can be connected to any of five preparations (Tuning, Tempo, Synchronic, Nostalgic, Direct). The color of the Modification will change to reflect the preparation it is modifying.
In the Basic Piano, create a Modification and connect it to the Direct preparation (it will turn orange). Double-click the Modification and you will see that it is essentially a Direct preparation with all of the parameters grayed out. If you make a change to any parameter, it will become highlighted indicated the modification you’ve made. This modification will apply its new settings to the attached preparation only when it receives an initial Keymap signal.
As with all bitKlavier preparations, you can save Modification presets within the preparation interface. Examples using Modifications include “Tuning 1” as well as “Undertow,” “Marbles,” “Wallumrod,” and “Systerslaat” in Nostalgic Synchronic.
Reset is essentially the reverse of Modification: Upon receiving a signal from an attached Keymap, a Reset will bring an attached preparation to its default state. “Tuning 2” in the Example Galleries uses a Reset.
The Piano Map preparation allows us to move through different Pianos in the same Gallery purely by using Keymap input. This could be used mid-performance to switch between movements, or while experimenting in bitKlavier with two different Piano presets.
When a Piano Map is created, double-click to reveal a drop-down menu including all of the Pianos in that Gallery. When the Piano Map is set to a specific Piano, bitKlavier will automatically switch to the selected Piano after receiving any Keymap input to that Piano Map. A Piano Map is not a global control and will only exist in the Piano in which it is created. For a basic example of how the Piano Map can be implemented, take a look at “Mike’s Gallery.”
For another example of how to use the Piano Map, look at the “Piano Map” Gallery in the Examples folder (Example 27). This example uses the keys C3, C4, and C5 to cycle through three different preset Pianos.
Hit (q) to add a comment to any Gallery, and double-click the text box to add notes, instructions, or any other text. Text boxes can be moved around and resized, and will save with the Gallery.
bitKlavier comes pre-programmed with a number of example Pianos that introduce, flesh out, and combine different preparations and settings. Here is a guide explaining a few select Pianos, many of which have explanatory text within the construction site itself.
This first example Piano provides a simple demonstration of how Synchronic can be used to create a metronomic pulse in a bitKlavier Piano. In this example, the cluster minimum is 2, meaning it takes at least two notes played within the cluster threshold time to trigger a Synchronic sequence. The cluster threshold is 500, meaning Synchronic is looking for notes spaced less than 500ms apart to begin a Sequence.
The cluster min is 2 and cluster max is 3 in this example, meaning any 2 or 3 notes played within 0.5 seconds will trigger a Synchronic sequence. A single note or any cluster of 4 or greater will stop the Synchronic sequence. This example also includes three sequenced accents of diminishing length, which cycle indefinitely.
Example 6 includes two tuning preparations. The direct preparation is routed to Equal Temperament, and the Synchronic preparation is routed to Just tuning. This means that if you play a chord, such as a G major chord or arpeggio, the initial chord will be in Equal Temperament, and the triggered Synchronic triad will be Just-tuned.
This example also includes three sequenced sustain length multipliers of diminishing value, which cycle until the end of the sequence.
In this example, none of the sequenced values have the same length, so the settings begin to phase and overlap.
This example features a Nostalgic wave of equal length to the duration of the note held down. Try playing a triad then lifting one note at a time to hear each note’s corresponding length.
This example also includes an Undertow of 1000ms that begins 200ms before the beginning of the sample, which provides a crest and fade rather than bouncing back and forth from the head of the sample. Watching the blue lines over the waveform in the Nostalgic settings panel should clarify what exactly is happening here.
There are a few layers to look at with this example. At its core, the Synchronic pulse is determining the length of the Nostalgic swell. There are three Keymaps, each attached to a different preparation.
The notes C4 and E4 are routed to the Synchronic preparation. This means that playing C4 and E4 together will begin a Synchronic sequence. The Keymap attached to this Synchronic preparation includes only C4 and E4.
This Synchronic preparation is connected to the Nostalgic preparation, which is set to “Synchronic Sync KeyDown.” The Keymap attached to the Nostalgic preparation includes all notes except for C4 and E4. This means that any note other than C4 and E4 will have a Nostalgic wave.
Because of the way these preparations are routed, every Nostalgic note will end as soon as the next Synchronic beat begins. The subsequent two Nostalgic Example Pianos (Examples 14 and 15) expand the functionality of these features.
The Mikroetudes are a collection of etudes written by fourteen composers and performers in 2015 as a means of exploring and uncovering some of the many musical opportunities presented by bitKlavier. Inspired by the way Bartók’s “Mikrokosmos” explore the identity of the piano from the ground up, these bitKlavier Mikroetudes were created by a variety of musicians who became acquainted with bitKlavier through their own composition/performance practices.
bitKlavier includes a preset Piano corresponding with each of the etudes in the Mikroetudes book. These Pianos can be used to perform the Mikroetudes, or can simply be used as jumping-off points of exploration. Some are wild and detailed, such as “Juxtaposed Weather” and “Keep It Steady,” while others are simple, like “Petite Gymnopedie” and “Southwing.”
For the full list of contributing composers, more information about the etudes, and to purchase the book of sheet music accompanying the bitKlavier Mikroetudes Galleries, please visit the Mikroetudes page through Many Arrows Music.
For an example of how to use bitKlavier in live performance context, take a look at Nostalgic Synchronic, a series of etudes written by Dan Trueman for prepared digital piano. The Nostalgic Synchronic website includes descriptions of the compositional process, live performance videos and recordings, and scores for the etudes. The eight Nostalgic Synchronic etudes are written with corresponding bitKlavier Galleries, each of which is preprogrammed in bitKlavier.
To learn more about tuning and temperament, check out bitSuite, a collection of apps built as learning tools to help understand the physics and process of tuning a keyboard instrument. The bitSuite apps were designed by Dan Trueman and use many of the same interfaces as bitKlavier.
A new online course—Reinventing the Piano—presented by Kadenze makes extensive use of bitKlavier to teach about the history and ongoing development of the piano.
About & Credits
bitKlavier is an open-source project developed by Dan Trueman and Mike Mulshine at Princeton University.
The bitKlavier manual was written by Noah Fishman and edited by Dan Trueman, Noah Fishman, and Mike Mulshine.
bitKlavier is the software engine that drives the prepared digital piano, running on MacOSX, iOS, and Windows, and has been used by dozens of performers—from young students to renowned professionals—in a range of compositions by Trueman and others.
Development of bitKlavier has been sponsored by the American Council of Learned Societies, the New Jersey State Council on the Arts, and Princeton University’s Center for Digital Humanities, Council on Science and Technology, Council of the Humanities, and Department of Music.
bitKlavier is an open-source project, created in C++ using JUCE. Developers interested in joining the project can of course download the source from the GitHub site. Don’t hesitate to contact us.
bitKlavier Temperament Tables by Ratio to Fundamental:
Well Tuned Piano
For the historical temperaments, visit Carey Beebe’s wonderful website, which describes all of the systems in bitKlavier, including how they are actually executed.