music21.braille.text

BrailleKeyboard

class music21.braille.text.BrailleKeyboard(lineLength=40)[source]

A subclass of BrailleText that handles both hands at once.

BrailleKeyboard bases

BrailleKeyboard read-only properties

Read-only properties inherited from ProtoM21Object:

BrailleKeyboard read/write properties

Read/write properties inherited from BrailleText:

BrailleKeyboard methods

BrailleKeyboard.addNoteGroupings(measureNumber, noteGroupingR, noteGroupingL)[source]
BrailleKeyboard.makeNewLines()[source]

Methods inherited from BrailleText:

BrailleText

class music21.braille.text.BrailleText(lineLength=40, showHand=None)[source]

Object that handles all the formatting associated with braille music notation on multiple lines.

>>> bt = braille.text.BrailleText(lineLength=10, showHand='right')
>>> bt
<music21.braille.text.BrailleText 1 line, 0 headings, 10 cols>
>>> bt.lineLength
10
>>> bt.allLines
[<music21.braille.text.BrailleTextLine '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀'>]
>>> bt.rightHandSymbol
True
>>> bt.leftHandSymbol
False
>>> bt.allHeadings
[]

BrailleText bases

BrailleText read-only properties

Read-only properties inherited from ProtoM21Object:

BrailleText read/write properties

BrailleText.showHand

BrailleText methods

BrailleText.addHeading(heading)[source]

adds a heading to the BrailleText. Heading can be a single or multiple line Unicode string representing a heading.

These headings are not stored in allHeadings, but instead in .allLines, what .allHeadings stores is the index of the start of a heading section and the index of the end of a heading section.

(since each BrailleTextLine knows whether it is a heading or not, storing the index of headings might be overkill)

>>> bt = braille.text.BrailleText(lineLength=10)
>>> headingText = braille.basic.timeSigToBraille(meter.TimeSignature('4/8'))
>>> bt.addHeading(headingText)
>>> len(bt.allLines)
2
>>> bt.allLines[0].isHeading
True
>>> print(str(bt.allLines[0]))
⠼⠙⠦
>>> bt.allHeadings
[(0, 1)]
>>> bt.addMeasureNumber(7)
>>> headingText = braille.basic.timeSigToBraille(meter.TimeSignature('3/4'))
>>> bt.addHeading(headingText)
>>> len(bt.allLines)
4
>>> bt.allHeadings
[(0, 1), (2, 3)]
BrailleText.addInaccord(inaccord)[source]
BrailleText.addLongExpression(longExpr)[source]

Adds an expression long enough that it is split at each space symbol such that line wrapping could occur.

BrailleText.addMeasureNumber(measureNumber)[source]

Add a measure number (either a braille number or an int).

>>> bt = braille.text.BrailleText(lineLength=10)
>>> bt
<music21.braille.text.BrailleText 1 line, 0 headings, 10 cols>
>>> bt.allLines
[<music21.braille.text.BrailleTextLine '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀'>]
>>> bt.addMeasureNumber(4)
>>> print(str(bt.allLines[0]))
⠼⠙
>>> bt.currentLine.textLocation
2

If there are already lines, then add a new one:

>>> bt.addMeasureNumber(5)
>>> bt.allLines
[<music21.braille.text.BrailleTextLine '⠼⠙⠀⠀⠀⠀⠀⠀⠀⠀'>,
 <music21.braille.text.BrailleTextLine '⠼⠑⠀⠀⠀⠀⠀⠀⠀⠀'>]
>>> print(str(bt.allLines[-1]))
⠼⠑
BrailleText.addSignatures(signatures)[source]

Appends signatures to the current location if there is space, otherwise appends to a new line:

>>> bt = braille.text.BrailleText(lineLength=5)
>>> bt.addSignatures(braille.basic.timeSigToBraille(meter.TimeSignature('4/8')))
>>> print(str(bt.currentLine))
⠼⠙⠦
>>> bt.addSignatures(braille.basic.timeSigToBraille(meter.TimeSignature('3/4')))
>>> print(str(bt.currentLine))
⠀⠀⠼⠉⠲
>>> len(bt.allLines)
2
BrailleText.addToNewLine(brailleNoteGrouping)[source]

