Skip to main content
Help the Python Software Foundation raise $60,000 USD by December 31st!  Building the PSF Q4 Fundraiser

Functional Ear Training for Musicians

Project description


Maintenance Travis Build Status Coveralls Awesome Sheet Music

GitHub (pre-)release PyPI Status PyPI Version PyPI Python Versions Documentation Status

For the support chat, please /join #birdears channel on freenode ( - ssl).




birdears screencast



birdears is a software written in Python 3 for ear training for musicians (musical intelligence, transcribing music, composing). It is a clone of the method used by Funcitional Ear Trainer app for Android.

It comes with four modes, or four kind of exercises, which are: melodic, harmonic, dictation and instrumental.

In resume, with the melodic mode two notes are played one after the other and you have to guess the interval; with the harmonic mode, two notes are played simoutaneously (harmonically) and you should guess the interval.

With the dictation mode, more than 2 notes are played (ie., a melodic dictation) and you should tell what are the intervals between them.

With the instrumental mode, it is a like the dictation, but you will be expected to play the notes on your instrument, ie., birdears will not wait for a typed reply and you should prectice with your own judgement. The melody can be repeat any times and you can have as much time as you want to try it out.

What is musical ear training

this needs to be written. The method.


  • questions
  • pretty much configurable
  • load from config file
  • you can make your own presets
  • can be used interactively (docs needed)
  • can be used as a library (docs needed)


Installing the dependencies

birdears depends only on python >= 3.5 and sox (which should be installed by your distribution's package manager, supposing you're using linux, and which provides the play command.)

Arch Linux

sudo pacman -Syu sox python python-pip

Installing birdears

pip3 install --user --upgrade --no-cache-dir birdears

In-depth installation

You can choose to use a virtualenv to use birdears; this should give you an idea on how to setup one virtualenv.

You should first install virtualenv (for python3) using your distribution's package (supposing you're on linux), then on terminal:

virtualenv -p python3 ~/.venv # use the directory ~/.venv/ for the virtualenv

source ~/.venv/bin/activate   # activate the virtualenv; this should be done
                              # every time you may want to run the software
                              # installed here.

pip3 install birdears         # this will install the software

birdears --help               # and this will run it

Alternative installation: Cloning this Repository

This way you can have the mainline version of birdears, which sometimes takes time to be updated to pip.

  1. Install python3 and sox for your linux distribution.

  2. Clone the repository:

ex. cloning it ro a directory named birdears-root

git clone birdears-root
  1. Set the PYTHONPATH environment variable to the directory you cloned birdears

first example:

export PYTHONPATH='/home/YOUR_USERNAME/my-git-repos/birdears-root'
python -m birdears

second example:

PYTHONPATH='/home/YOUR_USERNAME/my-git-repos/birdears-root' python -m birdears


You can also add an alias to your .bashrc to simplify this

alias birdears="PYTHONPATH='/home/YOUR_USERNAME/my-git-repos/birdears-root' python -m birdears"

explantion: the PYTHONPATH environment varible will make the birdears module be executed from that especified directory, having preemptiness even if there is already another version installed via pip.


After installing just run:

birdears --help


The following keyboard diagrams should give you an idea on how the keybindings work. Please note how the keys on the line from z (unison) to , (comma, octave) represent the notes that are natural to the mode, and the line above represent the chromatics.

Also, for exercises with two octaves, the uppercased keys represent the second octave. For example, z is unison, , is the octave, Z (uppercased) is the double octave. The same for all the other intervals.

Ionian (Major)

These are the keybindings for the Ionian (Major) Scale; black keys are the chromatic notes.

birdears - ionian(major) keybindings


birdears - dorian keybindings


birdears - phryigian keybindings


birdears - lydian keybindings


birdears - mixolydian keybindings

Aeolian (minor)

birdears - aeolian keybindings


birdears - locrian(minor) keybindings


birdears - advanced keybindings

this is still being improved

Legend for the keys on the diagram above:

Text Format Scale Direction Octave
blue (bold italic) descending second octave (shift or caps lock)
pink (bold) descending first octave
black/white (bold) ascending first octave
black (italic) ascending second octave (shift or caps lock)

White keys are the diatonic notes, black keys are the chromatic ones.

Descendent mode are usable for exercises with -d or --descendent.

Chromatic keys are usable for exercises with -c or --chromatic.

Second octave is usable for exercises with -n 2 or --n_octaves 2


Full documentation for this software is available at birdears Read The Docs and also in PDF format.


Those who want to contribute to this project can read


the screencast was recorded with a command similar to

COLUMNS=120 LINES=36 ttyrec
seq2gif -s 2 -i ttyrecord -w 120 -h 36 -o use.gif

ttyrec and seq2gif

keyboard layouts were generated with

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for birdears, version 0.3.3
Filename, size File type Python version Upload date Hashes
Filename, size birdears-0.3.3-py3-none-any.whl (311.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size birdears-0.3.3.tar.gz (273.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page