music21.style

The style module represents information about the style of a Note, Accidental, etc. such that precise positioning information, layout, size, etc. can be specified.

BeamStyle

class music21.style.BeamStyle

Style for beams

BeamStyle bases

BeamStyle read-only properties

Read-only properties inherited from ProtoM21Object:

BeamStyle read/write properties

Read/write properties inherited from Style:

BeamStyle methods

Methods inherited from ProtoM21Object:

BeamStyle instance variables

Instance variables inherited from Style:

BezierStyle

class music21.style.BezierStyle

From the MusicXML Definition.

BezierStyle bases

BezierStyle read-only properties

Read-only properties inherited from ProtoM21Object:

BezierStyle read/write properties

Read/write properties inherited from Style:

BezierStyle methods

Methods inherited from ProtoM21Object:

BezierStyle instance variables

Instance variables inherited from Style:

Enclosure

class music21.style.Enclosure(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enclosure bases

LineStyle

class music21.style.LineStyle

from the MusicXML Definition

Defines lineShape (‘straight’, ‘curved’ or None) lineType (‘solid’, ‘dashed’, ‘dotted’, ‘wavy’ or None) dashLength (in tenths) spaceLength (in tenths)

LineStyle bases

LineStyle read-only properties

Read-only properties inherited from ProtoM21Object:

LineStyle read/write properties

Read/write properties inherited from Style:

LineStyle methods

Methods inherited from ProtoM21Object:

LineStyle instance variables

Instance variables inherited from Style:

NoteStyle

class music21.style.NoteStyle

A Style object that also includes stem and accidental style information.

Beam style is stored on the Beams object. Lyric style is stored on the Lyric object.

NoteStyle bases

NoteStyle read-only properties

Read-only properties inherited from ProtoM21Object:

NoteStyle read/write properties

Read/write properties inherited from Style:

NoteStyle methods

Methods inherited from ProtoM21Object:

NoteStyle instance variables

NoteStyle.accidentalStyle

An optional style.Style object describing what the accidental looks like.

>>> n = note.Note()
>>> n.style.accidentalStyle is None
True

Note that accidentalStyle is not created automatically. Users must instantiate a Style object.

>>> n.style.accidentalStyle = style.Style()
>>> n.style.accidentalStyle.relativeX = -2.0

Note: do not use .hideObjectOnPrint in accidentalStyle to hide the accidental. Set the displayType on the Accidental itself.

This object may eventually move to Note.pitch.accidental.style.

NoteStyle.noteSize

An optional string representing the size of the note as a type of note.

Valid values are None (=normal), ‘cue’, ‘grace’, ‘graceCue’, and ‘large’ (taken from MusicXML, with “graceCue” replacing “grace-cue”).

NoteStyle.stemStyle

An optional style.Style object describing what the stem looks like.

>>> n = note.Note()
>>> n.style.stemStyle is None
True

Note that stemStyle is not created automatically. Users must instantiate a Style object.

>>> n.style.stemStyle = style.Style()
>>> n.style.stemStyle.color = 'red'

Instance variables inherited from Style:

StreamStyle

class music21.style.StreamStyle

Includes several elements in the MusicXML <appearance> tag in <defaults> along with <music-font> and <word-font>

StreamStyle bases

StreamStyle read-only properties

Read-only properties inherited from ProtoM21Object:

StreamStyle read/write properties

Read/write properties inherited from Style:

StreamStyle methods

Methods inherited from ProtoM21Object:

StreamStyle instance variables

Instance variables inherited from Style:

Style

class music21.style.Style

A style object is a lightweight object that keeps track of information about the look of an object.

>>> st = style.Style()
>>> st.units
'tenths'
>>> st.absoluteX is None
True

>>> st.absoluteX = 20.4
>>> st.absoluteX
20.4

Style bases

Style read-only properties

Read-only properties inherited from ProtoM21Object:

Style read/write properties

Style.absoluteY

Get or set the vertical position, where 0 is the top line of the staff and units are whatever is defined in .units, generally “tenths”, meaning 1/10th of a staff space.

Other legal positions are ‘above’ and ‘below’ which are synonyms for 10 and -70 respectively (for 5-line staves; other staves are not yet implemented) This behavior may change in music21 v8 or after.

>>> te = style.Style()
>>> te.absoluteY = 10
>>> te.absoluteY
10

>>> te.absoluteY = 'below'
>>> te.absoluteY
-70

Setting an invalid position raises a TextFormatException

>>> te.absoluteY = 'hello'
Traceback (most recent call last):
music21.style.TextFormatException:
    Not a supported absoluteY position: 'hello'
Style.enclosure

Get or set the enclosure as a style.Enclosure enum (or None, which means the enclosure is left unspecified).

Valid names are:

  • “rectangle”/style.Enclosure.RECTANGLE,

  • “square”/style.Enclosure.SQUARE,

  • “oval”/style.Enclosure.OVAL,

  • “circle”/style.Enclosure.CIRCLE,

  • “bracket”/style.Enclosure.BRACKET,

  • “inverted-bracket”/style.Enclosure.INVERTED_BRACKET (output in musicxml 4 only)

  • “none”/style.Enclosure.NO_ENCLOSURE

  • None (i.e. enclosure is unspecified)

or the following other shapes with their ALLCAPS Enclosure equivalents:

triangle, diamond, pentagon, hexagon, heptagon, octagon, nonagon, or decagon.

>>> tst = style.TextStyle()
>>> tst.enclosure = None
>>> tst.enclosure = style.Enclosure.RECTANGLE
>>> tst.enclosure
<Enclosure.RECTANGLE>

Setting as a string is still supported, but is converted to an enum.

>>> tst.enclosure = 'octagon'
>>> tst.enclosure
<Enclosure.OCTAGON>

Setting an invalid enclosure raises a TextFormatException

>>> tst.enclosure = 'parabola'
Traceback (most recent call last):
music21.style.TextFormatException:
    Not a supported enclosure: 'parabola'

Style methods

Methods inherited from ProtoM21Object:

Style instance variables

Style.hideObjectOnPrint

If set to True, the Music21Object will not print upon output (only used in MusicXML output at this point and in Lilypond output for notes, chords, and rests).

Style.units

What distances are measured in. The default “tenths” is a concept borrowed from MusicXML which refers to 1/10th of the distance between two staff lines. It is currently also the only supported unit.

StyleMixin

class music21.style.StyleMixin

Mixin for any class that wants to support style and editorial, since several non-music21 objects, such as Lyrics and Accidentals will support Style.

Not used by Music21Objects because of the added trouble in copying etc. so there is code duplication with base.Music21Object

StyleMixin bases

StyleMixin read-only properties

StyleMixin.hasEditorialInformation

Returns True if there is a Editorial object already associated with this object, False otherwise.

Calling .style on an object will always create a new Style object, so even though a new Style object isn’t too expensive to create, this property helps to prevent creating new Styles more than necessary.

>>> acc = pitch.Accidental('#')
>>> acc.hasEditorialInformation
False
>>> acc.editorial
<music21.editorial.Editorial {}>
>>> acc.hasEditorialInformation
True
StyleMixin.hasStyleInformation

Returns True if there is a Style object already associated with this object, False otherwise.

Calling .style on an object will always create a new Style object, so even though a new Style object isn’t too expensive to create, this property helps to prevent creating new Styles more than necessary.

>>> lObj = note.Lyric('hello')
>>> lObj.hasStyleInformation
False
>>> lObj.style
<music21.style.TextStylePlacement object at 0x10b0a2080>
>>> lObj.hasStyleInformation
True

StyleMixin read/write properties

StyleMixin.editorial

a Editorial object that stores editorial information (comments, footnotes, harmonic information, ficta).

Created automatically as needed:

>>> acc = pitch.Accidental()
>>> acc.editorial
<music21.editorial.Editorial {}>
>>> acc.editorial.ficta = pitch.Accidental('sharp')
>>> acc.editorial.ficta
<music21.pitch.Accidental sharp>
>>> acc.editorial
<music21.editorial.Editorial {'ficta': <music21.pitch.Accidental sharp>}>
StyleMixin.style

Returns (or Creates and then Returns) the Style object associated with this object, or sets a new style object. Different classes might use different Style objects because they might have different style needs (such as text formatting or bezier positioning)

Eventually will also query the groups to see if they have any styles associated with them.

>>> acc = pitch.Accidental()
>>> st = acc.style
>>> st
<music21.style.TextStyle object at 0x10ba96208>
>>> st.absoluteX = 20.0
>>> st.absoluteX
20.0
>>> acc.style = style.TextStyle()
>>> acc.style.absoluteX is None
True

TextStyle

class music21.style.TextStyle

A Style object that also includes text formatting.

>>> ts = style.TextStyle()
>>> ts.classes
('TextStyle', 'Style', 'ProtoM21Object', 'object')

TextStyle bases

TextStyle read-only properties

Read-only properties inherited from ProtoM21Object:

TextStyle read/write properties

TextStyle.alignHorizontal

Get or set the horizontal alignment. Valid values are left, right, center, or None

>>> te = style.TextStyle()
>>> te.alignHorizontal = 'right'
>>> te.alignHorizontal
'right'

Invalid horizontal aligns raise a TextFormatException:

>>> te.alignHorizontal = 'hello'
Traceback (most recent call last):
music21.style.TextFormatException:
    Invalid horizontal align: 'hello'
TextStyle.alignVertical

Get or set the vertical align. Valid values are top, middle, bottom, baseline or None

>>> te = style.TextStyle()
>>> te.alignVertical = 'top'
>>> te.alignVertical
'top'

Invalid vertical aligns raise a TextFormatException:

>>> te.alignVertical = 'hello'
Traceback (most recent call last):
music21.style.TextFormatException:
    Invalid vertical align: 'hello'
TextStyle.fontFamily

Returns a list of font family names associated with the style, or sets the font family name list.

If a single string is passed then it is converted to a list.

>>> ts = style.TextStyle()
>>> ff = ts.fontFamily
>>> ff
[]
>>> ff.append('Times')
>>> ts.fontFamily
['Times']
>>> ts.fontFamily.append('Garamond')
>>> ts.fontFamily
['Times', 'Garamond']
>>> ts.fontFamily = 'Helvetica, sans-serif'
>>> ts.fontFamily
['Helvetica', 'sans-serif']
TextStyle.fontSize

Get or set the size. Best, an int or float, but also a css font size

>>> tst = style.TextStyle()
>>> tst.fontSize = 20
>>> tst.fontSize
20
TextStyle.fontStyle

Get or set the style, as normal, italic, bold, and bolditalic. None is currently an acceptable value which should be “normal”.

>>> tst = style.TextStyle()
>>> tst.fontStyle = 'bold'
>>> tst.fontStyle
'bold'

Invalid values raise a TextFormatException

>>> tst.fontStyle = 'hello'
Traceback (most recent call last):
music21.style.TextFormatException:
    Not a supported fontStyle: 'hello'
TextStyle.fontWeight

Get or set the weight, as normal, or bold.

>>> tst = style.TextStyle()
>>> tst.fontWeight = 'bold'
>>> tst.fontWeight
'bold'
TextStyle.justify

Get or set the justification. Valid values are left, center, right, full (not supported by MusicXML), and None

>>> tst = style.TextStyle()
>>> tst.justify = 'center'
>>> tst.justify
'center'

Invalid values raise a TextFormatException

>>> tst.justify = 'hello'
Traceback (most recent call last):
music21.style.TextFormatException:
    Not a supported justification: 'hello'
TextStyle.letterSpacing

Get or set the letter spacing.

>>> tst = style.TextStyle()
>>> tst.letterSpacing = 20
>>> tst.letterSpacing
20.0
>>> tst.letterSpacing = 'normal'

Read/write properties inherited from Style:

TextStyle methods

Methods inherited from ProtoM21Object:

TextStyle instance variables

Instance variables inherited from Style:

TextStylePlacement

class music21.style.TextStylePlacement

TextStyle plus a placement attribute

TextStylePlacement bases

TextStylePlacement read-only properties

Read-only properties inherited from ProtoM21Object:

TextStylePlacement read/write properties

Read/write properties inherited from TextStyle:

Read/write properties inherited from Style:

TextStylePlacement methods

Methods inherited from ProtoM21Object:

TextStylePlacement instance variables

Instance variables inherited from Style: