richard/abcmidi
1
0
Fork 0
mirror of https://github.com/sshlien/abcmidi.git synced 2025-12-06 06:55:06 +00:00
Code Issues Projects Releases Wiki Activity

abcMIDI-2020.07.06.zip

Browse Source
This commit is contained in:
Seymour Shlien
2020-07-12 12:40:01 -04:00
commit 0497c9a75b
84 changed files with 66163 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
doc/AUTHORS Normal file
View File

@@ -0,0 +1,26 @@
This file contains additional documentation for the abcMIDI package :
Unix Man Pages
--------------
* abc2midi.1 man pages for abc2midi written by Christoph Dalitz.
* midi2abc.1 man page for midi2abc written by Christoph Dalitz.
* abc2abc.1 man page for abc2abc written by Anselm Lingnau.
* mftext.1 man page for mftext written by Anselm Lingnau.
These man pages are now supported by Seymour Shlien
If you wish to preview these man pages use groff with the -man
option. The output is normally in postscript format, but you
can override this using the -a option. For example,
groff -man -a abc2midi.1
To install the man pages, copy them to appropriate directory (typically
this will be /usr/man/man1). You may also need to run mandb after
copying them across.
Code Documentation
------------------
* abc2midi.txt : notes on the abc2midi code written by Seymour Shlien.
* midi2abc.txt : notes on the midi2abc code written by Seymour Shlien.

13748
doc/CHANGES Normal file
View File

File diff suppressed because it is too large Load Diff

123
doc/abc2abc.1 Normal file
View File

@@ -0,0 +1,123 @@
.TH ABC2ABC 1 "07 June 2011"
.SH NAME
abc2abc \- a simple abc checker/re-formatter/transposer
.SH SYNOPSIS
\fBabc2abc\fP \fIfile\fP [ \fB-s\fP ] [ \fB-n\fP ] [ \fB-b\fP ]
[ \fB-r\fP ] [ \fB-e\fP ] [ \fB-t \fP\fIsemitones\fP ] [ \fB-nda\fP ]
[ \fB-u\fP ] [ \fB-d\fP ] [ \fB-v\fP ] [ \fB-V\fP\fIvoice number\fP]
[\fB-P\fP\fivoice number\fp] [\fB-nokeys\fP]
[ \fB-nokeyf\fP] [ \fB-usekey\fP\fI(sharps/flats)\fP]
[\fB-useclef\fP\fI(treble/clef)\fP] [ \fB-OCC\fP ]
.SH "DESCRIPTION"
.PP
.B abc2abc
is a simple abc checker/re-formatter/transposer.
It will check whether the \fIfile\fP given on the command line
obeys basic abc syntax.
.PP
If you want to check an abc tune,
it is recommended that you use
.B abc2midi
with the \fB-c\fP option.
This performs extra checks that
.B abc2abc
does not do.
.PP
The output of
.B abc2abc
goes to standard output.
Use redirection to save it to a file.
.SH OPTIONS
.TP
.B \-s
Rework spacing in the file (which affects how notes are beamed together
when the music is printed out). This option does not appear to be working
correctly.
.TP
.BI \-n " X"
Reformats the abc file with line breaks every \fIX\fP bars.
.TP
.B \-b
Don't do bar checking.
.TP
.B \-r
Don't do repeat checking.
.TP
.B \-e
Don't report errors.
.TP
.BI \-t " n"
Transpose tune by \fIn\fP semitones. This function will also
work with K: none or one of \-nokeys or \-nokeyf.
If a voice is assigned to channel 10 (drum channel) using a
%%MIDI channel 10
command, then this voice is never transposed.
.TP
.B \-nda
Convert double accidentals in guitar chord to another chord though
strictly not correct.
.TP
.B \-u
Update notation; the older notation \fB+ +\fP for chords is replaced by
\fB[]\fP and \fBs s\fP for slurs is replaced by \fB()\fP.
.TP
.B \-OCC
Accept the old notation for chord. Normally this is turned off,
since it conflicts with abc draft standard version 2.0 for
decorations (eg. +crescendo(+).
.TP
.B \-d
Re-notate the tune with all note lengths doubled. The unit length specified by the L: field
command is halved (e.g. L:1/8 to L:1/16).
.TP
.B \-v
Re-notate the tune with all note lengths halved. The unit length specified by the L: field
command is doubled (e.g. L:1/8 to L:1/4).
.TP
.B \-ver
Prints version number and exits.
.TP
.BI \-V " X[,Y...]"
For multivoiced abc files (i.e. contains V: field commands), only voices \fIX[,Y,...]\fP are copied.
.TP
.BI \-P " X,[,Y...]"
For multivoiced abc files (i.e. contains V: field commands), all voices except \fIX[,Y...]\fP remain the same. Voices X,Y... are modified according the other runtime parameters.
.TP
.BI \-X " n"
For a file containing many tunes, the X: reference numbers are renumbered sequentially
starting from number \fIn\fP.
.TP
.BI \-xref " n"
Only the tune with X: n is processed.
.TP
.B \-nokeys
No key signature will be assumed. Instead, sharps and naturals will
be placed wherever they are needed.
.TP
.B \-nokeyf
No key signature will be assumed. Instead, flats and naturals will
be placed wherever they are needed.
.TP
.B \-usekey " sf
This will force abc2abc to output the notes in the key signature
keys[sf] where sf specifies the number of flats (\-negative) or
sharps (+positive) in the key signature. It is a number between
\-5 and +5 inclusive.
.TP
.B \-useclef
This works with only the -t (transpose) and provided the abc
file does not already have a clef command in the K: field. It
does not support voices.
.PP
* Normally abc2abc will convert the deprecated notation for
decorations (eg. !ppp!) to the abc version 2.0 draft standard (eg. +ppp+).
If you do not wish to change to this standard include the \-OCC flag.
.SH "SEE ALSO"
.IR abcmtex "(1), " abc2midi "(1), " midi2abc "(1), " mftext "(1)"
.SH AUTHOR
This manual page was written by Anselm Lingnau <lingnau@tm.informatik.uni-frankfurt.de> and is now supported by Seymour Shlien <fy733@ncf.ca>
for the GNU/Linux system.
.SH VERSION
This man page describes abc2abc version 2.04 from January 22 2020.

568
doc/abc2midi.1 Normal file
View File

@@ -0,0 +1,568 @@
.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.

1693
doc/abcguide.txt Normal file
View File

File diff suppressed because it is too large Load Diff

120
doc/abcmatch.1 Normal file
View File

@@ -0,0 +1,120 @@
.TH ABCMATCH 1
.SH NAME
abcmatch \- Search for specific sequences of notes in an abc file composed of many tunes.
.SH SYNOPSIS
\fBabcmatch\fP \fiabc\ file\fP [\fB-c\fP] [\fB-v\fP] [\fB-r\fP] [\fB-con\fP]\
[\fB-fixed nn\fP] [\fB-qnt\fP] [\fB-lev\fP] [\fB-a\fP] [\fB-ign\fP]\
[\fB-br %d\fP] [\fB-tp abc reference file\fP] [\fB-ver\fP]\
[\fB-pitch_hist\fP] [\fB-wpitch_hist\fP] [\fB-length_hist\fP]\
[\fB-interval_hist\fP] [\fB-pitch_table\fP] [\fB-interval_table\fP]\
\fireference\ number\fP
.SH "DESCRIPTION"
.PP
.B abcmatch
is used to search for specific sequences of notes in an abc file
composed of many tunes. For example, if you know a few bars of a tune,
you can use this program to find the tune having this sequence and perhaps
identify the tune.
At a minimum, abcmatch requires two files. A template file called
match.abc which contains the bars that you are searching for and a large
file consisting of a hundred or more abc tunes. The program automatically
loads up the match.abc file and then scans every tune in the large file
.SH OPTIONS
.TP
.B -v and -c
mainly used for debugging when the program does not do what was expected.
.TP
.B -ver
prints version number and then exits
.TP
.B --norhythm
Causes the matching algorithm to ignore the length of notes in a bar,
thus E3/2F/D GA2 would match EFD G2A. The option ignores \-r parameter
since it is now irrelevant.
.TP
.B -pitch_table
Used to produce a interval weighted pitch histogram for each tune in
the file. If this is saved in an external file, that file could be used
as a database for finding tunes with similar pitch probability density
functions (pdf).
.TP
.B -r
Controls how the matching criterion handles small rhythm variations in
the melody. The \-r option must be followed by a number which specifies
the temporal resolution for the match. When the number is zero, this
indicates that a perfect match should be performed, meaning that the
lengths of each note in the bar must match exactly in order to be
reported. For larger values a looser match will be performed as
described below. Note lengths are converted into temporal units where
a quarter note normally is assigned a value of 24. Therefore an eight
note has a value of 12, a sixteenth has a value of 6, a half note has
a value of 48 and etc. If you specify a temporal resolution of 12, then
the pitch values of the notes only need to match at time units which
are multiples of an eighth note.
.TP
.B -fixed n
Causes the program to disregard bar lines when does the matching. It
allows matching of notes between tunes having different time signatures.
n is a number which specifies the exact number of notes to match. For
example if n is 4, the program could match
|C E G E| .. with |C E|G E|
Note the matcher still starts at a beginning of a given bar for both the
tune and template.
.TP
.B -con
Specifies contour matching. In this case, the program uses the key
signature only to indicate accidentals. The pitch contour is computed
from the pitch difference or interval between adjacent notes.
.TP
.B -qnt
Uses the contour matching algorithm but also quantizes the intervals
using the following table:
unison and semitone 0
minor 2nd to major 2nd 1
minor 3rd to major 3rd 2
any larger interval 3
Negative numbers are descending intervals.
.TP
.B -tp file name, reference number
Substitute any tune for the template match.abc. When using this
feature, the entire tune is used as a template. Abcmatch does not match
the template with itself, and only bars which match bars in other tunes
are reported.
.TP
.B -br threshold
Runs the program in a brief mode designed to identify groups of tunes
sharing common bars. In this mode, the program counts the numbers of
bars in the test tune which are also present in match.abc. If the
number of common bars is larger or equal to the threshold then the
program reports the tune and the number of common bars.
The program scans all the tunes in the abc file and returns a list of
all the tunes which have more than a specific number of bars in common
with the template, match.abc. In actual use, the program is run
repeatedly by a script. For each tune in a abc file, it creates a
template file called match.abc and then executes abcmatch. The outputs
are displayed on the screen in a form easy to interpret. The user has
no control of the matching criterion. The rhythm must match exactly
and the notes are transposed to suit the key signature. In other words
the \-r parameter is independent of what is specified in the parameter
list.
.TP
.B -pitch_hist or -length_hist
Runs the program in another mode. It produces a histogram of the
distribution of the notes in the abc file.
The pitch is indicated in midi units. Thus middle C is 60 and the
pitches go up in semitone units. Following the pitch is a count
of the number of times that note occurred.
.TP
.B -pitch_table or -interval_table
Used to create a database for a collection of tunes in a file for
future analysis.
.SH "SEE ALSO"
.PP
.IR abc2abc "(1), " abc2midi "(1), " mftext "(1) ", midi2abc "(1) ", midicopy "(1) ", yaps "(1)"
.SH AUTHOR
This manual page was written by Ross Gammon based on abcmatch.txt by Seymour Shlien.
.SH VERSION
This man page describes abcmatch version 1.35 from January 15 2006.

318
doc/abcmatch.txt Normal file
View File

@@ -0,0 +1,318 @@
abcmatch version 1.35 January 15 2006.
seymour shlien <fy733@ncf.ca>
Introduction:
------------
The purpose of this program is to search for specific sequences of
notes in an abc file composed of many tunes. For example, if you
know a few bars of a tune, you can use this program to find the
tune having this sequence and perhaps identify the tune.
At a minimum, abcmatch requires two files. A template file called
match.abc which contains the bars that you are searching for and
a large file consisting of a hundred or more abc tunes.
The program automatically loads up the match.abc file and
then scans every tune in the large file.
The match.abc file is a regularly formatted abc file containing
the basic fields, X:, M:, L:, and K: and the body.
Normally, this file is created by runabc.tcl.
An example match.abc file is shown below.
X:1
M:6/8
L:1/8
K:E
cff f2e|
As well as the sample bars, abcmatch needs to know the meter
(given by M:) and the key signature (given by K:). The default note
length L: should also be given if it is not 1/8. It is important
that all bars be terminated with a bar line indicated by |
(otherwise that bar may not be seen by the program).
Abcmatch uses the key signature to know the relative position
of the notes in the scale. It also uses the key signature to
determine all the assumed sharps and flats. Thus the program
can find matching bars in a tune transposed to another key
signature (assuming the key difference is not too large).
When the program finds matches, they are returned in a list that
looks like this.
abcmatch.exe scotjig.abc
29 30 4
30 31 4
Each line indicates a particular match made by the program.
The first number, (eg. 29) indicates the relative position of
the tune in the abc file. Thus in this example, it indicates
that a match was found for the 29 th tune in compilation file
scotjib.abc. The next number is the X: reference number of
that tune, and the last number is the bar number of the matching
tune. Bar numbers are counted sequentially from the start of
the tune, ignoring all V: and P: indications. Thus the bar
numbers may not match the ones you get when you print the
tune using one of the variants of abc2ps or yaps.
Though the program can be run stand alone, it is really meant to
be run with a graphics user interface such as runabc.tcl (version
1.59 or higher). Most of its output is rather cryptic.
In performing the match, the program ignores all guitar chords,
karaoke, note decorations (eg. stacatto markings), grace notes
and hornpipe rhythm indications in either the match.abc template
file or in the target file. Furthermore if chords in the form
of [G2c2] are embedded in the abc file, only the higher note
c2 is matched. Any warnings and error messages that are normally
returned by the parser are suppressed unless the run time
parameter -c is included.
Installation:
------------
Unless you are running the program on Microsoft's windows
operating system, it will be necessary for you to build the
program from sources. For windows environment, I shall provide
the executable. Here is how the makefile looks.
CFLAGS=-c
abcmatch: parseabc.o matchsup.o abcmatch.o
gcc parseabc.o matchsup.o abcmatch.o -o abcmatch.exe
parseabc.o : parseabc.c abc.h
gcc $(CFLAGS) abcparse.c
matchsup.o : matchsup.c abc.h
gcc $(CFLAGS) abcstore.c
abcmatch.o : abcmatch.c abc.h
gcc $(CFLAGS) abcmatch.c
The program has been built using the gcc (GNU compiler) as well
as Microsoft Visual C++ (with many warning messages).
Operation:
---------
Here is now an explanation of the program and its run time
parameters. If you run abcmatch without any parameters you
will see:
abcmatch version 1.55
Usage : abcmatch <abc file> [-options]
[reference number] selects a tune
-c returns error and warning messages
-v selects verbose option
-r resolution for matching
-con pitch contour match
-fixed <n> fixed number of notes
-qnt quantized pitch contour
-lev use levenshtein distance
-a report any matching bars (default all bars)
-ign ignore simple bars
-br %d only report number of matched bars when
above given threshold
-tp <abc file> [reference number]
-ver returns version number
-pitch_hist pitch histogram
-wpitch_hist interval weighted pitch histogram
-length_hist pitch histogram
-interval_hist pitch interval histogram
-pitch_table separate pitch pdfs for each tune
-interval_table separate interval pdfs for each tune
When running this program, you must provide the name of the abc file name
containing the numerous tunes. The other parameters are optional and
are explained below.
The -c and -v options are mainly used for debugging when the
program does not do what was expected. The -ver option does
nothing but return the version number of the program. (This
is used to perform a sanity check when you are running it
from runabc).
All the remaining parameters (-r -con -a -br) control the matching
process.
The option -norhythm, causes the matching algorithm to ignore
the length of notes in a bar, thus E3/2F/D GA2 would match
EFD G2A. The option ignores -r parameter since it is now
irrelevant.
The option -pitch_table is used to produce a interval weighted
pitch histogram for each tune in the file. If this is saved
in an external file, that file could be used as a database
for finding tunes with similar pitch probability density functions
(pdf).
The -r parameter controls how the matching criterion handles
small rhythm variations in the melody. The -r option must be
followed by a number which specifies the temporal resolution
for the match. When the number is zero, this indicates that
a perfect match should be performed, meaning that the lengths
of each note in the bar must match exactly in order to be
reported. For larger values a looser match will be performed
as described below. Note lengths are converted into temporal
units where a quarter note normally is assigned a value of
24. Therefore an eight note has a value of 12, a sixteenth has
a value of 6, a half note has a value of 48 and etc. If you
specify a temporal resolution of 12, then the pitch values
of the notes only need to match at time units which are multiples
of an eighth note.
This means that the program would match the two bars
C2 D2| and C C D D|.
Similarly C2 D2| would also match C/D/C/D/D2|. By using
a suitable value of the resolution, you can perform the
matching only at the beginning of a measure or at the
beginning of each beat.
The -fixed <n> option causes the program to disregard
bar lines when does the matching. It allows matching
of notes between tunes having different time signatures.
n is a number which specifies the exact number of
notes to match. For example if n is 4, the program
could match
|C E G E| .. with |C E|G E|
Note the matcher still starts at a beginning
of a given bar for both the tune and template.
Normally, when the program is presented with a sequence
of several bars, the program will try it match it with
a matching sequence. If abcmatch is run with the -a option,
then the bars are matched individually in any sequence.
In other words any matching bar found is reported.
The -con option specifies contour matching. In this case,
the program uses the key signature only to indicate accidentals.
The pitch contour is computed from the pitch difference
or interval between adjacent notes.
Thus C2 DE| and c2 de| and G2 AB| all have the same pitch
contour.
The -qnt option will use the contour matching algorithm
but also quantize the intervals using the following table
unison and semitone 0
minor 2nd to major 2nd 1
minor 3rd to major 3rd 2
any larger interval 3
negative numbers are descending intervals.
The -tp followed by a file name and reference number
allows you to substitute any tune for the template match.abc.
When using this feature, the entire tune is used as a
template. Abcmatch does not match the template with itself,
and only bars which match bars in other tunes are reported.
The -br followed by a threshold, runs the program in a brief
mode designed to identify groups of tunes sharing common bars.
(-br stands for brief mode; I cannot think of a better name
right now.) In this mode, the program counts the numbers of bars
in the test tune which are also present in match.abc. If the
number of common bars is larger or equal to the threshold
then the program reports the tune and the number of common bars.
The program scans all the tunes in the abc file and returns
a list of all the tunes which have more than a specific number
of bars in common with the template, match.abc. In actual
use, the program is run repeatedly by a script. For each
tune in a abc file, it creates a template file called match.abc
and then executes abcmatch. The outputs are displayed on the
screen in a form easy to interpret. Currently, the user
has no control of the matching criterion. The rhythm must
match exactly and the notes are transposed to suit the key
signature. In other words the -r parameter is zero independent
of what is specified in the parameter list.
The -pitch_hist or -length_hist runs the program in another mode.
It produces a histogram of the distribution of the notes in the
abc file. Thus if you type
abcmatch.exe scotjig.abc -pitch_hist
pitch_histogram
64 2
66 9
67 11
69 30
71 18
73 12
74 14
76 14
78 14
79 4
81 4
The pitch is indicated in midi units. Thus middle C is 60 and the
pitches go up in semitone units. Following the pitch is a count
of the number of times that note occurred. If you type
abcmatch.exe scotjig.abc -length_hist
length histogram
12 100
24 20
36 6
48 2
72 4
The program quantizes a quarter note into 24 units. Thus eighth notes
have a value of 12, dotted half notes 72, etc. The program does
not require the match.abc file to be present if you are computing
the histograms since it does not perform any matching.
abcmatch.exe scotjig.abc -interval_hist
computes the histogram of the pitch interval in midi units
between adjacent notes. The histogram is restricted between
intervals -12 and 12 units.
eg.
interval_histogram
-5 2
-4 3
-3 10
-2 17
-1 3
0 8
1 3
2 23
3 11
4 1
5 4
For a collection of tunes in a file, you can use -pitch_table
or -interval_table to create a database for future analysis.
Limits of the program
---------------------
The program has some limits. For example, the abc file must
have bar lines. Tied notes cannot be longer than 8 quarter notes.
Specifying a too small resolution (eg. -r 1) may causes some
buffers to be exceeded. When there are differences of key
signatures more than 5 semitones, the program may transpose
the notes in the wrong direction.
Abc tunes with more than one key signature or time signature
may not be processed correctly.
Comment:
________
This program is designed to be a research tool to find
similarities between abc tunes. I have discovered a few
problems with tied notes and double or triple bar lines.

340
doc/gpl.txt Normal file
View File

@@ -0,0 +1,340 @@
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and
modification follow.
GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language. (Hereinafter, translation is included without limitation in
the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
b) You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.
c) If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
a) Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,
b) Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
c) Accompany it with the information you received as to the offer
to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable. However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.
If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.
5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.
10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) 19yy <name of author>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.
<signature of Ty Coon>, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library. If this is what you want to do, use the GNU Library General
Public License instead of this License.

