.. _moduleBraille.basic:

music21.braille.basic
=====================

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

.. module:: music21.braille.basic



.. function:: barlineToBraille(music21Barline)


    Takes in a :class:`~music21.bar.Barline` and returns its representation
    as a braille string in UTF-8 unicode.


    .. note:: Only double barlines and final barlines can be transcribed.



    >>> from music21.braille import basic
    >>> from music21 import bar
    >>> doubleBarline = bar.Barline('double')
    >>> print basic.barlineToBraille(doubleBarline)
    ⠣⠅⠄
    >>> finalBarline = bar.Barline('final')
    >>> print basic.barlineToBraille(finalBarline)
    ⠣⠅
    >>> heavyBarline = bar.Barline('heavy')
    >>> print basic.barlineToBraille(heavyBarline)
    ⠜⠦



.. function:: brailleAsciiToBrailleUnicode(brailleAscii)


    translates a braille ASCII string to braille UTF-8 unicode, which
    can then be displayed on-screen in braille on compatible systems.


    .. note:: The method works by corresponding ASCII symbols to braille
        symbols in a very direct fashion. It is not a translator from plain
        text to braille, because ASCII symbols may not correspond to their
        equivalents in braille. For example, a literal period is a 4 in
        braille ASCII. Also, all letters are translated into their lowercase
        equivalents, and any capital letters are indicated by preceding them
        with a comma.




    >>> from music21.braille import basic
    >>> from music21 import tempo
    >>> t1 = basic.brailleAsciiToBrailleUnicode(",ANDANTE ,MAESTOSO4")
    >>> t2 = basic.tempoTextToBraille(tempo.TempoText("Andante Maestoso"))
    >>> t1 == t2
    True



.. function:: brailleUnicodeToBrailleAscii(brailleUnicode)


    translates a braille UTF-8 unicode string into braille ASCII,
    which is the format compatible with most braille embossers.


    .. note:: The method works by corresponding braille symbols to ASCII symbols.
        The table which corresponds said values can be found
        `here <http://en.wikipedia.org/wiki/Braille_ASCII#Braille_ASCII_values>`_.
        Because of the way in which the braille symbols translate2, the resulting
        ASCII string will look like gibberish. Also, the eighth-note notes in braille
        music are one-off their corresponding letters in both ASCII and written braille.
        The written D is really a C eighth-note, the written E is really a
        D eighth note, etc.




    >>> from music21.braille import basic
    >>> from music21 import note
    >>> basic.brailleUnicodeToBrailleAscii(u'\u2800')
    ' '
    >>> Cs8 = note.Note('C#4', quarterLength = 0.5)
    >>> Cs8_braille = basic.noteToBraille(Cs8)
    >>> basic.brailleUnicodeToBrailleAscii(Cs8_braille)
    '%"D'
    >>> Eb8 = note.Note('E-4', quarterLength = 0.5)
    >>> Eb8_braille = basic.noteToBraille(Eb8)
    >>> basic.brailleUnicodeToBrailleAscii(Eb8_braille)
    '<"F'



.. function:: brailleUnicodeToSymbols(brailleUnicode, filledSymbol='o', emptySymbol='·')


    translates a braille unicode string into symbols (ASCII or UTF-8).



