.. _moduleBraille.translate:

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

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

.. module:: music21.braille.translate

Objects for exporting music21 data as braille. 


.. function:: instrumentToBraille(sampleInstrument=)


.. function:: keySigToBraille(sampleKeySig=sharps 1, mode None)

    Takes in a :class:`~music21.key.KeySignature` and returns its representation in braille as a string in utf-8 unicode. 

    >>> from music21.braille import translate
    >>> from music21 import key
    >>> ksFourSharps = key.KeySignature(4)
    >>> translate.keySigToBraille(ksFourSharps)
    u'\u283c\u2819\u2829' 

.. function:: measureToBraille(sampleMeasure=<music21.stream.Measure 0 offset=0.0>, showLeadingOctave=True)

    Method for translating a :class:`~music21.stream.Measure` into braille. Currently, only translates :class:`~music21.note.Note` and :class:`~music21.note.Rest` objects. 

    If showLeadingOctave is set to True, the first note of the measure carries an octave designation. Other notes in the measure carry an octave designation only if applicable. (See :meth:`~music21.braille.translate.showOctaveWithNote`.) 

.. function:: metronomeMarkToBraille(sampleMetronomeMark=<music21.tempo.MetronomeMark Half=80>)


.. function:: noteToBraille(sampleNote=<music21.note.Note C>, showOctave=True)

    Given a :class:`~music21.note.Note`, returns the appropriate braille characters as a string in utf-8 unicode. 

    The format for note display in braille is the accidental (if necessary) + octave (if necessary) + pitch name with length. 

    If the note has an :class:`~music21.pitch.Accidental`, the accidental is always displayed unless its :attr:`~music21.pitch.Accidental.displayStatus` is set to False. The octave of the note is only displayed if showOctave is set to True. 

    

    >>> from music21.braille import translate
    >>> from music21 import note
    >>> C4 = note.Note('C4')
    >>> translate.noteToBraille(sampleNote = C4)
    u'\u2810\u2839' 
    >>> C4.quarterLength = 2.0
    >>> translate.noteToBraille(sampleNote = C4)
    u'\u2810\u281d' 
    >>> Ds4 = note.Note('D#4')
    >>> translate.noteToBraille(sampleNote = Ds4)
    u'\u2829\u2810\u2831' 
    >>> translate.noteToBraille(sampleNote = Ds4, showOctave = False)
    u'\u2829\u2831' 
    >>> Ds4.pitch.setAccidentalDisplay(False)
    >>> translate.noteToBraille(sampleNote = Ds4)
    u'\u2810\u2831' 
    >>> A2 = note.Note('A2')
    >>> A2.quarterLength = 3.0
    >>> translate.noteToBraille(sampleNote = A2)
    u'\u2818\u280e\u2804' 

.. function:: partToBraille(samplePart=<music21.stream.Part 69855760>)

    Given a :class:`~music21.stream.Part`, returns the appropriate braille characters as a string in utf-8 unicode. 

    A thing to keep in mind: there is a 40 braille character limit per line. All spaces are filled in with empty six-cell braille characters. 

.. function:: restToBraille(sampleRest=<music21.note.Rest rest>)

    Given a :class:`~music21.note.Rest`, returns the appropriate braille characters as a string in utf-8 unicode. 

    Currently, only supports single rests with or without dots. Compound rests are not supported. 

    >>> from music21.braille import translate
    >>> from music21 import note
    >>> dottedQuarter = note.Rest(quarterLength = 1.5)
    >>> translate.restToBraille(dottedQuarter)
    u'\u2827\u2804' 
    >>> whole = note.Rest(quarterLength = 4.0)
    >>> translate.restToBraille(whole)
    u'\u280d' 
    >>> quarterPlusSixteenth = note.Rest(quarterLength = 1.25)
    >>> translate.restToBraille(quarterPlusSixteenth)
    Traceback (most recent call last): 
    BrailleTranslateException: Rest duration cannot be translated to braille. 

.. function:: showOctaveWithNote(previousNote=<music21.note.Note C>, currentNote=<music21.note.Note D>)

    Determines whether a currentNote carries an octave designation in relation to a previousNote. 

    Rules: 

    * If currentNote is found within a second or third of previousNote, currentNote does not carry an octave designation. 

    * If currentNote is found a sixth or more away from previousNote, currentNote does carry an octave designation. 

    * If currentNote is found within a fourth or fifth of previousNote, currentNote carries an octave designation if and only if currentNote and previousNote are not found in the same octave. 

.. function:: tempoTextToBraille(sampleTempoText=<TempoText adagio>)


.. function:: timeSigToBraille(sampleTimeSig=3/4)

    Takes in a :class:`~music21.meter.TimeSignature` and returns its representation in braille as a string in utf-8 unicode. 

    The format for a numerical time signature in braille is the number symbol + beat count as a braille number + beat units, also a braille number but brought down in the cell. 

    >>> from music21.braille import translate
    >>> from music21 import meter
    >>> translate.timeSigToBraille(sampleTimeSig = meter.TimeSignature('3/4'))
    u'\u283c\u2809\u2832' 
    >>> translate.timeSigToBraille(sampleTimeSig = meter.TimeSignature('12/8'))
    u'\u283c\u2801\u2803\u2826' 
    >>> translate.timeSigToBraille(sampleTimeSig = meter.TimeSignature('4/4'))
    u'\u283c\u2819\u2832' 

.. function:: wordStringToBraille(sampleWordString=Lento assai, cantante e tranquillo, returnSplit=False)


.. function:: wordToBraille(sampleWord=andante)

    

    >>> from music21.braille import translate