525
doc/history.txt Normal file
View File

@@ -0,0 +1,525 @@
This file has not been updated since I have taken over
the support of the abcMIDI package. To see the list
of the latest versions see the readme.txt file. To see
a log of all the changes I have made see the file CHANGES.
The abcguide.txt and the unix (linux) man files (eg. abc2midi.1)
contain the latest user guides. The abcguide.txt probably
contains the most detail. The official version number
of the abcMIDI package is given in the file VERSION.
Seymour Shlien 26 October 2003.
-------------------------------------------------------------
current versions :
midi2abc version 2.4
abc2midi version 1.24
abc2abc version 1.19
yaps version 1.12
Improvements made to abcMIDI package
------------------------------------
1. abc2midi was found not to handle comments at end of lines properly.
This was fixed in the source code with release 1.2.1 of abc2midi.
2. midi2abc was generating %MIDI instead of %%MIDI for a program change.
This was fixed in release 1.6.1
3. Release 1.2.2 of abc2midi introduced the -c checking only option and
some new error checking, as well as code to deduce repeats.
4. abc2abc 1.0 was released on 25th July 1996
5. Release 1.2.3 of abc2midi allowed more flexible use of ::, :| and |:,
improved handling of tuples and other minor improvements.
6. Added #ifdefs for Mac port.
7. Added -xm and -xl options to midi2abc plus a straight quantization
algorithm for better handling of MIDI output by another package.
8. Added -Q option to midi2abc.
9. Removed the default heuristic algorithm and use a straight quantization
algorithm by default, with code to find a good note length by brute-force
trial - Original algorithm sometimes made mistakes in quantizing.
10. Added V: field to allow multi-track output from abc2midi in version 1.3
11. Changed Error messages to Warning messages for some error conditions in
abc2midi.
12. Improved bar length checking to prevent errors being generated by the
anacrusis in abc2midi.
13. Added checking for equal track lengths in abc2midi.
14. Made midi2abc fail cleanly when it runs out of memory for notes.
15. Fixed part-handling bug in abc2midi.
16. Improved handling of bar placement in midi2abc.
17. Fixed various type inconsistencies in midifile.c to improve portability.
18. abc2midi was not handling propagation of accidentals within a bar e.g.
|^cdc|. This was fixed.
19. Added handling for the 7 key signature modes and re-wrote parsekey in
the process.
20. Fixed bug in hornpipe handling routine (tomidi.c).
21. Fixed bug in default unit calculation (toabc.c).
22. Changed midi2abc to look at last note to decide between equally likely
key signatures and suggest a mode for the tune if it does not appear
to be major mode.
23. Changed strchr to index in mftext.c to aid portability.
24. Changed handling of grace notes to report more error conditions.
25. Changed midi2abc to generate voice fields for format 1 files and also
to assume the same length anacrusis in each voice.
26. -xa option added to midi2abc to deduce anacrusis by looking for a strong
beat.
27. Release 1.4 of abc2midi allows [ and ] for chords, ( ) for slurs and also
introduced a queue mechanism for allowing general polyphony.
28. Release 1.4 of abc2midi appears to a fix a problem with chord generation.
29. Release 1.4 of abc2midi recognizes J, H, L and R as note decorations.
30. Fixed bug in hornpipe routine.
31. Fixed bug in note decoration recognition.
32. Added support for multiple fields in " " and ! ! separated by ; .
33. Fixed problem with grace notes before chords.
34. Added support for new K: field standard
35. Fixed bug that caused spurious ties from notes at the end of a slur
field.
36. Release 1.4.2 of abc2midi made on 15th January 1997.
36. Correction to midi2abc quantization algorithm
37. abc2midi changed to allow TAB character instead of space.
38. -n option added to abc2midi (not the PC version, which already uses
almost the maximum possible memory).
39. Support added for augmented and diminished chords.
40. Support added for repeats in part notation e.g. P:A(AB)6.
41. Added transpose option to abc2abc.
42. Release 1.4.3 of abc2midi made on 28th April 1997.
43. Added support for w: field in abc2midi
44. Fixed problem in chord handling in abc2abc
45. %%MIDI gchord allowed in mid-tune
46. added %%MIDI chordprog, bassprog, chordvol, bassvol
47. length specifiers allowed in %%MIDI gchord string
48. fixed bar-length checking in abc2abc to do chords and grace notes
49. Made the linebreaking option more intelligent in abc2abc.
50. Made abc2abc linebreak at P:
51. added -u option to abc2abc
52. added %%MIDI control command to abc2midi
53. added support for karaoke MIDI to abc2midi.
54. changed karaoke support to act line by line.
55. Minor bug fix to karaoke support in version 1.5.1
56. Fixed bug in part handling pointed out by Steve Allen.
58. Complete re-write of midi2abc to use dynamic data structures.
version 2.0 (beta) released on 8th June 1998.
59. Added -k (specify key) and -ga (guess anacrusis) options to midi2abc.
Fixed bug in printing rests.
60. version 2.0 of midi2abc released on 12th June 1998.
61. non-portable error diagnosis removed from mftext and midi2abc.
62. midi2abc fixed to always produce legimite length notes.
63. Parser changed to allow arbitrarily long lines.
64. midi2abc changed to recognize rests before each track.
65. midi2abc changed to used c = 72 (and undo abc2midi pitches).
66. Parser changed to allow decorations to be applied to chords.
67. abc2midi changed to allow broken rhythm between chords.
68. abc2midi changed to improve accuracy of reported line numbers.
69. abc2midi mallocs more space for notes or text when needed.
70. support for staccato notes in chord.
71. improved tie handling code.
72. fix to allow all channels to be used (suggested by De Clark).
73. Static limit on number of syllables in w: fields removed.
74. Allowed . in part specifier (P: field in header).
75. Used %%MIDI beat to implement !ppp! to !fff!.
76. Added -o option to abc2midi to specify filename.
77. Corrected problem with Voice/Part conflict reported by Brendan Macmillan.
78. Removed bug in line number generation for error reports.
79. Version 1.5.8 of abc2midi released on 21st Sept 1998.
80. Further bug fixing for Voice/Part problem.
81. Trap buffer overflow in NOFTELL version - problem reported by Richard
Robinson
82. Clean up NOFTELL modifications to remove linker problems (pcc version).
83. New NOFTELL mechanism introduced - do a dummy write track to determine
track length in abc2midi.
84. P:X in the header allowed to be a part marker in abc2midi.
85. Changed save_note() so that chord generation takes account of transpose
- problem report and bug fix by Seymour Shlien
86. Tidied up note off queue handling in abc2midi. Fixes problem with PCC
version NOFTELL fix.
87. Changed min to long in midi2abc guesslengths(). Fixes PCC divide by
zero error.
88. Added rtranspose to abc2midi.
89. Cleaned up midi2abc and midifilelib code (no implicit declarations of
parameter types).
90. Voices inherit global transpose, tempo and meter instead of values from
previous track.
91. Removed spaces from after tie signs in midi2abc : abc spec. does not
allow spaces in chords.
92. voicecontext structure introduced to make K: and L: fields local to
their own voice in file parsing stage.
93. printf() fix: DJGPP seems to require %ld and not %Ld in printf to print
longs.
94. exit value for all codes made 1 on error and 0 on normal termination.
95. re-write of karaoke code to integrate it into main mywritetrack() code.
Also allows multiple verses and has better error-checking.
96. Added %%MIDI chordname and library of named chords to abc2midi
97. Fixed bug in | handling in abc2midi w: field.
98. Better checking for M: field in abc2midi
99. chord handling and broken rhythm handling moved to first pass of
abc2midi.
100. Further bug fixes for abc2midi w: field.
101. %%MIDI nobarlines and %%MIDI barlines options added to abc2midi -
based on changes suggested by Laura Conrad.
102. Added support for M:none.
103. Voice numbers changed from absolute voice numbers to numerical labels.
104. Accompaniment written to separate track by abc2midi.
105. Support put in the parser for abc2ps's [X: ] inline field notation.
106. Fix to stop bogus Q: fields crashing abc2midi.
107. Support for "_Ignored words" in abc2midi.
108. abc2midi allows voices after voice 1 to be missing in some parts.
109. Changed mf_sec2ticks() in midifile.c to get rid of rounding errors
that were affecting the PCC version of midi2abc.
110. Fixed problem with tracks not starting at time=0 in abc2midi.
111. Fixed overflow problem with long H: fields in abc2midi.
112. [1 allowed to go mid-bar and [2 allowed to be separated from :|
in abc2midi. More robust repeat-fixing algorithm to take account of |1 and
:|2.
113. Fix to midifile.c suggested by Seymour Shlien to fix problem with
porting to MS visual C++.
114. Added support for trills in abc2midi.
116. Fixed bug in midi2abc that caused it to crash if input MIDI file
contained long metatext strings.
117. Added support for lyrics to tied notes in abc2midi.
118. Fixed bug that mangled %%MIDI lines in abc2abc and also stopped
abc2abc filtering out comments outside tune.
119. Added support for clefs in K: field.
120. Replaced K:cclef with proper clefs; baritone, tenor, alto, mezzo
and soprano.
121. Minor improvements to parseabc.c - recognizes multiple '/' in
length specifier and warns about c, or C'.
122. Added support for the I: field to parseabc.c and changed abc2midi
to recognize I:octave=X.
123. Added -d and -v options to abc2abc for changing unit note lengths.
124. Parser changed to report an error for \ * ** or ! in mid music line.
125. midi2abc changed to look for a filename if -f option is missing.
126. part-handling changed in abc2midi to handle an arbitrary number of
parts.
127. Support for variant endings more complicated than [1 and [2. Also
allow || to occur mid-bar.
128. Support for Mac-style text files (with \r as end of line).
129. -o and -sum options added to midi2abc by Seymour Shlien.
130. Fixed bug in Part/variant ending interaction in abc2midi.
131. Fixed bug in yaps' handling of in-tune M: fields.
132. Added font selection commands to yaps.
133. Added support for grace notes within broken rhythm to abc2midi.
134. Added page numbering to yaps.
135. Fixed bug in yaps which caused fonts to get lost after a newpage.
136. Added vskip command to yaps.
137. Added %% font and font-spacing commands to yaps.
138. Minor changes to support Pacific C compiler.
139. Added support in yaps for ties and slurs straddling 2 music lines.
140. Added -x (number tunes with number in X: field) to yaps.
150. Fix to yaps to handle guitar chords with characters in the
range 128-255.
151. Added proper tuple support to yaps - uses half-brackets when notes
in the tuple are not a beamed set.
152. Changed guitar chord transposition in abc2abc to handle A/B and A(B)
as well as not transposing anything with a leading underscore or other
special symbols.
153. Added support for flipping note heads and spacing out accidentals in
yaps.
154. Fix for K: parsing code which was running past the end-of-line character
in some cases and generating extra error messages in abc2midi.
155. Added support for treble-8, treble+8 and similar variants in yaps.
156. Fix for V: fields in header causing abc2midi to crash.
157. Changed K: field parser to accept clef=, octave= and transpose= .
160. Added support for %%staffsep to yaps.
161. Fix to make yaps bar-length checking cope with in-tune metre changes.
162. Changed yaps so that all tune spacing is calculated before output file
is opened. This is used to generate encapsulated PostScript and to
start a new page instead of breaking a tune across pages.
163. Added %%MIDI beatstring to abc2midi - using code by Martijn Versteegh.
164. Fixed BoundingBox generation in yaps.
165. Added explicit function type declarations and re-ordered some functions
as well as adding genmidi.h and queues.h to make code compile under
Pacific C and hopefully improve portability.
166. Added the %%MIDI drum command and !drum! and !nodrum! to abc2midi.
167. Added support for %%titleleft and %%titlecaps to yaps.
168. Fixed crash caused by !drum! with no %%MIDI drum statement.
169. Fixed obscure division by zero error in midi2abc.
170. Added landscape mode to yaps.
171. Shortened tempo note tail length in yaps so that it never collides
with the title.
172. Corrected positioning of C clef in yaps.
177. Added support for -n X to give X bars per line in abc2abc, with
correct handling of associated w: field.
178. Added support for dotted rests to yaps.
179. Fixed bug with broken rhythm in yaps.
180. Fixed bug causing abc2abc to crash with comments at end of w: field.
(code is still not ideal).
181. Created parser2.c for common code between abc2midi and yaps.
182. Made erroneous note-off events a non-fatal error in midi2abc.
184. Added drum track detection to midi2abc, with output that selects
channel 10 for drums.
185. Removed channel number from midi2abc %%MIDI program output, so that
abc2midi matches instrument to the correct voice in midi2abc output.
186. Added -s option to midi2abc to retain very short notes.
187. Support for abc2midi to handle very long filenames (provided by
Colin Watson).
188. Fix to allow abc2midi/abc2abc/yaps parser to handle space between
key A-G and mode.
189. Fix for abc2midi handling of non-consecutive voice numbers.
190. More user-friendly error message when chord buffer overflows in
abc2midi.
191. Support for w: line continuation characters in yaps.
192. Fixed problem with trill generation in abc2midi (was the wrong
length).
193. Fixed inconsistency in midi2abc.c causing a one octave transpose
if the -k switch was specified.
194. Changed abc2midi to support _, ^, <, > and @ in guitar chords.
195. Added support for /<inversion note> in abc2midi guitar chords.
196. Fix for Q:1/2=X in yaps.
197. Added support for breve notes and breve rests to yaps.
198. Changed yaps to accept rests in tuples.
199. Changed parser to accept tuples written as (n::r .
200. Fix for handling ties across chords in yaps.
201. Improved handling of M:none in yaps.
202. Fixes for bar-length checking in yaps.
203. Added %%MIDI ratio to abc2midi.
204. Applied fix supplied by Ingo Saitz for change of tempo not being
handled properly by abc2midi in multi-voice music.
205. Further fix for bar-length checking in yaps.
206. Added code change by Seymour Shlien to midi2abc for -sr option to
handle MIDI with gaps between notes that come out as rests.
207 Added %%chordsabove and %%chordsbelow to yaps.
208. Added handling for U: field (abbreviation) to parser.
209. Fix to abc2midi to stop accidentals in accompaniment chords from
being applied elsewhere in the bar.
210. Changed K: field parsing so that it only starts a tune if it
contains a key signature.
211. Trapped condition where double ties could cause segmentation faults
- thanks to Seymour Shlien for tracing down this problem.
212. Added -t and -n options to abc2midi for better handling of filenames.
213. Made parser more robust when handling L: field - thanks to Seymour
Shlien for telling me that this could cause division by zero errors.
214. Fix for problem reported by Ronan Keryell - gchord generation now
works after a meter change in the tune.
215. Added %%MIDI pitchbend command using code supplied by Peter Spath.
216. Modified readstr() in abc2midi/yaps parser to avoid potential buffer
overflow problem.
217. Added support for strings before and after Q: tempo field in yaps,
abc2midi and abc2abc. Also added support for yaps to print mid-tune
tempo change.
218. Added support for N: field to yaps.
219. Fixed problem with channel allocation in abc2midi following bug
report from Ronan Keryell.
220. Fixed abc2midi problem with broken rhythm > applied to chords
thanks to bug report by Ronan Keryell.
221. Added to support for multiple bar rests with Zn notation to
abc2abc, abc2midi and yaps.
222. Fix to abc2abc guitar chord transposing thanks to bug report by
Atte Jensen.
223. Fix to handling of reserved characters H-Z in abc2abc following
bug report by Luis Pablo Gasparotto.
224. Tidied abc2abc code by creating emit_() routines.
225. Fixed bug with broken rhythm marker able to insert itself in tied
notes. Thanks to Michel Chasseriau for reporting this.
226. Added support for voice filtering (-V option) to abc2abc. Many of
of the code changes for this were made by Seymour Shlien.
227. Added warning message to abc2midi when T: is found outside a tune.
228. Added -nt option to midi2abc to ignore triplets and broken rhythm.
229. Added -X n option to abc2abc.

20
doc/mftext.1 Normal file
View File

@@ -0,0 +1,20 @@
.TH MFTEXT 1
.SH NAME
mftext \- Dump a MIDI file as text
.SH SYNOPSIS
.BI mftext " file"
.SH "DESCRIPTION"
.PP
.B mftext
gives a verbose description of what is in a MIDI file.
You may wish to use it to check the output from
.BR abc2midi .
It is part of the original midifilelib distribution
available from
.IR http://www.harmony-central.com/MIDI/midifilelib.tar.gz .
.SH "SEE ALSO"
.PP
.IR abcmtex "(1), " abc2abc "(1), " abc2midi "(1), " midi2abc "(1)"
.SH AUTHOR
This manual page was written by Anselm Lingnau <lingnau@tm.informatik.uni-frankfurt.de>,
for the Debian GNU/Linux system.

106
doc/midi2abc-stats.txt Normal file
View File

@@ -0,0 +1,106 @@
The output of midi2abc with the -stats is used by
the midiexplorer application which can by found on
sourceforge.net. The output looks something like this
seymour@corsair:~/abc$ midi2abc summer.mid -stats
ntrks 10
ppqn 120
trk 1
timesig 4/4 0.00
keysig C 0 0 0.00
tempo 132.00 bpm
trk 2
metatext 3 Synth Bass 1
program 1 38
trkinfo 1 38 156 774 41022 50468
trk 3
metatext 3 Brass 1
program 2 61
trkinfo 2 61 102 0 6618 2982
trk 4
...
trk 10
metatext 3 Drums
program 10 17
trkinfo 10 17 1390 1158 108340 25777
npulses 58552
tempocmds 1
pitchbends 0
programcmd 0
progs 35 38 50 54 61 80 81 102
progsact 49460 50468 15426 3237 2982 22295 15938 4703
progcolor 0.00 0.00 0.00 0.00 0.00 1.71 0.00 0.26 0.06 0.05 0.00 0.00 0.00 0.65 0.00 0.08 0.00
drums 36 38 39 42 54
drumhits 548 287 128 1073 512
pitches 473 0 1267 216 20 344 36 717 0 321 364 0
pitchact 0.32 0.00 1.10 0.15 0.03 0.22 0.03 0.51 0.00 0.26 0.20 0.00
chnact 0.86 0.05 0.06 0.27 0.38 0.26 0.08 0.84 0.00 0.44 0.00 0.00 0.00 0.00 0.00 0.00
pitchentropy 2.567729
Here is a description of some of the values which are outputted.
timesig 4/4 beat number
is issued each time the time signature is redefined. The beat number
is a decimal number in quarter beats.
The same apples for keysig (key signature) and tempo redefinition.
For each channel, midi2abc prints a trkinfo vector which contains
the following information.
the channel number
the first program number assigned to the channel
the number of notes not appearing inside a chord
the number of notes appearing in a chord
the sum of all the MIDI pitches of the notes
the sum of all the note durations in pulses
Finally, midi2abc outputs the following data.
npulses -- the length of the longest track in pulses
tempocmds - the number of tempo commands encountered
pitchbends - the number of pitchbend commands encountered
programcmd - the number of times the program assignment is
reassigned
progs vector - list of all the MIDI programs used
progsact vector - the activity for each of the above MIDI programs. The
activity is the sum of the note durations in pulses for each of the
above programs.
progcolor - described below
drums - a list of all the MIDI percussion numbers used
drumhits - the number of note on commands for each of the above percussion
instruments.
pitches - the number of note on commands for each of the 12 pitch
classes (C, C#, D, D# ... B)
pitchact - duration in pulses of all notes grouped by pitch classes
chnact - duration in pulses of all notes grouped by channel
pitchentropy - entropy of the pitchact probability density function
progcolor: The 128 MIDI program numbers are mapped into 17 classes.
These classes group keyboard instruments, brass instruments, guitar
instruments etc into separate groups defined here.
static int progmapper[] = {
0, 0, 0, 0, 0, 0, 0, 0,
0, 1, 1, 1, 1, 1, 1, 2,
3, 3, 3, 3, 3, 3, 3, 3,
2, 2, 4, 4, 4, 4, 4, 2,
5, 5, 5, 5, 5, 5, 5, 5,
6, 6, 6, 6, 6, 2, 7, 10,
7, 7, 7, 7, 8, 8, 8, 8,
9, 9, 9, 9, 9, 9, 9, 9,
11, 11, 11, 11, 11, 11, 11, 11,
12, 12, 12, 12, 12, 12, 12, 12,
13, 13, 13, 13, 13, 13, 13, 13,
14, 14, 14, 14, 14, 14, 14, 14,
15, 15, 15, 15, 15, 15, 15, 15,
2, 2, 2, 2, 2, 12, 6, 12,
1, 1, 10, 10, 10, 10, 10, 1,
16, 16, 16, 16, 16, 16, 16, 16
};
The activity in each of these programs is measured, normalized to
a unit length vector and returned in the progcolor vector.

264
doc/midi2abc.1 Normal file
View File

@@ -0,0 +1,264 @@
.TH MIDI2ABC 1 "1 January 2017"
.SH NAME
\fBmidi2abc\fP \- program to convert MIDI format files to abc notation
.SH SYNOPSIS
midi2abc \-f \fIinfile\fP [\-xa] [\-ga]
[\-a \fIacbeats\fP] [\-m \fItime signature\fP]
[\-ppu \fiparts per unit\fP] [\-aul \fidenominator of unit length\fP]
[\-gu] [\-b \fIbars\fP] [\-Q \fItempo\fP] [\-u \fipulses\fP]
[\-k \fIkey\fP] [\-c \fIchannel\fP] [\-obpl] [\-bpl \fibars\fP] [\-bps \fPbars\fP]
[\-o \fIfilename\fP] [\-s] [\-sr \fiunits\fP] [\-sum] [\-nb] [\-nt]
[\-splitvoices] [\-midigram] [\-mftext] [-mftextpulses] [\-nogr] [\-title \fistring\fP]
[\-origin \fistring\fP]
.SH DESCRIPTION
\fImidi2abc\fP takes a MIDI format file and converts it to something as close
as possible to abc text format. The user then has to add text fields not
present in the MIDI header and possibly tidy up the abc note output.
.PP
The output of midi2abc is printed to the screen. To save it to a file, use
the redirection operator, (e.g. \fImidi2abc \-f file.mid > file.abc\fP) or
specify the output file using the \-o option.
.PP
Use only one or none of the options \-u \-gu, \-b and \-Q. Midi2abc normally
converts the MIDI time units into quantum units normally corresponding to the
abc 1/16th note or 1/32nd note. If none of these is present, the
program will use the PPQN information in the MIDI header to compute the suitable
conversion factor. For most MIDI files on the web, it is recommended to rely on
the MIDI header information and not use any of the options other than
the formatting options.
.PP
The program will extract the time signature information from the MIDI file
if it is present. Otherwise it will assume 4/4 or you could specify it with
\-m. option.
.PP
If the tune has an anacrusis, you can use either the \-ga or \-xa option to estimate the its length. Alternatively, you can specify its value using the \-a
option. The anacrusis is specified in half unit lengths, where the unit
length is defined by the L: field. For example if L: 1/8, then a
quarter note would be indicated by the value 4, (4 1/16 units).
.SS OPTIONS
.TP
.B -a \fIacbeats\fP
where acbeats specifies the anacrusis in half unit lengths.
.TP
.B -xa
extract the anacrusis from file by finding the first strong note
.TP
.B -ga
guess the anacrusis by minimizing the number of ties across bars
.TP
.B -m \fItime signature\fP
time signature
.TP
.B -b \fIbars\fP
number of bars wanted in output
.TP
.B -Q \fItempo\fP
tempo in quarter\-notes per minute
.TP
.B -u \fipulses\fP
Allows you to specify directly the number of midi pulses per
abc time unit.
.TP
.B -ppu \fiparts per abc unit length\fP
Normally, the smallest note unit that midi2abc can extract
is half the L: unit length.This is called the quantum unit.
Thus for L: 1/8, midi2abc can extract 1/16 notes but not 1/32 notes.
You can change this by specifying \-ppu 4 for example. The number of parts
should be a power of 2.
.TP
.B -aul \fidenominator of abc unit length\fP
Normally midi2abc chooses a unit length of 1/8 or 1/16
depending upon the time signature. For time signatures
smaller than 3/4 the L: 1/16 is used and for larger time
signatures L: 1/8 is used. You can specify the unit length
to be used using this parameter. Thus \-aul 32 will cause
midi2abc to use a unit length of 1/32 nd note.
.TP
.B -gu
Tells midi2abc to estimate the number of midi pulses per abc
time unit from the note duration or spacing in the MIDI file.
.TP
.B -gk
Tells midi2abc to guess the key signature by minimizing
the number of accidentals even if the key signature is
already specified in the MIDI file. By default the key
signature is the one specified in the MIDI file.
If it is not specified, then the program guesses the
key signature by minimizing accidentals.
.TP
.B -k \fIkey\fP
key signature: \-6 to 6 sharps.
.TP
.B -c \fIchannel\fP
select only this midi channel.
.TP
.B -f \fIinfile\fP
input file in midi format
.TP
.B -o \fIoutput file\fP
specifies the output abc file name.
.TP
.B -s
do not discard very short notes.
.TP
.B -sr \fIquantum units\fP
do not notate a short rest smaller than the specified size after a note. If the
size (in quantum units) is zero, nothing is done. For larger values, the rest
is absorbed into the preceding note. In other words, the preceding note
is lengthened to include that rest.
.TP
.B -sum
print a short summary of the input midi file.
.TP
.B -nb
do not look for broken rhythms
.TP
.B -nt
do not look for triplets
.TP
.B -obpl
Print only one bar per line instead of 4. For complex music this
improves the readability and avoids some problems with some abc
to postscript converters. This option is deprecated.
.TP
.B -nogr
(No note grouping.) Inserts a space between all notes. It makes
a less pretty postscript file but it is easier to edit.
.TP
.B -bpl \finbars\fP
Print nbars of music on every line followed by a backslash.
.TP
.B -bps \finbars\fP
When nbars have been printed (including those lines joined by
a backslash continuation) go to a new line (with no backslash).
.TP
.B -splitvoices
This parameter handles polyphonic chords by
splitting an entire voice into multiple voices. (A polyphonic
chord is a chord composed of notes that do not start
or end at the same time.) Normally, midi2abc joins the
longer notes to the notes in the following chord using ties.
Here is an example: [Bd-]d [Bd-]d|. This should
be separated into two voices ideally Bz Bz and d2 d2. However,
the separation is not unique. Bz d2 and d2 Bz are also ok.
.TP
.B -midigram
When this option appears, all other options are ignored and
no abc file is produced. Instead a list of all notes in the
MIDI file are printed in a fixed format. Each line represents
a pair of MIDI note on/off event. The line contains the
on/off time of the note, its track number, channel number,
midi pitch and midi velocity. The last record indicates
the duration of the MIDI file in MIDI pulse units. The
output is designed to go into a graphical user interface
which will produce a graphical representation (piano roll).
.TP
.B -mftext
When this option appears, all other options are ignored and
no abc file is produced. Instead a list of all the MIDI
commands are printed. The output is designed to go into
a graphical user interface provided by runabc.tcl.
.TP
.B -mftextpulses
Same as -mftext except the time units is in midi pulses.
.TP
.B -title \fistring\fP
Replaces the default title field following T: with
the given string.
.TP
.B -origin \fistring\fP
Adds an O: field with the given string.
.TP
.B -stats
Extracts the characteristics of the given midi file. They include
ntrks - the number of tracks, ppqn - pulses per quarter note,
timesig - time signature, keysig - key signature, program - mapping
between channel number and midi program, npulses - length of the
midi file in pulses, tempocmd - number of times the tempo has
been specified, pitchbends - number of pitchbends, pitchbendin -
number of pitchbends in each of the channels, programcmd - number of
times the midi program has been revised, progs and progsact - the
programs used and the number of pulses these programs used, drums -
the drum numbers that were used, drumhits - the number of times
each of those drums were hit, pitches - the number of times the
11 pitch classes (C C# etc...) were activated and a few other
complex variables. These characteristics are used in other
applications such as midiexplorer. More details are available
in the file midi2abc-stats.txt included in the doc/ folder
of the abcmidi distribution package.
.SS FEATURES
* The key is chosen so as to minimize the number of accidentals.
Alternatively, the user can specify the key numerically (a positive number
is the number of sharps, a negative number is minus the number of flats).
.PP
* Note length can be set by specifying the total number of bars or the
tempo of the piece. Alternatively the note length can be read from the file.
However, by default it is deduced in a heuristic manner from the inter-note
distances. This means that you do not have to use the MIDI clock as a
metronome when playing in a tune from a keyboard.
.PP
* Barlines are automatically inserted. The user specifies the number of
measures in the anacrusis before the first barline and the time signature.
.PP
* The program can guess how the length of the anacrusis,
either by looking for the first strong note or minimizing the number of
notes split by a tie across a barline.
.PP
* Where a note extends beyond a bar break, it is split into two tied notes.
.PP
* The output has 4 bars per line.
.PP
* Enough accidental signs are put in the music to ensure that no pitch
errors occur if a barline is added or deleted.
.PP
* The program attempts to group notes sensibly in each bar.
.PP
* Triplets and broken rhythm (a>b) are supported.
.PP
* Chords are identified.
.PP
* Text information from the original MIDI file is included as comments.
.PP
* The \-c option can be used to select only 1 MIDI channel. Events on
other channels are ignored.
.SS LIMITATIONS
midi2abc does not ...
.PP
* Supply tune title, composer or any other field apart from X: , K:, Q:, M:
and L: - these must be added by hand afterwards, though they may have been
included in the text of the MIDI file.
.PP
* Support duplets, quadruplets, other esoteric features.
.PP
* Support mid-tune key or time signature changes.
.PP
* Deduce repeats. The output is just the notes in the input file.
.PP
* Recover an abc tune as supplied to abc2midi. However, if you want to
do this, "midi2abc \-xa \-f file.mid" comes close.
.SH "SEE ALSO"
abc2ps(1), abc2midi(1), abc2abc(1)
.SH AUTHOR
James Allwright <J.R.Allwright@westminster.ac.uk>
.SH SUPPORTED
Seymour Shlien <fy733@ncf.ca>
.SH VERSION
This man page describes midi2abc version 2.91 from March 09 2008.
.SH COPYRIGHT
Copyright 1999 James Allwright
.PP
midi2abc does not work correctly if lyrics are embedded in
the same track as the notes. If you are producing the MIDI
file using abc2midi, use the \-STFW option to ensure that the
lyrics are put in a separate track.
.PP
midi2abc 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.

157
doc/midicopy.1 Normal file
View File

@@ -0,0 +1,157 @@
.TH MIDICOPY 1
.SH NAME
midicopy \- Copy selected track, channel, time interval of a MIDI file to another MIDI file
.SH SYNOPSIS
\fBmidicopy\fP [\fB-ver\fP] [\fB-trks\fP \fIn1,n2,..\fP]\
[\fB-xtrks\fP \fIn1,n2,..\fP]\
[\fB-xchns\fP \fIn1,n2,..\fP]\
[\fB-chans\fP \fIn1,n2,...\fP]\
[\fB-from\fP \fIn (in midi ticks)\fP] [\fB-to\fP \fIn (in midi ticks)\fP]\
[\fB-fromsec %f\fP \fIn (in seconds)\fP] [\fB-tosec\fP \fIn (in seconds)\fP]\
[\fB-frombeat %f\fP \fIn (in beats)\fP] [\fB-tobeat\fP \fIn (in beats)\fP]\
[\fB-replace\fP \fItrk,loc,val\fP] [\fB-tempo %n\fP] [\fB-speed %f\fP]\
[\fB-drumfocus\fP \fIn \fIm\fP] [\fB-mutenodrum [%d]\fP]\
[\fB-setdrumloudness\fP \fIn \fIm\fP]\
[\fB-focusontrack\fP \fIn1,n2,... (from 1)\fP]\
[\fB-focusonchannel\fP \fIn1,n2,... (from 1)\fP]\
[\fB-attenuation\fP \fIn\fP]\
[\fB-nobends\fP]\
[\fB-indrums\fP \fIn1,n2,...\fP]\
[\fB-xdrums\fP \fIn1,n2,...\fP]\
[\fB-onlydrums\fP]\
[\fB-nodrums\fP]\
\fIinput.mid output.mid\fP
.SH "DESCRIPTION"
.PP
.B midicopy
is used to copy part of a MIDI file to another MIDI file. You can select
a particular time interval, particular channels, and particular tracks
or any combinations. If one or both of the run time parameters \-from or \-to
are included, the program returns the playing time in seconds of the
output file. Midicopy was developed by Seymour Shlien from the
midifilelib distribution available from
.IR http://www.harmony-central.com/MIDI/midifilelib.tar.gz .
.SH OPTIONS
.TP
.B -ver
prints version number and then exits
.TP
.B -trks n1,n2, etc
Selects the tracks to be copied where the track numbers start
from 1. If more than one track is specified, they should be separated by
commas. You should always copy track 1 since by convention it contains
information pertinent to all the other tracks. By default all tracks
are copied unless you specify particular tracks using this run time
parameter.
.TP
.B -xtrks n1,n2, etc
Lists the tracks to exclude from copying. All other tracks are copied.
This option does not work in combination with \-trks.
.TP
.B -xchns n1,n2, etc
Lists the channels to exclude from copying. All other channels are copied.
This option does not work in combination with \-chns.
.TP
.B -chns n
Like above, it specifies the MIDI channels to be copied. By default
all channels are copied. Channel numbers also start from 1.
.TP
.B -from n
The program will copy all MIDI commands starting from midi pulse
number n. By default it will start from time zero or the beginning
of the MIDI file.
.TP
.B -to n
Stops copying all events after midi pulse number n. By default
the file is copied to the end.
.TP
.B -frombeat n
The program will copy all MIDI commands starting from quarter beat
number n. By default it will start from time zero or the beginning
of the MIDI file.
.TP
.B -tobeat n
Stops copying all events after quarter beat number n. By default
the file is copied to the end.
.TP
.B -fromsec n
The program will copy all MIDI commands starting from time n
in seconds.
.TP
.B -tosec n
Stops copying all events after time n in seconds. These two
options (\-fromsec and \-tosec) do not work accurately if the
MIDI file has more than one tempo command. Only the first
one is used for converting seconds into MIDI pulse units.
It is therefore preferable to use the \-from and \-to options.
.TP
.B -replace trk,loc,val
This option should be used alone. Midicopy will copy the entire
file verbatim except it will replace a byte by val, where the
byte is located in the specified track (trk) and specified position
(loc). Commonly this function is used for changing a particular
MIDI program number (instrument) associated with a channel.
You need to know the byte count in the track of that parameter
in order to use this function,
.TP
.B -tempo quarter notes/minute
All tempo indications in the midi file will be replaced with
the above value.
.TP
.B -speed factor
All tempo indications in the midi file will be multiplied with
this factor. Values greater than 1.0 will speed up the music while
lower values slow the music. The factor is a floating point value.
.TP
.B -drumfocus drum-code excluded_drum_velocities
The selected drum line (specified by the drum-code pitch value) is
highlighted by reducing the loudness of all other drum lines to
the excluded_drum_velocities value. The drum-code value must
be in the range of 35 to 81 inclusive.
.TP
.B -mutenodrum [level]
All channels which are not 9 (drum channel) are attenuated to the
given level. If level is not specified, it is assumed to be zero.
.TP
.B -setdrumloudness n m
where n is between 35 to 81 inclusive and m is the loudness between
0 and 127. The loudness of all instances of drum n are changed
to m.
.TP
.B -focusontrack n1,n2,...
The velocities of notes in all tracks except n are attenuated.
.TP
.B -focusonchannel n1,n2,...
The velocities of notes in all channels except n are attenuated.
.TP
.B -attenuation n
Specifies the amount the note velocities are reduced by either
-focusontracks or -focusonchannels. Current default is 70.
.TP
.B -nobends
Suppresses all channel pitchbend commands.
.TP
.B -indrums n1,n2,...
Only allow percussions with codes n1,n2,...
.TP
.B -xdrums n1,n2,...
Exclude the percussions with codes n1,n2,...
.TP
.B -onlydrums
Only copy the percussion channel.
.TP
.B -nodrums
Copy all channels except the percussion channel.
.SH EXAMPLE
.B midicopy.exe -trks 1,5 -from 2669 -to 8634 uzicko.mid fragment.mid
Midicopy will copy tracks 1 and 5 starting from midi pulse position
2669 and ending at MIDI pulse position 8634.
.SH "SEE ALSO"
.PP
.IR abcmtex "(1), " abc2abc "(1), " abc2midi "(1), " midi2abc "(1) ", yaps "(1)"
.SH AUTHOR
This manual page was written by Seymour Shlien.
.SH VERSION
This man page describes midicopy version 1.33 from December 22 2019.

420
doc/programming/abc2midi.txt Normal file
View File

@@ -0,0 +1,420 @@
Some Notes on the abc2midi Code
-------------------------------
written by Seymour Shlien
Abc2midi.txt - last updated 29 November 1999.
This file provides an algorithmic description of the program
abc2midi which converts an abc file into a midi file.
The sources of abc2midi now comprising of 6700 lines of C code are
contained in the following five files.
parseabc.c is the front end which scans the abc file and invokes
the appropriate event handler for each element it encounters
(eg. bar lines, notes, chords etc.) It happens to be the
front end for other programs such as abc2ps, yaps and
abc2abc.
store.c contains all the event handlers which are invoked from
parseabc. It converts the abc file into an internal
representation described later in this file.
genmidi.c converts this internal representation in an output midi
file.
queues.c are some utilities needed by genmidi.
midifile.c is a library of public domain routines to read and write
midifiles.
In order to handle the multiple voices, parts, repeats and accompaniments
which occur in abc files, the program performs multiple passes. The
midi file stores the different voices, accompaniment and lyrics in
individual tracks, so it is necessary to separates these parts prior
to writing it to the midi file. If there are repeats in the music,
something which appears only once in the abc file may be invoked twice
when creating the output midi file.
Parseabc.c
----------
The parser has been written so that it should be possible to write
your own utility to handle the interpreted abc and link it with
the parser code. This is very similar to the way that the midifilelib
utilities work. The parser is designed so that it can write out
almost exactly what it reads in. This means that in some cases
the level of parsing is fairly primitive and it may be necessary to make
use of routines in store.c which perform further processing on an item.
In the first phase of parsing, the abc file is read and when, say, a note
is encountered, the routine event_note() is called. The code for event_note
is in the file store.c. Encountering an X in the abc generally causes a
routine called event_X() to be called. An internal representation of the tune
is built up and when the end of an abc tune is reached, a little bit of
processing is done on the internal representation before the routine
mywritetrack() is called to actually write out the MIDI file.
The main program to abc2midi is contained in this file. Since this
main program is used to start other programs such as yaps, it is
fairly simple. It calls event_init defined in store.c which obtains
all the user parameters (eg. input filename) and then executes the
top level procedure, parsefile.
The procedure parsefile (filename), opens the specified file (or stdin)
and processes it one character at a time. The characters fill a line
buffer which is passed to the procedure parseline whenever a linebreak
character (eg. linefeed) is encountered. By doing it in this fashion,
abc2midi is able to eliminate the extra carriage return which occurs
in DOS files.
The procedure parseline first checks for blank lines and comments. A
blank line signals the end of the tune and the event_blankline is called
to initiate the next stage in processing. If it is neither a comment or
blank line, the procedure must decide whether the line is a a field line
(eg."X:2") or part of a music body (eg. "|:C>DGz|..."). This is decided
using the following rule. If the first letter begins with one of the field
letter commands and is immediately followed by a ":", then it is treated
as a field line and parsefield is called. Otherwise if a K: field line
was already encountered (variable inbody set to 1), then it is treated
as a line of music. If neither case is satisfied, then the line is
intepreted as plain text.
The procedure parsefield identifies the particular field line type
and invokes the appropriate support function or event handler. If the
field command occurs after the first K: line, then only certain field
lines are legal. (For example it is illegal to place a T: (title) line
after the K: (key signature) line.)
The procedure parsemusic is the most complex procedure in the file and
recognizes the musical notes, chords, guitar chord names, bar lines,
repeats, slurs, ties, graces etc. Appropriate event handlers and
support functions are called to complete the tasks of parsing the
information. The parsenote function, for example, must check for
decorations, accidentals, octave shifts as well as identifying the
note and its determining its duration.
Unlike the other software modules, parseabc.c contains few global
variables. The global variables linenum, inhead, inbody, parsing,
slur, parserinchord indicate which lexical component of the abc
tune is being processed.
store.c
-------
This is the most complex module consisting of almost 3000 lines
of source code. This module contains all of the event handlers which
may be invoked in the file parseabc.c. The main purpose of these
handlers are to build up an internal representation of the abc file
in the global memory arrays. This is a complete representation
which allows the regeneration of the abc file (eg. abc2abc) or
the creation of a midi file. The internal representation is used
by the genmidi.c software to create the midi file.
Global variables
The internal representation is stored in global variables defined
at the beginning of the file. A description of the most important
variables is given here.
The music is stored in the four arrays, feature, pitch, num, denom.
These arrays contains a list of the lexical components in the order
that they have been encountered or created.
The array "feature" identifies the type of component which can be one
of the following enum features.
SINGLE_BAR, DOUBLE_BAR, BAR_REP, REP_BAR, REP1, REP2, BAR1,
REP_BAR2, DOUBLE_REP, THICK_THIN, THIN_THICK, PART, TEMPO,
TIME, KEY, REST, TUPLE, NOTE, NONOTE, OLDTIE, TEXT, SLUR_ON,
SLUR_OFF, TIE, TITLE, CHANNEL, TRANSPOSE, RTRANSPOSE, GRACEON,
GRACEOFF, SETGRACE, SETC, GCHORD, GCHORDON, GCHORDOFF, VOICE,
CHORDON, CHORDOFF, SLUR_TIE, TNOTE, LT, GT, DYNAMIC, LINENUM,
MUSICLINE, MUSICSTOP, WORDLINE, WORDSTOP
The array pitch[] mainly stores the pitch of a musical note,
represented in the same manner as in a midi file. Thus middle
C has a value of 60. The array has other uses, for example
in a LINENUM feature it stores the line number relative to
the X: reference command where the lexical feature has been
detected. The LINENUM feature is useful when reporting warnings
or errors in the input file. Duration of the notes are represented
as a fraction, where the standard unit is defined by the L:
command. If feature[n] is a NOTE, then num[n] and denom[n]
contain the numerator and denominator of this fraction.
Here is an example of the contents of these arrays for the
following small file in the same order that they are stored in
these arrays.
X: 1
T: sample
M: 2/4
L: 1/8
K: G
|: C>D[EF]G |C4:|
Feature Pitch Num Denom
LINENUM 2 0 0
TITLE 0 0 0
LINENUM 3 0 0
LINENUM 4 0 0
LINENUM 5 0 0
DOUBLE_BAR 0 0 0
LINENUM 6 0 0
MUSICLINE 0 0 0
BAR_REP 0 0 0
NOTE 60 2 3
NOTE 62 1 3
CHORDON 0 0 0
NOTE 64 1 2
NOTE 66 1 2
CHORDOFF 0 1 2
NOTE 67 1 2
SINGLE_BAR 0 0 0
NOTE 60 2 1
REP_BAR 0 0 0
MUSIC_STOP 0 0 0
LINENUM 7 0 0
In order to support multivoice abc files in the form
V:1
| ...| ...|....
V:2
| ...| ...|....
%
V:1
| ...| ...|....
V:2
| ...| ...|....
etc.
abc2midi maintains a voicecontext structure for each voice.
This allows each voice to define its own key signature, default
note length using internal field commands. There is a head
voicecontext which is used when no voice field commands are
defined in the abc file. The v[] array maintains a set of
all voices active in the abc file and voicecount keeps track
of the number of voices.
Similarly, abcmidi maintains a list of all the part stored
in the feature[], pitch[], num[] and denom[] arrays.
All text items (eg. title and some other fields) are stored
in char atext[][] arrays, so that they can be included in
the midi output file. The textual information is repeated
in each track of the output midi file.
Following the conventions in the midi file, the program uses
the quarter note as the standard unit of time instead of the
whole note. In contrast, the standard length in the abc file
is based on the whole note. For example in L:1/8, the fraction
refers to a whole note. In order to convert time units to
quarter notes, the numerator of the time specifications
for note lengths is multiplied by 4 when it is added to
the feature list.
Table of contents of procedures in store.c
getarg(option, argc, argv) - gets run time arguments.
newvoice(n) - creates a new voice context.
getvoicecontext() - finds or makes a voice context.
clearvoicecontexts() - frees up the memory of the voice context
event_init() - called by main program
event_text(s) - called when a line of text is encountered.
event_reserved(p) - handles reserved character codes H-Z.
event_tex(s) - called whenever a TeX command is encountered.
event_linebreak() - called whenever a newline character is encountered.
event_startmusicline() - called for each new music line.
event_endmusicline() - called at the end of each music line.
event_eof() - end of abc file encountered.
event_fatal_error(s) - reports fatal error.
event_error(s) - reports an error.
event_warning(s) - reports a potential problem.
event_comment(s) - called whenever a comment is encountered.
event_specific(package, s) - recognizes %%package s.
event_startinline() - beginning of an in-music field command.
event_closeinline() - finishes an in-music field command.
event_field(k,f) - for R:, T: and any other unprocessed field commands.
event_words(p) - processes a w: field command.
char_out(list,out,ch) - for building up a parts list in a P: command.
read_spec() - converts P:A(AB)3 to P:AABABAB etc.
event_part(s) - handles a P: field.
char_break() - reports error for improper voice change.
event_voice(n,s) - processes a V: field.
event_length(n) - recognizes L: field
event_blankline - starts finishfile() procedure.
event_refno(n) - recognizes X:
event_tempo(n, a, b, rel) - recognizes Q:
event_timesig(n, m) - recognizes M:
event_key(sharps, s, minor, modmap, modmul) - recognizes K:
event_graceon() - start of grace notes, "{" encountered.
event_graceoff() - end of grace notes, "}" encountered.
event_rep1() - handles first repeat indicated by [1.
event_rep2() - handles second repeat indicated by [2.
event_slur(t) -called when s encountered in abc.
event_sluron(t) called when "(" is encountered in abc.
event_sluroff(t) called when ")" is encountered in abc.
slurtotie() - converts slur into tied notes.
event_tie() - handles tie indication "-".
event_rest(n,m) - processes rest indication Z or z.
event_bar(type) - processes various types of bar lines.
event_space() - space character encountered. Ignored here.
event_linend(ch,n) - handles line continuation at end of line (eg. \).
event_broken(type, mult) - handles >, <, >> etc. in abc.
event_tuple(n,q,r) - handles triplets and general tuplets.
event_chord() - called whenever + is encountered.
marknotestart() - remembers last few notes in voice context.
marknoteend() - this is used to process broken rhythms (eg. >).
marknote() - called for single note (as opposed to chord).
event_chordon() - called whenever [ is encountered.
event_chordoff() - called whenever ] is encountered.
splitstring(s,sep,handler) - splits string with separator sep.
event_instuction(s) - handles !...! event.
getchordnumber(s) - searches known chords for chord s.
addchordname(s, len, notes) - adds chord name to known chord list.
event_gchord(s) - handles guitar chords.
event_handle_gchord(s) - handler for guitar chords.
event_handle_instruction(s) - handles dynamic indications (eg. !ppp!).
event_finger(p) - handles 1,2,...5 in guitar chord field (does nothing).
hornp(num,denom) - modifies rhythm to hornpipe.
event_note(roll, staccato, updown, accidental, mult, note, octave, n, m)
doroll(note,octave,n,m,pitch) - applies roll to note.
dotrill(note,octave,n,m,pitch) - applies trill to note.
pitchof(note,accidental,mult,octave) -finds MIDI pitch value
setmap(sf,map,mult) - converts key signature to accidental map.
altermap(v,modmap,modmul) - modifies accidental map.
copymap(v) - sets up working accidental map at beginning of bar.
addfeature(f,p,n,d) - places feature in internal tables.
autoextend(maxnotes) - increase memory limits for feature arrays.
textextend(maxstrings, stringarray) - resize array pointers to strings.
myputc(c) - workaround for problems with PCC compiler.
tiefix() - connect up tied notes.
dotie(j,xinchord) - called in preprocessing stage to handle ties.
addfrac(xnum,xdenom,a,b) - add a/b to the number of units in bar.
applybroken(place, type, n) - adjust length of broken notes.
brokenadjust() -adjust length of broken notes.
applygrace() - assign lengths to grace notes.
dograce() - assign lengths to grace notes.
lenmul(n, a, b) - multiply num(n),denom(n) by a/b.
zerobar() - start a new count of beats in the bar.
delendrep() - remove bogus repeat.
placeendrep(j) - patch up missing repeat.
placestartrep(j) - patch up missing repeat.
fixreps() - find and correct missing repeats in music.
startfile() - initialization performed after an event_refno.
tempounits(t_num, t_denom) - interprets Q: field.
setbeat() - sets default gchord command for time signature.
headerprocess() - called after the first K: field in tune.
finishfile() - starts next stage of processing when end of tune
is encountered.
All the functions in this file respond to event calls from parseabc.
Once the internal representation of the abc file is completed, the
procedure finishfile is called to perform some clean up and create
the midi file. An internal representation of the midi file is
first created and then it is written onto the designated output file.
As finishfile provides the link to the next module, genmidi.c, here
is a brief description of what it does.
proc finishfile performs several passes through the internal
representation to clean up the graces (dograce), the tied notes
(tiefix) and any unbalanced repeats. It then calls writetrack(i)
for each midi track to create the internal midi representation
and finally the midi representation is recorded in the output
file.
genmidi.c
---------
The procedure finishfile described above, creates each midi track
by calling the function writetrack which is defined here. To create
a track from the internal representation, the program must find all
the parts and put them in order with all the repeats. In addition, if
it contains karaoke text, this too must be placed in a separate track.
Any chordal accompaniment is generated from the guitar chord indications
and placed in another track. For multivoice and multipart music, a voice
may be missing in a particular part. If the voice is missing, the
procedure fillvoice ensures that all voices remain properly aligned when
the voice reappears in another part.
Here is a simple road map to the important procedures included in this
file.
dodeferred is here used to handle any dynamic indications (eg. !ppp!)
which may be contained in the file. The %%MIDI messages are stored
in a atext string which is pointed to by the contents of the pitch[]
array.
checkbar is called each time a bar line is encountered and reports
a warning if the wrong number of beats occur.
Transitions between parts are handled by the procedure partbreak.
There are a number of procedures for handling karoake text --
karaokestarttrack(), findwline(startline), getword(place,w),
write_syllable(place) and checksyllables().
For the first track, the meter, tempo and key signature are recorded
using the functions set_meter(n,m), write_meter(n,m), write_keysig(sf,mi).
Chordal accompaniment is produced by the procedure dogchords(i).
queues.c
--------
For each midi note, it is necessary to send a note-on and a note-off
instruction. When polyphonic music is played on the same track, keeping
track of the time to issue a note-off instruction may get complicated.
The procedures in this file are used to maintain a linked list for the
notes to be turned off. The notes are put into the list in the order
that they are encountered but the order in which to issue note-off
commands is maintained by the links. As many as 50 notes playing
simultaneously can be handled by the list.
Addendum
--------
The following section contains clarifications on various components
of abc2midi.
29 June 2003
Treatment of octave shifts.
The key signature field command K: has provision for shifting
a note using either transpose= or octave= subcommands. Both
of these functions operate quite differently and deserve some
description especially for multivoiced tunes.
The octave shift, is performed in event_note in store.c, using
the cached value v.octaveshift which is stored in the global
voicecontext structure, v. There is a structure for each voice
in the abc file. Whenever a new V: command is encountered,
event_voice (store.c) is invoked, which swaps the appropriate
voices structure into the global v array using the function
getvoicecontext(n). If getvoicecontext cannot find a cached
structure for that voice, then a new voice structure is created
and added to the linked list of voice structures. The v.octaveshift
variable is updated by event_octave which is called by event_key
(store.c) which is called by parsekey in parseabc.c
(Comment: it is not too clear how an octave switch is
handled in the middle of a repeat section. i.e. does the old
value get restored when repeating.)
(Description of transpose shift is in CHANGES July 1 2003.)

426
doc/programming/coding.txt Normal file
View File

@@ -0,0 +1,426 @@
Notes on the code
-----------------
These notes are for anyone who wants to re-compile, re-write or re-use
bits of the code. Additional information is available by downloading
the file abcextra.zip. This includes :
* man pages for abc2midi and midi2abc.
* A detailed description of the inner workings of abc2midi, written by
Seymour Shlien.
Compilation
-----------
The file midifile.c and the header file midifile.h are slightly changed from
the midifilelib distribution. To see the program dependencies, examine the
Makefile.
The code is written in K&R style C and should be fairly easy to compile
on any system with a C compiler and a make utility. Makefiles are
provided for gcc/unix, DJGPP/DOS and PCC/DOS. There are also some notes
on using the GUI front-end to Pacific C/DOS. You may get warning
messages if your compiler prefers ANSI C style function prototypes.
Choose the most suitable makefile; unix.mak, djgpp.mak or pcc.mak and
rename it as 'makefile'. If you are not using any of the above compilers,
you may have to edit the makefile so that it uses compilation flags
suitable for your compiler.
To compile the code, type
make all
If the complete compilation does not work, you can try compiling the
individual programs separately :
make midi2abc (or make midi2abc.exe)
make abc2midi (or make abc2midi.exe)
make abc2abc (or make abc2abc.exe)
make mftext (or make mftext.exe)
make yaps (or make yaps.exe)
Note that the make utility on some systems (e.g. GNU make) may require the
Makefile to be a unix text file and not a DOS text file. The difference
is that unix uses newline to mark the end of each line while DOS uses
carriage return and newline.
Note, if you have difficulty compiling the package because you do not have
snprintf see the note in doc/CHANGES dated January 08 2005 (and also
December 17 2004).
---------------------------------------------------------------------
Calling abc2midi or midi2abc from a GUI.
----------------------------------------
The programs should now have an exit value of 0 for normal termination
and 1 for an error state. However, abc2midi will still exit with 0 if
it finds non-fatal errors in the code, so the user should always have
the option of looking at the program's text output (I don't want to
get blamed when useful diagnostic output turns into the ubiquitous
'OK' click-button).
----------------------------------------------------------------------
Man pages
---------
Files: abc2midi.1 and midi2abc.1
Christoph Dalitz has written some man pages for abc2midi and
midi2abc. These should be installed in the sub-directory /man1
of the directory given by the MANPATH environment variable.
(The man command is usually only found on Unix variants).
The source distribution has been re-organized to contain only the
source and a few text files. If you want these man pages, you need
to download the file abcextra.zip.
---------------------------------------------------------------------
Code Layout and Indentation style
---------------------------------
If you want to add your own code and make it fit in with the existing
coding style, you can use GNU indent. The following is a DOS batch file
to invoke indent with the appropriate options.
indent -bad -bap -br -ce -cli0 -npcs -di1 -nbc -i2 -ts0 -psl -lp -ipo %1
rem
rem options for GNU indent to achieve my personal style
rem
rem -bad blank line after declaration block
rem -bap blank line after procedure body
rem -br brace on same line after if, struct and enum
rem -ce cuddle else
rem -cli0 case at same identation as switch
rem -npcs no space between procedure name and following open bracket
rem -di1 one space between variable type and variable name
rem -nbc comma-separated variables on the same line
rem -i2 indent 2 spaces
rem -ts0 no tabs
rem -npsl function type on same line as function name
rem -lp continuations matched to left parenthesis
rem -ip0 no indention of variables in K&R function headers
rem -ncs no space after cast
---------------------------------------------------------------------
Extensions to the abc Format
----------------------------
1. The parser recognizes
%%package <string>
as some package-specific command and calls event_specific with the
package name and the string that follows it.
2. The abc standard defines notation for 4 octaves :
C, - B,
C - B
c - b
c' - b'
The parser recognizes each additional comma as meaning "going down
an extra octave", giving
C,, - B,,
C,,, - B,,,
and so on.
Likewise, each additional prime symbols s interpreted as "go up an extra
octave" :
c'' - b''
c''' - b'''
and so on.
----------------------------------------------------------------------
abc2midi
--------
abc2midi consists of the following C source files:
parseabc.c - parses the input text and calls a routine for
every parsed element encountered.
parser2.c - performs some additional parsing that may not be
required.
store.c - builds an internal representation of the abc tune.
genmidi.c - uses the internal representation to generate
the MIDI file, using calls to MIDI-specific routines
in midifile.c
queues.c - library of routines for handling 'queues', a data
structure used internally by genmidi.c
midifile.c - Thompson and Czeisperger's public domain library of
MIDI file manipulation routines.
In the first phase of parsing, the abc file is read and when, say, a note
is encountered, the routine event_note() is called. The code for event_note
is in the file store.c. Encountering an X in the abc generally causes a
routine called event_X() to be called. abc2midi builds up an internal
representation of the tune. At the end of the abc tune, a little bit of
processing is done on the internal representation before the routine
writetrack() is called to actually write out the MIDI file. If there are
repeats in the music, something that appears only once in the abc may be
invoked twice by writetrack().
The internal representation uses the arrays feature[], pitch[], num[],
and denom[]. feature[] holds a description of an object while the other
arrays hold data relating to the object. The list of possible features
can be found in the file abc.h . The main features are NOTE, a note of
specified duration, REST, a pause of specified duration and TNOTE, a
note of specified duration with no interval between when it starts and
when the next item starts. This provides a simple way of representing
chords. Ties, broken rhythm signs and grace note brackets are all
deal with before writetrack() is called.
To add your own special features, you could define a new feature type.
However, an easier option is to use the %%MIDI format. If the parser
encounters "%%MIDI command", where command is not recognized by the
routine event_specific(), the string following %%MIDI is stored away
and passed to the routine dodeferred() by writetrack() when the MIDI
file is being written.
----------------------------------------------------------------------
abc2abc
-------
abc2abc shares the parser with abc2midi, but instead of storing the
abc code in an internal format, it is written almost straight out
again. The components of abc2abc are:
parseabc.c - parser
toabc.c - generates output abc.
midifile.c - public domain MIDI library.
----------------------------------------------------------------------
YAPS
----
YAPS is written mainly using ANSI C style function headers and
compiled and tested using DJGPP (DOS/Windows port of gcc).
The code is composed of the following files:
parseabc.c - reads through the abc text file. When it recognizes an abc
"unit" it calls a routine such as event_note() or event_key().
yapstree.c - creates a data structure to represent a tune.
Generally, I have tried to use as small a number of passes through the
data structure as possible. This means that things like applying a
broken rhythm symbol > is done as the notes are read in, rather than
using a second pass. This results in a lot of variables being needed in
'struct voice' to keep track of what is going on as we read in the
current symbols. Different sets of these variables are used on different
passes through the data.
drawtune.c - responsible for creating the PostScript file. When a whole
tune has been read in, this calculates the size of each individual
element, works out spacing within each line, decides how to place the beam
for a group of beamed notes, then finally generates the PostScript for
the tune.
position.c - called by drawtune.c. This set of routines is responsible
for spacing each line correctly. Where the input abc is multi-voice,
elements played at the same time but in different voices are aligned.
pslib.c - a single routine to print out the entire library of PostScript
functions used by yaps.
debug.c - routines to print to screen the contents of a tune data
structure.
abc.h - header file defining abc element types.
structs.h - header file defining the data structures used by the program.
The voice structure holds a lot of cuurent context information, used by
the program as it does a pass through the voice.
sizes.h - header file containing macros to define sizes in points for all
the graphic elements.
Dynamic Memory Management
-------------------------
abc2midi uses a system of re-sizable arrays in order to handle arbitrary
size input. This scheme was a natural way to adapt the original fixed size
arrays, and is not as flexible as it might be. Yaps instead uses linked
lists. There is a tune data structure containing a linked list of voices
and the notes and other elements are stored in a linked list in each tune.
Some music elements contain their own linked lists; for example a note
may have a linked list of lyric syllables. Adding a new data item to an
element (e.g. a note) involves the following :
1. find 'struct note' in structs.h and add the element.
2. Initialize it in newnote().
3. If it is a pointer to a new data structure, make sure the new data
structure is de-allocated in freevoice().
----------------------------------------------------------------------
The abc parser
--------------
The parser (parseabc.c) has been written in such a way that it forms
an independent unit which must be linked with routines to handle
parsed units. This is very similar to the way that the
midifilelib utilities work.
The abc is parsed line by line. Each line may be
* A comment
* A package-specific command
* A field (which may have a trailing comment)
* A blank line
* A TeX command
Having detected one of these, the parser calls an appropriate
routine. If it is none of these, then within the tune body it is
* A line of music (which may have a trailing comment).
Which is parsed and individual elements recognized. Outside the tune
body it is
* A line of arbitrary text.
and an appropriate routine is called.
Routines called by the parser
-----------------------------
These may be a bit out of date - look in the file parseabc.c for the actual
interfaces.
event_init(argc, argv, filename)
int argc;
char* argv[];
char** filename;
- first routine called by the parser. Expects filename to be the name of the
abc file to parse on return.
event_text(s)
char *s;
- called whenever a line of text is encountered.
event_tex(s)
char *s;
- called whenever a TeX command is encountered.
event_linebreak()
- called whenever a newline character is encountered.
event_blankline()
- called whenever a blank line is encountered.
event_eof()
- called when the end of file is reached.
event_error(s)
char *s;
- called whenever an error condition is detected. Errors are
generally not fatal within the parser.
event_warning(s)
char *s;
- called whenever a condition which is likely to be an error is
detected.
event_comment(s)
char *s;
- called whenever a comment is encountered.
The following are calls are invoked by fields in the abc :
event_specific(package, s)
char *package, *s;
- recognizes %%package s
event_length(n)
int n;
- recognizes L:
event_refno(n)
int n;
- recognizes X:
event_tempo(n, a, b, rel)
int n, a, b;
int relative;
- recognizes Q:
event_timesig(n, m)
int n, m;
- recognizes M:
event_key(sharps, s, minor)
int sharps;
char *s;
int minor;
- recognizes K:
event_part(s)
char* s;
- recognizes P:
When any other field is encountered in the abc :
event_field(k, f)
char k;
char *f;
If a line of music is encountered, the elements of that line each
trigger a call to one of the following events, provided that parsing
of music lines has been enabled :
event_graceon()
event_graceoff()
event_rep1()
event_rep2()
event_slur(t)
int t;
event_tie()
event_rest(n,m)
int n, m;
event_bar(type)
int type;
event_space()
event_lineend(ch, n)
char ch;
int n;
event_broken(type, mult)
int type, n;
event_tuple(p, q, r)
int p, q, r;
- general tuple: q and r are zero if not present
event_chord()
- called whenever + is encountered.
event_chordon()
- called whenever [ is encountered.
event_chordoff()
- called whenever ] is encountered.
event_gchord(s)
char* s;
event_reserved(p)
char p;
event_note(roll, staccato, updown, accidental, mult, note, octave, n, m)
int roll, staccato, mult;
char updown, accidental, note;
int octave, n, m;
In addition, there are 2 other routines :
int getline() - returns the line currently being parsed
parseron() - enable parsing of music lines.
parseroff() - disable parsing of music lines.

6
doc/programming/cvs/Entries Normal file
View File

@@ -0,0 +1,6 @@
/abc2midi.txt/1.1.1.1/Thu Sep 28 18:17:04 2006//
/coding.txt/1.1.1.1/Thu Sep 28 18:17:04 2006//
/midi2abc.txt/1.1.1.1/Thu Sep 28 18:17:04 2006//
/split.abc/1.1.1.1/Thu Sep 28 18:17:04 2006//
/yaps.txt/1.1.1.1/Thu Sep 28 18:17:04 2006//
D

1
doc/programming/cvs/Repository Normal file
View File

@@ -0,0 +1 @@
abcmidi/doc/programming

1
doc/programming/cvs/Root Normal file
View File

@@ -0,0 +1 @@
/home/seymour/CVSREPOS

227
doc/programming/midi2abc.txt Normal file
View File

@@ -0,0 +1,227 @@
Notes on the midi2abc code
--------------------------
written by Seymour Shlien
midi2abc.txt - last updated December 5 1999
Introduction
Midi2abc is a program for converting a midi files into an abc file.
A midi file merely consists of a list of commands to turn on
and off a set of voices at specific times. The time units are
expressed in pulses where the number of pulses per second can
be deduced from the information in the midi file. Pitch is
specified in semitone units ranging from 0 to 127 where middle C
is assigned a value of 60.
There are two types of midi in general use. In type 0, all the
voices are interleaved in time in one track. Each voice goes
to a specific channel which is mapped to a particular musical
instrument or program. There is a limit of 16 voices since only
4 bits are assigned to indicate the channel number. In type 2,
the voices are placed in separate tracks. This format allows
handling more than 16 voices.
In order to create an abc file, midi2abc must determine the
length of a musical unit (for example an eighth note) in terms
of midi pulses, determine the key signature, and, finally map the
midi commands into musical notes.
Though the midi file specifies the number of pulses per quarter note
(PPQN) in the Mthd header chunk, this is not necessarily an
accurate indication. It is primarily used together with the tempo
indication to determine the number of pulses per second. Unless
the midi file was created by a computer program, the actual length
of a quarter note in midi pulses can depart from the nominal indication.
Midi2abc tries to determine the length using its own heuristic
algorithm.
The sources of the program are contained in two files: midi2abc.c and
midifile.c. This document does not try to describe completely how
this program works, but is more of a general road map to the software.
Algorithmic Description
The conversion is done in multiple passes. In the first pass, the
midi file is read and an internal representation of the file is
created and stored in global dynamic memory. In each subsequent pass,
other information is added to the internal representation and finally
it is written to the output abc file.
After parsing the input run parameters and performing various
initializations, the main program calls the procedure mfread
which is found in the midifile.c module. Mfread parses the different
midi components of the file and calls the appropriate functions
midi2abc to process these components. These functions begin with
the txt_ prefix, some of which are listed here.
txt_header midi header chunk
txt_trackstart start of midi track
txt_trackend end of midi track
txt_noteon note on channel command
txt_noteoff note off channel command
txt_program midi program definition or change
txt_metatext midi textual information
txt_keysig midi key signature indication
txt_tempo midi tempo indication
Many other functions such as txt_pressure and txt_parameter
corresponding to other midi commands, do nothing here.
These functions build up an internal representation of the midi file
in a global structure referenced through the track[64] structure.
Up to 64 midi tracks can be stored in the internal representation.
Each track structure (atrack structure) contains single and double
linked lists of notes or text strings which are described below.
In addition there are other linked lists (referenced by playinghead
and chordhead), used for keeping track of notes currently playing
and musical chords.
Each note is represented by an anote structure which stores various
parameters of the note. The anote structure is allocated dynamically
as the midi file is read. The first four entries of the structure
are filled in while the structures are being created by mfread.
These are entries are listed below.
anote.pitch pitch in midi units
anote.chan midi channel number
anote.vel midi velocity (corresponding to loudness)
anote.time time in midi pulses.
The other entries in the anote structure are determined in later passes.
The anote structures are linked together into a a listx structure which
is included in the atrack structure. The head and tail of the list are
contained in this structure to facilitate the construction of this list.
In addition there is tlistx structure for storing all the textual
information (for example words in a Karaoke midi file) which may be found
in the track.
There is a doubly linked list structure of anotes (dlistx,
*playinghead) which is used as a work space for matching the note off
command with the corresponding note on command. This is needed in order
to determine the length of time the note was turned on (called anote.tplay).
The internal representation is mainly constructed by the important
functions txt_noteon and txt_noteoff called by mfread. These functions
in turn call the functions addnote and notestop. The midi file contains
separate commands for turning a note on or off so that in order to
determine the length of time that a note has been on, it is necessary to
match a note-off command with the corresponding note-on command.
Every time a note is turned on, it is also added to the playhead (tail)
structure. The procedure notestop finds the corresponding note-on
command in the playhead structure, removes it, and records the
duration of the note which was turned on.
At the end of the first pass, the number of tracks is counted and each
track is processed by the function postprocess which computes the entry
anote.dtnext for each anote structure. This entry contains the time
interval between the current and the next note in the linked list of
notes.
The abc time unit length is either 1/8 or 1/16 depending on the time
signature. A time signature of 4/4 is assumed unless it is specified
by the run time parameters (-m or -xm). (If -xm is specified, then the
program uses the time signature given by the midi meta command if it
exists in the file.)
The next step involves the quantization of the midi time units
expressed in pulse counts into abc time units. It is first necessary
to estimate the length of an abc time unit in terms of midi time
units. This either is estimated using a heuristic algorithm,
guesslength, or is determined from the run time parameters (-Q or -b).
The function guesslength makes an initial guess by dividing the
total number of pulse counts in the track by the total number
of notes. It then tries 100 different lengths in the neighbourhood
of this initial guess and chooses the one which leads to the smallest
quantization error. The quantization error is determined by the function
quantizer which keeps track of the total deviation of the time
a note starts (in pulse counts) from the expected time the note
starts assuming the standard musical intervals. This deviation
can either drift positively or negatively with time. The total
error is determined by summing the absolute values of these
deviations for each bar.
Once the unit length has been determined, all the notes in all
tracks are quantized by the function quantizer. This function
assigns values to the anote entries, anote.xnum, anote.playnum
and anote.denom.
anote.xnum interval between the current note and following note
also called the gap.
anote.playnum note duration.
anote.denom always has the value of 2.
A musical part does not necessarily begin at the start of a bar line,
but may have some leading notes. This is called anacrusis.
There are two methods to estimate the anacrusis. The function findana
searches for the first upbeat by examining the velocities (loudness) of
the notes. The function guessana, chooses the anacrusis which minimizes
the number of tied notes across a bar line which is determined by the
function testtrack.
At this point the key signature of the tune must be determined.
The procedure findkey computes the frequency distribution of all the
notes in the piece and stores it in the local array n[]. The key
signature is determined by transposing the distribution by each
of the 12 keys and counting the number of sharp or flat notes. The
key signature is determined from the key which leads to the minimum
number of black keys on the piano. The mode of the scale (major,
minor, Dorian, etc.) is determined by looking at the final note of
the piece.
Once the key signature is determined, the assumed flats or sharps
are determined by the procedure setupkey. The program is now ready
for its final pass where the musical parts (or voices) are printed
in the output abc file.
The procedure printtrack processes the internal representation
of each midi track producing a separate voice for each track.
In order to handle chords which may be present in an individual
track, printtrack maintains a structure referenced by chordhead
by calling the support functions addchord(), advancechord(),
removechord() and printchord(). These functions handle single
notes as well as chords. Another function, dospecial(), handles
the triplets and broken rhythms (eg. dotted notes followed by
half sized note or vice versa) whenever they are detected. The
printchord() function is supported by the functions printfraction()
and printpitch().
After the track is printed, the memory allocated to the structures
for the internal representation of the tracks is freed.
The option -splitvoice was introduced to handle polyphonic chords.
Without this option polyphonic chords appear in the abc file
like this.
[DF-A-][FA-]Az|
this will be represented by three voices
V: split1A
D2 z6|
V: split1B
F4 z4|
V: split1C
A6 z2|
This option is implemented by the function printtrack_split_voice().
The function label_split_voices() is called to assign all the notes
in the track to their split voice. This assignment of each note is
stored in note->splitnum. This is a complex function since it needs
to try to match the onset and end of each note in the chord. If
it is unable to do this for a particular note, then the note is
assigned to a different split. At the end, nsplits were created.
The notes in each split are printed in a separate voice by the
function printtrack_split(). The function printtrack_split(splitnumber)
was derived from printtrack(); however, it only processes the
notes belonging to a particular splitnumber.
It was necessary to determine and store the offset of the first
note in each split using the function set_first_gaps() prior
to calling printtrack_split().

131
doc/programming/split.abc Normal file
View File

@@ -0,0 +1,131 @@
X:1
T: test split file 1
M: 2/4
L: 1/4
K: G
G & E & C|D|GA & EF|
X:2
T: test split file 2
M: 1/4
L: 1/4
K: G
%%MIDI program 20
D|G & E|C|F|G & E|
X:3
T: test split file 3
M: 2/4
L: 1/8
Q: 50
K: D
CD |EF AB & CD FG| G2 | BD D2 & GB B2|
X:4
T: test split file 4
M: 1/4
L: 1/4
K: G
V:1
|:G |[1 D & B:|
V:2
|:g |[1 d & b:|
V:1
[2 F & A|
V:2
[2 f & a|
X:5
T: test split file 5
M: 1/4
L: 1/4
K: G
G & E |D|
X:6
T: test split file 6
M: 1/4
L: 1/4
K: G
D|G & E|
X:7
T: test split file 7
M: 1/4
L: 1/4
K: G
D|G & E & C|F|
X:8
T: test split file 8
M: 1/4
L: 1/4
K: G
G & E & C|D|
X:9
T: test split file 9
M: 1/4
L: 1/4
K: G
G & E & C|D|F & A|
X:10
T: test split file 10
M: 1/4
L: 1/4
K: G
V:1
|:G |[1 D & B
V:2
|:g |[1 d & b
V:1
:|[2 F & A|
V:2
:|[2 f & a|
X:11
T: test split file 11
M: 1/4
L: 1/4
K: G
|:G & E :|D|F & A|
X:12
T: test split file 12
M: 1/4
L: 1/4
K: G
|:G & E |D:|F & A|
X:13
T: test split file 13
M: 1/4
L: 1/4
K: G
|:G & E |[1 D:|[2 F & A|
X:14
T: test split file 14
M: 1/4
L: 1/4
K: G
|:G |[1 D & B:|[2 F & A|
X:15
T: splits with octave=1
M: 4/4
L: 1/4
K: G octave=1
G A B C & E F G A|
X:16
T: test split file 13
M: 1/4
L: 1/4
K: G
|:G & E |1 D:|2 F & A|

134
doc/programming/yaps.txt Normal file
View File

@@ -0,0 +1,134 @@
Some Notes on the yaps Code
-------------------------------------------------------------
written by Seymour Shlien November 21 2004
This file gives an algorithmic description of the
yaps program which converts an abc file to a PostScript file.
The source consists of almost 10000 lines of C in the following
files.
parseabc.c is the front end which scans the abc file and invokes
the appropriate event handler for each element it encounters
(eg. bar lines, notes, chords etc.) It happens to be the
front end for other programs such as abc2midi, and
abc2abc. More details are given in abc2midi.txt.
yapstree.c contains all the event handlers called by the parser.
It produces a complex data structure called tune which
references many other structures. When the parser completes
processing the tune, event_blankline or event_eof calls
printtune (in drawtree.c) which processes the tune structure
producing a PostScript file. Unlike abc2midi, most of the
layout including the detailed beaming is done in the first
pass during the parsing stage. The information in this
structure is then processed by drawtune.c in two more
passes. An overview of these structures is provided here.
More details on the tune structure is provided in this
file.
drawtune.c contains the function printtune which turns the tune
structure into an actual PostScript file. This is done
in two passes. Before writing the PostScript file it
is necessary to determine the boundingbox of the output
image since this information is recorded in the header
of the output file. This is determined in the first pass
where functions monospace() or spacevoices() (in position.c)
are called. During this pass the pixel positions
of each object are recorded in the associated structures.
In the second pass, the actual PostScript file is written.
The function calls printlib() (in pslib.c) outputs
all the PostScript boiler plate macro definitions required
by yaps. The information in the tune structure is used
to output the music notation in a PostScript file.
position.c contains functions for determining the amount of space
that is required for the different music objects drawn
in the PostScript file.
parser2.c contains additional parsing functions missing in parseabc.
They handle more recent features added to the abcmidi package.
pslib.c Definition of new PostScript commands (eg. notes, clefs,
stems, tails, ...) which are copied to the PostScript
file.
debug.c Functions which support the -d option in yaps. It prints
some of the contents of the internal tune structure.
Data Structures
---------------
The data structures are defined in the include file structs.h.
The top level structure, tune is instantiated by init_tune which
is called by event_init or event_refno. It stores all the
information in the abc field commands (X: ,M:, L:, C:, O: and etc.).
It contains a pointer to the voice structure and a list of voice
pointers where most of the body information is recorded.
The voice structure is instantiated by the function newvoice
which is called by setvoice(n) whenever the voice context
switches in the abc file. Setvoice performs the voice switching
(which occurs in voice interleaved files) and either creates
a new voice or finds the matching voice structure already existing.
The voice structure contains the feature structure which
is somewhat similar in function to the one defined in store.c
(for abc2midi).
The feature structure encodes all the detailed information in
the body, using the same typedef enum featuretype defined
in abc.h. Unlike store.c there is no num and denom arrays. Instead
the feature struct contains a void* pointer called item which
can point to anything and where additional information can be
stored. If the feature type is a NOTE then a "note" struct
is created which records a lot of detailed information related
to the placement and visual representation of the note. They
include:
tail_type which specifies whether the note appears in
isolation or is part of a beamed group
base_exp whole, half, quarter, ... notes
dots how many dots follow
stemlength, stemup, fliphead, pitch, octave, accidentals, accents,...
(see struct.h)
Most of the information except actual positioning is determined
by functions such as count_dots and beamitem in yapstree.c.
You can view this information by running yaps.exe with the -d
run time parameter.
The handling of the note positioning is quite complex as
outlined below. It is therefore not easy to implement the
splitvoice feature into yaps. Here is a description.
The positioning of notes is done by the function
spacemultiline() which calls advance() unless one is printing
the voices separately. The positioning is done on all the voices
at the same time to ensure that they are lined up properly.
Spacemultiline accesses all the active voices using the functions
firstitem() and nextitem() which are used for handling any lists
of objects. Each voice maintains its own pointer to the current
feature being scanned (v->place). Each voice also maintains its
own pointer to the relative time of the note being scanned
in the variable v->time. (v->time contains both a numerator
and denominator.) The advance() function updates v->place,
v->time and interprets the voice features determining the
amount of space that is needed to plot the next object (itemspace)
and the number of plotable objects (items). The position to
plot the next object (x) is maintained by spacemultiline and
passed to advance. Advance() updates v->place->x with the position
to plot the object based on its width. Spacemultiline()
maintains a mastertime variable for maintaining synchrony
between all voices.
At least two passes are made through the voice features.
In the first pass provisional positions are computed for the
notes. The amount of space left over in the music lines is
computed and is used to determine the internote gaps.
In the second pass, the notes are repositioned to use up
the entire space in the staff line.
Spacemultiline is called for each staff line whose end is
signaled by a linefeed feature in the voice.

546
doc/readme.txt Normal file
View File

@@ -0,0 +1,546 @@
abcMIDI : abc <-> MIDI conversion utilities
midi2abc version 3.46 June 22 2020
abc2midi version 4.38 July 05 2020
abc2abc version 2.08 June 04 2020
yaps version 1.77 June 04 2020
abcmatch version 1.73 June 04 2020
midicopy version 1.36 June 04 2019
24th January 2002
Copyright James Allwright
J.R.Allwright@westminster.ac.uk
University of Westminster,
London, UK
February 2020
Seymour Shlien
Ottawa, Canada
fy733@ncf.ca
This is free software. You may copy and re-distribute it under the terms of
the GNU General Public License version 2 or later, which is available from
the Free Software Foundation (and elsewhere).
This package is to be found on the web at
http://abc.sourceforge.net/abcMIDI/
(The latest versions for the time being is found on
ifdo.ca/~seymour/runabc/top.html.)
Note, if you have difficulty compiling the package because you do not have
snprintf see the note in doc/CHANGES dated January 08 2005 (and also
December 17 2004).
These programs make use of the 'midifilelib' public domain MIDI file utilities,
which was originally available from
http://www.harmony-central.com/MIDI/midifilelib.tar.gz
If you have the source distribution and intend to re-compile the code,
read the file coding.txt.
---------------------------------------------------------------------
midi2abc - program to convert MIDI format files to abc notation.
This program takes a MIDI format file and converts it to something as close
as possible to abc text format. The user then has to add text fields not
present in the MIDI header and possibly tidy up the abc note output.
Features :
* The key is chosen so as to minimize the number of accidentals.
Alternatively, the user can specify the key numerically (a positive number
is the number of sharps, a negative number is minus the number of flats).
* Note length can be set by specifying the total number of bars or the
tempo of the piece. Alternatively the note length can be read from the file.
However, by default it is deduced in a heuristic manner from the inter-note
distances. This means that you do not have to use the MIDI clock as a
metronome when playing in a tune from a keyboard.
* Barlines are automatically inserted. The user specifies the number of
measures in the anacrusis before the first barline and the time signature.
* The program can guess how many beats there should be in the anacrusis,
either by looking for the first strong note or minimizing the number of
notes split by a tie across a barline.
* Where a note extends beyond a bar break, it is split into two tied notes.
* The output has 4 bars per line.
* Enough accidental signs are put in the music to ensure that no pitch
errors occur if a barline is added or deleted.
* The program attempts to group notes sensibly in each bar.
* Triplets and broken rhythm (a>b) are supported.
* Chords are identified.
* Text information from the original MIDI file is included as comments.
* The -c option can be used to select only 1 MIDI channel. Events on
other channels are ignored.
What midi2abc does not do :
* Supply tune title, composer or any other field apart from X: , K:, Q:, M:
and L: - these must be added by hand afterwards, though they may have been
included in the text of the MIDI file.
* Support duplets, quadruplets, other esoteric features.
* Support mid-tune key or meter changes.
* Deduce repeats. The output is just the notes in the input file.
* Recover an abc tune as supplied to abc2midi. However, if you want to
do this, "midi2abc -xa -f file.mid" comes close.
midi2abc
usage :
midi2abc <options>
-a <half L: units>
-xa extract anacrusis from file (find first strong note)
-ga guess anacrusis (minimize ties across bars)
-gk guess key signature by minimizing accidentals
-gu guess the number of midi pulses per note from note
duration statistics in the MIDI file
-m <time signature>
-b <bars wanted in output>
-Q <tempo in quarter-notes per minute>
-k <key signature> -6 to 6 sharps
-c <channel>
[-f] <input file>
-o <output file>
-s do not discard very short notes
-sr do not notate a short rest after a note
-sum summary
-nt do not look for triplets or broken rhythm
-u number of midi pulses per abc time unit
-ppu parts per abc unit length (power of 2 only)
-aul denominator of abc unit length (power of 2 only)
-obpl one bar per line (deprecated)
-bpl <number> of bars per printed line
-bps <number> of bars per staff line
-nogr No note grouping. Space put between every note.
-splitbars splits bars to avoid nonhomophonic chords.
-splitvoices splits voices to avoid nonhomophonic chords.
-midigram No abc file is created, but a list
of all notes is produced. Other parameters
are ignored.
-mftext No abc file is created, but a list of all
the midi commands (mftext like output) is
produced. The output is best viewed with
runabc.tcl
-stats prints summary and statistics of the midi file
which would be best viewed using an new application
midiexplorer.tcl.
-ver Prints version number and exits
Use only one of -u -gu -b and -Q or better none.
If none of these is present, the program uses the PPQN header
information in the MIDI file to determine the note length in
MIDI pulses. This usually results in the best output.
The output of midi2abc is printed to the screen. To save it to a file, use
the redirection operator or the -o option.
e.g.
midi2abc -f file.mid > file.abc
or
midi2abc -f file.mid -o file.abc
By default the program uses the key signature and time signature
specified in the MIDI file. If the key signature is not specified,
the program will automatically determine the key signature by
minimizing the number of accidentals. If there is no time signature
found, then 4/4 is assumed. You may also specify a time signature
using the -m option. Allowable time signatures are C,
4/4, 3/8, 2/4 and so on.
If the tune has an anacrusis, you should specify the number in quantum
units lengths. By default a quantum unit length is one half of
the unit length note specified by the L: command. (However, this
can be changed using the -ppu runtime parameter.) For example,
if the meter is 6/8 and L: is set to 1/8, a half unit length is
1/16 note. An anacrusis of a quarter note would be specified as 4.
The -bpl and -bps control the formatting of the output. -bpl controls
the number of bars put in every line. The lines are joined together
with a backslash (\) until the desired number of bars per staff are
printed. Since -bpl 1 is equivalent to -obpl, the latter parameter
is being deprecated.
Midi2abc has evolved quite a lot since James Allwright has
transferred support and development to me [SS]. Most of the
MIDI files posted on the web site appear to have been generated
from a music notation program and therefore convert cleanly
to abc files using all the information built into the file.
Therefore midi2abc no longer automatically estimates the number
of MIDI pulses per note from the file statistics, but uses
the indications embedded in the file. However, the user still
has the option of calling these functions or changing this
parameter by using the run time parameters Use only one of -u -gu
-b and -Q or better none. The -u parameter, allows you
to specify the number of MIDI pulses per unit length, assuming
you know what it should be. To find out the value that
midi2abc is using, run the program with the -sum parameter.
Midi2abc quantizes the note durations to a length of half
the L: value. Thus if L: was set to 1/8, then the smallest
note that midi2abc would extract would be a 1/16 th note.
This is the basic quantum unit. The L: note length is set
by midi2abc on the basis of the time signature. For time
signatures less than 3/4 it uses an L: 1/16 and for others
it uses a length of 1/8. This convention was probably chosen
so that midi2abc does not quantize the notes to a too fine
level producing outputs like C2-C/4 D2-D/8 etc which would
be difficult to read. For some music, this may be too coarse
and it may be preferable to allow the user take control of
the L: value or allow the splitting of the L: value into
smaller parts. Two new run time parameters were introduced:
-ppu specifies the number of parts to split the L: note.
It should be a power of 2 (eg. 1,2,4,8,16 ...) and by default
it remains as 2 as before. The -aul specifies the L: value to use,
for example, to get L: 1/32 you would put -aul 32.
Keyboard and guitar music has a lot of chords which frequently
poses a problem to midi2abc. If the notes in the chord do
not share a common onset or end time, midi2abc uses ties to join
the longer notes to other chords. This produces a mess looking
somewhat like
[AG-G-G-D-G,,,-][B/2-B/2-B/2-G/2G/2-G/2-D/2-G,,,/2-]...
which does not convert into something easy to read when
display in common music notation. Abcm2ps and abc2midi allow
a bar to be split into separate voices using the & sign.
Separating the notes which do not overlap exactly into
individual voices provides some improvement. If you encountering
this problem with your MIDI file, you may wish to try rerunning
the file with either the -splitbars or -splitvoices parameter.
This is a feature introduced in June 2005 (version 2.83).
The algorithm which separates the notes in a voice into
distinct voices (tracks) (label_split in midi2abc.c) is rather
crude and needs improvement. I welcome any suggestions
or improved code.
The -midigram option runs midi2abc in a completely different
mode. It does not produce any abc file but outputs a list
of all the notes found in the MIDI file. Each line of output
represents one note. For each line, the on and off time
in MIDI time units, the track number, the channel number,
midi pitch, and midi velocity are listed. The last line
contains a single value equal to the duration of the file
in MIDI pulses. The output is designed to eventually go into a
graphical user interface (runabc) which will display these events
in piano roll format.
Note: midi2abc does not work correctly if the lyrics are embedded
in the same track as the notes. If you intend to run midi2abc on
the MIDI file produced by abc2midi, you need to use the -STFW
option if the tune contains lyrics.
eg. abc2midi lyric_tune.abc -STFW
Since February 01 2010, abc2midi by default places the lyrics in
the same track as the notes. See doc/CHANGES.
-------------------------------------------------------------------------
abc2midi - converts abc file to MIDI file(s).
Usage : abc2midi <abc file> [reference number] [-c] [-v] [-o filename]
[-t] [-n <value>] [-ver] [-NFNP] [-NFER] [-NGRA] [-STFW] [-NCOM] [-OCC]
[reference number] selects a tune
-c selects checking only
-v <level> selects verbose option
-o <filename> selects output filename
-t selects filenames derived from tune titles
-n <limit> set limit for length of filename stem
-CS use 2:1 instead of 3:1 for broken rhythms
-quiet suppress some common warnings
-silent suppresses other messages
-Q <tempo> in quarter notes/minute
-NFNP ignore all dynamic indications (!f! !ff! !p! etc.)
-NFER ignore fermata markings
-NGRA ignore grace notes
-STFW separate tracks for words (lyrics)
-NCOM suppress comments
-ver prints version number and exits
-BF Barfly mode: invokes a stress model if possible
-OCC old chord convention (eg. +CE+)
-TT tune to A = <frequency>
-CSM <filename> load custom stress models from file
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. The -Q parameter sets
the default tempo in event the Q: command is not given in the
abc header. The program accepts both the deprecated (eg.
!trill!) and standard (+trill+) notation for decorations.
Older versions of this program handled the defunct convention
for chords (i.e +G2B2D2+ instead of [GBD]2). If you need to
handle the older notation, include the -OCC flag; however the
program will not accept the standard notation for decorations.
Broken rhythms indicated by > or < (eg. A > B) assume a
the hornpipe ratio of 3:1. To change it to the Celtic ratio
3:1 include the -CS flag.
Features :
* Broken rythms (>, <), chords, n-tuples, slurring, ties, staccatto notes,
repeats, in-tune tempo/length/meter changes are all supported.
* R:hornpipe or r:hornpipe is recognized and note timings are adjusted to
give a broken rhythm (ab is converted to a>b).
* Most errors in the abc input will generate a suitable error message in
the output and the converter keeps going.
* Comments and text fields in the abc source are converted to text events
in the MIDI output
* If guitar chords are present, they are used to generate an accompaniment
in the MIDI output.
* 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.
* Karaoke MIDI files can be generated by using the w: field to include
lyrics.
* Nonnumeric voice ids, eg V: soprano, as described as proposed
for the new abc standard is handled.
* Invisible rests specified as x, are treated as normal rests (z).
* There are some extensions to the abc syntax of the form
%%MIDI channel n
These control channel and program selection, transposing and various
other features of abc2midi. See the file abcguide.txt for more
details.
Bugs and Limitations :
* No field is inherited from above the X: field of the tune.
* Where an accidental is applied to a tied note that extends across
a barline, abc2midi requires that the note beyond the barline must
be explicitly given an accidental e.g.
^F- | F - will be reported as an error.
^F- | ^F - will produce a tied ^F note.
It is common to see no accidental shown when this occurs in published
printed music.
-------------------------------------------------------------------------
abc2abc
Usage: abc2abc <filename> [-s] [-n X] [-b] [-r] [-e] [-t X]
[-u] [-d] [-v] [-V X] [-ver] [-X n]
-s for new spacing
-n X to re-format the abc with a new linebreak every X bars
-b to remove bar checking
-r to remove repeat checking
-e to remove all error reports
-t X to transpose X semitones
-nda No double accidentals in guitar chords
-nokeys No key signature (i.e. K: none). Use sharps.
-nokeyf No key signature (i.e. K: none). Use flats.
-u to update notation ([] for chords and () for slurs)
-usekey n Use key signature sf (sharps/flats)
-useclef (treble or bass)
-d to notate with doubled note lengths
-v to notate with halved note lengths
-V X[,Y...] to output only voice X,Y...
-P X[,Y...] restricts action to voice X,Y... leaving other voices intact
-ver prints version number and exits
-X n renumber the all X: fields as n, n+1, ..
-xref n output only the tune with X reference number n.
-usekey sf Use key signature sf (flats/sharps)
-OCC old chord convention (eg. +CE+)
A simple abc checker/re-formatter/transposer. If the -n option is selected,
error checking is turned off.
If a voice is assigned to channel 10 (drum channel) using a
%%MIDI channel 10
command, then this voice is never transposed.
The -nokeys or -nokeyf option will set "K: none" and place accidentals on
all notes that should have accidentals for the expected key signature.
The first option will use only sharps; the second option will use
only flats.
The -usekey option will force the key signature to be key[sf] where
sf is a number between -5 and +5 inclusive.
sf -5 -4 -3 -2 -1 0 1 2 3 4 5
key Db Ab Eb Bb F C G D A E B
Accidentals will be added to preserve the correct notes. This
is useful for some music with many accidentals which does
not fit in any specific key signature. If sf = 0, abc2abc
use K:none.
If you want to check an abc tune, it is recommended that you use abc2midi
with the -c option as this performs extra checks that abc2abc does not do.
When using the -P X option, it may be necessary to insert some
field commands such as K: or L: following the voice X declaration,
so that they will be converted and appear in the output.
The output of abc2abc is printed to the screen. To save it to a file, use
the redirection operator.
e.g.
abc2abc file.abc -t 2 > newfile.abc
Known problems:
* When using the -n option on a program with lyrics, a barline in a w:
field may be carried forward to the next w: field.
-------------------------------------------------------------------------
mftext - MIDI file to text
This gives a verbose description of what is in a MIDI file. You may wish
to use it to check the output from abc2midi. It is part of the original
midifilelib distribution.
-------------------------------------------------------------------------
YAPS
----
YAPS is an abc to PostScript converter which can be used as an alternative
to abc2ps. See the file yaps.txt for a more detailed description of this
program.
-------------------------------------------------------------------------
midicopy is a stand alone application which copies a midi file or part
of a midi file to a new midi file. If you run it with no parameters, a
short description shown below will appear.
usage:
midicopy <options> input.mid output.mid
midicopy copies selected tracks, channels, time interval of the input midi file.options:
-ver version information
-trks n1,n2,..(starting from 1)
-xtrks n1,n2,... (tracks to exclude)
-xchns n1,n2,... (channels to exclude)
-chns n1,n2,..(starting from 1)
-from n (in midi ticks)
-to n (in midi ticks)
-fromsec %f (in seconds)
-tosec %f (in seconds)
-frombeat %f
-tobeat %f
-replace trk,loc,val
-tempo n (in quarter notes/min)
-speed %f (between 0.1 and 10.0)
-drumfocus n (35 - 81) m (0 - 127)
-mutenodrum [level]
-setdrumloudness n (35-81) m (0 -127)
-focusontrack n1,n2,...
-focusonchannel n1,n2,...
-attenuation n
midicopy.exe -ver
will print out something like
1.29 December 06 2017
midicopy.exe input.mid output.mid
does nothing interesting except copy the contents of input.mid to a
new file output.mid.
If you include the -from parameter followed by a midi pulse number,
then the program will select the appropriate data starting after the
given midi pulse location so that will you play midi file it will start
from that midi pulse number. In order to ensure that the right tempo,
channel assignments are used, all of these commands prior to that
pulse number are also copied.
If you include the -to command followed by a midi pulse number, the
midi file is truncated beyond that point, so that when you play the file
it will stop at this point. You can also specify the window using beats
with the options -frombeats and -tobeats. The program will print out
the estimated duration of the output midi file.
All the tracks will be copied unless you specify them in the list following
keyword -trks. You start counting tracks from 1.
Similarly, all channels will be copied unless you specify them following
keyword -chns. You start counting channels from 1.
The -xchns and -xtrk options will exclude the indicated channels or
tracks from the output midi file. The -xchns does not work together
with -chns and neither does -xtrks work with -trks. (Use one or the
other.)
The option -replace allows you to overwrite a specific byte given its
track number and offset loc, by the byte whose value is val. This is
used for changing the program number associated with a channel. The byte
is replaced in the output file. If you use the -replace option, all
other options like -from, -to, -chns etc. are ignored.
The embedded tempo commands can be replaced using
-tempo n
in units beats/minute.
-speed f
where f is a decimal number between 0.1 and 10.0 will multiply
the current tempo by this factor.
-drumfocus will accentuate the specified drum (35 to 81) to level
m (0 to 127).
-focusontracks will attenuate all tracks except those specified.
-focusonchannels will attenuate all channels except those specified.
-attenuation specifies the amount to reduce the note velocities
for the focus options.
-------------------------------------------------------------------------
abcmatch.exe - see abcmatch.txt
-------------------------------------------------------------------------
A Short Explanation of MIDI
---------------------------
MIDI stands for "Musical Instrument Digital Interface". MIDI was originally
designed to connect a controller, such as a piano-style keyboard, to a
synthesizer. A MIDI cable is similar to a serial RS232 cable but uses
different voltage levels and an unusual baud rate (31250 baud). The MIDI
standard also defines the meaning of the digital signals sent down the
cable; pressing and releasing a key produces 2 of these signals, a
"note on" followed by a "note off".
There is an additional standard for MIDI files, which describes how to
record these signals together with the time when each signal was produced.
This allows a complete performance to be recorded in a compact digital
form. It is also possible for a computer to write a MIDI file which can
be played back in exactly the same way as a MIDI file of a recorded
performance. This is what abc2midi does.
-------------------------------------------------------------------------
Note: DPMI server for DOS executables
If you have downloaded the executables compiled using DJGPP, you may get
an error message saying that a DPMI (Dos Protected Mode Interface) server
is needed. If you can run the programs from a DOS window within Windows,
this may solve the problem. Alternatively, download the DPMI server
recommended for DJGPP, called CWSDPMI.EXE. This needs to be on your path
for the executables to run.
-------------------------------------------------------------------------
Bug reports
Please report any bugs you find in abc2midi, midi2abc, midicopy, or
abcmatch, abc2abc to fy733@ncf.ca (preferably with
an example so that I can replicate the problem). Better still, send
me the repaired source files which fix the problem! If you add your
own features to the code that other people might want to use then let
me know. I may or may not want to add them to the official version.
So far I have been maintaining the code, but I don't guarantee anything.

201
doc/yaps.1 Normal file
View File

@@ -0,0 +1,201 @@
.TH YAPS 1 "13 August 2005"
.SH NAME
.B
YAPS
\- converts an abc file to a PostScript file
.SH SYNOPSIS
yaps \fiabc\ file\fP [\-d] [\-e\ <list>] [\-E] [\-l] [\-M \fiXXXxYYY\fP] \
[\-N] [\-k nn] [\-o \fifile\ name\fP] [\-P \-\fiss\fP] [\-s \fiXX\fP] [\-V]\
[\-ver] [\-x] [\-OCC]
.SH OPTIONS
.TP
.B -d
For debugging only. Displays the internal data structures used in the program.
.TP
.B -e \fi<list>\fP
Draws tunes with reference numbers in a comma separated list. Spaces are
not allowed but a range of reference numbers can be specified. For example,
1,3,7-10.
.TP
.B -E
Generates Encapsulated Postscript output.
.TP
.B -M \fiXXXxYYY\fb
Set margin sizes in points where 28.3 points = 1cm and 72 points = 1 inch.
.TP
.B -N
Adds page numbering.
.TP
.B -k [nn]
Adds bar numbering. If number nn is included, then every nn'th bar
is numbered. Otherwise all bars are numbered.
.TP
.B -o \fifilename\fP
Specifies the output postscript file name.
.TP
.B -P \fiss\fP
Specifies the paper size where 0 is A4 and 1 is US Letter
or XXXxYYY sets the paper size in point units.
units.
.TP
.B -s \fiXX\fP
Specifies the scaling factor (default is 0.7)
.TP
.B -V
Voices are printed out separately for a multi-voice tune. Otherwise they
are interleaved.
.TP
.B -ver
Prints version number and exits.
.TP
.B -x
Print tune number in X: field
.TP
.B -OCC
Required if the tune uses the old convention for chords delineated
with +..+ instead of [...].
.SH FEATURES
.PP
* Uses the abc2midi parsing code, so hopefully compatibility with
abc2midi will be good.
.PP
* Measures the width of lyric text for lyric typesetting.
.PP
* Uses dynamically extensible data structures in most places, so
you should not be restricted by compiled-in limits.
.PP
* Multiple voices drawn with notes played at the same time aligned.
.PP
* Supports special characters using ISO latin 1 font. Special
characters are created with a TeX-like code e.g. \'E or a 3 digit octal
code e.g. \315 .
.PP
* Supports the following clefs : baritone, tenor, alto, mezzo, soprano,
treble, bass. Recommended use is
.PP
* Invisible rests (x) are displayed like normal rests.
.PP
* Nonnumeric voice id's, eg. V: soprano are accepted.
.PP
I:clef=bass
.PP
To make it easier to enter tunes in clefs othan than treble clef,
yaps supports I:octave=-1 to indicate that a C in the tune represents
the note one octave below the pitch defined in the abc standard. These
may be combined in one I: statement e.g.
.PP
I:clef=bass octave=-2
.PP
You can also use clefs that are one, two or three octaves higher or
lower than normal using e.g. treble-8, treble+15, treble-22. The clef is
drawn with a small 8, 15 or 22 above or below the clef symbol. The clef=
and octave= commands may also go in the K: field e.g.
.PP
K:G clef=bass-8 octave=-3
.PP
Note that there is an incompatibility between the behaviour of yaps and
the behaviour of abc2ps 1.3.3. abc2ps 1.3.3 does not support the
I:octave=N command, but selecting certain clefs causes it to automatically
transpose by several octaves. You can produce abc that works for both by
following the clef change with an I:octave=N command to do the transpose
that abc2ps does automatically.
.PP
* Produces boxed part labels.
.PP
* Supports the segno symbol with !segno! and coda with !coda! . Other
musical instructions such as !fine! and !D.C.! come out as text.
* Supports the U: field for abbreviating symbols to single characters. e.g.
.PP
U:S = !segno!
.PP
allows S to be used to produce the segno symbol. Currently this only
allows new symbols to be defined and does not allow the existing
pre-defined symbols M,L,R,H and T to be altered.
.PP
* Supports the !red! and !black! instructions for switching from
black to red or vice-versa.
.PP
* Supports the following abc2ps extensions to abc :
.PP
%%newpage - start a new page,
.br
%%vskip N - adds vertical space of N points. If N is followed by
'cm' or 'in' the units are taken as centimetres or
inches instead of points e.g. 4cm.
.br
%%text - print text
.br
%%centre (or %%center for Americans) - print centred text.
.br
If %%text or %%centre appear in the header, the text appears above
the tune.
.PP
%%staffsep SIZE - set the vertical blank space between 2 consecutive
music staves.
.PP
%%titleleft N - select title placed to the left or centred. N = 1
places the title on the left while N = 0 centres it.
.br
%%titlecaps - title is displayed in upper case (capital) letters.
.br
%%textfont NAME SIZE - select font called NAME and point size SIZE
for text produced by %%text or %%centre. If only NAME is given, the
font stays the same size. Likewise, if '-' is given as the NAME,
only the font size changes.
.br
%%titlefont NAME SIZE - select font for title.
.br
%%subtitlefont NAME SIZE - select font for titles after the first
title.
.br
%%composerfont NAME SIZE - select font for words in C: and O: fields
and part specifier (P: in header).
.br
%%wordsfont NAME SIZE - select font for words in W: fields.
.br
%%partsfont NAME SIZE - select font for boxed parts and
!instruction! .
.br
%%vocalfont NAME SIZE - select font for words in w: fields.
.br
%%gchordfont NAME SIZE - select font for guitar chords in the music.
(It is advisable not to change the font name for the last two, since
the program calculates the width of strings using default fonts)
.br
%%titlespace, %%subtitlespace, %%textspace, %%composerspace,
%%wordsspace, %%partsspace, %%vocalspace and %%gchordspace
determine the amount of space left above the relevant type
of text. Each of these should be followed by a size in points
or value in centrimetres or inches.
.br
e.g. %%composerfont 3
%%titlefont 2cm
.PP
* Supports placing of accompaniment chords either above or below the
stave.
.PP
%%chordsabove - places accompaniment chords above the stave
(default).
.br
%%chordsbelow - places accompaniment chords below the stave.
.PP
* Supports optional text enclosed in quotes before and after the
tempo specification in the Q: field. This extension comes from
abc2ps.
.SH AUTHOR
James Allwright <J.R.Allwright@westminster.ac.uk>
.SH SUPPORTED
Seymour Shlien <fy733@ncf.ca>
.PP
More complete documentation can be found in abcguide.txt which
comes with the abcMIDI distribution package.
.SH VERSION
This man page describes version 1.39 August 13 2005.

211
doc/yapshelp.txt Normal file
View File

@@ -0,0 +1,211 @@
YAPS - an abc to PostScript Converter
YAPS is Yet Another abc to PostScript converter.
The original converter was Michael Methfessel's abc2ps program. Another
converter is abcm2ps, based on the abc2ps code. YAPS uses the library
of PostScript routines from abc2ps, but the parser and other C code does
not come from abc2ps.
What is PostScript ?
--------------------
This program is intended for converting an abc tune to high quality
printed output. If yaps created an image file in, say, GIF
or PNG format it would have to decide how many pixels wide and how
many pixels high the final image would be. When the image was printed
on a printer capable of much higher resolution, you would be able to
see that the image was built up of lower resolution pixels. PostScript
gets round this limitation by storing the image as a description of
all the objects that will appear on the page. These descriptions are
converted to pixels at the last moment, when the resolution of the
printer is known. This way, you can make full use of the resolution
available.
If you are lucky, you may have a PostScript printer, in which case
you can send the output of yaps directly to the printer. If not,
there are PostScript interpreter programs available, which will
turn a PostScript image into other image formats. A popular freely
available PostScript interpreter is called GhostScript. Another
freely available program, GSView, provides a graphical interface
to GhostScript and lets you view images on-screen.
For a full description of the PostScript language, see "PostScript
Language Reference (third edition)" by Adobe Systems Inc.
----------------------------------------------------------------
Executing yaps with no filename will give the yaps version and the
following message:
Usage: yaps <abc file> [<options>]
possible options are -
-d : debug - display data structure
-e <list> : draw tunes with reference numbers in list
list is comma-separated and may contain ranges
but no spaces e.g. 1,3,7-20
-E : generate Encapsulated PostScript
-l : landscape mode
-M XXXxYYY : set margin sizes in points
28.3 points = 1cm, 72 points = 1 inch
-N : add page numbering
-k [NN] : number every bar or every NN th bar
-o <filename> : specify output file
-P ss : paper size; 0 is A4, 1 is US Letter
or XXXxYYY to set size in points
-s XX : scaling factor (default is 0.7)
-V : separate voices in multi-voice tune
-x : print tune number in X: field
Takes an abc music file and converts it to PostScript.
If no output filename is given, then by default it is
the input filename but with extension .ps .
YAPS features
-------------
1. Uses the abc2midi parsing code, so hopefully compatibility with
abc2midi will be good.
2. Measures the width of lyric text for lyric typesetting.
3. Uses dynamically extensible data structures in most places, so
you should not be restricted by compiled-in limits.
4. Multiple voices drawn with notes played at the same time aligned.
5. Supports special characters using ISO latin 1 font. Special
characters are created with a TeX-like code e.g. \'E or a 3 digit octal
code e.g. \315 .
6. Supports the following clefs : baritone, tenor, alto, mezzo, soprano,
treble, bass. Recommended use is
I:clef=bass
To make it easier to enter tunes in clefs othan than treble clef,
yaps supports I:octave=-1 to indicate than a C in the tune represents
the note one octave below the pitch defined in the abc standard. These
may be combined in one I: statement e.g.
I:clef=bass octave=-2
You can also use clefs that are one, two or three octaves higher or
lower than normal using e.g. treble-8, treble+15, treble-22. The clef is
drawn with a small 8, 15 or 22 above or below the clef symbol. The clef=
and octave= commands may also go in the K: field e.g.
K:G clef=bass-8 octave=-3
Note that there is an incompatibility between the behaviour of yaps and
the behaviour of abc2ps 1.3.3. abc2ps 1.3.3 does not support the
I:octave=N command, but selecting certain clefs causes it to automatically
transpose by several octaves. You can produce abc that works for both by
following the clef change with an I:octave=N command to do the transpose
that abc2ps does automatically.
7. Produces boxed part labels.
8. Supports the segno symbol with !segno! and coda with !coda! . Other
musical instructions such as !fine! and !D.C.! come out as text.
9. Supports the U: field for abbreviating symbols to single characters.
e.g.
U:S = !segno!
allows S to be used to produce the segno symbol. Currently this only
allows new symbols to be defined and does not allow the existing
pre-defined symbols M,L,R,H and T to be altered.
10. Supports the following abc2ps extensions to abc :
%%newpage - start a new page,
%%vskip N - adds vertical space of N points. If N is followed by
'cm' or 'in' the units are taken as centimetres or inches
instead of points e.g. 4cm.
%%text - print text
%%centre (or %%center for Americans) - print centred text.
If %%text or %%centre appear in the header, the text appears above the
tune.
%%staffsep SIZE - set vertical blank space between 2 consecutive music
staves.
%%titleleft N - select title placed to the left or centred. N = 1 places
the title on the left while N = 0 centres it.
%%titlecaps - title is displayed in upper case (capital) letters.
%%textfont NAME SIZE - select font called NAME and point size SIZE for
text produced by %%text or %%centre. If only NAME is given, the font
stays the same size. Likewise, if '-' is given as the NAME, only the
font size changes.
%%titlefont NAME SIZE - select font for title.
%%subtitlefont NAME SIZE - select font for titles after the first title.
%%composerfont NAME SIZE - select font for words in C: and O: fields and
part specifier (P: in header).
%%wordsfont NAME SIZE - select font for words in W: fields.
%%partsfont NAME SIZE - select font for boxed parts and !instruction! .
%%vocalfont NAME SIZE - select font for words in w: fields.
%%gchordfont NAME SIZE - select font for guitar chords in the music.
(It is advisable not to change the font name for the last two, since
the program calculates the width of strings using default fonts)
%%titlespace, %%subtitlespace, %%textspace, %%composerspace, %%wordsspace,
%%partsspace, %%vocalspace and %%gchordspace determine the amount of
space left above the relevant type of text. Each of these should be
followed by a size in points or value in centrimetres or inches.
e.g. %%composerfont 3
%%titlefont 2cm
11. Supports placing of accompaniment chords either above or below the
stave.
%%chordsabove - places accompaniment chords above the stave (default).
%%chordsbelow - places accompaniment chords below the stave.
12. Supports optional text enclosed in quotes before and after the
tempo specification in the Q: field. This extension comes from abc2ps.
13. Allows highlighting notes by switching output from black to
red and vice-versa using the !red! and !black! instructions.
Known bugs and Limitations
--------------------------
1. Overfull lines of music are not split over multiple lines.
WARNING - the -s option is now used for scaling. Selecting separate
printing of each voice (which previously used -s) is now done with -V.
YAPS is still under development and missing a number of features. However,
it should produce acceptable output most of the time. You may want to try
abc2ps or abcm2ps if you find that YAPS will not do what you want.
Viewing PostScript Files from DOS
---------------------------------
Here is how I arranged things so that I can view PostScript from DOS :
1. Install Ghostscript 5.10 (compiled to run under DOS). This is not
totally straightforward; you have to install the fonts separately and
then set the environment variable GS_LIB to a path containing the
GhostScript initialization files and the fonts.
2. Install Pictview, a free image viewer.
3. Create a small batch file ps.bat containing the following line:
c:\gs5.10\gs386 -r120 -sOutputFile=out.tif -sDEVICE=tiffg3 -sPAPERSIZE=a4 -dNOPAUSE -dBATCH %1
When you run this, it creates a TIFF file out.tif containing all
pages in compressed format.
The following commands will show you the dots for an abc file:
yaps demo.abc
ps demo.ps
pictview out.tif
Copyright (c) James Allwright 1999
(parts of the code Copyright Michael Methfessel).
This code may be freely re-distributed under the terms of the
GNU public license. You are encouraged to modify and redistribute it,
provided this copyright notice is retained.