abcmidi/doc/abc2midi.1

.TH ABC2MIDI 1 "June 2017"
.SH NAME
\fBabc2midi\fP \- converts abc file to MIDI file(s)
.SH SYNOPSIS
abc2midi \fIinfile\fP [\fIrefnum\fP] [\-c] [\-v] [\-ver] [\-t] [\-n limit] [\-CS] [\-quiet] [\-silent] [\-Q tempo] [\-NFNP] [\-NFER] [\-NGRA] [\-NGUI] [\-STFW] [\-OCC] [\-NCOM] [\-HARP] [\-BF] [\-TT] [\-o outfile] \-CSM [filename]
.SH DESCRIPTION
 The default action is to write a MIDI file for each abc tune
 with the filename <stem>N.mid, where <stem> is the filestem
 of the abc file and N is the tune reference number. If the \-o
 option is used, only one file is written. This is the tune
 specified by the reference number or, if no reference number
 is given, the first tune in the file.
.SH OPTIONS
.TP
.B \fIrefnum\fP
process the tune with reference number \fIrefnum\fP
.TP
.B -c
selects checking only
.TP
.B -v n
selects verbose option where n is the level (optional)
.TP
.B -ver
prints version number and exits
.TP
.B -t
selects filenames derived from tune titles
.TP
.B -CS
use 2:1 instead of 3:1 for broken rhythms
.TP
.B -quiet
Suppresses some common warnings.
.TP
.B -silent
Suppresses other messages.
.TP
.B -n \fI X\fP
limits the length of the file name stem to X characters
.TP
.B -Q \fI tempo\fP
sets the default tempo in quarter notes per minute if it was not
specified in the abc header.
.TP
.B -NFNP
Ignore any dynamic indications !f! !ff! etc.
.TP
.B -NFER
Ignore any fermata indications (eg H or !fermata!).
.TP
.B -NGRA
Ignore any grace notes.
.TP
.B -NGUI
Ignore any guitar chords enclosed in double quotes.
.TP
.B -STFW
Place lyric text in separate MIDI tracks.
.TP
.B -NCOM
Suppress some comments in the output MIDI file.
.TP
.B -OCC
Accept old chord convention (eg +D2G2+ instead of [DG]2).
.TP
.B -BF
BarFly mode: invokes a stress model if possible.
.TP
.B -HARP
Roll ornaments=roll are generated for the harpist (same pitch)
.TP
.B -TT
Changes the tuning from A = 440 Hz.
.TP
.B -o \fIoutfile\fP
write output to \fIoutfile\fP
.TP
.B -CSM \fIinfile\fP
load a set of custom stress modes from a file
.SH FEATURES
.PP
* Broken rhythms (>, <), chords, n-tuples, slurring, ties, staccatto notes,
repeats, in-tune tempo/length/time signature changes are all supported.
.PP
* R:hornpipe or r:hornpipe is recognized and note timings are adjusted to
give a broken rhythm (ab is converted to a>b).
.PP
* Most errors in the abc input will generate a suitable error message in
the output and the converter keeps going.
.PP
* Comments and text fields in the abc source are converted to text events
in the MIDI output
.PP
* If guitar chords are present, they are used to generate an accompaniment
in the MIDI output.
.PP
* If there are mis-matched repeat signs in the abc, the program attempts to
fix them. However, it will not attempt this if a multi-part tune 
description has been used or if multiple voices are in use.
.PP
* Karaoke MIDI files can be generated by using the w: field to include 
lyrics.
.PP
* Nonnumeric voice id's, eg. V: soprano, as proposed for the new
abc standard is accepted.
.PP
* Invisible rests specified by x are treated the same way as
normal rests (z).
.PP
* Decorations may be indicated using either the deprecated
notation (eg. !fermata!) or the standard version 2.0 notation
(eg. +fermata+).
.PP
.SH LIMITATIONS
* No field is inherited from above the X: field of the tune.


.SH "ABC SYNTAX EXTENSIONS"
* There are some extensions to the abc syntax of the form
.PP
%%MIDI channel n
.PP
These control channel and program selection, transposing and various
other features of abc2midi.
.PP
Each of these should appear on a line by itself. All of them are allowed
within the abc tune body. By using these in combination with the part
notation, one can, for example, play a part transposed or in a different key.
.PP
The idea behind this syntax is that other programs will treat it as a
comment and ignore it.
.PP
%%MIDI channel n
.PP
selects melody channel n (in the range 1-16).
.PP
%%MIDI program [c] n
.PP
selects program n (in the range 0-127) on channel c. If c is not given, the
program is selected on the current melody channel. Most modern tone
generators follow the General MIDI standard which defines the instrument
type for each program number.
.PP
%%MIDI beat a b c n
.PP
controls the way note velocities are selected. The first note in a bar has
velocity a. Other "strong" notes have velocity b and all the rest have velocity
c. a, b and c must be in the range 0-127. The parameter n determines which
notes are "strong". If the time signature is x/y, then each note is given
a position number k = 0, 1, 2 .. x-1 within each bar. Note that the units for
n are not the unit note length. If k is a multiple of n, then the note is
"strong". The volume specifiers !ppp! to !fff! are equivalent to the
following :
.P
!ppp! = %%MIDI beat 30 20 10 1
.br
!pp!  = %%MIDI beat 45 35 20 1
.br
!p!   = %%MIDI beat 60 50 35 1
.br
!mp!  = %%MIDI beat 75 65 50 1
.br
!mf!  = %%MIDI beat 90 80 65 1
.br
!f!   = %%MIDI beat 105 95 80 1
.br
!ff!  = %%MIDI beat 120 110 95 1
.br
!fff! = %%MIDI beat 127 125 110 1

.PP
%%MIDI beatmod n
.PP
Increments by n (or decrements if n is negative) the velocities a, b and
c described above. The instructions !crescendo(! and !crescendo)!
are equivalent to inserting a %%MIDI beatmod 15 wherever they
occur. (Alternatively you can use !<(! and !<)!.) Similarly the
instructions !diminuendo(! and !diminuendo)! are equivalent
to %%MIDI beatmod \-15.

.PP
%%MIDI deltaloudness n
.PP
where n is a small positive number.  By default the crescendo and
diminuendo instructions modify the beat variables a, b, and c by
15 velocity units. This instruction allows you to set this default
to value n.

.PP
%%MIDI nobeataccents
.PP
For instruments such as church organ that have no greatly emphasized beat notes,
using this will force use of the 'b' velocity (see %%MIDI beat)
for every note irrespective of position in the bar.  This allows dynamics
(ff, f, etc) to be used in the normal way.
.PP
%%MIDI beataccents
.PP
Revert to emphasizing notes the the usual way. (default)

.PP
%%MIDI beatstring <string of f, m and p>
.PP
This provides an alternative way of specifying where the strong and weak
stresses fall within a bar. 'f' means velocity a (normally strong), 'm'
means velocity b (medium velocity) and 'p' means velocity c (soft velocity).
For example, if the time signature is 7/8 with stresses on the first, fourth
and sixth notes in the bar, we could use the following
.PP
%%MIDI beatstring fppmpmp
.PP
%%MIDI transpose n
.PP
transposes the output by the specified number of semitones. n may be
positive or negative.
.PP
%%MIDI rtranspose n
.PP
Relative transpose by the specified number of semitones. i.e.
%%MIDI transpose a followed by %%MIDI rtranspose b results in a
transposition of a+b. %%MIDI transpose b will result in a transposition
of b semitones, regardless of any previous transposition.
.PP
%%MIDI c n
.PP
specifies the MIDI pitch which corresponds to c. The default is 60. This
number should normally be a multiple of 12.
.PP
%%MIDI grace a/b
.PP
sets the fraction of the next note that grace notes will take up. a
must be between 1 and b-1. The grace notes may not sound natural
in this approach, since the length of the individual grace notes
vary with the complexity of the grace and the length of the
following note. A different approach (which is now the default)
assumes that the grace notes always have a fixed duration.
To use the other approach you would specify,

