subsequence.conductor
=====================

.. py:module:: subsequence.conductor

.. autoapi-nested-parse::

   Global automation signals — LFOs and ramps that modulate a composition over time.

   The Conductor holds named, time-varying signals (swells, fades, filter sweeps)
   that any pattern can read via ``p.signal(name)`` to shape velocity, CCs, or
   note choices across long stretches of music.





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

.. py:class:: Conductor

   A registry for global automation signals.

   The ``Conductor`` allows you to define time-varying signals (like LFOs or
   ramps) that are available to all pattern builders. This is ideal for
   modulating parameters (like velocity or filter cutoff) over long
   compositional timeframes.

   Create an empty conductor; register signals with lfo() or line().


   .. py:method:: get(name: str, beat: float) -> float

      Retrieve the value of a signal at a specific beat time.

      Most patterns should use ``p.signal("name")`` instead, which
      calls this method with the current bar time automatically.
      Use ``get()`` directly when you need a beat time other than
      the current bar.



   .. py:method:: lfo(name: str, shape: str = 'sine', cycle_beats: float = 16.0, min_val: float = 0.0, max_val: float = 1.0, phase: float = 0.0) -> None

      Register a named LFO signal.

      .. rubric:: Example

      .. code-block:: python

         comp.conductor.lfo("swell", shape="sine", cycle_beats=32)




   .. py:method:: line(name: str, start_val: float, end_val: float, duration_beats: float, start_beat: float = 0.0, loop: bool = False, shape: Union[str, subsequence.easing.EasingFn] = 'linear') -> None

      Register a named ramp signal.

      :param name: Signal name, used to retrieve the value via ``p.signal(name)``.
      :param start_val: Value at the start of the ramp.
      :param end_val: Value at the end of the ramp.
      :param duration_beats: Duration of the ramp in beats.
      :param start_beat: Beat time at which the ramp begins (default 0).
      :param loop: If True, the ramp restarts from start_val after each cycle.
      :param shape: Easing curve name or callable.  Defaults to ``"linear"``.
                    Use ``"ease_in_out"`` for smooth crossfades, ``"exponential"``
                    for filter sweeps.  See :mod:`subsequence.easing`.

      .. rubric:: Example

      .. code-block:: python

         comp.conductor.line("fadein", start_val=0, end_val=1, duration_beats=64)
         comp.conductor.line("filter", start_val=0, end_val=1, duration_beats=32, shape="ease_in_out")




   .. py:property:: signal_names
      :type: Tuple[str, Ellipsis]


      Names of all registered signals, in sorted order.


.. py:class:: LFO(shape: str = 'sine', cycle_beats: float = 16.0, min_val: float = 0.0, max_val: float = 1.0, phase: float = 0.0)

   Bases: :py:obj:`Signal`


   A Low-Frequency Oscillator for generating periodic modulation signals.

   LFOs are used to create cyclical changes (like a 'swell' or 'vibrato')
   over many bars.

   Initialize an LFO.

   :param shape: The waveform shape ("sine", "triangle", "saw", "square").
   :param cycle_beats: How many beats for one full cycle (e.g., 16.0 = 4 bars).
   :param min_val: The bottom of the LFO range (default 0.0).
   :param max_val: The top of the LFO range (default 1.0).
   :param phase: Phase offset (0.0 to 1.0).


   .. py:method:: value_at(beat: float) -> float

      Compute the signal value at a given beat time.



.. py:class:: Line(start_val: float, end_val: float, duration_beats: float, start_beat: float = 0.0, loop: bool = False, shape: Union[str, subsequence.easing.EasingFn] = 'linear')

   Bases: :py:obj:`Signal`


   A ramp signal that moves from one value to another over time.

   Initialize a ramp signal.

   :param start_val: Initial value.
   :param end_val: Target value.
   :param duration_beats: How long it takes to reach the target (in beats).
   :param start_beat: Global beat time when the ramp should start (default 0).
   :param loop: Whether to jump back to start_val and repeat (default False).
   :param shape: Easing curve — a name string (e.g. ``"ease_in_out"``) or any
                 callable that maps [0, 1] → [0, 1].  Defaults to ``"linear"``.
                 See :mod:`subsequence.easing` for available shapes.


   .. py:method:: value_at(beat: float) -> float

      Compute the ramp value at a given beat time.



.. py:class:: Signal

   Abstract base class for a time-varying signal.


   .. py:method:: value_at(beat: float) -> float
      :abstractmethod:


      Return the signal value at the given beat time.  Subclasses must override.