NAME
abcmatch - search sequences of notes in an ABC file
SYNOPSIS
abcmatch data-file [number] [-a] [-br d] [-c] [-con] [-ign]
[-length_hist] [-pitch_hist] [-qnt] [-r n] [-v] [-ver]
DESCRIPTION
abcmatch searches an ABC file containing (potentially) many tunes for
specific sequences of notes. 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.
Though the program can be run stand-alone, it is really meant to be run
with a GUI such as runabc.tcl (which is not yet part of Debian). Most
of its output is rather cryptic.
THE MATCHING PROCESS
The template file must be a well-formed ABC file containing the basic
X:, M:, L:, and K: headers as well as the bars to be matched.
(Normally, this file is created by runabc.tcl.) It is important to
finish each bar in the match file with a vertical line.
abcmatch uses the key signature to figure out the relative position of
the notes in the scale, and to determine all the assumed sharps and
flats. Therefore the program can find matching bars in a tune that has
been transposed to another key, as long as the key difference is not
too large. Matches are output in a list format looking like
29 30 4
30 31 4
Each line indicates a particular match found by the program. The first
number on each line gives the relative position of the tune in the
data-file, while the next number gives the X: number of that tune. The
last number is the bar number of the matching tune. Bar numbers are
counted sequentially from the start of the tune, and all V: and P:
indications are ignored. That is, the bar number returned by abcmatch
may not match bar numbers printed by one of the PostScript-producing
ABC processors such as abcm2ps or abcmidi-yaps.
For the purposes of matching, abcmatch ignores all guitar chords,
lyrics, note decorations (e.g., staccato markings), grace notes, etc.
In chords such as [G2c2], only the highest note is considered. Any
warnings or error messages from the ABC parser are suppressed unless
the -c option is given.
OPTIONS
-a Report any matching bars. By default, if the template file
contains a sequence of several bars, the program will try to
find places in the data file where the whole sequence matches.
With this option, it returns all places in the data file where
any of the bars in the template file match.
-br d ‘Brief mode’ is designed to identify groups of tunes sharing
common bars. In this mode, the program determines the number of
all bars in each tune from the data file which are also present
in the template file. If the number of common bars is greater
than or equal to the value of the d parameter, the program
reports the tune and the number of common bars. Currently there
is no user control of the matching criterion; the rhythm must
match exactly, and the notes are transposed to suit the key
signature.
-c Display error and warning messages from the ABC parser (which
are suppressed by default).
-con Do a pitch contour match. In this case, the program uses the key
signature only to indicate accidentals. The pitch contour is
computed from the pitch difference (interval) between adjacent
notes. That is, C2 DE, c2 de, and G2 AB all have the same pitch
contour.
-ign Ignore simple bars.
-length_hist
This does no matching at all but returns a histogram of the
distribution of note lengths in the data file. The output looks
like
length histogram
12 100
24 20
36 6
48 2
72 4
where a quarter note is 24 units, an eight note 12 units, a
dotted half note 72 units etc.
-pitch_hist
This does no matching at all but returns a histogram of the
distribution of pitches in the data file. The output looks like
pitch histogram
64 2
66 9
67 11
where the first number on each line is a MIDI note number and
the second is a count of the number of times that note occurred.
-qnt Do a quantized pitch contour match. This works as described
above for the -con option, but will also quantize the intervals
as follows: Unison and semitone intervals are assigned value 0,
major 2nds to major 3rds value 1, and a perfect 4th or greater
value 2. Negative numbers are used for descending intervals.
-r n Resolution for matching. If the n parameter is zero, a perfect
match must be found, meaning that the lengths of each note in a
bar must match exactly in order to be reported. The larger the
value of n, the looser the match will be. Note lengths are
converted into temporal units where a quarter note is normally
assigned a value of 24 (therefore an eighth note has a value of
12, a sixteenth a value of 6, a half note a value of 48 etc.) If
you specify a temporal resolution of 12, then the pitch values
of the notes only need to match at the time units that are
multiples of an eight note. This means that the program would
match the two bars C2 D2 and C C D D, as well as C2 D2 and
C/D/C/D/D2. By selecting a suitable value for n, you can search
for matches only at the beginning of a measure or at the
beginning of each beat.
-v Run verbosely.
-ver Display the program’s version number.
LIMITATIONS
The program has some limitations. For example, the data file must
contain bar lines, and tied notes cannot be longer than the equivalent
of 8 quarter notes. A resolution (-r option) that is too small may
cause some buffers to be exceeded. When there are differences of key
signatures of more than 5 semitones, the program may transpose the
notes in the wrong direction. Also, tunes with more than one key
signature or time signature may not be processed correctly.
SEE ALSO
abc2midi(1), midi2abc(1), mftext(1)
AUTHOR
This manual page was written by Anselm Lingnau <lingnau@debian.org> for
the GNU/Linux system.
VERSION
This manual page describes abcmatch version 1.42 as of 21 December
2006.
24 August 2007