%%MIDI gracedivider b

where b specifies how many parts to divide the unit length
specified by the L: field command. For example if b = 4 and
L: = 1/8, then every grace note would be 1/(8*4) or a 32nd
note. Time would be stolen from the note to which the grace
notes are applied. If that note is not long enough to handle
the grace then the grace notes would be assigned 0 duration.



.PP
%%MIDI chordname name n1 n2 n3 n4 n5 n6
.PP
Defines how to play a guitar chord called "name". n1 is usually 0 and
n2, n3 to n6 give the pitches of the other notes in semitones relative
to the root note. There may be fewer than 6 notes in the chord, but not
more.If "name" is already defined, this command re-defines it. Unlike
most other commands, chordname definitions stay in effect from where they
are defined to the end of the abc file. The following illustrates how
m, 7, m7 and maj7 could be set up if they were not already defined.
.PP
%%MIDI chordname m 0 3 7
.br
%%MIDI chordname 7 0 4 7 10
.br
%%MIDI chordname m7 0 3 7 10
.br
%%MIDI chordname maj7 0 4 7 11
.PP
%%MIDI gchord string
.PP
sets up how guitar chords are generated. The string is a sequence made of
of z's, c's  f's and b's for rests, chords, fundamental and fundamental
plus chord notes respectively.  This specifies how each bar is to be played.
An optional length is allowed to follow the z's, c's f's and b's  e.g. czf2zf3.
If the abc contains guitar chords, then abc2midi automatically adds chords and
fundamentals after encountering the first guitar chord. It keeps using that
chord until a new chord is specified in the abc. Whenever the M: field is
encountered in the abc, an appropriate default string is set :
.P
For 2/4 or 4/4 time default is equivalent to :
%%MIDI gchord fzczfzcz
.P
For 3/4 time default is equivalent to :
%%MIDI gchord fzczcz
.P
For 6/8 time default is equivalent to :
%%MIDI gchord fzcfzc
.P
For 9/8 time default is equivalent to :
%%MIDI gchord fzcfzcfzc
.P

The gchord command has been extended to allow you to play
the individual notes comprising the guitar chord. This allows
you to play broken chords or arpeggios. The new codes g,h,i,j,
G,H,I,J reference the individual notes starting from the
lowest note of the chord (not necessarily the root in the
case of inversions). For example for the C major chord, g
refers to C, h refers to E and i refers to G. For a gchord
command such as,
.P
%%MIDI gchord ghih
.P
Abc2midi will arpeggiate the C major guitar chord to
CEGE. The upper case letters G,H,I, and J refer to
the same notes except they are transposed down one
octave. Note for the first inversion of the C major
chord (indicated by "C/E"), E would be the lowest
note so g would reference the note E.
.P
Like other gchord codes, you may append a numeral indicating
the duration of the note. The same rules apply as before.
You can use any combination of the gchord codes,
(fcbghijGHIJz).


.PP
%%MIDI chordprog n
.PP
Sets the MIDI instrument for the chords to be n. If the command
includes the string octave=n where n is a number between \-2 and 2
inclusive, then this will shift the pitch of the instrument by n
octaves. For example %%MIDI chordprog 10 octave=1.)

