AudioTheory Piano Keys – User Guide

Getting Started

You can launch AudioTheory Piano Keys from the AudioTheory Piano Keys.exe executable file (Windows) or AudioTheory Piano Keys.app file (Mac OS). This loads up the main interface from where you can access the features detailed in this guide.

The on-screen piano accepts input from any of the following sources:

MIDI – AudioTheory Piano Keys works best when you connect a MIDI device. This could either be an electric piano/ keyboard or MIDI controller. With this connected you will receive highlighting and audio feedback in real time when playing.

You may find that the octave on your device doesn't match that of the application, and the highlighting is shifted to a different position on the on-screen piano. This may be fixed by changing the octave the MIDI device itself, but it's also possible to offset the input value in the application settings.

Mouse – you can highlight/ play any key by clicking on it directly.

Keyboard – press the ‘keyboard’ button (it will highlight in pink when this mode is on) the application will register QWERTY input from your computer keyboard. In the settings there are two QWERTY keyboard overlay types that you can choose between labeled ‘partial’ and ‘full’. The partial keyboard overlay covers a single octave and is split across two rows of the keyboard. In 'full' mode, all the piano keys are sequentially mapped across the keyboard.

The on-screen piano has additional options to customise how the application handles playback, including a sustain feature and instrument selector. There are also options to display or hide the keyboard note overlay as well as a 'lock to scale' feature where only notes selected in the scale will give audio feedback.

You will also notice an octave selector, this specifically controls the playback (output) octave. It can be configured independently from the MIDI (input) octave so you can control how the application receives audio in and how it plays it separately.

As you play notes on the keyboard you will receive visual and audio highlighting feedback as defined by your settings. This will display across both the on-screen piano and all loaded diagrams, giving you an overview of how what you're playing fits relative to scales and chords.

If you have any issues with MIDI input, there is an indicator in the settings which details exactly what input the application is receiving. This can be used to diagnose any issues you may encounter (e.g. if no notes were highlighting this could be used to asses if the input octave was out of range, or if the device was not properly connected to the computer).

The note boxes in the bottom left of the screen can be used to exclude specific notes from the keyboard, as well as the chord and wheel diagrams. The 'scale' button provides preset options for using a standard piano scale.

When a scale preset has been selected, the note highlighting updates to be context dependant. For example, if C♯/ D♭ is to be presented as C♯ in the selected scale the highlight colour will be yellow (the colour used for C). But when it's to be displayed as D♭ it will highlight in orange (the colour for D).

You can also control this manually by pressing the note name directly. For example, if you want C♯ to display as D♭ then press the label here and the highlighting and names will adjust accordingly.

The 'all scales' button can be used to access the full scale library, where you can view sets of scale diagrams side by side and choose one to load.

The scale library is a fullscreen view where you can play and choose between the scale presets. There is also a play button next to each scale, which will play through its contained notes in order.

This is the second row of piano keys that sits just above the on-screen piano. It is one of the application's more advanced features, but once understood it is a very powerful tool for quickly understanding how a note you play fits into two scales at the same time. Receiving this feedback in real-time makes it a useful tool for improvising.

Scale highlighting is most useful when you are using a scale preset. This is because (as long as 'auto' mode is set on the right hand side) the application will automatically display major/ minor or dim scales relevant to the context of the main scale you are working in.

The above screenshot illustrates how this works in practice. Here the main scale preset loaded is C Major and the 2nd note in this scale, D, is being played. The 2nd position of a Major scale is associated with a minor chord, which here would be D minor (D, F, A). Therefore it is the minor scale that is relevant to this context.

So when pressing the D note we are able to see the relevant scale for this note, and you will notice that it is highlighted against the C Major scale too (here this means that B♭ is marked up as position VI, but it is greyed out as B♭ is not part of C Major). As such, the notes we are viewing that are not greyed out show the D minor scale progression, but also filtered to our main song key (C Major).

The settings to the left and right of the scale highlighting view offer additional customisations in regard to how this works. On the left you will see the name of the displaying scale and also an option to turn off the dual highlighting filter.

There is also a hold mode, which allows you to keep the 2nd scale displaying even when additional input is received. By default, AudioTheory Piano Keys has its own algorithm for identifying the desired root note when a large amount of input (chords/ multiple notes at once) is received. Typically this will be to display the scale for the lowest input note received, which in most cases will be desirable. For example, if the D Minor chord is played this means that the D Minor scale will always show, regardless of the order (which may be milliseconds apart) between which input is registered for the three notes.

Hold mode gives additional manual control over this, allowing you to press a button on the keyboard and keep the current scale on screen for the duration of the press. By default the hold button is Left Shift, but there is also an option to remap it, and change the behaviour of this button to a toggle (rather than having the requirement for it to be continuously pressed down).

On the right hand side are options to configure the scale type used. As above, the 'auto' option is recommended for use with a scale preset as this will display the major/ minor or diminished scale relevant to the context. However you can alternatively specify a different scale type (or subsections such pentatonic or blues) to use.

The scale wheel is a new way to view a scale preset. The wheel will display in chromatic mode when no scale is loaded, but once you have a set a preset it will display over the wheel too.

The main use of the scale wheel is that it allows you to see how a scale operates as a set of fixed, relative positions. This is to say that the wheel displays as 12 evenly spaced indicators, where as the piano itself moves unevenly between white and black notes. As such, you have a diagram where you can easily observe how all scales of the same type (major/ minor etc.) use the same set of intervals. The scale wheel also consistently places the root note at the 12 o clock position on the wheel, again this allows the scale to be viewed primarily as a set of 'relative' notes, with the starting point and interval size not changing.

You can see here the difference between the two modes. When no scale is loaded the wheel displays with an empty center, however when the available notes match a scale preset, the details for this scale appear in the middle of the wheel and the notes in the scale are listed underneath too. The scale wheel works best like this as you have a few extra features, but it can also be used with any custom subsection of notes that don't match a specific preset.

The advantage of using a scale preset is that the application knows which chords within that scale are major, minor or diminished, and indicates this across the relative positions using the following shorthand:

    Uppercase – note in scale plays as a major chord
    Lowercase – note in scale plays as a minor chord
    Lowercase° – note in scale plays as a diminished chord


There are a couple more ways in which you can interact with the scale wheel. By clicking and dragging the outer wheel (the dark grey band with the note names) you can quickly swap the scale root note. Upon doing so, this will load the scale fully into the application so the note highlighting will adjust everywhere. You can also click on the scale type to quickly swap between the Major and Minor scales for the current root note.

Piano chords are loaded into the main top left area of the screen. By default, when setting a scale preset the corresponding set of chords are loaded too, although this can be turned off in the settings if desired. There is space for up to 12 chords so additional chords can be added by pressing the '+' icon on any blank space. Alternatively, each piano chord has a mini cog icon under it. You can press this button to bring up the settings for that individual chord, which includes an option to swap it out.

Each chord has a couple more options that sit just underneath it. The play button can be used to directly play back the chord. There is also a green tick which only shows when the chord is playing, this is useful for playing and verifying chord shapes using a MIDI device.

When hovering the mouse over a chord you will also see an arrow icon, this can be used to drag the chord around and quickly rearrange chords within your view.

The double arrow icon in the bottom right will display if the chord can play across more than octave on the diagram. If this is the case, you can press the button to cycle between the octave positions and the diagram will update accordingly.

When swapping out a piano chord you will be taken to the piano chord library, where you can select a new chord to load. In this view, chords are initially sorted by type and you can choose an option using the selector at the top and then view the relative chords for this type below.

There is also a button in the top right that lets you load the full set into the main application view all at once.

There are numerous options to customise the application view that are contained within the box in the bottom right of the screen. This box too can be hidden by pressing the cross button (visible when hovering over the area) or opened up by pressing the eye button (only visible when the box is already closed).

The view options here control which items display in the top two thirds. By default this is both the chords set and scale wheel, but you can instead choose to focus on just one of these items. There are also buttons here to open up the chord or scale libraries.

The application view settings in the bottom right are also where you can swap between the main 'piano practice' mode and the set of included ear training exercises. In 'ear training' mode the view options below are replaced with mode-specific options for configuring the exercises.

