subsequence.link_clock
======================

.. py:module:: subsequence.link_clock

.. autoapi-nested-parse::

   Ableton Link clock adapter for Subsequence.

   Wraps ``aalink.Link`` and adapts its asyncio-native API to Subsequence's
   24 PPQN pulse model.  Requires the optional ``link`` extra::

       pip install subsequence[link]

   Usage::

       link_clock = LinkClock(bpm=120, quantum=4.0, loop=asyncio.get_running_loop())
       beat_origin = await link_clock.wait_for_bar()
       # ... in the pulse loop:
       await link_clock.sync(beat_origin + pulse_count / PPQN)





Module Contents
---------------

.. py:class:: LinkClock(bpm: float, quantum: float, loop: asyncio.AbstractEventLoop)

   Thin wrapper around ``aalink.Link`` for Subsequence's pulse-based clock.

   :param bpm: Initial tempo in BPM (proposed to the Link session).
   :param quantum: Beat cycle length — 4.0 means one bar in 4/4 time.
   :param loop: The running asyncio event loop (required by aalink).

   Join the Link session immediately, proposing *bpm* and setting the bar length to *quantum* beats.


   .. py:method:: disable() -> None

      Disconnect from the Link session.



   .. py:method:: request_tempo(bpm: float) -> None

      Propose a new tempo to the Link session.

      Other peers may accept or reject the change depending on their own
      session rules.  Subsequence's sequencer will pick up the network-
      authoritative tempo on the next pulse.



   .. py:method:: sync(beat: float) -> float
      :async:


      Wait until the Link session beat reaches *beat*, then return *beat*.

      This is the primary timing primitive used by the sequencer loop.
      Calling ``await link_clock.sync(beat_origin + pulse / PPQN)`` for each
      successive pulse gives accurate, Link-synchronised timing.



   .. py:method:: wait_for_bar() -> float
      :async:


      Wait for the next quantum boundary (bar start) and return it.

      Use this to start the sequencer at a musically clean position that is
      phase-aligned with all other Link participants.

      Returns the beat value at which playback should begin (``beat_origin``).



   .. py:property:: beat
      :type: float


      Current absolute beat position in the Link session timeline.


   .. py:property:: num_peers
      :type: int


      Number of connected Link peers (not counting self).


   .. py:property:: playing
      :type: bool


      Whether the Link session transport is playing.


   .. py:property:: quantum
      :type: float


      Beat cycle length (e.g. 4.0 for one bar in 4/4).


   .. py:property:: tempo
      :type: float


      Current session tempo in BPM (authoritative from the Link network).