| 1 |
.TH ABCMATCH 1 |
| 2 |
.SH NAME |
| 3 |
abcmatch \- Search for specific sequences of notes in an abc file composed of many tunes. |
| 4 |
.SH SYNOPSIS |
| 5 |
\fBabcmatch\fP \fiabc\ file\fP [\fB-c\fP] [\fB-v\fP] [\fB-r\fP] [\fB-con\fP]\ |
| 6 |
[\fB-fixed nn\fP] [\fB-qnt\fP] [\fB-lev\fP] [\fB-a\fP] [\fB-ign\fP]\ |
| 7 |
[\fB-br %d\fP] [\fB-tp abc reference file\fP] [\fB-ver\fP]\ |
| 8 |
[\fB-pitch_hist\fP] [\fB-wpitch_hist\fP] [\fB-length_hist\fP]\ |
| 9 |
[\fB-interval_hist\fP] [\fB-pitch_table\fP] [\fB-interval_table\fP]\ |
| 10 |
\fireference\ number\fP |
| 11 |
.SH "DESCRIPTION" |
| 12 |
.PP |
| 13 |
.B abcmatch |
| 14 |
is used to search for specific sequences of notes in an abc file |
| 15 |
composed of many tunes. For example, if you know a few bars of a tune, |
| 16 |
you can use this program to find the tune having this sequence and perhaps |
| 17 |
identify the tune. |
| 18 |
At a minimum, abcmatch requires two files. A template file called |
| 19 |
match.abc which contains the bars that you are searching for and a large |
| 20 |
file consisting of a hundred or more abc tunes. The program automatically |
| 21 |
loads up the match.abc file and then scans every tune in the large file |
| 22 |
.SH OPTIONS |
| 23 |
.TP |
| 24 |
.B -v and -c |
| 25 |
mainly used for debugging when the program does not do what was expected. |
| 26 |
.TP |
| 27 |
.B -ver |
| 28 |
prints version number and then exits |
| 29 |
.TP |
| 30 |
.B --norhythm |
| 31 |
Causes the matching algorithm to ignore the length of notes in a bar, |
| 32 |
thus E3/2F/D GA2 would match EFD G2A. The option ignores \-r parameter |
| 33 |
since it is now irrelevant. |
| 34 |
.TP |
| 35 |
.B -pitch_table |
| 36 |
Used to produce a interval weighted pitch histogram for each tune in |
| 37 |
the file. If this is saved in an external file, that file could be used |
| 38 |
as a database for finding tunes with similar pitch probability density |
| 39 |
functions (pdf). |
| 40 |
.TP |
| 41 |
.B -r |
| 42 |
Controls how the matching criterion handles small rhythm variations in |
| 43 |
the melody. The \-r option must be followed by a number which specifies |
| 44 |
the temporal resolution for the match. When the number is zero, this |
| 45 |
indicates that a perfect match should be performed, meaning that the |
| 46 |
lengths of each note in the bar must match exactly in order to be |
| 47 |
reported. For larger values a looser match will be performed as |
| 48 |
described below. Note lengths are converted into temporal units where |
| 49 |
a quarter note normally is assigned a value of 24. Therefore an eight |
| 50 |
note has a value of 12, a sixteenth has a value of 6, a half note has |
| 51 |
a value of 48 and etc. If you specify a temporal resolution of 12, then |
| 52 |
the pitch values of the notes only need to match at time units which |
| 53 |
are multiples of an eighth note. |
| 54 |
.TP |
| 55 |
.B -fixed n |
| 56 |
Causes the program to disregard bar lines when does the matching. It |
| 57 |
allows matching of notes between tunes having different time signatures. |
| 58 |
n is a number which specifies the exact number of notes to match. For |
| 59 |
example if n is 4, the program could match |
| 60 |
|C E G E| .. with |C E|G E| |
| 61 |
Note the matcher still starts at a beginning of a given bar for both the |
| 62 |
tune and template. |
| 63 |
.TP |
| 64 |
.B -con |
| 65 |
Specifies contour matching. In this case, the program uses the key |
| 66 |
signature only to indicate accidentals. The pitch contour is computed |
| 67 |
from the pitch difference or interval between adjacent notes. |
| 68 |
.TP |
| 69 |
.B -qnt |
| 70 |
Uses the contour matching algorithm but also quantizes the intervals |
| 71 |
using the following table: |
| 72 |
|
| 73 |
unison and semitone 0 |
| 74 |
minor 2nd to major 2nd 1 |
| 75 |
minor 3rd to major 3rd 2 |
| 76 |
any larger interval 3 |
| 77 |
|
| 78 |
Negative numbers are descending intervals. |
| 79 |
.TP |
| 80 |
.B -tp file name, reference number |
| 81 |
Substitute any tune for the template match.abc. When using this |
| 82 |
feature, the entire tune is used as a template. Abcmatch does not match |
| 83 |
the template with itself, and only bars which match bars in other tunes |
| 84 |
are reported. |
| 85 |
.TP |
| 86 |
.B -br threshold |
| 87 |
Runs the program in a brief mode designed to identify groups of tunes |
| 88 |
sharing common bars. In this mode, the program counts the numbers of |
| 89 |
bars in the test tune which are also present in match.abc. If the |
| 90 |
number of common bars is larger or equal to the threshold then the |
| 91 |
program reports the tune and the number of common bars. |
| 92 |
The program scans all the tunes in the abc file and returns a list of |
| 93 |
all the tunes which have more than a specific number of bars in common |
| 94 |
with the template, match.abc. In actual use, the program is run |
| 95 |
repeatedly by a script. For each tune in a abc file, it creates a |
| 96 |
template file called match.abc and then executes abcmatch. The outputs |
| 97 |
are displayed on the screen in a form easy to interpret. The user has |
| 98 |
no control of the matching criterion. The rhythm must match exactly |
| 99 |
and the notes are transposed to suit the key signature. In other words |
| 100 |
the \-r parameter is independent of what is specified in the parameter |
| 101 |
list. |
| 102 |
.TP |
| 103 |
.B -pitch_hist or -length_hist |
| 104 |
Runs the program in another mode. It produces a histogram of the |
| 105 |
distribution of the notes in the abc file. |
| 106 |
The pitch is indicated in midi units. Thus middle C is 60 and the |
| 107 |
pitches go up in semitone units. Following the pitch is a count |
| 108 |
of the number of times that note occurred. |
| 109 |
.TP |
| 110 |
.B -pitch_table or -interval_table |
| 111 |
Used to create a database for a collection of tunes in a file for |
| 112 |
future analysis. |
| 113 |
|
| 114 |
.SH "SEE ALSO" |
| 115 |
.PP |
| 116 |
.IR abc2abc "(1), " abc2midi "(1), " mftext "(1) ", midi2abc "(1) ", midicopy "(1) ", yaps "(1)" |
| 117 |
.SH AUTHOR |
| 118 |
This manual page was written by Ross Gammon based on abcmatch.txt by Seymour Shlien. |
| 119 |
.SH VERSION |
| 120 |
This man page describes abcmatch version 1.35 from January 15 2006. |