Debian Codegraph @

upstream/debian-unstable/man1/abc2midi.1

raw
1 .TH ABC2MIDI 1 "June 2017"
2 .SH NAME
3 \fBabc2midi\fP \- converts abc file to MIDI file(s)
4 .SH SYNOPSIS
5 abc2midi \fIinfile\fP [\fIrefnum\fP] [\-c] [\-v] [\-ver] [\-t] [\-n limit] [\-CS] [\-quiet] [\-silent] [\-Q tempo] [\-NFNP] [\-NFER] [\-NGRA] [\-NGUI] [\-STFW] [\-OCC] [\-NCOM] [\-HARP] [\-BF] [\-TT] [\-o outfile] \-CSM [filename]
6 .SH DESCRIPTION
7 The default action is to write a MIDI file for each abc tune
8 with the filename <stem>N.mid, where <stem> is the filestem
9 of the abc file and N is the tune reference number. If the \-o
10 option is used, only one file is written. This is the tune
11 specified by the reference number or, if no reference number
12 is given, the first tune in the file.
13 .SH OPTIONS
14 .TP
15 .B \fIrefnum\fP
16 process the tune with reference number \fIrefnum\fP
17 .TP
18 .B -c
19 selects checking only
20 .TP
21 .B -v n
22 selects verbose option where n is the level (optional)
23 .TP
24 .B -ver
25 prints version number and exits
26 .TP
27 .B -t
28 selects filenames derived from tune titles
29 .TP
30 .B -CS
31 use 2:1 instead of 3:1 for broken rhythms
32 .TP
33 .B -quiet
34 Suppresses some common warnings.
35 .TP
36 .B -silent
37 Suppresses other messages.
38 .TP
39 .B -n \fI X\fP
40 limits the length of the file name stem to X characters
41 .TP
42 .B -Q \fI tempo\fP
43 sets the default tempo in quarter notes per minute if it was not
44 specified in the abc header.
45 .TP
46 .B -NFNP
47 Ignore any dynamic indications !f! !ff! etc.
48 .TP
49 .B -NFER
50 Ignore any fermata indications (eg H or !fermata!).
51 .TP
52 .B -NGRA
53 Ignore any grace notes.
54 .TP
55 .B -NGUI
56 Ignore any guitar chords enclosed in double quotes.
57 .TP
58 .B -STFW
59 Place lyric text in separate MIDI tracks.
60 .TP
61 .B -NCOM
62 Suppress some comments in the output MIDI file.
63 .TP
64 .B -OCC
65 Accept old chord convention (eg +D2G2+ instead of [DG]2).
66 .TP
67 .B -BF
68 BarFly mode: invokes a stress model if possible.
69 .TP
70 .B -HARP
71 Roll ornaments=roll are generated for the harpist (same pitch)
72 .TP
73 .B -TT
74 Changes the tuning from A = 440 Hz.
75 .TP
76 .B -o \fIoutfile\fP
77 write output to \fIoutfile\fP
78 .TP
79 .B -CSM \fIinfile\fP
80 load a set of custom stress modes from a file
81 .SH FEATURES
82 .PP
83 * Broken rhythms (>, <), chords, n-tuples, slurring, ties, staccatto notes,
84 repeats, in-tune tempo/length/time signature changes are all supported.
85 .PP
86 * R:hornpipe or r:hornpipe is recognized and note timings are adjusted to
87 give a broken rhythm (ab is converted to a>b).
88 .PP
89 * Most errors in the abc input will generate a suitable error message in
90 the output and the converter keeps going.
91 .PP
92 * Comments and text fields in the abc source are converted to text events
93 in the MIDI output
94 .PP
95 * If guitar chords are present, they are used to generate an accompaniment
96 in the MIDI output.
97 .PP
98 * If there are mis-matched repeat signs in the abc, the program attempts to
99 fix them. However, it will not attempt this if a multi-part tune
100 description has been used or if multiple voices are in use.
101 .PP
102 * Karaoke MIDI files can be generated by using the w: field to include
103 lyrics.
104 .PP
105 * Nonnumeric voice id's, eg. V: soprano, as proposed for the new
106 abc standard is accepted.
107 .PP
108 * Invisible rests specified by x are treated the same way as
109 normal rests (z).
110 .PP
111 * Decorations may be indicated using either the deprecated
112 notation (eg. !fermata!) or the standard version 2.0 notation
113 (eg. +fermata+).
114 .PP
115 .SH LIMITATIONS
116 * No field is inherited from above the X: field of the tune.
117
118
119 .SH "ABC SYNTAX EXTENSIONS"
120 * There are some extensions to the abc syntax of the form
121 .PP
122 %%MIDI channel n
123 .PP
124 These control channel and program selection, transposing and various
125 other features of abc2midi.
126 .PP
127 Each of these should appear on a line by itself. All of them are allowed
128 within the abc tune body. By using these in combination with the part
129 notation, one can, for example, play a part transposed or in a different key.
130 .PP
131 The idea behind this syntax is that other programs will treat it as a
132 comment and ignore it.
133 .PP
134 %%MIDI channel n
135 .PP
136 selects melody channel n (in the range 1-16).
137 .PP
138 %%MIDI program [c] n
139 .PP
140 selects program n (in the range 0-127) on channel c. If c is not given, the
141 program is selected on the current melody channel. Most modern tone
142 generators follow the General MIDI standard which defines the instrument
143 type for each program number.
144 .PP
145 %%MIDI beat a b c n
146 .PP
147 controls the way note velocities are selected. The first note in a bar has
148 velocity a. Other "strong" notes have velocity b and all the rest have velocity
149 c. a, b and c must be in the range 0-127. The parameter n determines which
150 notes are "strong". If the time signature is x/y, then each note is given
151 a position number k = 0, 1, 2 .. x-1 within each bar. Note that the units for
152 n are not the unit note length. If k is a multiple of n, then the note is
153 "strong". The volume specifiers !ppp! to !fff! are equivalent to the
154 following :
155 .P
156 !ppp! = %%MIDI beat 30 20 10 1
157 .br
158 !pp! = %%MIDI beat 45 35 20 1
159 .br
160 !p! = %%MIDI beat 60 50 35 1
161 .br
162 !mp! = %%MIDI beat 75 65 50 1
163 .br
164 !mf! = %%MIDI beat 90 80 65 1
165 .br
166 !f! = %%MIDI beat 105 95 80 1
167 .br
168 !ff! = %%MIDI beat 120 110 95 1
169 .br
170 !fff! = %%MIDI beat 127 125 110 1
171
172 .PP
173 %%MIDI beatmod n
174 .PP
175 Increments by n (or decrements if n is negative) the velocities a, b and
176 c described above. The instructions !crescendo(! and !crescendo)!
177 are equivalent to inserting a %%MIDI beatmod 15 wherever they
178 occur. (Alternatively you can use !<(! and !<)!.) Similarly the
179 instructions !diminuendo(! and !diminuendo)! are equivalent
180 to %%MIDI beatmod \-15.
181
182 .PP
183 %%MIDI deltaloudness n
184 .PP
185 where n is a small positive number. By default the crescendo and
186 diminuendo instructions modify the beat variables a, b, and c by
187 15 velocity units. This instruction allows you to set this default
188 to value n.
189
190 .PP
191 %%MIDI nobeataccents
192 .PP
193 For instruments such as church organ that have no greatly emphasized beat notes,
194 using this will force use of the 'b' velocity (see %%MIDI beat)
195 for every note irrespective of position in the bar. This allows dynamics
196 (ff, f, etc) to be used in the normal way.
197 .PP
198 %%MIDI beataccents
199 .PP
200 Revert to emphasizing notes the the usual way. (default)
201
202 .PP
203 %%MIDI beatstring <string of f, m and p>
204 .PP
205 This provides an alternative way of specifying where the strong and weak
206 stresses fall within a bar. 'f' means velocity a (normally strong), 'm'
207 means velocity b (medium velocity) and 'p' means velocity c (soft velocity).
208 For example, if the time signature is 7/8 with stresses on the first, fourth
209 and sixth notes in the bar, we could use the following
210 .PP
211 %%MIDI beatstring fppmpmp
212 .PP
213 %%MIDI transpose n
214 .PP
215 transposes the output by the specified number of semitones. n may be
216 positive or negative.
217 .PP
218 %%MIDI rtranspose n
219 .PP
220 Relative transpose by the specified number of semitones. i.e.
221 %%MIDI transpose a followed by %%MIDI rtranspose b results in a
222 transposition of a+b. %%MIDI transpose b will result in a transposition
223 of b semitones, regardless of any previous transposition.
224 .PP
225 %%MIDI c n
226 .PP
227 specifies the MIDI pitch which corresponds to c. The default is 60. This
228 number should normally be a multiple of 12.
229 .PP
230 %%MIDI grace a/b
231 .PP
232 sets the fraction of the next note that grace notes will take up. a
233 must be between 1 and b-1. The grace notes may not sound natural
234 in this approach, since the length of the individual grace notes
235 vary with the complexity of the grace and the length of the
236 following note. A different approach (which is now the default)
237 assumes that the grace notes always have a fixed duration.
238 To use the other approach you would specify,
239
240 %%MIDI gracedivider b
241
242 where b specifies how many parts to divide the unit length
243 specified by the L: field command. For example if b = 4 and
244 L: = 1/8, then every grace note would be 1/(8*4) or a 32nd
245 note. Time would be stolen from the note to which the grace
246 notes are applied. If that note is not long enough to handle
247 the grace then the grace notes would be assigned 0 duration.
248
249
250
251 .PP
252 %%MIDI chordname name n1 n2 n3 n4 n5 n6
253 .PP
254 Defines how to play a guitar chord called "name". n1 is usually 0 and
255 n2, n3 to n6 give the pitches of the other notes in semitones relative
256 to the root note. There may be fewer than 6 notes in the chord, but not
257 more.If "name" is already defined, this command re-defines it. Unlike
258 most other commands, chordname definitions stay in effect from where they
259 are defined to the end of the abc file. The following illustrates how
260 m, 7, m7 and maj7 could be set up if they were not already defined.
261 .PP
262 %%MIDI chordname m 0 3 7
263 .br
264 %%MIDI chordname 7 0 4 7 10
265 .br
266 %%MIDI chordname m7 0 3 7 10
267 .br
268 %%MIDI chordname maj7 0 4 7 11
269 .PP
270 %%MIDI gchord string
271 .PP
272 sets up how guitar chords are generated. The string is a sequence made of
273 of z's, c's f's and b's for rests, chords, fundamental and fundamental
274 plus chord notes respectively. This specifies how each bar is to be played.
275 An optional length is allowed to follow the z's, c's f's and b's e.g. czf2zf3.
276 If the abc contains guitar chords, then abc2midi automatically adds chords and
277 fundamentals after encountering the first guitar chord. It keeps using that
278 chord until a new chord is specified in the abc. Whenever the M: field is
279 encountered in the abc, an appropriate default string is set :
280 .P
281 For 2/4 or 4/4 time default is equivalent to :
282 %%MIDI gchord fzczfzcz
283 .P
284 For 3/4 time default is equivalent to :
285 %%MIDI gchord fzczcz
286 .P
287 For 6/8 time default is equivalent to :
288 %%MIDI gchord fzcfzc
289 .P
290 For 9/8 time default is equivalent to :
291 %%MIDI gchord fzcfzcfzc
292 .P
293
294 The gchord command has been extended to allow you to play
295 the individual notes comprising the guitar chord. This allows
296 you to play broken chords or arpeggios. The new codes g,h,i,j,
297 G,H,I,J reference the individual notes starting from the
298 lowest note of the chord (not necessarily the root in the
299 case of inversions). For example for the C major chord, g
300 refers to C, h refers to E and i refers to G. For a gchord
301 command such as,
302 .P
303 %%MIDI gchord ghih
304 .P
305 Abc2midi will arpeggiate the C major guitar chord to
306 CEGE. The upper case letters G,H,I, and J refer to
307 the same notes except they are transposed down one
308 octave. Note for the first inversion of the C major
309 chord (indicated by "C/E"), E would be the lowest
310 note so g would reference the note E.
311 .P
312 Like other gchord codes, you may append a numeral indicating
313 the duration of the note. The same rules apply as before.
314 You can use any combination of the gchord codes,
315 (fcbghijGHIJz).
316
317
318 .PP
319 %%MIDI chordprog n
320 .PP
321 Sets the MIDI instrument for the chords to be n. If the command
322 includes the string octave=n where n is a number between \-2 and 2
323 inclusive, then this will shift the pitch of the instrument by n
324 octaves. For example %%MIDI chordprog 10 octave=1.)
325
326 .PP
327 %%MIDI bassprog n
328 .PP
329 Sets the MIDI instrument for the bass notes to be n. If the command
330 includes the string octave=n where n is a number between \-2 and 2
331 inclusive, then this will shift the pitch of the instrument by n
332 octaves. For example %%MIDI bassprog 10 octave=\-1.)
333 .PP
334 %%MIDI chordvol n
335 .PP
336 Sets the volume (velocity) of the chord notes at n.
337 .PP
338 %%MIDI bassvol n
339 .PP
340 Sets the volume (velocity) of the bass notes at n. There is no corresponding
341 melodyvol command since there are 3 velocity values for melody, set using the
342 beat command.
343 .PP
344 %%MIDI gchordon
345 .PP
346 Turns on guitar chords (they are turned on by default at the start of a
347 tune).
348 .PP
349 %%MIDI gchordoff
350 .PP
351 Turns off guitar chords.
352 .PP
353 %%MIDI droneon
354 .PP
355 Turns on a continuous drone (used in bagpipe music) consisting
356 of two notes. By default the notes are A, and A,, played
357 on a bassoon at a velocity of 80. This can be configured
358 by the %%MIDI drone command described below.
359 .PP
360 %%MIDI droneoff
361 .PP
362 Turns off the continuous drone.
363 .PP
364 %%MIDI drone n1 n2 n3 n4 n5
365 .PP
366 Sets the drone parameters where n1 is the MIDI program, n2 and
367 n3 specify the MIDI pitches of the two notes in the chord, and n4
368 and n5 specify the MIDI velocities of the two notes.
369 If you do not set these parameters they are by default
370 70 45 33 80 80. A value of zero or less indicates that
371 the setting of this parameter should be left as it is.
372 .PP
373 %%MIDI drum string [drum programs] [drum velocities]
374 .PP
375 This sets up a drum pattern. The string determines when there is a drum beat
376 and the drum program values determine what each drum strike sounds like.
377 .PP
378 e.g. %%MIDI drum d2zdd 35 38 38 100 50 50
379 .PP
380 The string may contain 'd' for a drum strike or 'z' for a rest. By default
381 a voice starts with no drum pattern and '%%MIDI drumon' is
382 needed to enable the drumming. The drum pattern is repeated during
383 each bar until '%%MIDI drumoff' is encountered. The %%MIDI drum
384 command may be used within a tune to change the drum pattern.
385 This command places the drum sounds on channel 10 and
386 assumes your tone generator complies with the General Midi standard - if
387 it does not, then you may hear tones instead of drum sounds.
388 .PP
389 In both the gchord and drum commands, the standard note length of
390 a single note f,c,z or d is not set by the L: command. Instead it
391 is adjusted so that the entire gchord string or drum string fits
392 exactly into one bar. In other words the duration of each note
393 is divided by the total duration of the string. This means that,
394 for example, the drum string "dd" is equivalent to drum string "d4d4".
395 You cannot currently specify fractions directly (eg. C3/2)
396 as done in the body of the music, but it is still possible to express
397 complex rhythms. For example, to indicate a rhythm such as
398 (3ddd d/d/d/d, you would write the string "d4d4d4d3d3d3d3".
399 .PP
400 %%MIDI drumbars n
401 .PP
402 The %%MIDI drum line can sound quite monotonous if it is repeated
403 each bar. To circumvent this problem a new MIDI command
404 %%MIDI drumbars n
405 where n is a small number will spread out the drum string over
406 n consecutive bars. By default drumbars is set to 1 maintaining
407 compatibility with existing abc files. You should take
408 care that the drumstring is evenly divisible between the
409 drumbar bars. Also the time signature should not change
410 between bars in a drumbar unit. (Sample abc file in doc/CHANGES
411 June 24 2008.)
412 .PP
413 %%MIDI gchordbars n
414 .PP
415 This command spreads the gchord string over n consecutive bars
416 just like drumbars (above). (A sample is found in doc/CHANGES
417 March 17 2009.)
418
419
420
421
422 .PP
423 With version 1.54 Dec 4 2004 of abc2midi, notes in chords
424 (eg. [FAc]) are not played in the same instant but offsetted
425 and shortened by 10 MIDI time units. Thus the first note
426 in the chord (eg. F) is played for the full indicated time,
427 the second note (eg. A) starts 10 MIDI units later and is shortened
428 by the same amount and the third note starts another 10 MIDI
429 units later and is shortened by another 10 units. This introduces
430 an "expressivo" option and avoids the heavy attack. (This
431 does not apply to gchords or multivoiced chords.) The amount
432 of the delay and shortening may be configured by the MIDI command
433
434 .PP
435 %%MIDI chordattack n
436
437 .PP
438 where n is a small number. If n is zero, then abc2midi should
439 behave as in earlier versions. The delay n is in MIDI time units
440 where there are 480 units in a quarter note beat. The program
441 may not run correctly if n is too large and there are short
442 chords.
443
444 .PP
445 %%MIDI randomchordattack n
446 .PP
447 Like above except that the delay is a random variable uniformly
448 distributed between 0 and n-1.
449
450 .PP
451 %%MIDI trim x/y
452 .PP
453 where x and y are two numbers. This command controls the articulation
454 of notes and chords by placing silent gaps between the notes. The length
455 of these gaps is determined by x/y and the unit length specified by the L:
456 command. These gaps are produced by shortening the notes by the same amount.
457 If the note is already shorter than the specified gap, then the gap
458 is set to half the length of the note. The fraction x/y indicates
459 a note duration in the same manner as specified in the abc file.
460 The actual duration is based on the unit length specified by the
461 L: field command. It is recommended that x/y be a fraction close
462 to zero. Note trimming is disabled inside slurs as specified by
463 parentheses. You can turn off all note trimming by setting x to 0,
464 eg 0/1. By default, note trimming is turned off at the beginning
465 of a tune or voice command.
466
467 .PP
468 %%MIDI expand x/y
469 .PP
470 where x and y are two numbers defining a fraction less than 1.
471 This command controls the articulation of notes and chords in the
472 reverse manner. The notes are lengthened by this fraction so they
473 overlap the start of the next note.
474
475
476 .PP
477 %%MIDI drummap note midipitch
478 .PP
479 Please see abcguide.txt.
480 .PP
481 %%MIDI ptstress filename
482 .PP
483 This command loads file filename into abc2midi which contains
484 the Phil Taylor stress parameters and puts abc2midi in the mode
485 where it applies these stress parameters on every note. This
486 model runs in opposition to the standard beat model, so the
487 MIDI beat, beatstring, beatmod commands become ineffectual.
488 This also means that the dynamic indications !f! !pp! etc.
489 do not work any more.
490 .PP
491 There are two different implementations of the stress model.
492 Model 1 modifies the note articulation and takes
493 control of the MIDI trim parameters too. To revert back to
494 the standard model, put the command %%MIDI beataccents.
495 Model 2 modifies both the onset and ending of each note
496 allowing a musical beat to expand or contract in time. However,
497 the length of a musical measure should be preserved. Note
498 if you using model 2, which the current default, you must
499 include \-BF as one of the runtime parameters of abc2midi.
500 .PP
501 The model divides a bar into equal segments. For each segment,
502 a loudness or MIDI velocity is specified and a duration multiplier
503 is specified. If a note falls into a specific segment, it assumes
504 the velocity of that segment and its duration is modified
505 accordingly. If the note overlaps more than one segment, then
506 the note assumes the average of those segment values.
507 .PP
508 The input file specifies the number of segments and the loudness
509 and duration multipliers for each segment. The file has the
510 following format. The first value is the number of segments and each line
511 specifies the velocity and duration multiplier of the specific
512 segment. The velocity is limited to 127 and the duration is a
513 decimal number. The note durations is modified by varying the
514 gap between notes, so it is not possible to extend a note. This
515 preserves the regular tempo of the music. The program scales,
516 the note duration indications by dividing it by the maximum
517 value which here is 1.4.
518
519 .PP
520 %%MIDI stressmodel n
521 .PP
522
523 where n is either 1 or 2, selects the stress model implementation.
524
525 .PP
526 other %%MIDI commands such as bendvelocity, bendstring,
527 controlstring have been introduced recently and are described
528 in the file abcguide.txt.
529
530
531
532 .SH "COMPATIBILITY WITH DRAFT STANDARD 2.0"
533
534 .PP
535 The proposed standard introduces a new copyright field
536 using the syntax
537
538 .PP
539 %%abc-copyright (c) Copyright John Smith 2003
540
541 .PP
542 Abc2midi now inserts this in the MIDI file in the form of a
543 metatext copyright tag. Changes were made to the event_specific
544 function in store.c to process the copyright information. It
545 is also copied into the Karaoke track (if it is created) as
546 as @T field.
547
548 .PP
549
550
551 .SH SEE ALSO
552 abc2ps(1), midi2abc(1), yaps(1).
553 .SH AUTHOR
554 James Allwright <[email protected]>
555 .SH SUPPORTED
556 by Seymour Shlien <[email protected]>
557 .SH VERSION
558 This man page describes abc2midi version 2.27 June 25 2006.
559 .SH COPYRIGHT
560 Copyright 1999 James Allwright
561 .PP
562 abc2midi is supplied "as is" without any warranty. It
563 is free software and can be used, copied, modified and
564 distributed without fee under the terms of the GNU General
565 Public License.
566 .PP
567 More complete documentation may be found in abcguide.txt
568 which comes with the abcMIDI distribution.