# ly.pitch package

## Module contents

Pitch manipulation.

class ly.pitch.LanguageName(string, pos)

  Bases: `ly.lex._token.Token`

  A Token that denotes a language name.

  end
  pos

class ly.pitch.Pitch(note=0, alter=0, octave=0, accidental='', 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='nederlands')

    Returns our string representation.

class ly.pitch.PitchIterator(source, language='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: `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 = '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='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='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='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='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.