.. function:: chordToBraille(music21Chord, descending=True, showOctave=True)


    Takes in a :class:`~music21.chord.Chord` and returns its representation
    as a braille string in UTF-8 unicode.


    In braille, only one pitch of a chord is brailled, with the rest represented
    as numeric intervals from that one pitch. If descending is True, the highest
    (sounding) pitch is brailled, and intervals are labeled in descending order;
    if descending is False, the lowest (sounding) pitch is brailled, and the
    intervals are labeled in ascending order. Convention dictates that chords
    found in the treble clef are brailled descending, and those found in the bass
    clef are brailled ascending.


    If showOctave is True, the octave of the brailled pitch is shown. Other
    octave marks are shown in context relative to the brailled pitch.



    >>> from music21.braille import basic
    >>> from music21 import chord
    >>> gMajorTriadA = chord.Chord(['G4','B4','D5','G5'], quarterLength = 4.0)
    >>> print basic.chordToBraille(gMajorTriadA, descending = True)
    ⠨⠷⠼⠴⠤
    >>> gMajorTriadB = chord.Chord(['G2','B2','D3','G3'], quarterLength = 4.0)
    >>> print basic.chordToBraille(gMajorTriadB, descending = False)
    ⠘⠷⠬⠔⠤
    >>> gMajorTriadRightHand = chord.Chord(['D4','B4','G5'], quarterLength = 4.0)
    >>> print basic.chordToBraille(gMajorTriadRightHand, descending = True)
    ⠨⠷⠴⠼
    >>> gMajorTriadLeftHand = chord.Chord(['G2','D3','B3'], quarterLength = 4.0)
    >>> print basic.chordToBraille(gMajorTriadLeftHand, descending = False)
    ⠘⠷⠔⠬
    >>> cMajorTriadRightHand = chord.Chord(['C4','E5'], quarterLength = 4.0)
    >>> print basic.chordToBraille(cMajorTriadRightHand, descending = True)
    ⠨⠯⠐⠬
    >>> cMajorTriadLeftHand = chord.Chord(['C2','E3'], quarterLength = 4.0)
    >>> print basic.chordToBraille(cMajorTriadLeftHand, descending = False)
    ⠘⠽⠸⠬
    >>> cMajorSeventhRightHand = chord.Chord(['C6','E5','B4'], quarterLength = 4.0)
    >>> print basic.chordToBraille(cMajorSeventhRightHand, descending = True)
    ⠰⠽⠴⠌
    >>> cMajorSeventhLeftHand = chord.Chord(['G2','E3','E4'], quarterLength = 4.0)
    >>> print basic.chordToBraille(cMajorSeventhLeftHand, descending = False)
    ⠘⠷⠴⠐⠴



.. function:: clefToBraille(music21Clef)


    Takes in a :class:`~music21.clef.Clef` and returns its representation
    as a braille string in UTF-8 unicode.

    Only :class:`~music21.clef.TrebleClef`, :class:`~music21.clef.BassClef`, :class:`~music21.clef.AltoClef`, and :class:`~music21.clef.TenorClef` can be transcribed.




    >>> from music21.braille import basic
    >>> from music21 import clef
    >>> trebleClef = clef.TrebleClef()
    >>> print basic.clefToBraille(trebleClef)
    ⠜⠌⠇
    >>> bassClef = clef.BassClef()
    >>> print basic.clefToBraille(bassClef)
    ⠜⠼⠇
    >>> altoClef = clef.AltoClef()
    >>> print basic.clefToBraille(altoClef)
    ⠜⠬⠇
    >>> tenorClef = clef.TenorClef()
    >>> print basic.clefToBraille(tenorClef)
    ⠜⠬⠐⠇
    >>> sopranoClef = clef.SopranoClef()
    >>> print basic.clefToBraille(sopranoClef)
    ⠜⠦



.. function:: dynamicToBraille(music21Dynamic, precedeByWordSign=True)


    Takes in a :class:`~music21.dynamics.Dynamic` and returns its
    :attr:`~music21.dynamics.Dynamic.value` as a braille string in
    UTF-8 unicode.


    If precedeByWordSign is True, the value is preceded by a word
    sign (⠜).




    >>> from music21.braille import basic
    >>> from music21 import dynamics
    >>> print basic.dynamicToBraille(dynamics.Dynamic('f'))
    ⠜⠋
    >>> print basic.dynamicToBraille(dynamics.Dynamic('pp'))
    ⠜⠏⠏



.. function:: instrumentToBraille(music21Instrument)


    Takes in a :class:`~music21.instrument.Instrument` and returns its "best name"
    as a braille string in UTF-8 unicode.




    >>> from music21.braille import basic
    >>> from music21 import instrument
    >>> print basic.instrumentToBraille(instrument.Bassoon())
    ⠠⠃⠁⠎⠎⠕⠕⠝
    >>> print basic.instrumentToBraille(instrument.BassClarinet())
    ⠠⠃⠁⠎⠎⠀⠉⠇⠁⠗⠊⠝⠑⠞



.. function:: keySigToBraille(music21KeySignature, outgoingKeySig=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 basic
    >>> from music21 import key
    >>> print basic.keySigToBraille(key.KeySignature(4))
    ⠼⠙⠩


    If given an old key signature, then its cancellation will be applied before
    and in relation to the new key signature.




    >>> print basic.keySigToBraille(key.KeySignature(0), outgoingKeySig = key.KeySignature(-3))
    ⠡⠡⠡



.. function:: metronomeMarkToBraille(music21MetronomeMark)


    Takes in a :class:`~music21.tempo.MetronomeMark` and returns it as a braille string in UTF-8 unicode.
    The format is (note C with duration of metronome's referent)(metronome symbol)(number/bpm).



    >>> from music21.braille import basic
    >>> from music21 import tempo
    >>> print basic.metronomeMarkToBraille(tempo.MetronomeMark(number = 80, referent = note.HalfNote()))
    ⠝⠶⠼⠓⠚
    >>> print basic.metronomeMarkToBraille(tempo.MetronomeMark(number = 135, referent = note.Note(quarterLength = 0.5)))
    ⠙⠶⠼⠁⠉⠑



.. function:: noteToBraille(music21Note, showOctave=True, upperFirstInFingering=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 basic
    >>> from music21 import note
    >>> C4 = note.Note('C4')
    >>> print basic.noteToBraille(C4)
    ⠐⠹
    >>> C4.quarterLength = 2.0
    >>> print basic.noteToBraille(C4)
    ⠐⠝
    >>> Ds4 = note.Note('D#4')
    >>> print basic.noteToBraille(Ds4)
    ⠩⠐⠱
    >>> print basic.noteToBraille(Ds4, showOctave = False)
    ⠩⠱
    >>> Ds4.pitch.setAccidentalDisplay(False)
    >>> print basic.noteToBraille(Ds4)
    ⠐⠱
    >>> A2 = note.Note('A2')
    >>> A2.quarterLength = 3.0
    >>> print basic.noteToBraille(A2)
    ⠘⠎⠄



.. function:: numberToBraille(sampleNumber, withNumberSign=True)


    Transcribes a number to UTF-8 braille.



    >>> from music21.braille import basic
    >>> print basic.numberToBraille(12)
    ⠼⠁⠃
    >>> print basic.numberToBraille(7)
    ⠼⠛
    >>> print basic.numberToBraille(37)
    ⠼⠉⠛



.. function:: restToBraille(music21Rest)


    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.
    Complex rests are not supported.



    >>> from music21.braille import basic
    >>> from music21 import note
    >>> dottedQuarter = note.Rest(quarterLength = 1.5)
    >>> print basic.restToBraille(dottedQuarter)
    ⠧⠄
    >>> whole = note.Rest(quarterLength = 4.0)
    >>> print basic.restToBraille(whole)
    ⠍
    >>> quarterPlusSixteenth = note.Rest(quarterLength = 1.25)
    >>> print basic.restToBraille(quarterPlusSixteenth)
    ⠜⠦



.. function:: showOctaveWithNote(previousNote, currentNote)


    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.


    Of course, these rules cease to apply in quite a few cases, which are not directly reflected
    in the results of this method:


    1) If a braille measure goes to a new line, the first note in the measure carries an
       octave designation regardless of what the previous note was.


    2) If a braille measure contains a new key or time signature, the first note carries
       an octave designation regardless of what the previous note was.


    3) If a new key or time signature occurs in the middle of a measure, or if a double bar
       line is encountered, both of which would necessitate a music hyphen, the next note after
       those cases needs an octave marking.


    If any special case happens, previousNote can be set to None and the method will return
    True.




    >>> from music21.braille import basic
    >>> from music21 import note
    >>> basic.showOctaveWithNote(note.Note('C4'), note.Note('E4'))
    False
    >>> basic.showOctaveWithNote(note.Note('C4'), note.Note('F4'))
    False
    >>> basic.showOctaveWithNote(note.Note('C4'), note.Note('F3'))
    True
    >>> basic.showOctaveWithNote(note.Note('C4'), note.Note('A4'))
    True



