.. _moduleBeam:

music21.beam
============

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

.. module:: music21.beam


The module defines Beam and Beams (note plural) objects.

The Beams object holds multiple Beam objects (e.g., a 32nd note might
have three Beam objects in its Beam object).

The Beams object is stored in :class:`~music21.note.Note`
and :class:`~music21.chord.Chord` objects as their
:attr:`~music21.note.Note.beams` attributes.   Beams objects can
largely be treated as a list.

See `meter.TimeSignature`.:meth:`~music21.meter.TimeSignature.getBeams` for a way of getting
beam information for a measure given the meter.
The `meter.TimeSignature`.:attr:`~music21.meter.TimeSignature.beamSequence`
attribute holds information about how to beam given the TimeSignature

Run `stream.Stream`.:meth:`~music21.stream.Stream.makeBeams` to set beaming information
automatically given the current meter.







Beams
-----

Inherits from: :class:`~music21.base.JSONSerializer`

.. class:: Beams()


    The Beams object stores in it attribute beamsList (a list) all
    the Beam objects defined above.  Thus len(beam.Beams) tells you how many
    beams the note currently has on it, and iterating over a Beams object gives
    you each Beam.



    >>> from music21 import *
    >>> n = note.Note(type='16th')
    >>> isinstance(n.beams, beam.Beams)
    True
    >>> n.beams.fill(2, 'start')
    >>> len(n.beams)
    2
    >>> for thisBeam in n.beams:
    ...     thisBeam.type
    'start'
    'start'



    **Beams** **attributes**

        Attributes without Documentation: `feathered`, `beamsList`

    **Beams** **properties**

        .. attribute:: mx


            Returns a list of mxBeam objects



        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **Beams** **methods**

        .. method:: append(type=None, direction=None)

            Append a new Beam object to this Beams, automatically creating the Beam object and incrementing the number count.



        .. method:: fill(level=None, type=None)


            A quick way of setting the beams list for a particular duration,
            for instance, fill("16th") will clear the current list of beams in the
            Beams object and add two beams.  fill(2) will do the same (though note
            that that is an int, not a string).

            It does not do anything to the direction that the beams are going in, or by default.
            Either set type here or call setAll() on the Beams object afterwards.

            Both "eighth" and "8th" work.  Adding more than six beams (i.e. things like
            512th notes) raises an error.



            >>> from music21 import *
            >>> a = beam.Beams()
            >>> a.fill('16th')
            >>> len(a)
            2
            ⁠ 
            >>> a.fill('32nd', type='start')
            >>> len(a)
            3
            >>> a.beamsList[2]
            <music21.beam.Beam object at 0x...>
            >>> a.beamsList[2].type
            'start'



        .. method:: getByNumber(number)

            Gets an internal beam object by number...



            >>> from music21 import *
            >>> a = beam.Beams()
            >>> a.fill('16th')
            >>> a.setAll('start')
            >>> a.getByNumber(2).type
            'start'



        .. method:: getNumbers()

            Returns a list of all defined beam numbers; it should normally be
            a set of consecutive integers, but it might not be.



            >>> from music21 import *
            >>> a = beam.Beams()
            >>> a.fill('32nd')
            >>> a.getNumbers()
            [1, 2, 3]



        .. method:: getTypeByNumber(number)

            Get beam type, with direction, by number



            >>> from music21 import *
            >>> a = beam.Beams()
            >>> a.fill('16th')
            >>> a.setAll('start')
            >>> a.setByNumber(2, 'partial-right')
            >>> a.getTypeByNumber(2)
            'partial-right'
            >>> a.getTypeByNumber(1)
            'start'



        .. method:: getTypes()

            Returns a list of all beam types defined for the current beams



            >>> from music21 import *
            >>> a = beam.Beams()
            >>> a.fill('16th')
            >>> a.setAll('start')
            >>> a.getTypes()
            ['start', 'start']



        .. method:: jsonAttributes()

            Define all attributes of this object that should be JSON serialized for storage and re-instantiation.



        .. method:: setAll(type, direction=None)


            setAll is a method of convenience that sets the type
            of each of the beam objects within the beamsList to the specified type.
            It also takes an optional "direction" attribute that sets the direction
            for each beam (otherwise the direction of each beam is set to None)
            Acceptable directions (start, stop, continue, etc.) are listed under
            Beam() above.



            >>> from music21 import *
            >>> a = beam.Beams()
            >>> a.fill('16th')
            >>> a.setAll('start')
            >>> a.getTypes()
            ['start', 'start']




        .. method:: setByNumber(number, type, direction=None)

            Set an internal beam object by number, or rhythmic symbol level



            >>> from music21 import *
            >>> a = beam.Beams()
            >>> a.fill('16th')
            >>> a.setAll('start')
            >>> a.setByNumber(1, 'continue')
            >>> a.beamsList[0].type
            'continue'
            >>> a.setByNumber(2, 'stop')
            >>> a.beamsList[1].type
            'stop'
            >>> a.setByNumber(2, 'partial-right')
            >>> a.beamsList[1].type
            'partial'
            >>> a.beamsList[1].direction
            'right'



        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


Beam
----

Inherits from: :class:`~music21.base.JSONSerializer`

.. class:: Beam(type=None, direction=None)


    A Beam is an object representation of one single beam, that is, one horizontal
    line connecting two notes together (or less commonly a note to a rest).  Thus it
    takes two separate Beam objects to represent the beaming of a 16th note.

    The Beams object (note the plural) is the object that handles groups of Beam objects;
    it is defined later on.

    Here are two ways to define the start of a beam


    >>> from music21 import *
    >>> b1 = beam.Beam(type = 'start')
    >>> b2 = beam.Beam('start')

    Here is a partial beam (that is, one that does not
    connect to any other note, such as the second beam of
    a dotted eighth, sixteenth group)

    Two ways of doing the same thing


    >>> b3 = beam.Beam(type = 'partial', direction = 'left')
    >>> b4 = beam.Beam('partial', 'left')




    **Beam** **attributes**

        Attributes without Documentation: `direction`, `type`, `number`, `independentAngle`

    **Beam** **properties**

        .. attribute:: mx





            >>> from music21 import *
            >>> a = beam.Beam()
            >>> a.type = 'start'
            >>> a.number = 1
            >>> b = a.mx
            >>> b.get('charData')
            'begin'
            >>> b.get('number')
            1
            ⁠ 
            >>> a.type = 'partial'
            >>> a.direction = 'left'
            >>> b = a.mx
            >>> b.get('charData')
            'backward hook'



        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **Beam** **methods**

        .. method:: jsonAttributes()

            Define all attributes of this object that should be JSON serialized for storage and re-instantiation.



        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


