Man Linux: Main Page and Category List

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