⠀FreeDots⠀⠀⠀⠀⢀⣀⡤⠤⠴⠒⠒⠒⠒⠦⠤⢤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀V0.1⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡤⠖⠉⠉⠀⢆⠀⠀⠀⠀⠽⠀⠀⠀⡔⠀⠉⠑⠲⢄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⣠⠚⠁⠀⠿⠀⠀⠀⠘⡄⠀⠀⠀⠀⠀⠀⢠⠃⠀⠀⠀⠷⠀⠈⠳⣄⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⡰⠞⢄⠀⠀⠀⠀⠀⠀⠀⠀⢣⠀⠀⠀⡀⠀⠀⡜⠀⠀⠀⠀⠀⠀⠀⠀⡠⠙⢆⠀⠀⠀⠀⠀
⠀⠀⠀⢠⠞⠀⠀⠀⠱⢄⠀⠀⠀⢀⠤⠔⠚⡍⠉⠉⠈⠉⢹⠓⠢⠤⡀⠀⠀⠀⣠⠊⠀⠀⠈⠳⡀⠀⠀⠀
⠀⠀⢠⠏⠀⠣⠾⠀⠀⠀⠑⣤⠒⠁⠀⠀⠀⢱⠀⠀⠀⠀⡎⠀⠀⠀⠈⠑⣤⠚⠀⠀⠀⠀⠵⠀⠙⡄⠀⠀
⠀⢀⠏⠀⠀⠀⠀⠀⠀⢀⠞⠀⠑⢆⠀⠀⠀⠈⡆⠀⠀⢠⠁⠀⠀⠀⣠⠊⠀⠱⡀⠀⠀⠀⠀⠀⠀⠹⡄⠀
⠀⡼⠠⣀⣀⠀⠀⠀⢀⠇⠀⠀⠀⠀⠑⢆⠀⠀⢱⠀⠀⡎⠀⠀⣠⠊⠀⠀⠀⠀⠘⡄⠀⠀⠀⣀⣀⠄⢧⠀
⢀⡇⠀⠀⠀⠉⠉⠒⡞⠤⢄⣀⡀⠀⠀⠀⠱⢄⠈⡆⢰⠁⡠⠚⠀⠀⠀⢀⣀⡠⠤⠷⠒⠉⠉⠀⠀⠀⠸⡄
⢸⠆⠀⠣⠯⠀⠀⢀⠇⠀⠀⠀⠈⠉⠒⠒⠢⠤⣱⣷⣾⣎⠤⠤⠒⠊⠉⠁⠀⠀⠀⢈⠄⠀⠀⠀⠮⠀⠈⡇
⢸⠄⠀⠀⠀⠀⠀⢀⡂⠀⠀⠀⠀⣀⡠⠤⠔⠒⣪⢿⢿⢗⠒⠢⠤⢄⣀⡀⠀⠀⠀⢐⠂⠀⠀⠀⠀⠀⠀⡇
⠈⡇⠀⠀⠀⢀⣀⠤⢧⠒⠒⠉⠁⠀⠀⠀⡠⠚⠀⡇⠸⡀⠑⢆⠀⠀⠀⠈⠉⠒⠒⡾⠤⣀⣀⠀⠀⠀⢰⠃
⠀⢳⠐⠉⠉⠀⠀⠀⠈⢄⠀⠀⠀⠀⣠⠊⠀⠀⡸⠀⠀⢇⠀⠀⠱⢄⠀⠀⠀⠀⡠⠃⠀⠀⠀⠉⠉⠂⡼⠀
⠀⠈⢇⠀⠀⠀⠀⠀⠀⠈⢆⡀⡠⠚⠀⠀⠀⠀⠇⠀⠀⠸⡀⠀⠀⠀⠑⢆⠀⡰⠁⠀⠀⠀⠀⠀⠀⢰⠃⠀
⠀⠀⠘⣆⠀⠣⠮⠀⠀⠀⡠⠛⢤⡀⠀⠀⠀⡸⠀⠀⠀⠀⢣⠀⠀⠀⢀⡠⠛⢆⠀⠀⠀⠀⠯⠀⣠⠃⠀⠀
⠀⠀⠀⠈⢦⠀⠀⠀⣠⠊⠀⠀⠀⠈⠑⠤⢄⣇⡀⢀⡀⢀⣘⣄⠤⠒⠁⠀⠀⠀⠱⢄⠀⠀⠀⡴⠃⠀⠀⠀
⠀⠀⠀⠀⠀⠓⣄⠊⠀⠀⠀⠀⠀⠀⠀⠀⡸⠀⠀⠁⠈⠀⠀⢕⠀⠀⠀⠀⠀⠀⠀⠀⠑⣠⠎⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠓⢤⡀⠀⠣⠵⠀⠀⢠⠃⠀⠀⠀⠀⠀⠀⠘⡄⠀⠀⠀⠾⠀⢀⡤⠚⠁⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠓⠤⣄⡀⠀⠜⠀⠀⠣⠷⠩⠿⠀⠀⠩⡀⢀⣀⠴⠒⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠓⠒⠦⠤⠤⠤⠤⠴⠒⠒⠋⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-------------------------------------------------------------------------------
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 transform
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, you will also need the braille fonts from
http://brl.thefreecat.org/linux-brl-console.tgz

Requirements:
  You will need to have the python setuptools package installed.
  For playback, pygame is required.

To install FreeDots, simply execute:

  # python setup.py install

To run freedots, use the 'freedots' command-line utility:

  $ freedots 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.

When a proper font is used, 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 the latest development version of
BRLTTY.  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:

www.musedata.org has a big collection of baroque music
in MuseData and Humdrum formats.  There is a hum2xml
conversion tool available from http://extras.humdrum.net/man/hum2xml/
which you can use to transform Humdrum files from www.musedata.org
into MusicXML.  Note that the license of musedata.org prevents redistribution
of derived works, so you will have to download and convert
the data from musedata.org 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.
We might implement humdrum input format in FreeDots directly one day to
get around this problem.

www.wikifonia.org 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 wikifonia.org MusicXML files.
Work on support for chord symbols is planned.

www.mutopiaproject.org 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 www.mutopiaproject.org 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 mutopiaproject.org sources,
since these are free to distribute.  If you produce any
freely distributable MusicXML files from public domain sources,
please consider sending them to mlang@delysid.org so that we
can include them with FreeDots to avoid duplicate work
by other people.

 -- Mario Lang <mlang@delysid.org>

