simfile.timing
==============

.. py:module:: simfile.timing

.. autoapi-nested-parse::

   Timing data classes, plus submodules that operate on timing data.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/simfile/timing/displaybpm/index
   /autoapi/simfile/timing/engine/index


Classes
-------

.. autoapisummary::

   simfile.timing.Beat
   simfile.timing.BeatValue
   simfile.timing.BeatValues
   simfile.timing.TimingData


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

.. py:class:: Beat

   Bases: :py:obj:`fractions.Fraction`


   A fractional beat value, denoting vertical position in a simfile.

   The constructor takes the same arguments as Python's :code:`Fraction`:

       Takes a string like '3/2' or '1.5', another Rational instance,
       a numerator/denominator pair, or a float.

   If the input is a float or string, the resulting fraction will be
   rounded to the nearest :meth:`tick`.


   .. py:method:: tick() -> Beat
      :classmethod:


      1/48 of a beat (1/192 of a measure).



   .. py:method:: from_str(beat_str) -> Beat
      :classmethod:


      Convert a decimal string to a beat, rounding to the nearest tick.



   .. py:method:: round_to_tick() -> Beat

      Round the beat to the nearest tick.



.. py:class:: BeatValue

   Bases: :py:obj:`NamedTuple`


   An event that occurs on a particular beat, e.g. a BPM change or stop.

   The decimal value's semantics vary based on the type of event:

   * BPMS: the new BPM value
   * STOPS, DELAYS: number of seconds to pause
   * WARPS: number of beats to skip


   .. py:attribute:: beat
      :type:  Beat


   .. py:attribute:: value
      :type:  decimal.Decimal


.. py:class:: BeatValues(items: Optional[Iterable[E]] = None)

   Bases: :py:obj:`simfile._private.generic.ListWithRepr`\ [\ :py:obj:`BeatValue`\ ]


   A list of :class:`BeatValue` instances.


   .. py:method:: from_str(string: Optional[str], strict: bool = True) -> BeatValues
      :classmethod:


      Parse the MSD value component of a timing data list::

          #BPMS:0.000=128.000,64.000=140.000;
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

      The timing data lists supported by this class include
      `BPMS`, `STOPS`, `DELAYS`, and `WARPS`.



.. py:class:: TimingData(source: Union[simfile.types.Simfile, simfile.types.AttachedChart])

   Timing data for a simfile, possibly enriched with SSC chart timing.

   If both an :class:`.SSCSimfile` (version 0.7 or higher) and an
   :class:`.SSCChart` are supplied to the constructor, and if the chart
   contains any timing fields, the chart will be used as the source of
   timing data.

   Per StepMania's behavior, the offset defaults to zero if the simfile
   (and/or SSC chart) doesn't specify one. (However, unlike StepMania, the
   BPM does not default to 60 when omitted; the default BPM doesn't appear
   to be used deliberately in any existing simfiles, whereas the default
   offset does get used intentionally from time to time.)


   .. py:attribute:: bpms
      :type:  BeatValues


   .. py:attribute:: stops
      :type:  BeatValues


   .. py:attribute:: delays
      :type:  BeatValues


   .. py:attribute:: warps
      :type:  BeatValues


   .. py:attribute:: fakes
      :type:  BeatValues


   .. py:attribute:: offset
      :type:  decimal.Decimal