Skip to content
MusicXML to Braille Music transcription
Java Python Emacs Lisp AMPL NSIS HTML Other
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


FreeDots is a music notation converter primarily for blind users.
It can handle input in MusicXML format, a file format
typically produced by optical music recognition software.

A user can use their favourite OMR software to scan (and possibly
correct) a piece of music, and use FreeDots to transcribe
the resulting XML file to braille music notation.
Optionally, the music can also be played back.

Braille output is currently implemented using the Unicode Braille row.
You will need your environment to be configured to use UTF-8.
If you are on Linux console, you will also need the braille fonts from

  A Java6 Runtime Environment

To run freedots, use the -jar option to the "java" command:

  $ java -jar freedots.jar

If you prefer to use FreeDots without the graphical user interface for
batch operations or as a pure command-line tool, supply the -nw
option (no-window) on the command-line:

  $ java -jar freedots.jar -nw bwv1013.xml

Output format:
FreeDots uses UTF-8 encoded Unicode to output braille dot patterns.
This has the big advantage that it works independently of the users
braille translation table.  Therefore, output of FreeDots
can easily be shared between people living in different countries.

In the graphical user interface the dot patterns are also displayed on screen.
This allows sighted people that have knowledge of braille music notation
to work together with a blind user on a computer.
It also allows seamless interchange of digital braille music notation
files across the Internet, since the differences between
localized braille variants are completely irrelevant if Unicode braille is
used.  This guarantees the readability of braille music by everyone,
no matter what translation table is in use.

Unfortunately, many screen readers do not support unicode braille patterns
yet.  On Linux console, you will need BRLTTY starting from version 3.10.
If you are using Orca on Linux, Unicode braille patterns
do work in GNOME terminal even with older versions of BRLTTY.
In the meantime, you can use iconv to convert Unicode Braille to BRF format.
See the FAQ for details.

MusicXML data files:
FreeDots currently only supports input in MusicXML format.
Such files are written by every major optical music recognition
software available today.  So one way to obtain music for FreeDots
to work with (which was the primary motivation to write this program) is to
scan sheet music yourself using one of the OMR programs available.

However, there are other sources you can obtain music from: has a big collection of baroque music
in MuseData and Humdrum formats.  There is a hum2xml
conversion tool available from
which you can use to transform Humdrum files from
into MusicXML.  Note that the license of prevents redistribution
of derived works, so you will have to download and convert
the data from yourself, we can not provide
preconverted MusicXML files for you.
Our tests have shown that hum2xml does not always produce correct
results when it comes to multiple voices inside a staff. has a growing collection of lead-sheets
for popular and traditional music.  While FreeDots does
not fully support lead-sheet style MusicXML files yet,
you can already extract the melody and lyric of MusicXML files.
Work on support for chord symbols is planned. is a big collection of public domain music
in Lilypond format.  While we have no Lilypond support at all,
the PDF files available for download from can
usually be processed with OMR software quite easily.
There will still be scanning errors, but at least there is
a relatively big repository of free sheet music you can readily play with.
We will collect MusicXML files produced from sources,
since these are free to distribute.

If you produce any freely distributable MusicXML files from public domain
sources, we encourage you to consider sending them to so
that we can include them with FreeDots to avoid duplicate work by other people.

 -- Mario Lang <>
You can’t perform that action at this time.