simfile.notes
=============

.. py:module:: simfile.notes

.. autoapi-nested-parse::

   Note data classes, plus submodules that operate on note data.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/simfile/notes/count/index
   /autoapi/simfile/notes/counter/index
   /autoapi/simfile/notes/group/index
   /autoapi/simfile/notes/timed/index


Classes
-------

.. autoapisummary::

   simfile.notes.NoteType
   simfile.notes.Note
   simfile.notes.NoteData


Package Contents
----------------

.. py:class:: NoteType(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Known note types supported by StepMania.


   .. py:attribute:: TAP
      :value: '1'



   .. py:attribute:: HOLD_HEAD
      :value: '2'



   .. py:attribute:: TAIL
      :value: '3'



   .. py:attribute:: ROLL_HEAD
      :value: '4'



   .. py:attribute:: ATTACK
      :value: 'A'



   .. py:attribute:: FAKE
      :value: 'F'



   .. py:attribute:: KEYSOUND
      :value: 'K'



   .. py:attribute:: LIFT
      :value: 'L'



   .. py:attribute:: MINE
      :value: 'M'



.. py:class:: Note

   Bases: :py:obj:`NamedTuple`


   A note, corresponding to a nonzero character in a chart's note data.

   Note objects are intrinsically ordered according to their position in
   the underlying note data: that is, if `note1` would appear earlier in
   the note data string than `note2`, then `note1 < note2` is true.


   .. py:attribute:: beat
      :type:  simfile.timing.Beat


   .. py:attribute:: column
      :type:  int


   .. py:attribute:: note_type
      :type:  NoteType


   .. py:attribute:: player
      :type:  int
      :value: 0


      Only used in routine charts. The second player's note data will have
      this value set to 1.



   .. py:attribute:: keysound_index
      :type:  Optional[int]
      :value: None


      Only used in keysounded SSC charts. Notes followed by a number in square
      brackets will have this value set to the bracketed number.



.. py:class:: NoteData(source: Union[str, simfile.types.Chart, NoteData])

   Wrapper for note data with iteration & serialization capabilities.

   The constructor accepts a string of note data, any :data:`.Chart`, or
   another :class:`NoteData` instance.


   .. py:property:: columns

      How many note columns this chart has.



   .. py:method:: from_notes(notes: Iterable[Note], columns: int) -> NoteData
      :classmethod:


      Convert a stream of notes into note data.

      This method assumes the following preconditions:

      * The input notes are naturally sorted.
      * Every note's beat is nonnegative.
      * Every note's column is nonnegative and less than `columns`.

      Note that this method doesn't quantize beats to 192nd ticks,
      and off-grid notes may result in measures with more rows than
      the StepMania editor would produce. StepMania will quantize
      these notes gracefully during gameplay, but you can apply
      :meth:`.Beat.round_to_tick` to each note's beat
      if you'd prefer to keep the note data tidy.