Initially when you select the ear training mode you will be prompted to start a game using the button. Ahead of this, you can adjust the game configuration using the options in the bottom right. During the game, you can swap modes at any time. Any other changes to the settings (including changes to the current scale preset) will take affect from the next round (e.g. if you exclude the note C, it may still be present in the current round, it will only be from the next round onwards that it won't be used).

When the 'chord match' exercise is selected you will also see a chord type selector on the right hand size of the screen. This will let you choose which chord types will be presented at random for you to identify.

'Higher or Lower' is a good training exercise to start out with as it is the easiest and most straight forward. In this mode you are presented with two notes and must identify if the first is higher or lower (or the same) as the second. This game references the current scale preset, so you can play it with a subsection of the notes if desired. Note that with this game if the number of octaves is increased from 1 to 3 (set in the bottom right) this makes the game easier, as it results in a typically greater (more obvious) differentiation in pitch between the randomly selected notes.

'Note Match' is in many ways a more advanced version of 'H'igher or Lower', but in this exercise you must identify the exact note match. This can be made easier by using a subsection of notes (for example the C Major scale). It can be made harder by swapping setting the number of octaves to use (found in the bottom right) from 1 to 3, as this means a much wider selection of notes are used.

A tip for this exercise is to make use of the main on-screen piano, you can press the notes here to match up the sound before selecting your answer.

'Chord Match' is the most advanced exercise, however it's also the one with the largest degree of configuration, as you can define exactly which root notes and which chord types are used.

A tip for this exercise is therefore to start out with a restricted set of chords, you can even choose a single root note and work on differentiating between chord types only. As you become more familiar with an initial set, you can then start to add in additional chord types.

As above, you can make use of the on-screen piano (although here you will likely need a MIDI device to successfully play the chords) to match up sounds.

The application settings can be opened using the cog icon in the top left. Here you have numerous configuration settings including some tools for debugging MIDI input, and configuration for various other elements of the application. These include visual customisations, such as different backgrounds and a highlighting delay that keeps note colours on the screen for longer.

The Save and Load icons found within the settings can be used to write your current view to a plain text file and then load it back into the application. This works well for quickly swapping between arrangements.

As well as the default English note names it is possible to change over the notes to either used fixed do solfège (Do, Re, Mi...) or to use relative names (relative Do or as numerals). Please note that relative names require a scale preset to be loaded (as this is what they will be relative to) and otherwise the notes will not display.

The DSP settings control the audio latency of the application, a lower DSP value means less latency (the delay between input and audio output) however this requires more CPU power. This will typically result in audio glitches such as pops and clicks if the DSP is set too low.

When the application is run for the first time it automatically generates a 'Colours.ini' file that includes the hex values for all of the note highlighting colours. It's possible to change these by opening the Colour.ini file in the text or code editor of your choice and adjusting the hex values as desired.

The 'Colours.ini' file location varies depending on your platform:

Windows and Linux
    {path to app}/AudioTheory Piano Keys/Data/

If you've purchased the app through Steam then you can easily open this folder by right clicking on the application in your Steam library and selecting 'Manage --> Browse Local Files'.

Mac
  ~Library/Application Support/com.DraculasCave.AudioTheoryPianoKeys/Data/

If you want to revert back to the original colours, the easiest way to do this is to delete the Colours.ini file and then next time the application is run it will make a new one automatically with the default values.

Audio latency is the amount of time it takes for the computer to process and play audio. There are features in AudioTheory Piano Keys which simulate the playback of an instrument in real-time and what this means is that a delay of even a few milliseconds can be noticeable and undesirable.

To optimise response times, AudioTheory Piano Keys comes with some platform-specific options as Mac/Linux and Windows handle audio differently.

On Mac and Linux the built-in audio drivers are able to support low latencies out-of-the-box. This means you are unlikley to have latency issues with the default settings, however there is still a DSP buffer size that can be configured in the options. A lower DSP value means less latency, however this requires more CPU power. If the DSP is set too low for the computer to handle then this will typically result in audio glitches such as pops and clicks.


The DSP value can be set using the dropdown here in the options.

To get the best result may require a bit of trial and error. Essentially you want to have the buffer set to as lower value as possible without audio playback glitching or containing artefacts. For many modern computers you will be able to set this all the way down to the smallest (fastest) value, 32kbps.

On Windows the ASIO4ALL driver can be used to achieve ultra low latencies. Most DAWs require the use of an ASIO driver, and whilst it is optional for AudioTheory Piano Keys, it's recommended for better performance over the built-in Windows driver.

You can download and install this driver for free from the ASIO4ALL website here:

https://www.asio4all.org/

Once it's installed, load up AudioTheory Piano Keys (if it was open prior to the install you will need to close it and open it up again) and you will be able to swap between the ASIO driver and the built-in driver in the application settings. Any changes made here will require the application to be restarted to take effect.


When using the ASIO4ALL driver, there are elements of the configuration (notably the output device and the DSP buffer size) that are controlled in the ASIO4ALL settings, not the AudioTheory Piano Keys settings. These can be opened up by pressing the 'config.' button which appears next to the dropdown when the ASIO driver is in use.


It's worth noting that ASIO4ALL requires a dedicated stream for audio output, meaning other applications cannot output audio at the same time when it's in use. You can always swap back to the built-in driver in the settings, and increased latency times may not be an issue depending on how you are using the application.