Provided by: abcmidi_20070318-3_amd64 bug

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                              ABCMATCH(1)