# ly.pitch package

## Module contents

Pitch manipulation.

class `ly.pitch.``LanguageName`

  Bases: `ly.lex._token.Token`

  A Token that denotes a language name.

class `ly.pitch.``Pitch`(note=0, alter=0, octave=0, accidental=u'', octavecheck=None)

  Bases: `object`

  A pitch with note, alter and octave attributes.

  Attributes may be manipulated directly.

  classmethod `c0`()

    Returns a pitch c.

  classmethod `c1`()

    Returns a pitch c’.

  `copy`()

    Returns a new instance with our attributes.

  classmethod `f0`()

    Return a pitch f.

  `makeAbsolute`(lastPitch)

    Makes ourselves absolute, i.e. sets our octave from lastPitch.

  `makeRelative`(lastPitch)

    Makes ourselves relative, i.e. changes our octave from lastPitch.

  `output`(language=u'nederlands')

    Returns our string representation.

class `ly.pitch.``PitchIterator`(source, language=u'nederlands')

  Bases: `object`

  Iterate over notes or pitches in a source.

  `pitches`()

    Yields all tokens, but collects Note and Octave tokens.

    When a Note is encountered, also reads octave and octave check and then a Pitch is yielded instead of the tokens.

  `position`(t)

    Returns the cursor position for the given token or Pitch.

  `read`(token)

    Reads the token and returns (note, alter) or None.

  `setLanguage`(lang)

    Changes the pitch name language to use.

    Called internally when language or include tokens are encountered with a valid language name/file.

    Sets the language attribute to the language name and the read attribute to an instance of ly.pitch.PitchReader.

  `tokens`()

    Yield all the tokens from the source, following the language.

  `write`(pitch, language=None)

    Output a changed Pitch.

    The Pitch is written in the Source’s document.

    To use this method reliably, you must instantiate the PitchIterator with a ly.document.Source that has tokens_with_position set to True.

exception `ly.pitch.``PitchNameNotAvailable`(language)

  Bases: `exceptions.Exception`

  Exception raised when there is no name for a pitch.

  Can occur when translating pitch names, if the target language e.g. does not have quarter-tone names.

class `ly.pitch.``PitchReader`(names, accs, replacements=())

  Bases: `object`

class `ly.pitch.``PitchWriter`(names, accs, replacements=())

  Bases: `object`

  `language` = u'unknown'

`ly.pitch.``octaveToNum`(octave)

  Converts string octave to an integer:

  “” -> 0 ; ”,” -> -1 ; “’‘’” -> 3 ; etc.

`ly.pitch.``octaveToString`(octave)

  Converts numeric octave to a string with apostrophes or commas.

  0 -> “” ; 1 -> “’” ; -1 -> ”,” ; etc.

`ly.pitch.``pitchReader`(language)

  Returns a PitchReader for the specified language.

`ly.pitch.``pitchWriter`(language)

  Returns a PitchWriter for the specified language.

## Submodules

## ly.pitch.abs2rel module

Convert absolute music to relative music.

`ly.pitch.abs2rel.``abs2rel`(cursor, language=u'nederlands', startpitch=True, first_pitch_absolute=False)

  Converts pitches from absolute to relative.

  language: language to start reading pitch names in

  startpitch: if True, write a starting pitch before the opening bracket of
    a relative expression.
  first_pitch_absolute: this option only makes sense when startpitch is False.

    If first_pitch_absolute is True, the first pitch of a relative expression is written as absolute. This mimics the behaviour of LilyPond >= 2.18. (In fact, the starting pitch is then assumed to be f.)

    If False, the first pitch is written as relative to c’ (LilyPond < 2.18 behaviour).

  Existing relative expressions are not changed.

## ly.pitch.rel2abs module

Convert relative music to absolute music.

`ly.pitch.rel2abs.``rel2abs`(cursor, language=u'nederlands', first_pitch_absolute=False)

  Converts pitches from relative to absolute.

  language: language to start reading pitch names in

  first_pitch_absolute: if True, the first pitch of a relative expression

    is regarded as absolute, when no starting pitch was given. This mimics the behaviour of LilyPond >= 2.18. (In fact, the starting pitch is then assumed to be f.)

    If False, the starting pitch, when not given, is assumed to be c’ (LilyPond < 2.18 behaviour).

## ly.pitch.translate module

Translating the language of pitch names

`ly.pitch.translate.``insert_language`(document, language, version=None)

  Inserts a language command in the document.

  The command is inserted at the top or just below the version line.

  If the LilyPond version specified < (2, 13, 38), the include command is used, otherwise the newer language command.

`ly.pitch.translate.``translate`(cursor, language, default_language=u'nederlands')

  Changes the language of the pitch names.

  May raise ly.pitch.PitchNameNotAvailable if the current pitch language has no quarter tones.

  Returns True if there also was a language or include language command that was changed. If not and the cursor specified only a part of the document, you could warn the user that a language or include command should be added to the document. Or you could call insert_language to add a language command to the top of the document.

## ly.pitch.transpose module

Transposing music.

class `ly.pitch.transpose.``ModalTransposer`(numSteps=1, scaleIndex=0)

  Bases: `object`

  Transpose pitches by number of steps within a given scale.

  Instantiate with the number of steps (+/-) in the scale to transpose by, and a mode index. The mode index is the index of the major scale in the circle of fifths (C Major = 0).

  static `getKeyIndex`(text)

    Get the index of the key in the circle of fifths.

    ‘Cb’ returns 0, ‘C’ returns 7, ‘B#’ returns 14.

  `transpose`(pitch)

class `ly.pitch.transpose.``ModeShifter`(key, scale)

  Bases: `ly.pitch.transpose.Transposer`

  Shift pitches to optional mode/scale.

  The scale should be formatted in analogy to the scale in the Transposer parent class.

  The key should be an instance of ly.pitch.Pitch.

  `closestPitch`(pitch)

    Get closest pitch from scale.

    If only one scale note with the same base step exist that is returned. Otherwise the closest is calculated.

  `transpose`(pitch)

    Shift to closest scale pitch if not already in scale.

class `ly.pitch.transpose.``Simplifier`(scale=None)

  Bases: `ly.pitch.transpose.Transposer`

  Make complicated accidentals simpler by substituting naturals where possible.

  `transpose`(pitch)

class `ly.pitch.transpose.``Transposer`(fromPitch, toPitch, scale=None)

  Bases: `object`

  Transpose pitches.

  Instantiate with a from- and to-Pitch, and optionally a scale. The scale is a list with the pitch height of the unaltered step (0 .. 6). The default scale is the normal scale: C, D, E, F, G, A, B.

  `scale` = (0, 1, 2, Fraction(5, 2), Fraction(7, 2), Fraction(9, 2), Fraction(11, 2))
  `transpose`(pitch)

`ly.pitch.transpose.``transpose`(cursor, transposer, language=u'nederlands', relative_first_pitch_absolute=False)

  Transpose pitches using the specified transposer.

  If relative_first_pitch_absolute is True, the first pitch in a relative expression is considered to be absolute, when a startpitch is not given. This is LilyPond >= 2.18 behaviour.

  If relative_first_pitch_absolute is False, the first pitch in a relative expression is considered to be relative to c’, is no startpitch is given. This is LilyPond < 2.18 behaviour.

  Currently, relative_first_pitch_absolute defaults to False.