ly.pitch package
****************


Module contents
===============

Pitch manipulation.

class ly.pitch.LanguageName

   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.
