NAME

atonal-util - routines for atonal composition and analysis

SYNOPSIS

Prime form and APIC vector for a pitch set:

  $ atonal-util basic --ly f fis c

Apply a series of transformations to a pitch set:

  $ cat rules
  retrograde
  invert 6
  transpose 1
  $ atonal-util recipe --file=rules 0 11 3
  4,8,7

Among many other options.

DESCRIPTION

Routines for atonal music composition and analysis, plus other random music theory related tasks. Global options and an operating mode should be supplied, followed by any mode specific arguments and a pitch set. Pitch sets can be read as arguments or from standard input; some modes require two pitch sets that must be supplied one per line on standard input.

The output will vary depending on the mode, and may include Cope tension numbers (average, min, max tension for the pitch set). Other programs should not be written to use this program, as the output may change. Use the underlying code or modules called by this program, as this program is mostly intended for interactive use.

OPTIONS

This script currently supports the following global command line switches:

--flats | --noflats

Uses flats instead of sharps in output (but only with --ly). Specify --noflats to disable flats, in the event you have an alias that sets --flats by default. There is currently no --sharps option, sorry.

--help

Displays help and exits.

--listmodes

Displays supported operation modes.

--ly

Show lilypond note names instead of raw pitch numbers.

--scaledegrees

Adjust the number of scale degrees (default: 12).

MODES

Most all modes accept a pitch set (list of raw pitch numbers (0..number of scale degrees) or lilypond note names (bis, c, des, etc.) either on the command line or via standard input, though there are exceptions.

The global --ly and --flats can be specified as options to modes that emit pitches. See also Music::AtonalUtil for more documentation.

basic pitch_set

Shows the prime_form and interval_class_content.

circular_permute

See Music::AtonalUtil.

combos freq1 freq2 [freq3 ...]

Shows the combination tones of the input frequencies (or with the optional --pitches flag, MIDI pitch numbers or lilypond note names) relative to the first listed frequency. The delta of equal temperament tuning from the actual combination tone is also shown.

  $ atonal-util --ly combos 220 440
  $ atonal-util --ly combos --pitches "c' g'"

https://en.wikipedia.org/wiki/Combination_tone

complement

See Music::AtonalUtil.

equivs

Equivalents under transposition and inverse transposition. An optional axis of inversion (default: 0, though some forms use 6) can be supplied.

findall [--exclude=p1[,p2]] [--fn=nums] [--root=pitch] pitches

Find all Forte pitch sets in which the given pitches exist. Like findin, except iterates over all Forte pitch sets instead of just the given one.

With --exclude, omits results containing the listed pitches. With -- fn, limits the search to the mentioned forte number prefixes (the number of pitches in the set). With --root, limits matches to those with the named root pitch.

  $ atonal-util findall --root=c --fn=4-5 c e g bes

Tensions may be lower than expected if the root pitch creates an open position chord versus a closed position of that set.

findin [--exclude=p1[,p2]] [--root=pitch] --pitchset=base_set pitches

Answers questions such as, given a base pitch set of [0,3,7], and the notes d and bes, what pitch sets (via any transpose or transpose_invert operation) complete the base pitch set. With -- exclude, omits results containing the listed pitches. With --root, limits matches to those with the named root pitch.

  $ atonal-util findin --exclude=c,ees --pitchset=5-25 d fis a

Tensions may be lower than expected if the root pitch creates an open position chord versus a closed position of that set.

fnums

Return a list of all Forte Numbers and corresponding pitch sets (and their interval_class_content), plus average tension, min tension, and max tension via Music::Tension::Cope.

forte2pcs forte_number

Given a Forte Number, return the corresponding pitch set.

freq2pitch frequencies...|-

Converts the listed frequencies (in Hz) into the closest MIDI note numbers. Reads frequencies line-per-line from standard input if the only frequency given is a -. With --ly also converts the MIDI note number to a lilypond note name.

interval_class_content

See Music::AtonalUtil.

intervals2pcs

See Music::AtonalUtil.

invariance_matrix

See Music::AtonalUtil.

invariants

Returns list of transpose or transpose_invert operations that have invariant pitches with the supplied pitch set, along with which pitches have not varied.

invert [--axis=inversion_axis]

See Music::AtonalUtil. Default axis is around 0.

ly2pitch [--relative=note] [-|notes...]

Converts lilypond note names to pitch numbers, via absolute mode by default. The input unlike in other modes may be quoted to protect the lilypond ' register change from shell quoting rules. Example usages:

  $ echo c e g | atonal-util ly2pitch -
  $ atonal-util ly2pitch "c d' e f, g"
  $ atonal-util ly2pitch --relative=a\' a c d b
multiply

See Music::AtonalUtil.

normal_form

See Music::AtonalUtil.

pcs2forte

Given a pitch set, returns the corresponding Forte Number, if any.

pcs2intervals

See Music::AtonalUtil.

pitch2freq pitches...|-

Converts pitches to a frequency (in Hz) using the standard MIDI note number conversion equation. Reads pitches line-by-line from standard input if only pitch given is -.

pitch2intervalclass pitch

See Music::AtonalUtil.

pitch2ly [--mode=relative|absolute] pitches...|-

Converts pitches (integers) to lilypond note names. Reads pitches line-by- line from standard input if only pitch given is -. Use the --mode option to specify relative or absolute conversion.

prime_form

See Music::AtonalUtil.

recipe --file=recipefile

Apply a series of named operations from a batch file to a pitch set, for example:

  retrograde
  invert 6
  transpose 1
retrograde

See Music::AtonalUtil.

rotate [--rotate=integer]

See Music::AtonalUtil.

set_complex

See Music::AtonalUtil.

subsets [--length=integer]

See Music::AtonalUtil. The length, if supplied, must be a magnitude equal to or less than the number of pitches supplied, and probably also 2 or higher.

tcis

See Music::AtonalUtil.

tcs

See Music::AtonalUtil.

tension pitch_set

Returns the average, min, max, and tension values for all the tensions in the passed pitch set, from the first notes in the set up to the last. (Via Music::Tension::Cope.)

transpose --transpose=integer_or_note

See Music::AtonalUtil. Transposes the supplied pitches by the specified integer (by default 0, or a no-op), or to the specified note.

  $ atonal-util transpose --transpose=4 --ly c e g
  e gis b
  $ atonal-util transpose --transpose=e --ly c e g
  e gis b

Register aware transpositions are possible with the canonical tool of the App::MusicTools module, using the exact mode and --transpose option.

transpose_invert --transpose=integer_or_note [--axis=integer_or_note]

See Music::AtonalUtil. Transposes supplied pitch set by the specified integer, or to the specified note. Default axis for inversion is 0 (c).

variances

Accepts two pitch sets, one per line, via standard input.

zrelation

Accepts two pitch sets, one per line, via standard input.

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.

http://github.com/thrig/App-MusicTools

Known Issues

Poor naming conventions and standards of underlying music theory and any associated mistakes in understanding thereof by the author.

SEE ALSO

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

Music::AtonalUtil, Music::LilyPondUtil, Music::Tension::Cope

AUTHOR

Jeremy Mates

COPYRIGHT

Copyright (C) 2012-2013 by Jeremy Mates

This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.16 or, at your option, any later version of Perl 5 you may have available.