Debian Codegraph @

upstream/debian-unstable/man1/abcmatch.1

raw
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.