Adds a NoteGrouping to a new line, prefacing that new line with the appropriate spaces or keyboard symbols and dots.

>>> bt = braille.text.BrailleText(10)
>>> bt.currentLine.append('hi', addSpace=False)
>>> print(str(bt))
hi
>>> c = braille.lookup.pitchNameToNotes['C']['quarter']  # dots 1456
>>> bt.addToNewLine(c + c + c)
>>> print(str(bt))
hi
⠀⠀⠹⠹⠹

It is done differently if there are hand symbols involved:

>>> bt = braille.text.BrailleText(10)
>>> bt.showHand = 'right'
>>> bt.currentLine.append('hi', addSpace=False)
>>> bt.addToNewLine(c + c + c)
>>> print(str(bt))
hi
⠨⠜⠄⠹⠹⠹
BrailleText.appendOrInsertCurrent(brailleExpr, addSpace=True)[source]

append expression to the current line if it is possible, or make a new line and insert it there:

>>> bt = braille.text.BrailleText(lineLength=10)
>>> bt.appendOrInsertCurrent('hello', addSpace=False)
>>> print(str(bt))
hello
>>> bt.appendOrInsertCurrent(braille.lookup.symbols['space'] + 'hi')
>>> print(str(bt))
hello⠀⠀hi
>>> bt.appendOrInsertCurrent(braille.lookup.symbols['space'] + 'there')
>>> print(str(bt))
hello⠀⠀hi
⠀⠀⠀there
BrailleText.makeNewLine()[source]

Add a newline to the BrailleText

>>> bt = braille.text.BrailleText(lineLength=10)
>>> len(bt.allLines)
1
>>> bt.makeNewLine()
>>> len(bt.allLines)
2
>>> bt.makeNewLine()
>>> len(bt.allLines)
3
BrailleText.optionalAddKeyboardSymbolsAndDots(noteGrouping=None)[source]

Adds symbols for rh_keyboard or lh_keyboard depending on what is appropriate

returns a boolean indicating whether a space needs to be added before the next symbol is needed.

BrailleText.recenterHeadings()[source]

Recenter each of the headings so that they exactly align with the text beneath them.

Demonstration with non braille text:

>>> heading1 = 'hello'
>>> body1 = 'anyoneHome?' + braille.lookup.symbols['space'] + 'yup!'
>>> bt = braille.text.BrailleText(lineLength=12)
>>> bt.addHeading(heading1)
>>> bt.addLongExpression(body1)
>>> bt.allHeadings
[(0, 1)]
>>> bt.recenterHeadings()
>>> print(str(bt))
⠀⠀⠀hello⠀⠀⠀⠀
⠀anyoneHome?
⠀⠀yup!

Each heading is aligned with its own text

>>> heading2 = 'buh'
>>> body2 = 'short' + braille.lookup.symbols['space'] + 'court'
>>> bt.addHeading(heading2)
>>> bt.addLongExpression(body2)
>>> bt.allHeadings
[(0, 1), (3, 4)]
>>> bt.recenterHeadings()
>>> print(str(bt))
⠀⠀⠀hello⠀⠀⠀⠀
⠀anyoneHome?
⠀⠀yup!
⠀⠀⠀⠀buh⠀⠀⠀⠀⠀
⠀short⠀court

BrailleTextLine

class music21.braille.text.BrailleTextLine(lineLength: int = 40)[source]

An object representing a single line of braille text:

The initial value is the length of the line:

>>> btl = braille.text.BrailleTextLine(40)
>>> btl
<music21.braille.text.BrailleTextLine '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀'>
>>> btl.isHeading
False
>>> btl.containsNoteGrouping
False
>>> btl.lineLength
40
>>> btl.textLocation
0
>>> btl.highestUsedLocation
0
>>> btl.allChars == 40 * [braille.lookup.symbols['space']]
True

>>> btl.append(braille.lookup.symbols['tie'])
>>> btl
<music21.braille.text.BrailleTextLine '⠀⠈⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀'>
>>> print(str(btl))
⠀⠈⠉

BrailleTextLine bases

BrailleTextLine read-only properties

Read-only properties inherited from ProtoM21Object:

BrailleTextLine methods

BrailleTextLine.append(text, addSpace=True)[source]

Appends text (with optional space at the beginning) or raises an exception if it cannot be appended.

>>> btl = braille.text.BrailleTextLine(6)
>>> btl.append(braille.lookup.symbols['tie'], addSpace=False)
>>> print(str(btl))
⠈⠉
>>> btl.textLocation
2
>>> btl.highestUsedLocation
2

Default is to add a space:

>>> btl.append(braille.lookup.symbols['tie'])
>>> print(str(btl))
⠈⠉⠀⠈⠉

Out of room:

>>> btl.append(braille.lookup.symbols['tie'])
Traceback (most recent call last):
music21.braille.text.BrailleTextException: Text does not fit at end of braille text line.

Text is appended at textLocation, overwriting other text that might be there.

>>> btl.textLocation = btl.highestUsedLocation = 0
>>> btl.append('hi', addSpace=False)
>>> btl.textLocation = btl.highestUsedLocation = 5
>>> print(str(btl))
hi⠀⠈⠉
BrailleTextLine.canAppend(text, addSpace=True)[source]

Returns True if there is enough space in this line to append the text, or False if not:

>>> btl = braille.text.BrailleTextLine(10)
>>> btl.canAppend('1234567890', addSpace=False)
True
>>> btl.canAppend('12345678901', addSpace=False)
False
>>> btl.canAppend('1234567890', addSpace=True)
False
>>> btl.textLocation
0
>>> btl.textLocation = 5
>>> btl.canAppend('12345', addSpace=False)
True
>>> btl.canAppend('123456', addSpace=False)
False

If highestUsedLocation > textLocation, highestUsedLocation is used instead:

>>> btl.highestUsedLocation = 7
>>> btl.canAppend('123', addSpace=False)
True
>>> btl.canAppend('1234', addSpace=False)
False
BrailleTextLine.canInsert(textLocation, text)[source]

Returns True if there is enough space starting at textLocation to append the text. False otherwise:

>>> btl = braille.text.BrailleTextLine(10)
>>> btl.canInsert(4, '123456')
True
>>> btl.canInsert(5, '123456')
False
BrailleTextLine.insert(textLocation, text)[source]

Inserts text at a certain location, updating textLocation and possibly highestUsedLocation:

>>> btl = braille.text.BrailleTextLine(6)
>>> btl.insert(2, braille.lookup.symbols['tie'])
>>> print(str(btl))
⠀⠀⠈⠉
>>> btl.textLocation
4
>>> btl.highestUsedLocation
4

>>> btl.insert(0, braille.lookup.symbols['tie'])

It looks like we have deleted the previous tie:

>>> print(str(btl))
⠈⠉

But that’s because only characters up to .textLocation are printed (this may change later)

>>> btl.textLocation
2
>>> btl.highestUsedLocation
4

Let’s change textLocation and now see:

>>> btl.textLocation = btl.highestUsedLocation
>>> print(str(btl))
⠈⠉⠈⠉

Inserting beyond the end creates an error:

>>> btl.insert(5, braille.lookup.symbols['tie'])
Traceback (most recent call last):
music21.braille.text.BrailleTextException: Text cannot be inserted at specified location.

Unlike list inserts, this insert overwrites the previous text:

>>> btl.insert(0, 'hi')
>>> btl.textLocation = btl.highestUsedLocation
>>> print(str(btl))
hi⠈⠉
BrailleTextLine.lastHyphenToSpace()[source]

Occasionally a line ends with a hyphen because the last appender thought it would be helpful, such as to put more characters into a line. But in case it is not, then this method will change that last character to a space and set textLocation back one character, so it is not printed.

>>> bt = braille.text.BrailleTextLine(10)
>>> bt.append('hi', addSpace=False)
>>> bt.append(braille.lookup.symbols['music_hyphen'], addSpace=False)
>>> print(str(bt))
hi⠐
>>> bt.textLocation
3
>>> print(bt.allChars[2])
⠐
>>> bt.lastHyphenToSpace()
>>> print(str(bt))
hi
>>> bt.allChars[2] == braille.lookup.symbols['space']
True
>>> bt.textLocation
2