.. function:: tempoTextToBraille(music21TempoText, maxLineLength=40)


    Takes in a :class:`~music21.tempo.TempoText` and returns its representation in braille
    as a string in UTF-8 unicode. The tempo text is returned uncentered, and is split around
    the comma, each split returned on a separate line. The literary period required at the end
    of every tempo text expression in braille is also included.




    >>> from music21.braille import basic
    >>> from music21 import tempo
    >>> print basic.tempoTextToBraille(tempo.TempoText("Lento assai, cantante e tranquillo"))
    ⠠⠇⠑⠝⠞⠕⠀⠁⠎⠎⠁⠊⠂
    ⠉⠁⠝⠞⠁⠝⠞⠑⠀⠑⠀⠞⠗⠁⠝⠟⠥⠊⠇⠇⠕⠲
    >>> print basic.tempoTextToBraille(tempo.TempoText("Andante molto grazioso"))
    ⠠⠁⠝⠙⠁⠝⠞⠑⠀⠍⠕⠇⠞⠕⠀⠛⠗⠁⠵⠊⠕⠎⠕⠲



.. function:: textExpressionToBraille(music21TextExpression, precedeByWordSign=True)


    Takes in a :class:`~music21.expressions.TextExpression` and returns its
    representation in UTF-8 unicode.



    >>> from music21.braille import basic
    >>> from music21 import expressions
    >>> print basic.textExpressionToBraille(expressions.TextExpression('dim. e rall.'))
    ⠜⠙⠊⠍⠄⠀⠑⠀⠗⠁⠇⠇⠄⠜
    >>> print basic.textExpressionToBraille(expressions.TextExpression('dolce'))
    ⠜⠙⠕⠇⠉⠑



.. function:: timeSigToBraille(music21TimeSignature)


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



    >>> from music21.braille import basic
    >>> from music21 import meter
    >>> print basic.timeSigToBraille(meter.TimeSignature('4/4'))
    ⠼⠙⠲
    >>> print basic.timeSigToBraille(meter.TimeSignature('3/4'))
    ⠼⠉⠲
    >>> print basic.timeSigToBraille(meter.TimeSignature('12/8'))
    ⠼⠁⠃⠦
    >>> print basic.timeSigToBraille(meter.TimeSignature('c'))
    ⠨⠉