.PP
%%MIDI bassprog n
.PP
Sets the MIDI instrument for the bass notes to be n. If the command
includes the string octave=n where n is a number between \-2 and 2
inclusive, then this will shift the pitch of the instrument by n
octaves. For example %%MIDI bassprog 10 octave=\-1.)
.PP
%%MIDI chordvol n
.PP
Sets the volume (velocity) of the chord notes at n.
.PP
%%MIDI bassvol n
.PP
Sets the volume (velocity) of the bass notes at n. There is no corresponding
melodyvol command since there are 3 velocity values for melody, set using the
beat command.
.PP
%%MIDI gchordon
.PP
Turns on guitar chords (they are turned on by default at the start of a
tune).
.PP
%%MIDI gchordoff
.PP
Turns off guitar chords.
.PP
%%MIDI droneon
.PP
Turns on a continuous drone (used in bagpipe music) consisting
of two notes. By default the notes are A, and A,, played
on a bassoon at a velocity of 80. This can be configured
by the %%MIDI drone command described below.
.PP
%%MIDI droneoff
.PP
Turns off the continuous drone.
.PP
%%MIDI drone n1 n2 n3 n4 n5
.PP
Sets the drone parameters where n1 is the MIDI program, n2 and
n3 specify the MIDI pitches of the two notes in the chord, and n4 
and n5 specify the MIDI velocities of the two notes.
If you do not set these parameters they are by default
70 45 33 80 80. A value of zero or less indicates that
the setting of this parameter should be left as it is.
.PP
%%MIDI drum string [drum programs] [drum velocities]
.PP
This sets up a drum pattern. The string determines when there is a drum beat
and the drum program values determine what each drum strike sounds like.
.PP
e.g. %%MIDI drum d2zdd 35 38 38  100 50 50
.PP
The string may contain 'd' for a drum strike or 'z' for a rest. By default
a voice starts with no drum pattern and '%%MIDI drumon' is 
needed to enable the drumming. The drum pattern is repeated during
each bar until '%%MIDI drumoff' is encountered. The %%MIDI drum 
command may be used within a tune to change the drum pattern. 
This command places the drum sounds on channel 10 and
assumes your tone generator complies with the General Midi standard - if
it does not, then you may hear tones instead of drum sounds.
.PP
In both the gchord and drum commands, the standard note length of
a single note f,c,z or d is not set by the L: command. Instead it
is adjusted so that the entire gchord string or drum string fits
exactly into one bar. In other words the duration of each note
is divided by the total duration of the string. This means that,
for example, the drum string "dd" is equivalent to drum string "d4d4".
You cannot currently specify fractions directly (eg. C3/2)
as done in the body of the music, but it is still possible to express
complex rhythms. For example, to indicate a rhythm such as
(3ddd d/d/d/d, you would write the string "d4d4d4d3d3d3d3".
.PP
%%MIDI drumbars n
.PP
The %%MIDI drum line can sound quite monotonous if it is repeated
each bar. To circumvent this problem a new MIDI command
%%MIDI drumbars n
where n is a small number will spread out the drum string over
n consecutive bars. By default drumbars is set to 1 maintaining
compatibility with existing abc files. You should take
care that the drumstring is evenly divisible between the
drumbar bars. Also the time signature should not change
between bars in a drumbar unit. (Sample abc file in doc/CHANGES
June 24 2008.)
.PP
%%MIDI gchordbars n
.PP
This command spreads the gchord string over n consecutive bars
just like drumbars (above). (A sample is found in doc/CHANGES
March 17 2009.)




.PP
With version 1.54 Dec 4 2004 of abc2midi, notes in chords
(eg. [FAc]) are not played in the same instant but offsetted
and shortened by 10 MIDI time units. Thus the first note
in the chord (eg. F) is played for the full indicated time,
the second note (eg. A) starts 10 MIDI units later and is shortened
by the same amount and the third note starts another 10 MIDI
units later and is shortened by another 10 units. This introduces
an "expressivo" option and avoids the heavy attack. (This
does not apply to gchords or multivoiced chords.) The amount
of the delay and shortening may be configured by the MIDI command

.PP
%%MIDI chordattack n

.PP
where n is a small number. If n is zero, then abc2midi should
behave as in earlier versions. The delay n is in MIDI time units
where there are 480 units in a quarter note beat. The program
may not run correctly if n is too large and there are short
chords.

.PP
%%MIDI randomchordattack n
.PP
Like above except that the delay is a random variable uniformly
distributed between 0 and n-1.

.PP
%%MIDI trim x/y
.PP
where x and y are two numbers. This command controls the articulation
of notes and chords by placing silent gaps between the notes.  The length
of these gaps is determined by x/y and the unit length specified by the L:
command. These gaps are produced by shortening the notes by the same amount.
If the note is already shorter than the specified gap, then the gap
is set to half the length of the note.  The fraction x/y indicates
a note duration in the same manner as specified in the abc file.
The actual duration is based on the unit length specified by the
L: field command. It is recommended that x/y be a fraction close
to zero. Note trimming is disabled inside slurs as specified by
parentheses. You can turn off all note trimming by setting x to 0,
eg 0/1. By default, note trimming is turned off at the beginning
of a tune or voice command.

.PP
%%MIDI expand x/y
.PP
where x and y are two numbers defining a fraction less than 1.
This command controls the articulation of notes and chords in the
reverse manner. The notes are lengthened by this fraction so they
overlap the start of the next note.


.PP
%%MIDI drummap note midipitch
.PP
Please see abcguide.txt.
.PP
%%MIDI ptstress filename
.PP
This command loads file filename into abc2midi which contains
the Phil Taylor stress parameters and puts abc2midi in the mode
where it applies these stress parameters on every note. This
model runs in opposition to the standard beat model, so the
MIDI beat, beatstring, beatmod commands become ineffectual.
This also means that the dynamic indications !f! !pp! etc.
do not work any more.
.PP
There are two different implementations of the stress model.
Model 1 modifies the note articulation and takes
control of the MIDI trim parameters too. To revert back to
the standard model, put the command %%MIDI beataccents.
Model 2 modifies both the onset and ending of each note
allowing a musical beat to expand or contract in time. However,
the length of a musical measure should be preserved. Note
if you using model 2, which the current default, you must
include \-BF as one of the runtime parameters of abc2midi.
.PP
The model divides a bar into equal segments. For each segment,
a loudness or MIDI velocity is specified and a duration multiplier
is specified. If a note falls into a specific segment, it assumes
the velocity of that segment and its duration is modified
accordingly. If the note overlaps more than one segment, then
the note assumes the average of those segment values.
.PP
The input file specifies the number of segments and the loudness
and duration multipliers for each segment. The file has the
following format. The first value is the number of segments and each line
specifies the velocity and duration multiplier of the specific
segment. The velocity is limited to 127 and the duration is a
decimal number. The note durations is modified by varying the
gap between notes, so it is not possible to extend a note. This
preserves the regular tempo of the music. The program scales,
the note duration indications by dividing it by the maximum
value which here is 1.4.

.PP
%%MIDI stressmodel n
.PP

where n is either 1 or 2, selects the stress model implementation.

.PP
 other %%MIDI commands such as bendvelocity, bendstring,
controlstring have been introduced recently and are described
in the file abcguide.txt.



.SH "COMPATIBILITY WITH DRAFT STANDARD 2.0"

.PP
The proposed standard introduces a new copyright field
using the syntax

.PP
%%abc-copyright (c) Copyright John Smith 2003

.PP
Abc2midi now inserts this in the MIDI file in the form of a
metatext copyright tag. Changes were made to the event_specific
function in store.c to process the copyright information. It
is also copied into the Karaoke track (if it is created) as
as @T field.

.PP


.SH SEE ALSO
abc2ps(1), midi2abc(1), yaps(1).
.SH AUTHOR
James Allwright <J.R.Allwright@westminster.ac.uk>
.SH SUPPORTED
 by Seymour Shlien <fy733@ncf.ca>
.SH VERSION
This man page describes abc2midi version 2.27  June 25 2006.
.SH COPYRIGHT
Copyright 1999 James Allwright
.PP
abc2midi is supplied "as is" without any warranty. It
is free software and can be used, copied, modified and
distributed without fee under the terms of the GNU General 
Public License.
.PP
More complete documentation may be found in abcguide.txt
which comes with the abcMIDI distribution.