/ 
App-MusicTools-1.38
River stage one • 1 direct dependent • 1 total dependent
/ canonical

NAME

canonical - compute canon voices via the Music::Canon module

SYNOPSIS

$ canonical --contrary --retrograde exact c cis d
$ canonical --transpose=12 exact c ees g
$ canonical --raw --contrary exact 1 2 3

$ canonical modal --input=lydian --output=locrian c e g

Raw pitch numbers or lilypond note names (though only in the default "nederlands" language) are accepted. Consult the lilypond "Notation Reference" section "Note names in other languages" for the syntax.

DESCRIPTION

Command line interface to the mapping methods present in the Music::Canon module. Certain questions might be better answered by coding directly against Music::Canon; see the eg/ directory under the distribution of that Perl module for examples.

Note that input via the command line is handled differently from notes supplied via standard input; in the first case, all of the input is considered to be notes. In the second case, only the first column (delimited by a space) is considered to be note material, and the other columns should be passed through unchanged.

$ echo 42 cat | canonical exact --transpose=a
a cat

GLOBAL OPTIONS

This program currently supports the following global command line switches. These can also be specified to the underlying modes.

--contrary | -c | --nocontrary

Whether to compute the output line in contrary motion or not (default is not to).

--duration=value

Set the default duration for rhythm handling (4 by default). Rhythm handling should be transparent, though does not extend to tied notes, triplet groups, or grace notes.

--flats --noflats

Print notes with flats instead of sharps.

--help

Emits help and exits the program.

--map --nomap

Whether to show the original input pitch numbers or note names one per line alongside the corresponding output pitch number or note name. Disabled by default.

--raw --noraw

Whether to emit output in raw pitch numbers (default is to emit lilypond note names).

--relative=lilypond_note

Use relative mode in Music::LilyPondUtil and make the input notes relative to the specified note. Without this option, the assumption is that the lilypond input is specified in absolute form:

g d\'             # MIDI pitches 55 62 (absolute)
--rel=g\' g d\'   # MIDI pitches 67 74 (relative to g' or 67)
--retrograde | -r | --noretrograde

Whether to reverse the output phrase or not. (Default is not to.)

--transpose=pitch_or_lilypond_note | -t=...

Transpose to the first note of the output phrase by the specified amount in semitones (integer) or to the specified lilypond note name. (Default is no transposition.)

MODES

EXACT

Exact interval canon computation. No new options beyond the global ones listed above.

$ canonical exact --transpose=e c e g

Modal interval canon computation. In addition to the global options listed above, accepts:

--chrome=troolean

Chrome weighting. Default is 0, for proportional weighting. Negative or positive values use the literal chromatic offset from the input mode at the bottom or top of the appropriate interval in the output mode. See Music::Canon for details. The weighting only applies when the output scale has steps of three or more semitones (e.g. Hugarian minor, pentatonic scales, and so forth).

--endpitch=pitch_or_note | --ep=pitch_or_note

Sets the output mode starting pitch. Probably should also be called with --startpitch.

--input=scale_or_forte_number

Scale name (see Music::Scales) or Forte Number or interval list to use for the input. A colon delimits the ascending versus descending versions of the scale; commas delimit specific scale degrees. Examples:

--input=mm
--input=major:minor
--input=2,2,2,2,1:5-25

See Music::Canon for the algorithm that maps input to output mode.

--nos

Allow non-octave scales. Necessary if the scale intervals sum up to more than 12, or if scales repeat not at the usual 12-pitch octave point.

--output=scale_or_forte_number

Like --input, except for the output line.

--startpitch=pitch_or_note | --sp=pitch_or_note

Sets the input mode starting pitch via set_modal_pitches. Probably should also be called with --endpitch. Necessary if the phrase begins on a non-tonic scale degree, as otherwise the input mode will shift to be based on that now-the-tonic note.

--undef=string

String to use for notes or pitches that cannot be converted. If unset, defaults to x. For example, under contrary motion, using Major to Major scales, C to D via C sharp is impossible, as there is no space between C and B downwards in the output line for the chromatic C sharp:

$ canonical --relative=c modal --contrary --undef=OOPS c cis d
c OOPS b

Set this to r or s to have lilypond or ly-fu ignore the impossible note.

EXAMPLES

Fugue answers can readily be calculated with this program, for example to transpose to the key of the dominant (WTC II, Fugue 9 in E major).

$ canonical --rel=e modal --t=7 e1 fis2 a gis fis e4
b1 cis2 e dis cis b4

This handles the need to raise the leading tone of the key of the Dominant automatically where A needs to raise to A# (WTC I, Fugue 9 in E major).

$ canonical --rel=e\' modal --t=7 \
  r8 e8 fis4 r16 b,16 cis dis e dis e fis g
r8 b8 cis4 r16 fis,16 gis ais b ais b cis d

Or the need to raise both II and VII in the minor key (WTC I, Fugue 4 in C# minor).

$ canonical --rel=e\' modal --t=7 cis1 bis2 e dis1 cis4                    
gis1 g2 b ais1 gis4

Or even complicated things with chromatic alterations (WTC I, Fugue 14 in F# minor).

$ canonical --rel b modal --t=7 r4 fis gis a1 \
  gis8 ais b4 b ais8 gis ais bis cis4. b8 a8 cis b a gis2 fis
r4 cis dis e1 dis8 f fis4 fis f8 dis f g gis4. fis8 e8 gis fis e dis2 cis

If the phrase is not in, say, C-Major, be sure to use the --sp flag to indicate that. This following line transposes the result up by a major third:

$ canonical --flats modal --undef=r --rel=des --sp=des --transpose=4 \
  "des8 r des r des c16 bes aes8 ges aes8 ges16 f ees8 des8"

Complicated input may benefit from the use of standard input, as in this case canonical will only read pitch values from the first column of input, and will leave the rest unchanged. This would allow rhythmic, dynamics, or other metadata to pass through canonical unchanged, provided this information is not in the first column.

$ (echo 0 4. f; echo 2 8 p; echo 4 4 ff) | canonical -t c exact

Mapping may be used to construct hash lookup tables for given inputs, with suitable doctoring of the mapped data. This allows the use of pre- computed canonic mappings in other programming languages, for example.

$ canonical exact --relative=c --map 1 2 3 4
1 cis
2 d
3 dis
4 e
$ echo '(setf *h* (make-hash-table))' > x
$ canonical exact --relative=c --map 1 2 3 4 \
  | awk '{printf "(setf (gethash '\''%s *h*) '\''%s)\n", $1, $2}' >> x
$ clisp -repl x
[1]> (gethash 3 *h*)
dis ;
t
[2]>

FILES

A ZSH completion script is available in the zsh-compdef/ directory of the App::MusicTools distribution. Install this to a $fpath directory.

BUGS

Reporting Bugs

If the bug is in the latest version, send a report to the author. Patches that fix problems or add new features are welcome.

https://thrig.me/src/App-MusicTools.git

SEE ALSO

http://www.lilypond.org/ and in particular the Learning and Notation manuals should be consulted to understand lilypond note syntax. Or, use raw pitch numbers.

http://en.wikipedia.org/wiki/Forte_number

"The Technique of Canon" and "Foundation Studies in Fugue" by Hugo Norden.

Music::Canon, Music::LilyPondUtil, Music::Scales

COPYRIGHT

Copyright 2012 Jeremy Mates

This program is distributed under the (Revised) BSD License: http://www.opensource.org/licenses/BSD-3-Clause