Welcome to MIDI-to-Mup-dot-perl.  I'm your host, Doug Taylor.  

* What is MIDI-to-Mup-dot-perl and how do you use it?

MIDI-to-Mup-dot-perl is a little program I wrote in the Perl language
to convert standard MIDI files into Mup notation, one Mup voice per MIDI
track.  You can get the latest version from
	http://dougspc.uts.ohio-state.edu/midi2mup.zip

To use it, you simply run midi2mup.pl and answer the questions.  It'll
expect your MIDI file to have the name <filename>.mid.  It will also
create (and destroy) files named <filename>.wrk and <filename>.wk2.
The Mup translation will be placed in <filename>.mup.

You can also invoke it with command-line arguments, like so:

  perl midi2mup.pl <filename>.mid keysig clef1 clef2 clef3 . . .

where keysig is the key signature (1 = 1 sharp, -1 = 1 flat, etc.) and
clefn is the clef (T or B) for track n of the MIDI file.  

Knowing the key signature helps the program to decide what to call
each note, in addition to letting it generate Mup "key=" messages.
It will ignore the key signature you give if it finds a key signature
MIDI event, but not all MIDI files have them.  Knowing the clef for
each track lets the program determine the default octave and causes
it to generate Mup "staff=" messages.

* Why'd you do it, Doug?  Why?!

I wrote MIDI-to-Mup-dot-perl for three quite selfish reasons.  (1)  I
wanted to learn some MIDI programming.  (2)  I wanted to learn Perl.
(3)  I had written some music which I wanted to convert quickly to Mup
format.  Just in case you wanted to know.

Since this is my first MIDI project and my first Perl project, it may be
the ugliest hack you've ever seen.  It works, though.

* How much does it cost?

Nothing.  I have released the code into the public domain.  Feel free to
hack into it yourself, steal routines from it, etc.  In particular, I
think the algorithm for determining note names is kinda clever.  More on
that in a moment.

*What platforms does it run on?

Um, I dunno.  Any platform that has a Perl interpreter, I guess.  I
developed it on an x86 running Redhat Linux 6.1 and perl 5.005_03.  I
don't think I used any weird stuff though, so it should run pretty much
anywhere.

* What should I do if I find a bug?

Fix it.  :-)

Seriously, I probably won't put much effort into supporting this thing.
I've written it, and now I'll start working on other projects.
If you have a really great idea for improving it, let me know and
I might do something.  Otherwise, I probably won't be interested.
Congratulatory e-mails are nice, though.  :-)

* What things can I change about the way it operates?

There are two variable settings you might want to fiddle with --
Granularity and SplitPoint.

Granularity determines how finely the program calculates the notes'
time values.  Right now it's set to 16, which means that it will
calculate to the nearest 16th note.  If you want to calculate to,
say, the nearest eighth note, change the line

 $Granularity = 16;

to read

 $Granularity = 8;

Got it?  Good.

SplitPoint is a little more subtle.  When MIDI-to-Mup-dot-Perl finds
out the key the piece is supposed to be in, it calls this cute little
algorithm to determine what it should call each note.  For instance,
if you're in the key of E major, then A-natural should be represented
by "a", while the note between A and G should be "g".  However,
if you're in E-flat major, A-natural should be "an" (with a natural
accidental mark) and the note between A and G would be just "a".

MIDI-to-Mup-dot-Perl does all this automatically.  (See, I told you
it was kinda clever.  :-) However, there's a tiny bit of room for
individual taste.

If you're in C-major, for instance, then the note between F and G
is almost always going to be "f#", and the note between A and B is
almost always going to be "b&".  But what do you call the note between
G and A?  It might be "a&" (like in a temporary modulation to f-minor)
or it might be "g#" (like if you were really in a-minor).  Simply put,
if SplitPoint is set to 2, then it'll be written as "g#"; if you set
it to 3, then it'll be written as "a&".  Don't change it to anything
except 2 or 3 or you'll screw everything up.  It's currently set to 2.

* When I ran it I got all sorts of warning about ties and accidentals.

Yeah, I know.  MIDI-to-Mup-dot-Perl isn't smart enough to recognize the
"one accidental per note per bar" rule.  If you have an f# quarter tied
to an f# eighth, it'll put sharps on both notes.  Won't hurt anything,
I suppose, but it's bad notation.  You should probably take all those
out by hand.

One consequence of this is that if you're in C-major and you write
something like "F F-sharp F-natural", then it will be written as
"f;f#;f" instead of "f;f#;fn".  Things like that will have to be
fixed by hand as well.

* What other quirks are there?

I'm *so* glad you asked.  :-)

The algorithm for determining note length is a total hack.  I'm not
really happy with it, but it works well enough.  It won't let you
tie notes across barlines and it sometimes has trouble with rests at
the start of a piece.  Nor will it let you embed rests between notes
within a bar.  If you have something like "eighth rest eighth rest",
then it'll come out as "quarter quarter".  I think.

You shouldn't get any Mup complaints about having too many (or too few)
counts in a bar, though.  It'll pad a bar out with rests or truncate
note lengths if necessary to make things fit.  It also does a decent
job of converting MIDI time slices to note lengths, although it always
writes dotted rythms as tied notes, e.g. a dotted half will be written
as a half tied to a quarter.  In a tie, the note of larger value will
always be written first.

It *will* do chords.  However, it assumes that all notes in a chord
have the same duration.

According to the MIDI file spec, a MIDI file can specify timing info
on the file header either as "pulses per quarter note" (PPQN) or
something else which I didn't really understand.  MIDI-to-Mup-dot-Perl
handles PPQN just fine, but it might choke if your MIDI file uses the
"something else".

Some MIDI sequencers put out a dummy track that just has MIDI events
on it, but no actual notes.  MIDI-to-Mup-dot-Perl will read those
tracks and use whatever MIDI info is there, but it's not smart enough
to recognize that it's a no-note track.  This may result in a "phantom
voice" in the Mup file.  You'll have to remove those by hand.

I've noticed that the timing on some of my MIDI files gets way off when
I convert it to Mup.  In one piece, the first beat of the bar eventually
migrates to somewhere around beat three.  I *think* that's due to timing
problems with the MIDI file itself, not with MIDI-to-Mup-dot-Perl, but
I'm not entirely sure.  The whole timing business should probably be
re-written, but it works well enough for now.

* A final word

I hope you enjoy the program and use it to help you write lots of good
music.  The world needs more good music.

Doug Taylor
doug-taylor+@osu.edu