.. function:: transcribeHeading(music21KeySignature=None, music21TimeSignature=None, music21TempoText=None, music21MetronomeMark=None, maxLineLength=40)


    Takes in a :class:`~music21.key.KeySignature`, :class:`~music21.meter.TimeSignature`, :class:`~music21.tempo.TempoText`, and
    :class:`~music21.tempo.MetronomeMark` and returns its representation in braille as a string in UTF-8 unicode. The contents
    are always centered on a line, whose width is 40 by default.


    In most cases, the format is (tempo text)(space)(metronome mark)(space)(key/time signature), centered, although all of
    these need not be included. If all the contents do not fit on one line with at least 3 blank characters on each side, then
    the tempo text goes on the first line (and additional lines if necessary), and the metronome mark + key and time signature
    goes on the last line.

    If the resulting heading is of length zero, a BrailleBasicException is raised.



    >>> from music21.braille import basic
    >>> from music21 import key
    >>> from music21 import meter
    >>> from music21 import note
    >>> from music21 import tempo
    >>> print basic.transcribeHeading(key.KeySignature(5), meter.TimeSignature('3/8'), tempo.TempoText("Allegretto"),
    ... tempo.MetronomeMark(number = 135, referent = note.EighthNote()))
    ⠀⠀⠀⠀⠀⠀⠀⠠⠁⠇⠇⠑⠛⠗⠑⠞⠞⠕⠲⠀⠙⠶⠼⠁⠉⠑⠀⠼⠑⠩⠼⠉⠦⠀⠀⠀⠀⠀⠀⠀
    >>> print basic.transcribeHeading(key.KeySignature(-2), meter.TimeSignature('common'),
    ... tempo.TempoText("Lento assai, cantante e tranquillo"), None)
    ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠠⠇⠑⠝⠞⠕⠀⠁⠎⠎⠁⠊⠂⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
    ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠁⠝⠞⠁⠝⠞⠑⠀⠑⠀⠞⠗⠁⠝⠟⠥⠊⠇⠇⠕⠲⠀⠀⠀⠀⠀⠀⠀⠀⠀
    ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠣⠣⠨⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀



.. function:: transcribeNoteFingering(sampleNoteFingering='1', upperFirstInFingering=True)


    Takes in a note fingering, an attribute :attr:`~music21.note.Note.fingering`, and
    returns its correct transcription to braille. Fingering is not officially supported
    by music21, but it is described in Chapter 9 of the "Introduction to Braille Music
    Transcription" manual.



    >>> from music21.braille import basic
    >>> print basic.transcribeNoteFingering('4')
    ⠂

    A change of fingering:




    >>> print basic.transcribeNoteFingering('2-1')
    ⠃⠉⠁

    A choice of fingering, both on either the top or bottom of the staff:




    >>> print basic.transcribeNoteFingering('5|4', upperFirstInFingering=True)
    ⠅⠂
    >>> print basic.transcribeNoteFingering('5|4', upperFirstInFingering=False)
    ⠂⠅

    A choice of fingering, one on top and one below the staff:




    >>> print basic.transcribeNoteFingering('2,1', upperFirstInFingering=True)
    ⠃⠁
    >>> print basic.transcribeNoteFingering('2,1', upperFirstInFingering=False)
    ⠁⠃

    A choice of fingering, first set missing fingermark:




    >>> print basic.transcribeNoteFingering('2,x')
    ⠃⠄

    A choice of fingering, second set missing fingermark:




    >>> print basic.transcribeNoteFingering('x,2')
    ⠠⠃



.. function:: transcribeNoteGrouping(brailleElementGrouping, showLeadingOctave=True)


.. function:: transcribeSignatures(music21KeySignature, music21TimeSignature, outgoingKeySig=None)


    Takes in a :class:`~music21.key.KeySignature` and :class:`~music21.meter.TimeSignature` and returns its representation
    in braille as a string in UTF-8 unicode. If given an old key signature, then its cancellation will be applied before
    and in relation to the new key signature.


    Raises a BrailleBasicException if the resulting key and time signature is empty, which happens if the time signature
    is None and (a) the key signature is None or (b) the key signature has zero sharps and there is no previous key signature.



    >>> from music21.braille import basic
    >>> from music21 import key
    >>> from music21 import meter
    >>> print basic.transcribeSignatures(key.KeySignature(5), meter.TimeSignature('3/8'), None)
    ⠼⠑⠩⠼⠉⠦
    >>> print basic.transcribeSignatures(key.KeySignature(0), None, key.KeySignature(-3))
    ⠡⠡⠡



.. function:: wordToBraille(sampleWord, isTextExpression=False)


    Transcribes a word to UTF-8 braille.



    >>> from music21.braille import basic
    >>> print basic.wordToBraille('Andante')
    ⠠⠁⠝⠙⠁⠝⠞⠑
    >>> print basic.wordToBraille('Fagott')
    ⠠⠋⠁⠛⠕⠞⠞



