music21.braille.text

BrailleKeyboard

class music21.braille.text.BrailleKeyboard(lineLength=40)

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)
BrailleKeyboard.makeNewLines()

Methods inherited from BrailleText:

Methods inherited from ProtoM21Object:

BrailleText

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

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)

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)
BrailleText.addLongExpression(longExpr)

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

BrailleText.addMeasureNumber(measureNumber)

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)

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)

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)

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()

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)

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()

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

Methods inherited from ProtoM21Object:

BrailleTextLine

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

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)

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)

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)

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)

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()

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

Methods inherited from ProtoM21Object: