.. _moduleBraille.translate:

music21.braille.translate
=========================

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. Edit the .py file directly

.. module:: music21.braille.translate


Methods for exporting music21 data as braille.


This module was made in consultation with the manual "Introduction to Braille
Music Transcription, Second Edition" by Mary Turner De Garmo, 2005. It is
available from the Library of Congress `here <http://www.loc.gov/nls/music/>`_,
and will henceforth be referred to as BMTM.


The most important method, and the only one that is needed to translate music
into braille, is :meth:`~music21.braille.translate.objectToBraille`. This method,
as well as the others, accept keyword arguments that serve to modify the output.
If no keyword arguments are needed, then using the method is equivalent to
calling :meth:`~music21.base.Music21Object.show` on the music.


Keywords:


* **inPlace** (False): If False, then :meth:`~music21.stream.Stream.makeNotation` is called
  on all :class:`~music21.stream.Measure`, :class:`~music21.stream.Part`, and
  :class:`~music21.stream.PartStaff` instances. Copies of those objects are then
  used to transcribe the music. If True, the transcription is done "as is."
  This is useful for strict transcription because sometimes :meth:`~music21.stream.Stream.makeNotation`
  introduces some unwanted artifacts in the music. However, the music needs
  to be organized into measures for transcription to work.
* **debug** (False): If True, a braille-english representation of the music is returned. Useful
  for knowing how the music was interpreted by the braille transcriber.


The rest of the keywords are segment keywords. A segment is "a group of measures occupying
more than one braille line." Music is divided into segments so as to "present the music to
the reader in a meaningful manner and to give him convenient reference points to use in
memorization" (BMTM, 71). Some of these keywords are changed automatically in context.


* **cancelOutgoingKeySig** (True): If True, whenever a key signature change is encountered, the new
  signature should be preceded by the old one.
* **descendingChords** (True): If True, then chords are spelled around the highest note. If False,
  then chords are spelled around the lowest note. This keyword is overriden by any valid clefs
  present in the music.
* **dummyRestLength** (None) For a given positive integer n, adds n "dummy rests" near the beginning
  of a segment. Designed for test purposes, as the rests are used to demonstrate measure division at
  the end of braille lines.
* **maxLineLength** (40): The maximum amount of braille characters that should be present in a line of braille.
* **segmentBreaks** ([]): A list consisting of (measure number, offset start) tuples indicating where the
  music should be broken into segments.
* **showClefSigns** (False): If True, then clef signs are displayed. Since braille does not use clefs and
  staves to represent music, they would instead be shown for referential or historical purposes.
* **showFirstMeasureNumber** (True): If True, then a measure number is shown following the heading
  (if applicable) and preceding the music.
* **showHand** (None): If set to "right" or "left", the corresponding hand sign is shown before the music. In
  keyboard music, the hand signs are shown automatically.
* **showHeading** (True): If True, then a braille heading is created above the initial segment. A heading consists
  of an initial :class:`~music21.key.KeySignature`, :class:`~music21.meter.TimeSignature`,
  :class:`~music21.tempo.TempoText`, and :class:`~music21.tempo.MetronomeMark`, or any subset thereof. The heading
  is centered above the music automatically.
* **showLongSlursAndTiesTogether** (False), **showShortSlursAndTiesTogether** (False): If False, then the slur on
  either side of the phrase is reduced by the amount that ties are present. If True, then slurs and ties are shown
  together (i.e. the note can have both a slur and a tie).
* **slurLongPhraseWithBrackets** (True): If True, then the slur of a long phrase (4+ consecutive notes) is brailled
  using the bracket slur. If False, the double slur is used instead.
* **suppressOctaveMarks** (True): If True, then all octave marks are suppressed. Designed for test purposes, as
  octave marks were not presented in BMTM until Chapter 7.
* **upperFirstInNoteFingering** (True): If True, then whenever there is a choice fingering (i.e. 5|4), the upper
  number is transcribed before the lower number. If False, the reverse is the case.




.. function:: objectToBraille(music21Obj, **keywords)



    Translates an arbitrary object to braille.



    >>> from music21.braille import translate
    >>> from music21 import tinyNotation
    >>> samplePart = tinyNotation.TinyNotationStream("C4 D16 E F G# r4 e2.", "3/4")
    >>> samplePart.show()





        .. image:: images/objectToBraille.*
                :width: 700





    >>> print translate.objectToBraille(samplePart)
    ⠀⠀⠀⠀⠀⠀⠀⠼⠉⠲⠀⠀⠀⠀⠀⠀⠀
    ⠼⠁⠀⠸⠹⠵⠋⠛⠩⠓⠧⠀⠐⠏⠄⠣⠅


    For normal users, you'll just call this, which starts a text editor:




    >>> samplePart.show('braille')
    ⠀⠀⠀⠀⠀⠀⠀⠼⠉⠲⠀⠀⠀⠀⠀⠀⠀
    ⠼⠁⠀⠸⠹⠵⠋⠛⠩⠓⠧⠀⠐⠏⠄⠣⠅


    Other examples:




    >>> from music21 import note
    >>> sampleNote = note.Note("C3")
    >>> print translate.objectToBraille(sampleNote)
    ⠸⠹
    ⁠ 
    >>> from music21 import dynamics
    >>> sampleDynamic = dynamics.Dynamic("fff")
    >>> print translate.objectToBraille(sampleDynamic)
    ⠜⠋⠋⠋



.. function:: keyboardPartsToBraille(music21PartStaffUpper, music21PartStaffLower, **keywords)


    Translates two :class:`~music21.stream.Part` instances to braille, an upper part and a lower
    part. Assumes that the two parts are aligned and well constructed. Bar over bar format is used.



.. function:: measureToBraille(music21Measure, **keywords)


    Translates a :class:`~music21.stream.Measure` to braille.



.. function:: metadataToString(music21Metadata)




    >>> from music21.braille import translate
    >>> from music21 import corpus
    >>> corelli = corpus.parse("corelli")
    >>> corelli[0].__class__
    <class 'music21.metadata.Metadata'>
    >>> print translate.metadataToString(corelli[0])
    Title: Church Sonatas, Op. 3: Sonata I
    Movement Name: [Movement 1]
    Number: 3
    Movement Number: 1



.. function:: opusToBraille(music21Opus, **keywords)


    Translates an :class:`~music21.stream.Opus` to braille.



.. function:: partToBraille(music21Part, **keywords)


    Translates a :class:`~music21.stream.Part` to braille.



.. function:: scoreToBraille(music21Score, **keywords)


    Translates a :class:`~music21.stream.Score` to braille.



.. function:: streamToBraille(music21Stream, **keywords)


    Translates a :class:`~music21.stream.Stream` to braille.



