======================================================================
=== FILE: scamp_extensions.composers/scamp_extensions.composers.barlicity.calculate_metric_coherence.txt
======================================================================

scamp_extensions.composers.barlicity.calculate_metric_coherence
***************************************************************

scamp_extensions.composers.barlicity.calculate_metric_coherence(rhythmic_strata_1: Sequence[Tuple | int], bar_tempo_1: float, rhythmic_strata_2: Sequence[Tuple | int], bar_tempo_2: float, standard_barlow: bool = True) -> float

   Calculates the "metric coherence" of two meters, as described on
   pages 46-47 of Barlow's "On Musiquantics". Essentially this is a
   (square) correlation between the indispensabilities of the two
   meters when they are placed side-by-side. Often this will require
   first subdiving one or both of the meters further so that they
   share a common basic pulse.

   Parameters:
      * **rhythmic_strata_1** -- Metric strata defining the first
        meter, of the exact same type that would be passed to
        "get_indispensability_array()" or to
        "get_standard_indispensability_array()". (Which of these
        functions it gets passed to depends on the *standard_barlow*
        argument.

      * **bar_tempo_1** -- Number of complete cycles of the first
        meter per minute.

      * **rhythmic_strata_2** -- Metric strata defining the second
        meter.

      * **bar_tempo_2** -- Number of complete cycles of the second
        meter per minute.

      * **standard_barlow** -- Whether or not to interpret the
        rhythmic strata using the standard Barlow version of
        indispensability, or my slightly broader version that allows
        additive layers.

   Returns:
      the coherence of the two meters as a float between 0 and 1


======================================================================
=== FILE: scamp_extensions.composers/scamp_extensions.composers.barlicity.calculate_metric_similarity.txt
======================================================================

scamp_extensions.composers.barlicity.calculate_metric_similarity
****************************************************************

scamp_extensions.composers.barlicity.calculate_metric_similarity(rhythmic_strata_away: Sequence[Tuple | int], bar_tempo_away: float, rhythmic_strata_home: Sequence[Tuple | int], bar_tempo_home: float, standard_barlow: bool = True)

   As Barlow explains on page 46 of "On Musiquantics," the metric
   coherece of a meter with itself is not always 1. This is because
   metric coherence conflates a measurement of the similarity of two
   meters with a measurement of the complexity of each of these
   meters. Metric similarity compensates for this by comparing a
   "home" meter with an "away" meter, and dividing the coherence of
   the two meters by the auto_coherence of the first meter with
   itself. With this scaling, the metric similarity of a meter with
   itself is always 1. (Note that this is not commutative the
   similarity of A to B is not the same as the similarity of B to A.
   This is why we distinguish a home from an away meter.)

   Parameters:
      * **rhythmic_strata_away** -- see
        "calculate_metric_coherence()".

      * **bar_tempo_away** -- see "calculate_metric_coherence()".

      * **rhythmic_strata_home** -- see
        "calculate_metric_coherence()".

      * **bar_tempo_home** -- see "calculate_metric_coherence()".

      * **standard_barlow** -- see "calculate_metric_coherence()".

   Returns:
      the similarity of the two meters as a float between 0 and 1


======================================================================
=== FILE: scamp_extensions.composers/scamp_extensions.composers.barlicity.get_indispensability_array.txt
======================================================================

scamp_extensions.composers.barlicity.get_indispensability_array
***************************************************************

scamp_extensions.composers.barlicity.get_indispensability_array(rhythmic_strata: Sequence[Tuple | int], normalize: bool = False) -> Sequence[IntOrFloat]

   A slightly more general approach to indispensability than the one
   proposed by Barlow. In this version, each rhythmic layer can be a
   tuple representing an additive grouping. Thus a 3+2+3 layer would
   be represented by (3, 2, 3). Rhythmic layers can also simply be
   numbers, in which case their indispensabilities are treated as
   increasing monotonically towards the downbeat.

   Parameters:
      * **rhythmic_strata** -- List of tuples representing rhythmic
        strata, or simple numbers

      * **normalize** -- if True, scale indispensabilities to go from
        0 to 1

   Returns:
      a list of ints or floats representing the indispensabilities or
      normalized indispensabilities, respectively


======================================================================
=== FILE: scamp_extensions.composers/scamp_extensions.composers.barlicity.get_standard_indispensability_array.txt
======================================================================

scamp_extensions.composers.barlicity.get_standard_indispensability_array
************************************************************************

scamp_extensions.composers.barlicity.get_standard_indispensability_array(rhythmic_strata: Sequence[int], normalize: bool = False) -> Sequence[IntOrFloat]

   Returns a list of the indispensabilities of different pulses in a
   meter defined by the rhythmic_strata. (See Barlow's "On
   Musiquantics", http://clarlow.org/wp-content/uploads/2016/10/On-
   MusiquanticsA4.pdf)

   Parameters:
      * **rhythmic_strata** -- a tuple representing the rhythmic
        groupings from large scale to small scale. For instance, the
        sixteenth-note pulses in a measure of 9/8 would be represented
        by (3, 3, 2), since there are three beats of three eighth
        notes, each of which has two sixteenth notes.

      * **normalize** -- if True, scale all indispensabilities to the
        range 0 to 1

   Returns:
      a list of integer indispensabilities, or float if normalize is
      set to true


======================================================================
=== FILE: scamp_extensions.composers/scamp_extensions.composers.barlicity.harmonicity.txt
======================================================================

scamp_extensions.composers.barlicity.harmonicity
************************************************

scamp_extensions.composers.barlicity.harmonicity(p: int, q: int) -> float

   Returns a number representing the simplicity (and thereby a kind of
   consonance) of an interval with frequency ratio of p/q.


======================================================================
=== FILE: scamp_extensions.composers/scamp_extensions.composers.barlicity.indigestibility.txt
======================================================================

scamp_extensions.composers.barlicity.indigestibility
****************************************************

scamp_extensions.composers.barlicity.indigestibility(n: int) -> float

   Returns a number representing how hard it is for a human to divide
   an object (e.g. cake, span of time) into n equal pieces. (See
   Clarence Barlow's "Musiquantics".)


======================================================================
=== FILE: scamp_extensions.composers/scamp_extensions.composers.barlicity.rationalize_scale.txt
======================================================================

scamp_extensions.composers.barlicity.rationalize_scale
******************************************************

scamp_extensions.composers.barlicity.rationalize_scale(cents_values: Sequence[float], nominal_tolerance: float, min_harmonicity: float, num_candidates: int, num_to_return: int = None, write_pretty: bool = False) -> Tuple[Sequence, float] | Sequence[Tuple[Sequence, float]]

   Uses Clarence Barlow's algorithms for scale rationalization to
   determine optimal rational tunings given an input scale in cents
   values. Candidate scales are generated by finding rational
   frequency ratios from the start note that satisfy the minimum
   harmonicity requirement, and that resolve to near the specified
   number of cents. The nominal tolerance specifies the maximum
   acceptable deviation from the desired cents value. Having generated
   interval candidates for each scale degree, all possible scales
   using these candidates are compared, resulting in a ranking from
   highest to lowest "specific harmonicity" (which is just a measure
   of how simple the intrascalar ratios are)..

   Parameters:
      * **cents_values** -- An array of cent values for the pitches of
        the scale, all in reference to a distance from the first
        degree of the scale

      * **nominal_tolerance** -- Number of cents that ratio candidates
        are allowed to deviate from the specified cents value.
        (Intervals that fall further away also rank lower when
        choosing the top candidates.)

      * **min_harmonicity** -- Minimum harmonicity of intervals used
        to generate interval candidates.

      * **num_candidates** -- Number of alternative candidates
        considered for each interval.

      * **num_to_return** -- if None, we just return the best tuning
        (or a list of equally best tunings) and the specific
        harmonicity. If a number n, we return a list of the top n
        tunings as ordered pairs (tuning, harmonicity)

      * **write_pretty** -- if True, it returns a list fraction
        strings (easier to read); if false, a list of tuples

   Returns:
      a list of (tuning, specific_harmonicity) tuples, if n > 1,
      otherwise just the (tuning, harmonicity) pair for the scale with
      greatest specific harmonicity.


======================================================================
=== FILE: scamp_extensions.composers/scamp_extensions.composers.barlicity.txt
======================================================================

scamp_extensions.composers.barlicity
************************************

Module containing implementations of many of Clarence Barlow's
theoretical constructs. These include:

   * Indigestibility

   * Harmonicity (including harmonicity-based scale rationalization)

   * Rhythmic indispensability

   * Metric Coherence

All of these are described in his book, "On Musiquantics".
(http://clarlow.org/wp-content/uploads/2016/10/On-MusiquanticsA4.pdf)

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "calculate | Calculates the "metric coherence" of two meters, as described on pages 46-47 of Barlow's   |
| _metric_co | "On Musiquantics".                                                                         |
| herence"(. |                                                                                            |
| ..[, ...]) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "calculate | As Barlow explains on page 46 of "On Musiquantics," the metric coherece of a meter with    |
| _metric_si | itself is not always 1.                                                                    |
| milarity"( |                                                                                            |
| ...[,      |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "get_indis | A slightly more general approach to indispensability than the one proposed by Barlow.      |
| pensabilit |                                                                                            |
| y_array"(r |                                                                                            |
| hythmic_st |                                                                                            |
| rata)      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "get_stand | Returns a list of the indispensabilities of different pulses in a meter defined by the     |
| ard_indisp | rhythmic_strata.                                                                           |
| ensability |                                                                                            |
| _array"(.. |                                                                                            |
| .[, ...])  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "harmonici | Returns a number representing the simplicity (and thereby a kind of consonance) of an      |
| ty"(p, q)  | interval with frequency ratio of p/q.                                                      |
+------------+--------------------------------------------------------------------------------------------+
| "indigesti | Returns a number representing how hard it is for a human to divide an object (e.g. cake,   |
| bility"(n) | span of time) into n equal pieces.                                                         |
+------------+--------------------------------------------------------------------------------------------+
| "rationali | Uses Clarence Barlow's algorithms for scale rationalization to determine optimal rational  |
| ze_scale"( | tunings given an input scale in cents values.                                              |
| cents_valu |                                                                                            |
| es, ...[,  |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.composers.barlicity.calculate_metric_coherence

  * "calculate_metric_coherence()"

* scamp_extensions.composers.barlicity.calculate_metric_similarity

  * "calculate_metric_similarity()"

* scamp_extensions.composers.barlicity.get_indispensability_array

  * "get_indispensability_array()"

* scamp_extensions.composers.barlicity.get_standard_indispensability_a
  rray

  * "get_standard_indispensability_array()"

* scamp_extensions.composers.barlicity.harmonicity

  * "harmonicity()"

* scamp_extensions.composers.barlicity.indigestibility

  * "indigestibility()"

* scamp_extensions.composers.barlicity.rationalize_scale

  * "rationalize_scale()"


======================================================================
=== FILE: scamp_extensions.composers.txt
======================================================================

scamp_extensions.composers package
**********************************

Subpackage containing composer-specific tools and theoretical devices.

-[ Modules: ]-

+------------+--------------------------------------------------------------------------------------------+
| "barlicity | Module containing implementations of many of Clarence Barlow's theoretical constructs.     |
| "          |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.composers.barlicity

  * scamp_extensions.composers.barlicity.calculate_metric_coherence

    * "calculate_metric_coherence()"

  * scamp_extensions.composers.barlicity.calculate_metric_similarity

    * "calculate_metric_similarity()"

  * scamp_extensions.composers.barlicity.get_indispensability_array

    * "get_indispensability_array()"

  * scamp_extensions.composers.barlicity.get_standard_indispensability
    _array

    * "get_standard_indispensability_array()"

  * scamp_extensions.composers.barlicity.harmonicity

    * "harmonicity()"

  * scamp_extensions.composers.barlicity.indigestibility

    * "indigestibility()"

  * scamp_extensions.composers.barlicity.rationalize_scale

    * "rationalize_scale()"


======================================================================
=== FILE: scamp_extensions.engraving/scamp_extensions.engraving.note_graph.PartNoteGraph.txt
======================================================================

scamp_extensions.engraving.note_graph.PartNoteGraph
***************************************************

class scamp_extensions.engraving.note_graph.PartNoteGraph(performance_part: ~scamp.performance.PerformancePart, height_parameter: str = 'pitch', height_parameter_range: ~typing.Tuple[~numbers.Real, ~numbers.Real] = None, width_parameter: str = 'volume', width_parameter_range: ~typing.Tuple[~numbers.Real, ~numbers.Real] = None, width_range: ~typing.Tuple[~numbers.Real, ~numbers.Real] = (1, 20), color_parameter: str = None, color_parameter_range: ~typing.Tuple[~numbers.Real, ~numbers.Real] = None, color_map: ~typing.Callable[[~numbers.Real], ~typing.Tuple[~numbers.Real, ~numbers.Real, ~numbers.Real]] = <function default_color_map>, time_range: ~typing.Tuple[~numbers.Real, ~numbers.Real] = None, fill_color: str = 'black', outline_color: str = 'black', outline_width: ~numbers.Real = 1, guide_lines: ~typing.Sequence[~numbers.Real] = (), guide_line_width: ~numbers.Real = 2, guide_line_color: str = 'black', attack_only: bool = False)

   Bases: "object"

   Class that takes a performance part and a bunch of
   drawing/visualization settings, and can render to a
   *class:svgDraw.Drawing*.

   Parameters:
      * **performance_part** -- the PerformancePart on which to base
        this note graph

      * **height_parameter** -- the playback parameter of that governs
        each note's height on the graph; defaults to pitch

      * **height_parameter_range** -- range of values expected from
        the parameter that governs height. If the parameter is pitch,
        defaults to the min and max pitch found in the part. Otherwise
        defaults to (0, 1).

      * **width_parameter** -- the playback parameter of that governs
        each note's width on the graph; defaults to volume

      * **width_parameter_range** -- range of values expected from the
        parameter that governs width. If the parameter is pitch,
        defaults to the min and max pitch found in the part. Otherwise
        defaults to (0, 1).

      * **width_range** -- range of note widths mapped to in the
        drawing

      * **color_parameter** -- the parameter governing note color, if
        any (overrides fill_color); inactive by default

      * **color_parameter_range** -- range of values expected from the
        parameter that governs color. If the parameter is pitch,
        defaults to the min and max pitch found in the part. Otherwise
        defaults to (0, 1).

      * **color_map** -- function from the interval [0, 1] to an RGB
        color tuple, where 0 represents the color parameter at the
        bottom of its range and 1 at the top.

      * **time_range** -- time range to map horizontal space to;
        defaults to 0 to length of part

      * **fill_color** -- the fill color of note glyphs; overridden by
        color parameter, if active

      * **outline_color** -- note outline color

      * **outline_width** -- note outline width

      * **guide_lines** -- the values of the height parameter at which
        to draw horizontal guide lines.

      * **guide_line_width** -- width of the guide lines

      * **guide_line_color** -- color of the guide lines

      * **attack_only** -- if true, only draw the attack of each note
        as a circle.

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "render"(d | Draw this note graph into an existing drawing, within the rectangle described by           |
   | rawing, bo | *bottom_left* and *dimensions*.                                                            |
   | ttom_left, |                                                                                            |
   | dimensions |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "render_to | Render this note graph to an SVG file of its own.                                          |
   | _file"(fil |                                                                                            |
   | e_path, di |                                                                                            |
   | mensions[, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   render(drawing: Drawing, bottom_left: Tuple[Real, Real], dimensions: Tuple[Real, Real])

      Draw this note graph into an existing drawing, within the
      rectangle described by *bottom_left* and *dimensions*.

      Parameters:
         * **drawing** -- the "drawsvg.Drawing" to draw into

         * **bottom_left** -- the (x, y) coordinate of the bottom left
           corner of the graph

         * **dimensions** -- the (width, height) of the graph

   render_to_file(file_path, dimensions, bg_color=None, h_padding=100, v_padding=100, pixel_scale=2)

      Render this note graph to an SVG file of its own.

      Parameters:
         * **file_path** -- path of the SVG file to write

         * **dimensions** -- the (width, height) of the image, padding
           included

         * **bg_color** -- background color of the image; left
           transparent if None

         * **h_padding** -- horizontal padding between the graph and
           the edge of the image

         * **v_padding** -- vertical padding between the graph and the
           edge of the image

         * **pixel_scale** -- factor by which to scale the image's
           pixel dimensions, for higher resolution


======================================================================
=== FILE: scamp_extensions.engraving/scamp_extensions.engraving.note_graph.default_color_map.txt
======================================================================

scamp_extensions.engraving.note_graph.default_color_map
*******************************************************

scamp_extensions.engraving.note_graph.default_color_map(intensity)

   The color map used by a "PartNoteGraph" unless another is given: a
   blue-to-red gradient.

   Parameters:
      **intensity** -- a value from 0 to 1

   Returns:
      the corresponding (red, green, blue) tuple, each component from
      0 to 255


======================================================================
=== FILE: scamp_extensions.engraving/scamp_extensions.engraving.note_graph.get_fill.txt
======================================================================

scamp_extensions.engraving.note_graph.get_fill
**********************************************

scamp_extensions.engraving.note_graph.get_fill(parameter, start_x, end_x, color_map=<function default_color_map>, value_range=None)

   The SVG fill to use for a note whose color is governed by the given
   parameter value: a gradient if that value is an envelope, and a
   plain hex color if it is a constant.

   Parameters:
      * **parameter** -- the value of the note's color parameter,
        either a number or an "Envelope"

      * **start_x** -- x coordinate at which the note starts

      * **end_x** -- x coordinate at which the note ends

      * **color_map** -- function from the interval [0, 1] to an (red,
        green, blue) tuple

      * **value_range** -- the (min, max) range of parameter values to
        map onto that interval; if None, the values are taken to
        already run from 0 to 1


======================================================================
=== FILE: scamp_extensions.engraving/scamp_extensions.engraving.note_graph.make_intensity_gradient.txt
======================================================================

scamp_extensions.engraving.note_graph.make_intensity_gradient
*************************************************************

scamp_extensions.engraving.note_graph.make_intensity_gradient(envelope, start_x, end_x, color_map=<function default_color_map>, value_range=None)

   Create an SVG linear gradient that spans horizontally from
   *start_x* to *end_x*, taking its color at each point from the value
   of the given envelope there. Used to color a note whose color
   parameter changes over the course of that note.

   Parameters:
      * **envelope** -- the envelope whose value determines the color
        along the gradient

      * **start_x** -- x coordinate at which the gradient starts

      * **end_x** -- x coordinate at which the gradient ends

      * **color_map** -- function from the interval [0, 1] to an (red,
        green, blue) tuple

      * **value_range** -- the (min, max) range of envelope values to
        map onto that interval; if None, the envelope's values are
        taken to already run from 0 to 1


======================================================================
=== FILE: scamp_extensions.engraving/scamp_extensions.engraving.note_graph.rgb_to_hex.txt
======================================================================

scamp_extensions.engraving.note_graph.rgb_to_hex
************************************************

scamp_extensions.engraving.note_graph.rgb_to_hex(rgb)

   Convert an (red, green, blue) tuple, each component from 0 to 255,
   to a hex color string like "#ff7a00".

   Parameters:
      **rgb** -- the (red, green, blue) tuple to convert


======================================================================
=== FILE: scamp_extensions.engraving/scamp_extensions.engraving.note_graph.txt
======================================================================

scamp_extensions.engraving.note_graph
*************************************

Module containing the "PartNoteGraph" class, which makes it possible
to draw the notes of a "PerformancePart" to an SVG file. Ultimately, I
plan to make it so that you can save a whole Performance to an SVG
file or even to a PDF.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "PartNoteG | Class that takes a performance part and a bunch of drawing/visualization settings, and can |
| raph"(perf | render to a *class:svgDraw.Drawing*.                                                       |
| ormance_pa |                                                                                            |
| rt, ...)   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.engraving.note_graph.PartNoteGraph

  * "PartNoteGraph"

    * "PartNoteGraph.render()"

    * "PartNoteGraph.render_to_file()"

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "default_c | The color map used by a "PartNoteGraph" unless another is given: a blue-to-red gradient.   |
| olor_map"( |                                                                                            |
| intensity) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "get_fill" | The SVG fill to use for a note whose color is governed by the given parameter value: a     |
| (parameter | gradient if that value is an envelope, and a plain hex color if it is a constant.          |
| , start_x, |                                                                                            |
| end_x[,    |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "make_inte | Create an SVG linear gradient that spans horizontally from *start_x* to *end_x*, taking    |
| nsity_grad | its color at each point from the value of the given envelope there.                        |
| ient"(enve |                                                                                            |
| lope,      |                                                                                            |
| start_x,   |                                                                                            |
| end_x)     |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "rgb_to_he | Convert an (red, green, blue) tuple, each component from 0 to 255, to a hex color string   |
| x"(rgb)    | like "#ff7a00".                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.engraving.note_graph.default_color_map

  * "default_color_map()"

* scamp_extensions.engraving.note_graph.get_fill

  * "get_fill()"

* scamp_extensions.engraving.note_graph.make_intensity_gradient

  * "make_intensity_gradient()"

* scamp_extensions.engraving.note_graph.rgb_to_hex

  * "rgb_to_hex()"


======================================================================
=== FILE: scamp_extensions.engraving.txt
======================================================================

scamp_extensions.engraving package
**********************************

Subpackage containing engraving-related extensions.

-[ Modules: ]-

+------------+--------------------------------------------------------------------------------------------+
| "note_grap | Module containing the "PartNoteGraph" class, which makes it possible to draw the notes of  |
| h"         | a "PerformancePart" to an SVG file.                                                        |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.engraving.note_graph

  * scamp_extensions.engraving.note_graph.PartNoteGraph

    * "PartNoteGraph"

      * "PartNoteGraph.render()"

      * "PartNoteGraph.render_to_file()"

  * scamp_extensions.engraving.note_graph.default_color_map

    * "default_color_map()"

  * scamp_extensions.engraving.note_graph.get_fill

    * "get_fill()"

  * scamp_extensions.engraving.note_graph.make_intensity_gradient

    * "make_intensity_gradient()"

  * scamp_extensions.engraving.note_graph.rgb_to_hex

    * "rgb_to_hex()"

-[ Public-Facing API (result of *import **): ]-

+------------+--------------------------------------------------------------------------------------------+
| "PartNoteG | Class that takes a performance part and a bunch of drawing/visualization settings, and can |
| raph"(perf | render to a *class:svgDraw.Drawing*.                                                       |
| ormance_pa |                                                                                            |
| rt, ...)   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


======================================================================
=== FILE: scamp_extensions.interaction/scamp_extensions.interaction.key_plane.KeyPlane.txt
======================================================================

scamp_extensions.interaction.key_plane.KeyPlane
***********************************************

class scamp_extensions.interaction.key_plane.KeyPlane(callback: Callable, normalize_coordinates: bool = False)

   Bases: "object"

   Abstraction used to transform keyboard input into a two-dimensional
   control space. Each key pressed corresponds to a vertical and
   horizontal position, which is passed to the callback function,
   along with (optionally) whether it was an up or down keystroke and
   what modifiers were present.

   Parameters:
      * **callback** -- a function of the form "callback(coordinates,
        up_or_down, modifiers)". Can also have the signature
        "callback(coordinates, up_or_down)" or
        "callback(coordinates)", in which case it is simply not passed
        that information.

      * **normalize_coordinates** -- if True, the keys coordinates go
        from 0-1 horizontally and vertically. if False, they go from
        0-3 (inclusive) vertically and 0-9, 10 or 11 horizontally
        (depending on row)

   Variables:
      **modifiers_down** -- a list of modifier keys currently pressed

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "start"([s | Starts up the KeyPlane listening to keyboard input.                                        |
   | uppress,   |                                                                                            |
   | blocking,  |                                                                                            |
   | session])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Attributes ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "all_modif | tuple of all names of modifier keys                                                        |
   | iers"      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "callback" | Callback function as described in the constructor, which responds to keyboard presses.     |
   +------------+--------------------------------------------------------------------------------------------+

   all_modifiers = ('ctrl', 'alt', 'shift', 'cmd', 'caps_lock', 'tab', 'enter', 'backspace', 'up', 'left', 'down', 'up')

      tuple of all names of modifier keys

   property callback: Callable

      Callback function as described in the constructor, which
      responds to keyboard presses.

   start(suppress: bool = False, blocking: bool = False, session: bool = None) -> None

      Starts up the KeyPlane listening to keyboard input.

      Parameters:
         * **suppress** -- if True, suppresses all other keyboard
           events so that nothing gets triggered unintentionally.
           (Make sure you have a way of stopping the script with the
           mouse!)

         * **blocking** -- if True causes this call to block (by
           calling "wait_forever()" on the underlying
           "scamp.session.Session").

         * **session** -- a "scamp.session.Session" on which to run
           the keyboard listener. If None, looks to see if there's a
           session running on the current thread.


======================================================================
=== FILE: scamp_extensions.interaction/scamp_extensions.interaction.key_plane.txt
======================================================================

scamp_extensions.interaction.key_plane
**************************************

Module containing the "KeyPlane" class for treating the keys of the
computer as a discrete, 2-dimensional input plane.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "KeyPlane" | Abstraction used to transform keyboard input into a two-dimensional control space.         |
| (callback[ |                                                                                            |
| , normaliz |                                                                                            |
| e_coordina |                                                                                            |
| tes])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.interaction.key_plane.KeyPlane

  * "KeyPlane"

    * "KeyPlane.all_modifiers"

    * "KeyPlane.callback"

    * "KeyPlane.start()"


======================================================================
=== FILE: scamp_extensions.interaction.txt
======================================================================

scamp_extensions.interaction package
************************************

Subpackage containing utilities for human interface devices and other
live interactions.

-[ Modules: ]-

+------------+--------------------------------------------------------------------------------------------+
| "key_plane | Module containing the "KeyPlane" class for treating the keys of the computer as a          |
| "          | discrete, 2-dimensional input plane.                                                       |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.interaction.key_plane

  * scamp_extensions.interaction.key_plane.KeyPlane

    * "KeyPlane"

      * "KeyPlane.all_modifiers"

      * "KeyPlane.callback"

      * "KeyPlane.start()"

-[ Public-Facing API (result of *import **): ]-

+------------+--------------------------------------------------------------------------------------------+
| "KeyPlane" | Abstraction used to transform keyboard input into a two-dimensional control space.         |
| (callback[ |                                                                                            |
| , normaliz |                                                                                            |
| e_coordina |                                                                                            |
| tes])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


======================================================================
=== FILE: scamp_extensions.parsing/scamp_extensions.parsing.midi.Note.txt
======================================================================

scamp_extensions.parsing.midi.Note
**********************************

class scamp_extensions.parsing.midi.Note(track, channel, pitch, volume, start_time, length)

   Bases: "tuple"

   -[ Inherited Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "count"(va | Return number of occurrences of value.                                                     |
   | lue, /)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "index"(va | Return first index of value.                                                               |
   | lue[,      |                                                                                            |
   | start,     |                                                                                            |
   | stop])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Attributes ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "channel"  | Alias for field number 1                                                                   |
   +------------+--------------------------------------------------------------------------------------------+
   | "length"   | Alias for field number 5                                                                   |
   +------------+--------------------------------------------------------------------------------------------+
   | "pitch"    | Alias for field number 2                                                                   |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_tim | Alias for field number 4                                                                   |
   | e"         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "track"    | Alias for field number 0                                                                   |
   +------------+--------------------------------------------------------------------------------------------+
   | "volume"   | Alias for field number 3                                                                   |
   +------------+--------------------------------------------------------------------------------------------+

   channel

      Alias for field number 1

   count(value, /)

      Return number of occurrences of value.

   index(value, start=0, stop=9223372036854775807, /)

      Return first index of value.

      Raises ValueError if the value is not present.

   length

      Alias for field number 5

   pitch

      Alias for field number 2

   start_time

      Alias for field number 4

   track

      Alias for field number 0

   volume

      Alias for field number 3


======================================================================
=== FILE: scamp_extensions.parsing/scamp_extensions.parsing.midi.scrape_midi_file_to_dict.txt
======================================================================

scamp_extensions.parsing.midi.scrape_midi_file_to_dict
******************************************************

scamp_extensions.parsing.midi.scrape_midi_file_to_dict(midi_file_path, filter_func=None) -> dict

   Scrapes a dictionary of note info from a MIDI file.

   Parameters:
      * **midi_file_path** -- the MIDI file path

      * **filter_func** -- function that takes a Note object and
        returns whether to include it

   Returns:
      a dict with the following keys, each of which is presented in
      chronological order of the notes from which they derive:
      "pitches", "start_times", "volumes", "lengths",
      "inter_onset_times" (how long since the last note started),
      "tracks"


======================================================================
=== FILE: scamp_extensions.parsing/scamp_extensions.parsing.midi.scrape_midi_file_to_note_list.txt
======================================================================

scamp_extensions.parsing.midi.scrape_midi_file_to_note_list
***********************************************************

scamp_extensions.parsing.midi.scrape_midi_file_to_note_list(midi_file_path, filter_func=None) -> List[Note]

   Scrapes a list of "Note" objects from all of the tracks of the
   given MIDI file.

   Parameters:
      * **midi_file_path** -- path to midi file

      * **filter_func** -- function that takes a Note object and
        returns whether to include it


======================================================================
=== FILE: scamp_extensions.parsing/scamp_extensions.parsing.midi.txt
======================================================================

scamp_extensions.parsing.midi
*****************************

Utilities for scraping notes from MIDI files.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "Note"(tra |                                                                                            |
| ck,        |                                                                                            |
| channel,   |                                                                                            |
| pitch,     |                                                                                            |
| volume,    |                                                                                            |
| ...)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.parsing.midi.Note

  * "Note"

    * "Note.channel"

    * "Note.count()"

    * "Note.index()"

    * "Note.length"

    * "Note.pitch"

    * "Note.start_time"

    * "Note.track"

    * "Note.volume"

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "scrape_mi | Scrapes a dictionary of note info from a MIDI file.                                        |
| di_file_to |                                                                                            |
| _dict"(mid |                                                                                            |
| i_file_pat |                                                                                            |
| h[, ...])  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "scrape_mi | Scrapes a list of "Note" objects from all of the tracks of the given MIDI file.            |
| di_file_to |                                                                                            |
| _note_list |                                                                                            |
| "(midi_fil |                                                                                            |
| e_path)    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.parsing.midi.scrape_midi_file_to_dict

  * "scrape_midi_file_to_dict()"

* scamp_extensions.parsing.midi.scrape_midi_file_to_note_list

  * "scrape_midi_file_to_note_list()"


======================================================================
=== FILE: scamp_extensions.parsing.txt
======================================================================

scamp_extensions.parsing package
********************************

Subpackage containing utilities for parsing data formats.

-[ Modules: ]-

+------------+--------------------------------------------------------------------------------------------+
| "midi"     | Utilities for scraping notes from MIDI files.                                              |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.parsing.midi

  * scamp_extensions.parsing.midi.Note

    * "Note"

      * "Note.channel"

      * "Note.count()"

      * "Note.index()"

      * "Note.length"

      * "Note.pitch"

      * "Note.start_time"

      * "Note.track"

      * "Note.volume"

  * scamp_extensions.parsing.midi.scrape_midi_file_to_dict

    * "scrape_midi_file_to_dict()"

  * scamp_extensions.parsing.midi.scrape_midi_file_to_note_list

    * "scrape_midi_file_to_note_list()"


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.chord_builder.chord_from_pitch_classes.txt
======================================================================

scamp_extensions.pitch.chord_builder.chord_from_pitch_classes
*************************************************************

scamp_extensions.pitch.chord_builder.chord_from_pitch_classes(pcs, min_pitch, max_pitch, num_notes, prefer_unique_pcs=True, spacing_and_range_prefs=('compact', 'mid', 'even'))

   Find the single voicing of the given pitch classes that best fits
   the given preferences. See "chords_from_pitch_classes()", of which
   this is the single-result version.

   Parameters:
      * **pcs** -- the pitch classes (integers from 0 to 11) to voice

      * **min_pitch** -- lowest MIDI pitch the voicing may use

      * **max_pitch** -- highest MIDI pitch the voicing may use

      * **num_notes** -- how many notes the chord should have; capped
        at the number of pitches available

      * **prefer_unique_pcs** -- if True, prefer voicings covering as
        many distinct pitch classes as possible

      * **spacing_and_range_prefs** -- the qualities to prefer, in
        decreasing order of priority

   Returns:
      the best voicing, as a tuple of MIDI pitches


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.chord_builder.chords_from_pitch_classes.txt
======================================================================

scamp_extensions.pitch.chord_builder.chords_from_pitch_classes
**************************************************************

scamp_extensions.pitch.chord_builder.chords_from_pitch_classes(pcs, min_pitch, max_pitch, num_notes, prefer_unique_pcs=True, spacing_and_range_prefs=('compact', 'mid', 'even'), how_many=1)

   Find the voicings of the given pitch classes that best fit the
   given preferences.

   Parameters:
      * **pcs** -- the pitch classes (integers from 0 to 11) to voice

      * **min_pitch** -- lowest MIDI pitch the voicing may use

      * **max_pitch** -- highest MIDI pitch the voicing may use

      * **num_notes** -- how many notes the chord should have; capped
        at the number of pitches available

      * **prefer_unique_pcs** -- if True, prefer voicings that cover
        as many distinct pitch classes as possible, ahead of any of
        the other preferences

      * **spacing_and_range_prefs** -- the qualities to prefer in a
        voicing, in decreasing order of priority. These are keys of
        "measurement_functions": "wide"/"compact" (spread out or close
        together), "even"/"uneven" (equally or unequally spaced), and
        "high"/"low"/"mid" (placement within the range).

      * **how_many** -- how many voicings to return

   Returns:
      a list of the best *how_many* voicings, each a tuple of MIDI
      pitches, best last


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.chord_builder.get_pcs_instances_in_range.txt
======================================================================

scamp_extensions.pitch.chord_builder.get_pcs_instances_in_range
***************************************************************

scamp_extensions.pitch.chord_builder.get_pcs_instances_in_range(pcs, min_pitch, max_pitch)

   Every pitch within the given range belonging to one of the given
   pitch classes.

   Parameters:
      * **pcs** -- the pitch classes (integers from 0 to 11) in
        question

      * **min_pitch** -- lowest MIDI pitch to consider (inclusive)

      * **max_pitch** -- highest MIDI pitch to consider (exclusive)


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.chord_builder.txt
======================================================================

scamp_extensions.pitch.chord_builder
************************************

Module containing functions for voicing a chord: given a set of pitch
classes and a range to place them in, these search the possible
voicings and return whichever one best fits the preferences given,
such as being compactly spaced or centered in the range.

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "chord_fro | Find the single voicing of the given pitch classes that best fits the given preferences.   |
| m_pitch_cl |                                                                                            |
| asses"(pcs |                                                                                            |
| ,          |                                                                                            |
| min_pitch, |                                                                                            |
| ...)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "chords_fr | Find the voicings of the given pitch classes that best fit the given preferences.          |
| om_pitch_c |                                                                                            |
| lasses"(pc |                                                                                            |
| s,         |                                                                                            |
| min_pitch, |                                                                                            |
| ...)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "get_pcs_i | Every pitch within the given range belonging to one of the given pitch classes.            |
| nstances_i |                                                                                            |
| n_range"(p |                                                                                            |
| cs,        |                                                                                            |
| min_pitch, |                                                                                            |
| ...)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.pitch.chord_builder.chord_from_pitch_classes

  * "chord_from_pitch_classes()"

* scamp_extensions.pitch.chord_builder.chords_from_pitch_classes

  * "chords_from_pitch_classes()"

* scamp_extensions.pitch.chord_builder.get_pcs_instances_in_range

  * "get_pcs_instances_in_range()"


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.scale.PitchInterval.txt
======================================================================

scamp_extensions.pitch.scale.PitchInterval
******************************************

class scamp_extensions.pitch.scale.PitchInterval(cents: float, ratio: Fraction)

   Bases: "SavesToJSON"

   Represents an interval between two pitches. This combines a cents
   displacement and a frequency ratio, allowing it to represent both
   just and equal-tempered intervals, or even a combination of both.
   PitchIntervals can be added, negated, and subtracted.

   Parameters:
      * **cents** -- cents displacement

      * **ratio** -- frequency ratio, either instead of or in addition
        to the cents displacement

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "parse"(re | Parses several different possible types of data into a PitchInterval object.               |
   | presentati |                                                                                            |
   | on)        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "to_cents" | Resolves this interval to its size in cents.                                               |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "to_half_s | Resolves this interval to its size in half steps.                                          |
   | teps"()    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "to_scala_ | Returns a string representation of this interval for use in exporting to scala files.      |
   | string"()  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Inherited Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "duplicate | Returns a copy of this object by serializing to and from JSON.                             |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_dump | Dump this object as a JSON string.                                                         |
   | s"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_load | Load this object from a JSON string.                                                       |
   | s"(s)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "load_from | Load this object from a JSON file with the given path.                                     |
   | _json"(fil |                                                                                            |
   | e_path)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "save_to_j | Save this object to a JSON file using the given path.                                      |
   | son"(file_ |                                                                                            |
   | path)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   classmethod parse(representation)

      Parses several different possible types of data into a
      PitchInterval object.

      Parameters:
         **representation** -- One of the following: - a float
         (representing cents) - an int or a Fraction object
         (representing a ratio) - a tuple of (cents, ratio) - a
         string, which will be evaluated as a (cents, ratio) tuple if
         it has a comma, and will be evaluated as a Fraction if it has
         a slash. e.g. "3" is a ratio, "37." is cents, "4/3" is a
         ratio, and "200., 5/4" is a cents displacement followed by a
         ratio.

      Returns:
         a PitchInterval

   to_cents() -> float

      Resolves this interval to its size in cents.

   to_half_steps() -> float

      Resolves this interval to its size in half steps.

   to_scala_string()

      Returns a string representation of this interval for use in
      exporting to scala files. Scala intervals can be either in cents
      or frequency ratio, however, unlike "PitchInterval", they cannot
      combine the two. Thus, if this PitchInterval combines the two,
      it will be converted to a flat cents value.

   duplicate() -> T

      Returns a copy of this object by serializing to and from JSON.

   json_dumps() -> str

      Dump this object as a JSON string. This uses a custom encoder
      that recognizes and appropriately converts any attributes that
      are object inheriting from SavesToJSON.

   classmethod json_loads(s: str) -> T

      Load this object from a JSON string. This uses a custom decoder
      that looks for a "_type" key in any object/dictionary being
      parsed and converts it to the class specified (assuming it a
      subclass of SavesToJSON).

      Parameters:
         **s** -- a string representing this object in JSON format

   classmethod load_from_json(file_path: str) -> T

      Load this object from a JSON file with the given path. This uses
      a custom decoder that looks for a "_type" key in any
      object/dictionary being parsed and converts it to the class
      specified (assuming it a subclass of SavesToJSON).

      Parameters:
         **file_path** -- path for loading the file

   save_to_json(file_path: str) -> None

      Save this object to a JSON file using the given path. This uses
      a custom encoder that recognizes and appropriately converts any
      attributes that are object inheriting from SavesToJSON.

      Parameters:
         **file_path** -- path for saving the file


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.scale.Scale.txt
======================================================================

scamp_extensions.pitch.scale.Scale
**********************************

class scamp_extensions.pitch.scale.Scale(scale_type: ScaleType, start_pitch: Real, cycle: bool = True)

   Bases: "SavesToJSON"

   Class representing a scale starting on a specific pitch. A "Scale"
   combines a "ScaleType" with a starting pitch, and also an option as
   to whether the pitch collection should cycle (as pretty much all
   the standard scales do). To illustrate the difference between a
   "ScaleType" and a "Scale", "D dorian" would be represented by a
   "Scale", whereas "dorian" would be represented by a "ScaleType".

   Parameters:
      * **scale_type** -- a "ScaleType" object

      * **start_pitch** -- a pitch to treat as the starting note of
        the scale

      * **cycle** -- whether or not this scale cycles. If so, the
        interval from the first pitch to the last pitch is treated as
        the cycle size.

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "aeolian"( | Convenience method for creating a aeolian scale with the given start pitch.                |
   | start_pitc |                                                                                            |
   | h[,        |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "blues"(st | Returns a 6-note blues scale starting on the specified pitch.                              |
   | art_pitch[ |                                                                                            |
   | , cycle])  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "ceil"(pit | Returns the nearest note of the scale above or equal to the given pitch.                   |
   | ch)        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "chromatic | Returns a 12-tone equal tempered chromatic scale starting on the specified pitch.          |
   | "([start_p |                                                                                            |
   | itch,      |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "degree_to | Given a degree of the scale, returns the pitch that it corresponds to.                     |
   | _pitch"(de |                                                                                            |
   | gree)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "diatonic" | Returns a diatonic scale starting on the specified pitch, and with the specified modal     |
   | (start_pit | shift.                                                                                     |
   | ch[, modal |                                                                                            |
   | _shift,    |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "dorian"(s | Convenience method for creating a dorian scale with the given start pitch.                 |
   | tart_pitch |                                                                                            |
   | [, cycle]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "equal_div | Convenience method for creating a EDO or equal division of a different interval.           |
   | isions"(st |                                                                                            |
   | art_pitch, |                                                                                            |
   | ...[,      |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "floor"(pi | Returns the nearest note of the scale below or equal to the given pitch.                   |
   | tch)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_pitc | Constructs a Scale from a list of seed pitches, given as floating- point MIDI pitch        |
   | hes"(seed_ | values.                                                                                    |
   | pitches[,  |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_scal | Constructs a Scale from a scala file located at the given file path, and a start pitch.    |
   | a_file"(fi |                                                                                            |
   | le_path, s |                                                                                            |
   | tart_pitch |                                                                                            |
   | [, cycle]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_star | Creates a scale from a start pitch and a sequence of intervals (either cents or frequency  |
   | t_pitch_an | ratios).                                                                                   |
   | d_cent_or_ |                                                                                            |
   | ratio_inte |                                                                                            |
   | rvals"(... |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "harmonic_ | Returns a harmonic minor scale starting on the specified pitch, and with the specified     |
   | minor"(sta | modal shift.                                                                               |
   | rt_pitch[, |                                                                                            |
   | modal_shif |                                                                                            |
   | t, cycle]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "ionian"(s | Alias of "Scale.diatonic()".                                                               |
   | tart_pitch |                                                                                            |
   | [, modal_s |                                                                                            |
   | hift,      |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "locrian"( | Convenience method for creating a locrian scale with the given start pitch.                |
   | start_pitc |                                                                                            |
   | h[,        |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "lydian"(s | Convenience method for creating a lydian scale with the given start pitch.                 |
   | tart_pitch |                                                                                            |
   | [, cycle]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "major"(st | Alias of "Scale.diatonic()".                                                               |
   | art_pitch[ |                                                                                            |
   | , modal_sh |                                                                                            |
   | ift,       |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "melodic_m | Returns a melodic minor scale starting on the specified pitch, and with the specified      |
   | inor"(star | modal shift.                                                                               |
   | t_pitch[,  |                                                                                            |
   | modal_shif |                                                                                            |
   | t, cycle]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "mixolydia | Convenience method for creating a mixolydian scale with the given start pitch.             |
   | n"(start_p |                                                                                            |
   | itch[,     |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "natural_m | Alias of "Scale.aeolian()".                                                                |
   | inor"(star |                                                                                            |
   | t_pitch[,  |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "octatonic | Returns an octatonic scale with the given start pitch.                                     |
   | "(start_pi |                                                                                            |
   | tch[,      |                                                                                            |
   | cycle, who |                                                                                            |
   | le_step_fi |                                                                                            |
   | rst])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pentatoni | Returns a pentatonic scale starting on the specified pitch, and with the specified modal   |
   | c"(start_p | shift.                                                                                     |
   | itch[, mod |                                                                                            |
   | al_shift,  |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pentatoni | Returns a pentatonic minor scale starting on the specified pitch.                          |
   | c_minor"(s |                                                                                            |
   | tart_pitch |                                                                                            |
   | [, cycle]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "phrygian" | Convenience method for creating a phrygian scale with the given start pitch.               |
   | (start_pit |                                                                                            |
   | ch[,       |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pitch_to_ | Given a pitch, returns the scale degree that it corresponds to.                            |
   | degree"(pi |                                                                                            |
   | tch)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "round"(pi | Rounds the given pitch to the nearest note of the scale.                                   |
   | tch)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "transpose | Transposes this scale (in place) by the given number of half steps.                        |
   | "(half_ste |                                                                                            |
   | ps)        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "transpose | Same as "Scale.transpose()", except that it returns a transposed copy, leaving this scale  |
   | d"(half_st | unaltered.                                                                                 |
   | eps)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "whole_ton | Returns a whole tone scale with the given start pitch.                                     |
   | e"(start_p |                                                                                            |
   | itch[,     |                                                                                            |
   | cycle])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Inherited Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "duplicate | Returns a copy of this object by serializing to and from JSON.                             |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_dump | Dump this object as a JSON string.                                                         |
   | s"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_load | Load this object from a JSON string.                                                       |
   | s"(s)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "load_from | Load this object from a JSON file with the given path.                                     |
   | _json"(fil |                                                                                            |
   | e_path)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "save_to_j | Save this object to a JSON file using the given path.                                      |
   | son"(file_ |                                                                                            |
   | path)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Attributes ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "cycle"    | Whether or not this scale repeats after a full cycle.                                      |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_pit | The pitch that scale starts from.                                                          |
   | ch"        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   property start_pitch: Real

      The pitch that scale starts from.

   property cycle: bool

      Whether or not this scale repeats after a full cycle.

   classmethod from_pitches(seed_pitches: Sequence[Real], cycle: bool = True) -> Scale

      Constructs a Scale from a list of seed pitches, given as
      floating-point MIDI pitch values. For instance, a C major scale
      could be constructed by calling Scale.from_pitches([60, 62, 64,
      65, 67, 69, 71, 72]). Note that the upper C needs to be
      specified, since it is not assumed that scales will be octave
      repeating, and the repeat interval is given by the distance
      between the first and last seed pitch. Also note that this
      particular C major scale would place scale degree 0 at middle C,
      whereas Scale.from_pitches([48, 50, 52, 53, 55, 57, 59, 60])
      would place it an octave lower.

      Parameters:
         * **seed_pitches** -- a list of floating-point MIDI pitch
           values.

         * **cycle** -- Whether or not to cycle the scale, creating
           multiple "octaves" (or perhaps not octaves if the scale
           repeats at a different interval.

   classmethod from_scala_file(file_path: str, start_pitch: Real, cycle: bool = True) -> Scale

      Constructs a Scale from a scala file located at the given file
      path, and a start pitch.

      Parameters:
         * **file_path** -- path of the scala file to load

         * **start_pitch** -- the pitch to define as scale degree 0

         * **cycle** -- whether or not this scale is treated as cyclic

   classmethod from_start_pitch_and_cent_or_ratio_intervals(start_pitch: Real, intervals, cycle: bool = True) -> Scale

      Creates a scale from a start pitch and a sequence of intervals
      (either cents or frequency ratios).

      Parameters:
         * **start_pitch** -- The pitch to start on

         * **intervals** -- a sequence of intervals above the start
           pitch. These can be either "PitchInterval" objects or
           anything that can be interpreted by
           "PitchInterval.parse()".

         * **cycle** -- whether or not this scale is treated as
           cyclic. See explanation in "Scale.from_pitches()" about
           defining cyclic scales.

   degree_to_pitch(degree: Real) -> float

      Given a degree of the scale, returns the pitch that it
      corresponds to. Degree 0 corresponds to the start pitch, and
      negative degrees correspond to notes below the start pitch (for
      cyclical scales). Fractional degrees are possible and result in
      pitches interpolated between the scale degrees. The first
      argument can optionally be a list, tuple, or iterator, in which
      case this is performed on each element.

      Parameters:
         **degree** -- a (potentially floating-point) scale degree

   pitch_to_degree(pitch: Real) -> float

      Given a pitch, returns the scale degree that it corresponds to.
      Pitches that lie in between the notes of the scale will return
      fractional degrees via interpolation. The first argument can
      optionally be a list, tuple, or iterator, in which case this is
      performed on each element.

      Parameters:
         **pitch** -- a pitch, potentially in between scale degrees

   round(pitch: Real) -> float

      Rounds the given pitch to the nearest note of the scale. The
      first argument can optionally be a list, tuple, or iterator, in
      which case this is performed on each element.

   floor(pitch: Real) -> float

      Returns the nearest note of the scale below or equal to the
      given pitch. The first argument can optionally be a list, tuple,
      or iterator, in which case this is performed on each element.

   ceil(pitch: Real) -> float

      Returns the nearest note of the scale above or equal to the
      given pitch. The first argument can optionally be a list, tuple,
      or iterator, in which case this is performed on each element.

   transpose(half_steps: float) -> Scale

      Transposes this scale (in place) by the given number of half
      steps.

      Parameters:
         **half_steps** -- number of half steps to transpose up or
         down by

      Returns:
         self, for chaining purposes

   transposed(half_steps: float) -> Scale

      Same as "Scale.transpose()", except that it returns a transposed
      copy, leaving this scale unaltered.

   classmethod chromatic(start_pitch: Real = 60, cycle: bool = True) -> Scale

      Returns a 12-tone equal tempered chromatic scale starting on the
      specified pitch.

      Parameters:
         * **start_pitch** -- the pitch this scale starts from
           (doesn't affect the scale in this case, but affects where
           we count scale degrees from).

         * **cycle** -- whether or not this scale repeats after an
           octave or is constrained to a single octave.

   classmethod diatonic(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) -> Scale

      Returns a diatonic scale starting on the specified pitch, and
      with the specified modal shift.

      Parameters:
         * **start_pitch** -- the pitch this scale starts from

         * **modal_shift** -- how many steps up or down to shift the
           scale's interval relationships. 0 is ionian, 1 is dorian, 2
           is phrygian, etc. (There are also convenience methods for
           creating these modal scales.)

         * **cycle** -- whether or not this scale repeats after an
           octave or is constrained to a single octave.

   classmethod major(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) -> Scale

      Alias of "Scale.diatonic()".

   classmethod ionian(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) -> Scale

      Alias of "Scale.diatonic()".

   classmethod dorian(start_pitch: Real, cycle: bool = True) -> Scale

      Convenience method for creating a dorian scale with the given
      start pitch. (Same as "Scale.diatonic()" with a modal shift of
      1.)

   classmethod phrygian(start_pitch: Real, cycle: bool = True) -> Scale

      Convenience method for creating a phrygian scale with the given
      start pitch. (Same as "Scale.diatonic()" with a modal shift of
      2.)

   classmethod lydian(start_pitch: Real, cycle: bool = True) -> Scale

      Convenience method for creating a lydian scale with the given
      start pitch. (Same as "Scale.diatonic()" with a modal shift of
      3.)

   classmethod mixolydian(start_pitch: Real, cycle: bool = True) -> Scale

      Convenience method for creating a mixolydian scale with the
      given start pitch. (Same as "Scale.diatonic()" with a modal
      shift of 4.)

   classmethod aeolian(start_pitch: Real, cycle: bool = True) -> Scale

      Convenience method for creating a aeolian scale with the given
      start pitch. (Same as "Scale.diatonic()" with a modal shift of
      5.)

   classmethod natural_minor(start_pitch: Real, cycle: bool = True) -> Scale

      Alias of "Scale.aeolian()".

   classmethod locrian(start_pitch: Real, cycle: bool = True) -> Scale

      Convenience method for creating a locrian scale with the given
      start pitch. (Same as "Scale.diatonic()" with a modal shift of
      6.)

   classmethod harmonic_minor(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) -> Scale

      Returns a harmonic minor scale starting on the specified pitch,
      and with the specified modal shift.

      Parameters:
         * **start_pitch** -- the pitch this scale starts from

         * **modal_shift** -- How many steps up or down to shift the
           scale's interval relationships. To get a regular harmonic
           minor scale, simply use the default modal shift of 0.

         * **cycle** -- whether or not this scale repeats after an
           octave or is constrained to a single octave.

   classmethod melodic_minor(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) -> Scale

      Returns a melodic minor scale starting on the specified pitch,
      and with the specified modal shift.

      Parameters:
         * **start_pitch** -- the pitch this scale starts from

         * **modal_shift** -- How many steps up or down to shift the
           scale's interval relationships. To get a regular melodic
           minor scale, simply use the default modal shift of 0. A so-
           called acoustic scale (major sharp-4, flat-7) can be
           produced with a modal shift of 4.

         * **cycle** -- whether or not this scale repeats after an
           octave or is constrained to a single octave.

   classmethod whole_tone(start_pitch: Real, cycle: bool = True) -> Scale

      Returns a whole tone scale with the given start pitch.

      Parameters:
         * **start_pitch** -- the pitch this scale starts from

         * **cycle** -- whether or not this scale repeats after an
           octave or is constrained to a single octave.

   classmethod octatonic(start_pitch: Real, cycle: bool = True, whole_step_first: bool = True) -> Scale

      Returns an octatonic scale with the given start pitch.

      Parameters:
         * **start_pitch** -- the pitch this scale starts from

         * **cycle** -- whether or not this scale repeats after an
           octave or is constrained to a single octave.

         * **whole_step_first** -- whether this is a whole-half or
           half-whole octatonic scale.

   classmethod pentatonic(start_pitch: Real, modal_shift: int = 0, cycle: bool = True) -> Scale

      Returns a pentatonic scale starting on the specified pitch, and
      with the specified modal shift.

      Parameters:
         * **start_pitch** -- the pitch this scale starts from

         * **modal_shift** -- How many steps up or down to shift the
           scale's interval relationships. To get a regular harmonic
           minor scale, simply use the default modal shift of 0.

         * **cycle** -- whether or not this scale repeats after an
           octave or is constrained to a single octave.

   classmethod pentatonic_minor(start_pitch: Real, cycle: bool = True) -> Scale

      Returns a pentatonic minor scale starting on the specified
      pitch.

      Parameters:
         * **start_pitch** -- the pitch this scale starts from

         * **cycle** -- whether or not this scale repeats after an
           octave or is constrained to a single octave.

   classmethod blues(start_pitch: Real, cycle: bool = True) -> Scale

      Returns a 6-note blues scale starting on the specified pitch.

      Parameters:
         * **start_pitch** -- the pitch this scale starts from

         * **cycle** -- whether or not this scale repeats after an
           octave or is constrained to a single octave.

   classmethod equal_divisions(start_pitch: Real, interval_to_divide: int, num_divisions: int, cycle: bool = True) -> ScaleType

      Convenience method for creating a EDO or equal division of a
      different interval.

   duplicate() -> T

      Returns a copy of this object by serializing to and from JSON.

   json_dumps() -> str

      Dump this object as a JSON string. This uses a custom encoder
      that recognizes and appropriately converts any attributes that
      are object inheriting from SavesToJSON.

   classmethod json_loads(s: str) -> T

      Load this object from a JSON string. This uses a custom decoder
      that looks for a "_type" key in any object/dictionary being
      parsed and converts it to the class specified (assuming it a
      subclass of SavesToJSON).

      Parameters:
         **s** -- a string representing this object in JSON format

   classmethod load_from_json(file_path: str) -> T

      Load this object from a JSON file with the given path. This uses
      a custom decoder that looks for a "_type" key in any
      object/dictionary being parsed and converts it to the class
      specified (assuming it a subclass of SavesToJSON).

      Parameters:
         **file_path** -- path for loading the file

   save_to_json(file_path: str) -> None

      Save this object to a JSON file using the given path. This uses
      a custom encoder that recognizes and appropriately converts any
      attributes that are object inheriting from SavesToJSON.

      Parameters:
         **file_path** -- path for saving the file


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.scale.ScaleType.txt
======================================================================

scamp_extensions.pitch.scale.ScaleType
**************************************

class scamp_extensions.pitch.scale.ScaleType(*intervals)

   Bases: "SavesToJSON"

   A ScaleType represents the intervallic relationships in a scale
   without specifying a specific starting point. This maps closely to
   what is represented in a Scala .scl file, which is why this object
   can load from and save to that format. In fact, the one difference
   between the data stored here and that stored in a .scl file is that
   this object allows a scale degree to be defined by both a cents
   offset and a subsequently applied ratio.

   Parameters:
      **intervals** -- a sequence of intervals above the starting
      note. These can be either "PitchInterval" objects or anything
      that can be interpreted by "PitchInterval.parse()".

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "aeolian"( | Convenience method for creating an aeolian ScaleType.                                      |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "blues"()  | Convenience method for creating a blues ScaleType.                                         |
   +------------+--------------------------------------------------------------------------------------------+
   | "chromatic | Returns a 12-tone equal tempered chromatic ScaleType.                                      |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "diatonic" | Returns a diatonic ScaleType with the specified modal shift.                               |
   | ([modal_sh |                                                                                            |
   | ift])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "dorian"() | Convenience method for creating a dorian ScaleType.                                        |
   +------------+--------------------------------------------------------------------------------------------+
   | "equal_div | Convenience method for creating a blues ScaleType.                                         |
   | isions"(in |                                                                                            |
   | terval_to_ |                                                                                            |
   | divide,    |                                                                                            |
   | ...)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "harmonic_ | Returns a harmonic minor ScaleType with the specified modal shift.                         |
   | minor"([mo |                                                                                            |
   | dal_shift] |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "ionian"([ | Alias of "ScaleType.diatonic()".                                                           |
   | modal_shif |                                                                                            |
   | t])        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "load_from | Loads a ScaleType from a scala file.                                                       |
   | _scala"(fi |                                                                                            |
   | le_path)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "locrian"( | Convenience method for creating an locrian ScaleType.                                      |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "lydian"() | Convenience method for creating a lydian ScaleType.                                        |
   +------------+--------------------------------------------------------------------------------------------+
   | "major"([m | Alias of "ScaleType.diatonic()".                                                           |
   | odal_shift |                                                                                            |
   | ])         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "melodic_m | Returns a melodic minor ScaleType with the specified modal shift.                          |
   | inor"([mod |                                                                                            |
   | al_shift]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "mixolydia | Convenience method for creating a myxolydian ScaleType.                                    |
   | n"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "natural_m | Alias of "ScaleType.aeolian()".                                                            |
   | inor"()    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "octatonic | Convenience method for creating an octatonic (alternating whole and half steps) ScaleType  |
   | "([whole_s |                                                                                            |
   | tep_first] |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pentatoni | Returns a pentatonic ScaleType with the specified modal shift.                             |
   | c"([modal_ |                                                                                            |
   | shift])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pentatoni | Convenience method for creating a pentatonic minor ScaleType.                              |
   | c_minor"() |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "phrygian" | Convenience method for creating a phrygian ScaleType.                                      |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "rotate"(s | Rotates the step sizes of this scale type in the manner of a modal shift.                  |
   | teps[,     |                                                                                            |
   | in_place]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "save_to_s | Converts and saves this ScaleType to a scala file at the given file path.                  |
   | cala"(file |                                                                                            |
   | _path[, de |                                                                                            |
   | scription] |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "to_half_s | Returns a list of floats representing the number of half steps from the starting pitch for |
   | teps"()    | each scale degree.                                                                         |
   +------------+--------------------------------------------------------------------------------------------+
   | "whole_ton | Convenience method for creating a whole tone ScaleType.                                    |
   | e"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Inherited Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "duplicate | Returns a copy of this object by serializing to and from JSON.                             |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_dump | Dump this object as a JSON string.                                                         |
   | s"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_load | Load this object from a JSON string.                                                       |
   | s"(s)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "load_from | Load this object from a JSON file with the given path.                                     |
   | _json"(fil |                                                                                            |
   | e_path)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "save_to_j | Save this object to a JSON file using the given path.                                      |
   | son"(file_ |                                                                                            |
   | path)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   to_half_steps() -> Sequence[float]

      Returns a list of floats representing the number of half steps
      from the starting pitch for each scale degree.

   rotate(steps: int, in_place: bool = True) -> ScaleType

      Rotates the step sizes of this scale type in the manner of a
      modal shift. E.g. going from ionian to lydian would be a
      rotation of 3.

      Parameters:
         * **steps** -- the number of steps to shift the starting
           point of the scale up or down by. Can be negative.

         * **in_place** -- whether to modify this ScaleType in place,
           or to return a modified copy.

      Returns:
         the modified ScaleType

   classmethod chromatic()

      Returns a 12-tone equal tempered chromatic ScaleType.

   classmethod diatonic(modal_shift: int = 0) -> ScaleType

      Returns a diatonic ScaleType with the specified modal shift.

      Parameters:
         **modal_shift** -- how many steps up or down to shift the
         starting note of the scale. 0 returns ionian, 1 returns
         dorian, 2 returns phrygian, etc. (There are also convenience
         methods for creating these modal scale types.)

   classmethod major(modal_shift: int = 0) -> ScaleType

      Alias of "ScaleType.diatonic()".

   classmethod ionian(modal_shift: int = 0) -> ScaleType

      Alias of "ScaleType.diatonic()".

   classmethod dorian() -> ScaleType

      Convenience method for creating a dorian ScaleType.

   classmethod phrygian() -> ScaleType

      Convenience method for creating a phrygian ScaleType.

   classmethod lydian() -> ScaleType

      Convenience method for creating a lydian ScaleType.

   classmethod mixolydian() -> ScaleType

      Convenience method for creating a myxolydian ScaleType.

   classmethod aeolian() -> ScaleType

      Convenience method for creating an aeolian ScaleType.

   classmethod natural_minor() -> ScaleType

      Alias of "ScaleType.aeolian()".

   classmethod locrian() -> ScaleType

      Convenience method for creating an locrian ScaleType.

   classmethod harmonic_minor(modal_shift: int = 0) -> ScaleType

      Returns a harmonic minor ScaleType with the specified modal
      shift.

      Parameters:
         **modal_shift** -- How many steps up or down to shift the
         starting note of the scale. The default value of zero creates
         the standard harmonic minor scale.

   classmethod melodic_minor(modal_shift: int = 0) -> ScaleType

      Returns a melodic minor ScaleType with the specified modal
      shift.

      Parameters:
         **modal_shift** -- How many steps up or down to shift the
         starting note of the scale. The default value of zero creates
         the standard melodic minor scale.

   classmethod whole_tone() -> ScaleType

      Convenience method for creating a whole tone ScaleType.

   classmethod octatonic(whole_step_first: bool = True) -> ScaleType

      Convenience method for creating an octatonic (alternating whole
      and half steps) ScaleType

      Parameters:
         **whole_step_first** -- whether to start with a whole step or
         a half step.

   classmethod pentatonic(modal_shift: int = 0) -> ScaleType

      Returns a pentatonic ScaleType with the specified modal shift.

      Parameters:
         **modal_shift** -- how many steps up or down to shift the
         starting note of the scale. A shift of 3 creates a minor
         pentatonic scale.

   classmethod pentatonic_minor() -> ScaleType

      Convenience method for creating a pentatonic minor ScaleType.

   classmethod blues() -> ScaleType

      Convenience method for creating a blues ScaleType.

   classmethod equal_divisions(interval_to_divide, num_divisions) -> ScaleType

      Convenience method for creating a blues ScaleType.

   save_to_scala(file_path: str, description: str = 'Mystery scale saved using SCAMP') -> None

      Converts and saves this ScaleType to a scala file at the given
      file path. Note that any intervals that combine cents and ratio
      information will be flattened out to only cents information,
      since the combination is not possible in scala files.

      Parameters:
         * **file_path** -- path of the file to save

         * **description** -- description of the scale for the file
           header

   classmethod load_from_scala(file_path: str) -> ScaleType

      Loads a ScaleType from a scala file.

      Parameters:
         **file_path** -- file path of a correctly formatted scala
         file

   duplicate() -> T

      Returns a copy of this object by serializing to and from JSON.

   json_dumps() -> str

      Dump this object as a JSON string. This uses a custom encoder
      that recognizes and appropriately converts any attributes that
      are object inheriting from SavesToJSON.

   classmethod json_loads(s: str) -> T

      Load this object from a JSON string. This uses a custom decoder
      that looks for a "_type" key in any object/dictionary being
      parsed and converts it to the class specified (assuming it a
      subclass of SavesToJSON).

      Parameters:
         **s** -- a string representing this object in JSON format

   classmethod load_from_json(file_path: str) -> T

      Load this object from a JSON file with the given path. This uses
      a custom decoder that looks for a "_type" key in any
      object/dictionary being parsed and converts it to the class
      specified (assuming it a subclass of SavesToJSON).

      Parameters:
         **file_path** -- path for loading the file

   save_to_json(file_path: str) -> None

      Save this object to a JSON file using the given path. This uses
      a custom encoder that recognizes and appropriately converts any
      attributes that are object inheriting from SavesToJSON.

      Parameters:
         **file_path** -- path for saving the file


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.scale.txt
======================================================================

scamp_extensions.pitch.scale
****************************

Module containing classes for flexibly representing musical scales.
This includes the "PitchInterval" class, for representing just and/or
equal-tempered intervals; the "ScaleType" class, which represents a
succession of intervals without specifying a starting point; and the
"Scale" class, which combines a ScaleType with a starting reference
pitch, and also allows for a choice between cyclical and non-cyclical.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "PitchInte | Represents an interval between two pitches.                                                |
| rval"(cent |                                                                                            |
| s, ratio)  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "Scale"(sc | Class representing a scale starting on a specific pitch.                                   |
| ale_type,  |                                                                                            |
| start_pitc |                                                                                            |
| h[,        |                                                                                            |
| cycle])    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "ScaleType | A ScaleType represents the intervallic relationships in a scale without specifying a       |
| "(*interva | specific starting point.                                                                   |
| ls)        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.pitch.scale.PitchInterval

  * "PitchInterval"

    * "PitchInterval.parse()"

    * "PitchInterval.to_cents()"

    * "PitchInterval.to_half_steps()"

    * "PitchInterval.to_scala_string()"

    * "PitchInterval.duplicate()"

    * "PitchInterval.json_dumps()"

    * "PitchInterval.json_loads()"

    * "PitchInterval.load_from_json()"

    * "PitchInterval.save_to_json()"

* scamp_extensions.pitch.scale.Scale

  * "Scale"

    * "Scale.start_pitch"

    * "Scale.cycle"

    * "Scale.from_pitches()"

    * "Scale.from_scala_file()"

    * "Scale.from_start_pitch_and_cent_or_ratio_intervals()"

    * "Scale.degree_to_pitch()"

    * "Scale.pitch_to_degree()"

    * "Scale.round()"

    * "Scale.floor()"

    * "Scale.ceil()"

    * "Scale.transpose()"

    * "Scale.transposed()"

    * "Scale.chromatic()"

    * "Scale.diatonic()"

    * "Scale.major()"

    * "Scale.ionian()"

    * "Scale.dorian()"

    * "Scale.phrygian()"

    * "Scale.lydian()"

    * "Scale.mixolydian()"

    * "Scale.aeolian()"

    * "Scale.natural_minor()"

    * "Scale.locrian()"

    * "Scale.harmonic_minor()"

    * "Scale.melodic_minor()"

    * "Scale.whole_tone()"

    * "Scale.octatonic()"

    * "Scale.pentatonic()"

    * "Scale.pentatonic_minor()"

    * "Scale.blues()"

    * "Scale.equal_divisions()"

    * "Scale.duplicate()"

    * "Scale.json_dumps()"

    * "Scale.json_loads()"

    * "Scale.load_from_json()"

    * "Scale.save_to_json()"

* scamp_extensions.pitch.scale.ScaleType

  * "ScaleType"

    * "ScaleType.to_half_steps()"

    * "ScaleType.rotate()"

    * "ScaleType.chromatic()"

    * "ScaleType.diatonic()"

    * "ScaleType.major()"

    * "ScaleType.ionian()"

    * "ScaleType.dorian()"

    * "ScaleType.phrygian()"

    * "ScaleType.lydian()"

    * "ScaleType.mixolydian()"

    * "ScaleType.aeolian()"

    * "ScaleType.natural_minor()"

    * "ScaleType.locrian()"

    * "ScaleType.harmonic_minor()"

    * "ScaleType.melodic_minor()"

    * "ScaleType.whole_tone()"

    * "ScaleType.octatonic()"

    * "ScaleType.pentatonic()"

    * "ScaleType.pentatonic_minor()"

    * "ScaleType.blues()"

    * "ScaleType.equal_divisions()"

    * "ScaleType.save_to_scala()"

    * "ScaleType.load_from_scala()"

    * "ScaleType.duplicate()"

    * "ScaleType.json_dumps()"

    * "ScaleType.json_loads()"

    * "ScaleType.load_from_json()"

    * "ScaleType.save_to_json()"


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.utilities.bark_to_freq.txt
======================================================================

scamp_extensions.pitch.utilities.bark_to_freq
*********************************************

scamp_extensions.pitch.utilities.bark_to_freq(b: Real | Sequence[Real]) -> Real | Sequence[Real]

   Converts a Bark number to its corresponding frequency in hertz. See
   "freq_to_bark()". The first argument can optionally be a list,
   tuple, or iterator, in which case this is performed on each
   element.

   Parameters:
      **b** -- a (floating point) bark number


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.utilities.cents_to_ratio.txt
======================================================================

scamp_extensions.pitch.utilities.cents_to_ratio
***********************************************

scamp_extensions.pitch.utilities.cents_to_ratio(cents: Real | Sequence[Real]) -> Real | Sequence[Real]

   Given a number of cents, convert it to a corresponding frequency
   ratio. The first argument can optionally be a list, tuple, or
   iterator, in which case this is performed on each element.

   Parameters:
      **cents** -- number of cents (e.g. 700 for a perfect fifth)


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.utilities.freq_to_bark.txt
======================================================================

scamp_extensions.pitch.utilities.freq_to_bark
*********************************************

scamp_extensions.pitch.utilities.freq_to_bark(f: Real | Sequence[Real]) -> Real | Sequence[Real]

   Converts a frequency in hertz to a (floating point) Bark number
   according to the psychoacoustic Bark scale
   (https://en.wikipedia.org/wiki/Bark_scale). This is a scale that
   compensates for the unevenness in human pitch acuity across our
   range of hearing. Here we use the function approximation proposed
   by Terhardt, which was chosen in part for its ease of inverse
   calculation. The first argument can optionally be a list, tuple, or
   iterator, in which case this is performed on each element.

   Parameters:
      **f** -- the input frequency


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.utilities.hertz_to_midi.txt
======================================================================

scamp_extensions.pitch.utilities.hertz_to_midi
**********************************************

scamp_extensions.pitch.utilities.hertz_to_midi(hertz_value: Real | Sequence[Real], A: Real = 440) -> Real | Sequence[Real]

   Given a frequency in hertz, returns the corresponding (floating
   point) MIDI pitch. The first argument can optionally be a list,
   tuple, or iterator, in which case this is performed on each
   element.

   Parameters:
      * **hertz_value** -- a frequency in hertz

      * **A** -- the tuning of A4 in hertz


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.utilities.map_keyboard_to_microtonal_pitches.txt
======================================================================

scamp_extensions.pitch.utilities.map_keyboard_to_microtonal_pitches
*******************************************************************

scamp_extensions.pitch.utilities.map_keyboard_to_microtonal_pitches(microtonal_pitches: Sequence[float], squared_penalty: bool = True) -> Dict[int, float]

   Given a list of microtonal (floating-point) MIDI pitches, finds an
   efficient map from keyboard-friendly (integer) pitches to the
   original microtonal pitches. This is really useful if you're trying
   to audition a microtonal collection on the keyboard and don't want
   to deal with making a mapping manually. Note: the code here is
   taken nearly verbatim from StackOverflow user *sacha* in response
   to this question: https://stackoverflow.com/questions/61825905
   /match-list-of-floats-to-nearest-integers-without-repeating

   Parameters:
      * **microtonal_pitches** -- a collection of floating-point
        (microtonal) pitches

      * **squared_penalty** -- whether or not the choice is based on
        simple or squared error. (I.e. are we using taxicab or
        euclidean distance.)

   Returns:
      a dictionary mapping keyboard-friendly (integer) pitches to the
      microtonal collection given


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.utilities.midi_to_hertz.txt
======================================================================

scamp_extensions.pitch.utilities.midi_to_hertz
**********************************************

scamp_extensions.pitch.utilities.midi_to_hertz(midi_value: Real | Sequence[Real], A: Real = 440) -> Real | Sequence[Real]

   Given a MIDI pitch, returns the corresponding frequency in hertz.
   The first argument can optionally be a list, tuple, or iterator, in
   which case this is performed on each element.

   Parameters:
      * **midi_value** -- a midi pitch (e.g. 60 for middle C)

      * **A** -- the tuning of A4 in hertz


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.utilities.note_name_to_number.txt
======================================================================

scamp_extensions.pitch.utilities.note_name_to_number
****************************************************

scamp_extensions.pitch.utilities.note_name_to_number(note_name: str) -> int

   Converts a note name (e.g. "Bb5" or "C#2") to its corresponding
   MIDI number. The first argument can optionally be a list, tuple, or
   iterator, in which case this is performed on each element.

   Parameters:
      **note_name** -- The note name, e.g. "Bb5". The accidental can
      be any of "#", "s", "f", "b", "x", or "bb". Uses the convention
      of "C4" = 60.


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.utilities.ratio_to_cents.txt
======================================================================

scamp_extensions.pitch.utilities.ratio_to_cents
***********************************************

scamp_extensions.pitch.utilities.ratio_to_cents(ratio: Real | Sequence[Real]) -> Real | Sequence[Real]

   Given a frequency ratio, convert it to a corresponding number of
   cents. The first argument can optionally be a list, tuple, or
   iterator, in which case this is performed on each element.

   Parameters:
      **ratio** -- frequency ratio (e.g. 1.5 for a perfect fifth)


======================================================================
=== FILE: scamp_extensions.pitch/scamp_extensions.pitch.utilities.txt
======================================================================

scamp_extensions.pitch.utilities
********************************

Module containing pitch-related utility functions, such as those that
convert between midi and hertz.

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "bark_to_f | Converts a Bark number to its corresponding frequency in hertz.                            |
| req"(b)    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "cents_to_ | Given a number of cents, convert it to a corresponding frequency ratio.                    |
| ratio"(cen |                                                                                            |
| ts)        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "freq_to_b | Converts a frequency in hertz to a (floating point) Bark number according to the           |
| ark"(f)    | psychoacoustic Bark scale (https://en.wikipedia.org/wiki/Bark_scale).                      |
+------------+--------------------------------------------------------------------------------------------+
| "hertz_to_ | Given a frequency in hertz, returns the corresponding (floating point) MIDI pitch.         |
| midi"(hert |                                                                                            |
| z_value[,  |                                                                                            |
| A])        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "map_keybo | Given a list of microtonal (floating-point) MIDI pitches, finds an efficient map from      |
| ard_to_mic | keyboard-friendly (integer) pitches to the original microtonal pitches.                    |
| rotonal_pi |                                                                                            |
| tches"(... |                                                                                            |
| [, ...])   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "midi_to_h | Given a MIDI pitch, returns the corresponding frequency in hertz.                          |
| ertz"(midi |                                                                                            |
| _value[,   |                                                                                            |
| A])        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "note_name | Converts a note name (e.g. "Bb5" or "C#2") to its corresponding MIDI number.               |
| _to_number |                                                                                            |
| "(note_nam |                                                                                            |
| e)         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "ratio_to_ | Given a frequency ratio, convert it to a corresponding number of cents.                    |
| cents"(rat |                                                                                            |
| io)        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.pitch.utilities.bark_to_freq

  * "bark_to_freq()"

* scamp_extensions.pitch.utilities.cents_to_ratio

  * "cents_to_ratio()"

* scamp_extensions.pitch.utilities.freq_to_bark

  * "freq_to_bark()"

* scamp_extensions.pitch.utilities.hertz_to_midi

  * "hertz_to_midi()"

* scamp_extensions.pitch.utilities.map_keyboard_to_microtonal_pitches

  * "map_keyboard_to_microtonal_pitches()"

* scamp_extensions.pitch.utilities.midi_to_hertz

  * "midi_to_hertz()"

* scamp_extensions.pitch.utilities.note_name_to_number

  * "note_name_to_number()"

* scamp_extensions.pitch.utilities.ratio_to_cents

  * "ratio_to_cents()"


======================================================================
=== FILE: scamp_extensions.pitch.txt
======================================================================

scamp_extensions.pitch package
******************************

Subpackage containing pitch-related extensions. These include
abstractions for intervals and scales, as well as utilities for unit
conversions.

-[ Modules: ]-

+------------+--------------------------------------------------------------------------------------------+
| "chord_bui | Module containing functions for voicing a chord: given a set of pitch classes and a range  |
| lder"      | to place them in, these search the possible voicings and return whichever one best fits    |
|            | the preferences given, such as being compactly spaced or centered in the range.            |
+------------+--------------------------------------------------------------------------------------------+
| "scale"    | Module containing classes for flexibly representing musical scales.                        |
+------------+--------------------------------------------------------------------------------------------+
| "utilities | Module containing pitch-related utility functions, such as those that convert between midi |
| "          | and hertz.                                                                                 |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.pitch.chord_builder

  * scamp_extensions.pitch.chord_builder.chord_from_pitch_classes

    * "chord_from_pitch_classes()"

  * scamp_extensions.pitch.chord_builder.chords_from_pitch_classes

    * "chords_from_pitch_classes()"

  * scamp_extensions.pitch.chord_builder.get_pcs_instances_in_range

    * "get_pcs_instances_in_range()"

* scamp_extensions.pitch.scale

  * scamp_extensions.pitch.scale.PitchInterval

    * "PitchInterval"

      * "PitchInterval.parse()"

      * "PitchInterval.to_cents()"

      * "PitchInterval.to_half_steps()"

      * "PitchInterval.to_scala_string()"

      * "PitchInterval.duplicate()"

      * "PitchInterval.json_dumps()"

      * "PitchInterval.json_loads()"

      * "PitchInterval.load_from_json()"

      * "PitchInterval.save_to_json()"

  * scamp_extensions.pitch.scale.Scale

    * "Scale"

      * "Scale.start_pitch"

      * "Scale.cycle"

      * "Scale.from_pitches()"

      * "Scale.from_scala_file()"

      * "Scale.from_start_pitch_and_cent_or_ratio_intervals()"

      * "Scale.degree_to_pitch()"

      * "Scale.pitch_to_degree()"

      * "Scale.round()"

      * "Scale.floor()"

      * "Scale.ceil()"

      * "Scale.transpose()"

      * "Scale.transposed()"

      * "Scale.chromatic()"

      * "Scale.diatonic()"

      * "Scale.major()"

      * "Scale.ionian()"

      * "Scale.dorian()"

      * "Scale.phrygian()"

      * "Scale.lydian()"

      * "Scale.mixolydian()"

      * "Scale.aeolian()"

      * "Scale.natural_minor()"

      * "Scale.locrian()"

      * "Scale.harmonic_minor()"

      * "Scale.melodic_minor()"

      * "Scale.whole_tone()"

      * "Scale.octatonic()"

      * "Scale.pentatonic()"

      * "Scale.pentatonic_minor()"

      * "Scale.blues()"

      * "Scale.equal_divisions()"

      * "Scale.duplicate()"

      * "Scale.json_dumps()"

      * "Scale.json_loads()"

      * "Scale.load_from_json()"

      * "Scale.save_to_json()"

  * scamp_extensions.pitch.scale.ScaleType

    * "ScaleType"

      * "ScaleType.to_half_steps()"

      * "ScaleType.rotate()"

      * "ScaleType.chromatic()"

      * "ScaleType.diatonic()"

      * "ScaleType.major()"

      * "ScaleType.ionian()"

      * "ScaleType.dorian()"

      * "ScaleType.phrygian()"

      * "ScaleType.lydian()"

      * "ScaleType.mixolydian()"

      * "ScaleType.aeolian()"

      * "ScaleType.natural_minor()"

      * "ScaleType.locrian()"

      * "ScaleType.harmonic_minor()"

      * "ScaleType.melodic_minor()"

      * "ScaleType.whole_tone()"

      * "ScaleType.octatonic()"

      * "ScaleType.pentatonic()"

      * "ScaleType.pentatonic_minor()"

      * "ScaleType.blues()"

      * "ScaleType.equal_divisions()"

      * "ScaleType.save_to_scala()"

      * "ScaleType.load_from_scala()"

      * "ScaleType.duplicate()"

      * "ScaleType.json_dumps()"

      * "ScaleType.json_loads()"

      * "ScaleType.load_from_json()"

      * "ScaleType.save_to_json()"

* scamp_extensions.pitch.utilities

  * scamp_extensions.pitch.utilities.bark_to_freq

    * "bark_to_freq()"

  * scamp_extensions.pitch.utilities.cents_to_ratio

    * "cents_to_ratio()"

  * scamp_extensions.pitch.utilities.freq_to_bark

    * "freq_to_bark()"

  * scamp_extensions.pitch.utilities.hertz_to_midi

    * "hertz_to_midi()"

  * scamp_extensions.pitch.utilities.map_keyboard_to_microtonal_pitche
    s

    * "map_keyboard_to_microtonal_pitches()"

  * scamp_extensions.pitch.utilities.midi_to_hertz

    * "midi_to_hertz()"

  * scamp_extensions.pitch.utilities.note_name_to_number

    * "note_name_to_number()"

  * scamp_extensions.pitch.utilities.ratio_to_cents

    * "ratio_to_cents()"

-[ Public-Facing API (result of *import **): ]-

+------------+--------------------------------------------------------------------------------------------+
| "PitchInte | Represents an interval between two pitches.                                                |
| rval"(cent |                                                                                            |
| s, ratio)  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "Scale"(sc | Class representing a scale starting on a specific pitch.                                   |
| ale_type,  |                                                                                            |
| start_pitc |                                                                                            |
| h[,        |                                                                                            |
| cycle])    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "ScaleType | A ScaleType represents the intervallic relationships in a scale without specifying a       |
| "(*interva | specific starting point.                                                                   |
| ls)        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "bark_to_f | Converts a Bark number to its corresponding frequency in hertz.                            |
| req"(b)    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "cents_to_ | Given a number of cents, convert it to a corresponding frequency ratio.                    |
| ratio"(cen |                                                                                            |
| ts)        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "freq_to_b | Converts a frequency in hertz to a (floating point) Bark number according to the           |
| ark"(f)    | psychoacoustic Bark scale (https://en.wikipedia.org/wiki/Bark_scale).                      |
+------------+--------------------------------------------------------------------------------------------+
| "hertz_to_ | Given a frequency in hertz, returns the corresponding (floating point) MIDI pitch.         |
| midi"(hert |                                                                                            |
| z_value[,  |                                                                                            |
| A])        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "map_keybo | Given a list of microtonal (floating-point) MIDI pitches, finds an efficient map from      |
| ard_to_mic | keyboard-friendly (integer) pitches to the original microtonal pitches.                    |
| rotonal_pi |                                                                                            |
| tches"(... |                                                                                            |
| [, ...])   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "midi_to_h | Given a MIDI pitch, returns the corresponding frequency in hertz.                          |
| ertz"(midi |                                                                                            |
| _value[,   |                                                                                            |
| A])        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "ratio_to_ | Given a frequency ratio, convert it to a corresponding number of cents.                    |
| cents"(rat |                                                                                            |
| io)        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


======================================================================
=== FILE: scamp_extensions.playback/scamp_extensions.playback.multi_preset_instrument.MultiNoteHandle.txt
======================================================================

scamp_extensions.playback.multi_preset_instrument.MultiNoteHandle
*****************************************************************

class scamp_extensions.playback.multi_preset_instrument.MultiNoteHandle(note_handles: Sequence[NoteHandle | ChordHandle] = ())

   Bases: "object"

   The equivalent of an "NoteHandle" but for a
   "MultiPresetInstrument".

   Parameters:
      **note_handles** -- a list of the NoteHandles for the underlying
      ScampInstruments. (One for the silent notation part, and one for
      the active preset.)

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "change_pa | See "change_parameter()"                                                                   |
   | rameter"(p |                                                                                            |
   | aram_name, |                                                                                            |
   | ...[,      |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "change_pi | See "change_pitch()"                                                                       |
   | tch"(targe |                                                                                            |
   | t_value_or |                                                                                            |
   | _values[,  |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "change_vo | See "change_volume()"                                                                      |
   | lume"(targ |                                                                                            |
   | et_value_o |                                                                                            |
   | r_values[, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "end"()    | See "end()"                                                                                |
   +------------+--------------------------------------------------------------------------------------------+
   | "split"()  | See "split()"                                                                              |
   +------------+--------------------------------------------------------------------------------------------+

   change_parameter(param_name: str, target_value_or_values: float | Sequence, transition_length_or_lengths: float | Sequence = 0, transition_curve_shape_or_shapes: float | Sequence = 0, clock: Clock = None) -> None

      See "change_parameter()"

   change_pitch(target_value_or_values: float | Sequence, transition_length_or_lengths: float | Sequence = 0, transition_curve_shape_or_shapes: float | Sequence = 0, clock: Clock = None) -> None

      See "change_pitch()"

   change_volume(target_value_or_values: float | Sequence, transition_length_or_lengths: float | Sequence = 0, transition_curve_shape_or_shapes: float | Sequence = 0, clock: Clock = None) -> None

      See "change_volume()"

   split() -> None

      See "split()"

   end() -> None

      See "end()"


======================================================================
=== FILE: scamp_extensions.playback/scamp_extensions.playback.multi_preset_instrument.MultiPresetInstrument.txt
======================================================================

scamp_extensions.playback.multi_preset_instrument.MultiPresetInstrument
***********************************************************************

class scamp_extensions.playback.multi_preset_instrument.MultiPresetInstrument(session: Session, name: str, default_spelling_policy: SpellingPolicy | None = None, clef_preference: str = 'from_name')

   Bases: "object"

   A convenient wrapper for bundling multiple *ScampInstrument*
   objects or soundfont presets into a single notated part, and
   assigning particular notations to these presets.

   Parameters:
      * **session** -- the session in which this MultiPresetInstrument
        operates

      * **name** -- name of this MultiPresetInstrument (e.g. in the
        score)

      * **default_spelling_policy** -- see "ScampInstrument"

      * **clef_preference** -- see "ScampInstrument"

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "add_prese | Add a new preset with a given instrument and name.                                         |
   | t"(name, i |                                                                                            |
   | nstrument_ |                                                                                            |
   | or_soundfo |                                                                                            |
   | nt_preset) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "end_all_n | Ends all notes currently playing                                                           |
   | otes"()    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "num_notes | Returns the number of notes currently playing.                                             |
   | _playing"( |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "play_chor | Play a chord using this MultiPresetInstrument.                                             |
   | d"(pitches |                                                                                            |
   | , volume,  |                                                                                            |
   | length[,   |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "play_note | Play a note using this MultiPresetInstrument                                               |
   | "(pitch,   |                                                                                            |
   | volume,    |                                                                                            |
   | length[,   |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "send_midi | Send a midi cc message to every "ScampInstrument:" used by this MultiPresetInstrument.     |
   | _cc"(cc_nu |                                                                                            |
   | mber, valu |                                                                                            |
   | e_from_0_t |                                                                                            |
   | o_1)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "set_max_p | Set the max pitch bend for all midi playback implementations on this instrument            |
   | itch_bend" |                                                                                            |
   | (semitones |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_cho | Start a note using this MultiPresetInstrument.                                             |
   | rd"(pitche |                                                                                            |
   | s,         |                                                                                            |
   | volume[, p |                                                                                            |
   | roperties, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_not | Start a note using this MultiPresetInstrument.                                             |
   | e"(pitch,  |                                                                                            |
   | volume[, p |                                                                                            |
   | roperties, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Attributes ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "clef_pref | The clef preference for this instrument.                                                   |
   | erence"    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "default_s | The default spelling policy for notes played back by this instrument.                      |
   | pelling_po |                                                                                            |
   | licy"      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "name"     | Name of this MultiPresetInstrument (e.g. in the score).                                    |
   +------------+--------------------------------------------------------------------------------------------+

   property name

      Name of this MultiPresetInstrument (e.g. in the score)

   add_preset(name: str, instrument_or_soundfont_preset: ScampInstrument | str | int | Tuple[int, int], bundled_properties: str | dict | Sequence | NoteProperty = None, bundled_properties_on_switch: str | dict | Sequence | NoteProperty = None, bundled_properties_on_switch_away: str | dict | Sequence | NoteProperty = None, make_default=False)

      Add a new preset with a given instrument and name.

      Parameters:
         * **instrument_or_soundfont_preset** -- either a
           ScampInstrument, or a soundfont preset name or number.

         * **name** -- name for this preset used when calling
           play_note

         * **bundled_properties** -- Any properties that we wish to
           bundle with every note played by this preset. For example,
           diamond noteheads for harmonics.

         * **bundled_properties_on_switch** -- Any properties that we
           wish to bundle with this preset when we switch to it (the
           last note was a different preset). For example, "pizz."

         * **bundled_properties_on_switch_away** -- Any properties
           that we wish to bundle with this preset when we switch to
           it (the last note was a different preset). For example,
           "pizz."

         * **make_default** -- if True, moves this preset to the front
           of the list so that it becomes the default preset. If this
           is the first preset defined, it will become the default
           regardless of the setting of this parameter.

      Returns:
         self, for chaining purposes

   play_note(pitch, volume, length, properties: str | dict | Sequence | NoteProperty = None, preset: str = None, blocking: bool = True, clock: Clock = None, silent: bool = False, transcribe: bool = True) -> None

      Play a note using this MultiPresetInstrument

      Parameters:
         * **pitch** -- see "play_note()"

         * **volume** -- see "play_note()"

         * **length** -- see "play_note()"

         * **preset** -- Name of the preset to use for this note.

         * **properties** -- see "play_note()"

         * **blocking** -- see "play_note()"

         * **clock** -- see "play_note()"

   play_chord(pitches: Sequence, volume, length, properties: str | dict | Sequence | NoteProperty = None, preset: str = None, blocking: bool = True, clock: Clock = None) -> None

      Play a chord using this MultiPresetInstrument.

      Parameters:
         * **pitches** -- see "play_chord()"

         * **volume** -- see "play_chord()"

         * **length** -- see "play_chord()"

         * **properties** -- see "play_chord()"

         * **preset** -- Name of the preset to use for this chord.

         * **blocking** -- see "play_chord()"

         * **clock** -- see "play_chord()"

   start_note(pitch: float, volume: float, properties: str | dict | Sequence | NoteProperty = None, preset: str = None, clock: Clock = None, fixed: bool | str = 'auto', velocity: float = None) -> MultiNoteHandle

      Start a note using this MultiPresetInstrument.

      Parameters:
         * **pitch** -- see "start_note()"

         * **volume** -- see "start_note()"

         * **properties** -- see "start_note()"

         * **preset** -- name of the preset to use for this note.

         * **clock** -- see "start_note()"

         * **fixed** -- see "start_note()"

         * **velocity** -- see "start_note()"

      Returns:
         a "MultiNoteHandle" with which to later manipulate the note

   start_chord(pitches: Sequence[float], volume: float, properties: str | dict | Sequence | NoteProperty = None, preset: str = None, clock: Clock = None, fixed: bool | str = 'auto', velocity: float = None) -> MultiNoteHandle

      Start a note using this MultiPresetInstrument.

      Parameters:
         * **pitches** -- see "start_chord()"

         * **volume** -- see "start_chord()"

         * **properties** -- see "start_chord()"

         * **preset** -- name of the preset to use for this note.

         * **clock** -- see "start_chord()"

         * **fixed** -- see "start_chord()"

         * **velocity** -- see "start_chord()"

      Returns:
         a "MultiNoteHandle" with which to later manipulate the chord

   send_midi_cc(cc_number: int, value_from_0_to_1: float) -> None

      Send a midi cc message to every "ScampInstrument:" used by this
      MultiPresetInstrument.

      Parameters:
         * **cc_number** -- MIDI cc number

         * **value_from_0_to_1** -- value to send (scaled from 0 to 1)

   end_all_notes() -> None

      Ends all notes currently playing

   num_notes_playing() -> int

      Returns the number of notes currently playing.

   set_max_pitch_bend(semitones: int) -> None

      Set the max pitch bend for all midi playback implementations on
      this instrument

   property clef_preference

      The clef preference for this instrument. See "ScampInstrument"

   property default_spelling_policy

      The default spelling policy for notes played back by this
      instrument. See "ScampInstrument"


======================================================================
=== FILE: scamp_extensions.playback/scamp_extensions.playback.multi_preset_instrument.txt
======================================================================

scamp_extensions.playback.multi_preset_instrument
*************************************************

This module defines the "MultiPresetInstrument" class, a convenience
class that combines multiple "ScampInstrument" objects so that they
can create a single part in the score. A typical use case would be to
combine arco, pizzicato and harmonic presets from a soundfont into a
single string instrument part.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "MultiNote | The equivalent of an "NoteHandle" but for a "MultiPresetInstrument".                       |
| Handle"([n |                                                                                            |
| ote_handle |                                                                                            |
| s])        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "MultiPres | A convenient wrapper for bundling multiple *ScampInstrument* objects or soundfont presets  |
| etInstrume | into a single notated part, and assigning particular notations to these presets.           |
| nt"(sessio |                                                                                            |
| n, name[,  |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.playback.multi_preset_instrument.MultiNoteHandle

  * "MultiNoteHandle"

    * "MultiNoteHandle.change_parameter()"

    * "MultiNoteHandle.change_pitch()"

    * "MultiNoteHandle.change_volume()"

    * "MultiNoteHandle.split()"

    * "MultiNoteHandle.end()"

* scamp_extensions.playback.multi_preset_instrument.MultiPresetInstrum
  ent

  * "MultiPresetInstrument"

    * "MultiPresetInstrument.name"

    * "MultiPresetInstrument.add_preset()"

    * "MultiPresetInstrument.play_note()"

    * "MultiPresetInstrument.play_chord()"

    * "MultiPresetInstrument.start_note()"

    * "MultiPresetInstrument.start_chord()"

    * "MultiPresetInstrument.send_midi_cc()"

    * "MultiPresetInstrument.end_all_notes()"

    * "MultiPresetInstrument.num_notes_playing()"

    * "MultiPresetInstrument.set_max_pitch_bend()"

    * "MultiPresetInstrument.clef_preference"

    * "MultiPresetInstrument.default_spelling_policy"


======================================================================
=== FILE: scamp_extensions.playback/scamp_extensions.playback.multi_staff_instrument.MultiStaffInstrument.txt
======================================================================

scamp_extensions.playback.multi_staff_instrument.MultiStaffInstrument
*********************************************************************

class scamp_extensions.playback.multi_staff_instrument.MultiStaffInstrument(name: str, staff_parts: Sequence[ScampInstrument], decision_protocol: Callable[[float], int] | Sequence = (60,))

   Bases: "object"

   A convenient wrapper for bundling multiple *ScampInstrument*
   objects into a single meta instrument that represents a grand staff
   of group of staves.

   Parameters:
      * **name** -- name of this instrument

      * **staff_parts** -- list of ScampInstrument objects that
        represent the different staves

      * **decision_protocol** -- either a tuple of pitch boundaries
        that decide which part plays or a function that maps pitch to
        part index.

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "end_all_n | Ends all notes currently playing                                                           |
   | otes"()    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "num_notes | Returns the number of notes currently playing.                                             |
   | _playing"( |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "play_chor | Play a chord using this MultiPresetInstrument.                                             |
   | d"(pitches |                                                                                            |
   | , volume,  |                                                                                            |
   | length[,   |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "play_note | Play a note using this MultiStaffInstrument                                                |
   | "(pitch,   |                                                                                            |
   | volume,    |                                                                                            |
   | length[,   |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "send_midi | Send a midi cc message to every "ScampInstrument:" used by this MultiPresetInstrument.     |
   | _cc"(cc_nu |                                                                                            |
   | mber, valu |                                                                                            |
   | e_from_0_t |                                                                                            |
   | o_1)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "set_max_p | Set the max pitch bend for all midi playback implementations on this instrument            |
   | itch_bend" |                                                                                            |
   | (semitones |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_cho | Start a note using this MultiPresetInstrument.                                             |
   | rd"(pitche |                                                                                            |
   | s,         |                                                                                            |
   | volume[, p |                                                                                            |
   | roperties, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_not | Start a note using this MultiPresetInstrument.                                             |
   | e"(pitch,  |                                                                                            |
   | volume[, p |                                                                                            |
   | roperties, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Attributes ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "default_s | The default spelling policy for notes played back by this instrument.                      |
   | pelling_po |                                                                                            |
   | licy"      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   play_note(pitch, volume, length, properties: str | dict | Sequence | NoteProperty = None, force_staff: int = None, blocking: bool = True, clock: Clock = None) -> None

      Play a note using this MultiStaffInstrument

      Parameters:
         * **pitch** -- see "play_note()"

         * **volume** -- see "play_note()"

         * **length** -- see "play_note()"

         * **force_staff** -- force this note to play on the given
           staff index

         * **properties** -- see "play_note()"

         * **blocking** -- see "play_note()"

         * **clock** -- see "play_note()"

   play_chord(pitches: Sequence, volume, length, properties: str | dict | Sequence | NoteProperty = None, force_staff: int = None, blocking: bool = True, clock: Clock = None) -> None

      Play a chord using this MultiPresetInstrument.

      Parameters:
         * **pitches** -- see "play_chord()"

         * **volume** -- see "play_chord()"

         * **length** -- see "play_chord()"

         * **properties** -- see "play_chord()"

         * **force_staff** -- force this chord to play on the given
           staff index

         * **blocking** -- see "play_chord()"

         * **clock** -- see "play_chord()"

   start_note(pitch: float, volume: float, properties: str | dict | Sequence | NoteProperty = None, force_staff: int = None, clock: Clock = None, fixed: bool | str = 'auto', velocity: float = None) -> MultiNoteHandle

      Start a note using this MultiPresetInstrument.

      Parameters:
         * **pitch** -- see "start_note()"

         * **volume** -- see "start_note()"

         * **properties** -- see "start_note()"

         * **force_staff** -- force this note to play on the given
           staff index

         * **clock** -- see "start_note()"

         * **fixed** -- see "start_note()"

         * **velocity** -- see "start_note()"

      Returns:
         a "MultiNoteHandle" with which to later manipulate the note

   start_chord(pitches: Sequence[float], volume: float, properties: str | dict | Sequence | NoteProperty = None, force_staff: int = None, clock: Clock = None, fixed: bool | str = 'auto', velocity: float = None) -> MultiNoteHandle

      Start a note using this MultiPresetInstrument.

      Parameters:
         * **pitches** -- see "start_chord()"

         * **volume** -- see "start_chord()"

         * **properties** -- see "start_chord()"

         * **force_staff** -- force this chord to play on the given
           staff index

         * **clock** -- see "start_chord()"

         * **fixed** -- see "start_chord()"

         * **velocity** -- see "start_chord()"

      Returns:
         a "MultiNoteHandle" with which to later manipulate the chord

   send_midi_cc(cc_number: int, value_from_0_to_1: float) -> None

      Send a midi cc message to every "ScampInstrument:" used by this
      MultiPresetInstrument.

      Parameters:
         * **cc_number** -- MIDI cc number

         * **value_from_0_to_1** -- value to send (scaled from 0 to 1)

   end_all_notes() -> None

      Ends all notes currently playing

   num_notes_playing() -> int

      Returns the number of notes currently playing.

   set_max_pitch_bend(semitones: int) -> None

      Set the max pitch bend for all midi playback implementations on
      this instrument

   property default_spelling_policy

      The default spelling policy for notes played back by this
      instrument. See "ScampInstrument"


======================================================================
=== FILE: scamp_extensions.playback/scamp_extensions.playback.multi_staff_instrument.txt
======================================================================

scamp_extensions.playback.multi_staff_instrument
************************************************

This module defines the "MultiStaffInstrument" class, a convenience
class that combines multiple "ScampInstrument" objects so that they
can create a single part in the score. A typical use case would be to
combine arco, pizzicato and harmonic presets from a soundfont into a
single string instrument part.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "MultiStaf | A convenient wrapper for bundling multiple *ScampInstrument* objects into a single meta    |
| fInstrumen | instrument that represents a grand staff of group of staves.                               |
| t"(name, s |                                                                                            |
| taff_parts |                                                                                            |
| [, ...])   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.playback.multi_staff_instrument.MultiStaffInstrumen
  t

  * "MultiStaffInstrument"

    * "MultiStaffInstrument.play_note()"

    * "MultiStaffInstrument.play_chord()"

    * "MultiStaffInstrument.start_note()"

    * "MultiStaffInstrument.start_chord()"

    * "MultiStaffInstrument.send_midi_cc()"

    * "MultiStaffInstrument.end_all_notes()"

    * "MultiStaffInstrument.num_notes_playing()"

    * "MultiStaffInstrument.set_max_pitch_bend()"

    * "MultiStaffInstrument.default_spelling_policy"


======================================================================
=== FILE: scamp_extensions.playback.txt
======================================================================

scamp_extensions.playback package
*********************************

Subpackage containing playback-related extensions, such as support for
multi-preset instruments.

-[ Modules: ]-

+------------+--------------------------------------------------------------------------------------------+
| "multi_pre | This module defines the "MultiPresetInstrument" class, a convenience class that combines   |
| set_instru | multiple "ScampInstrument" objects so that they can create a single part in the score.     |
| ment"      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "multi_sta | This module defines the "MultiStaffInstrument" class, a convenience class that combines    |
| ff_instrum | multiple "ScampInstrument" objects so that they can create a single part in the score.     |
| ent"       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.playback.multi_preset_instrument

  * scamp_extensions.playback.multi_preset_instrument.MultiNoteHandle

    * "MultiNoteHandle"

      * "MultiNoteHandle.change_parameter()"

      * "MultiNoteHandle.change_pitch()"

      * "MultiNoteHandle.change_volume()"

      * "MultiNoteHandle.split()"

      * "MultiNoteHandle.end()"

  * scamp_extensions.playback.multi_preset_instrument.MultiPresetInstr
    ument

    * "MultiPresetInstrument"

      * "MultiPresetInstrument.name"

      * "MultiPresetInstrument.add_preset()"

      * "MultiPresetInstrument.play_note()"

      * "MultiPresetInstrument.play_chord()"

      * "MultiPresetInstrument.start_note()"

      * "MultiPresetInstrument.start_chord()"

      * "MultiPresetInstrument.send_midi_cc()"

      * "MultiPresetInstrument.end_all_notes()"

      * "MultiPresetInstrument.num_notes_playing()"

      * "MultiPresetInstrument.set_max_pitch_bend()"

      * "MultiPresetInstrument.clef_preference"

      * "MultiPresetInstrument.default_spelling_policy"

* scamp_extensions.playback.multi_staff_instrument

  * scamp_extensions.playback.multi_staff_instrument.MultiStaffInstrum
    ent

    * "MultiStaffInstrument"

      * "MultiStaffInstrument.play_note()"

      * "MultiStaffInstrument.play_chord()"

      * "MultiStaffInstrument.start_note()"

      * "MultiStaffInstrument.start_chord()"

      * "MultiStaffInstrument.send_midi_cc()"

      * "MultiStaffInstrument.end_all_notes()"

      * "MultiStaffInstrument.num_notes_playing()"

      * "MultiStaffInstrument.set_max_pitch_bend()"

      * "MultiStaffInstrument.default_spelling_policy"

-[ Public-Facing API (result of *import **): ]-

+------------+--------------------------------------------------------------------------------------------+
| "MultiNote | The equivalent of an "NoteHandle" but for a "MultiPresetInstrument".                       |
| Handle"([n |                                                                                            |
| ote_handle |                                                                                            |
| s])        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "MultiPres | A convenient wrapper for bundling multiple *ScampInstrument* objects or soundfont presets  |
| etInstrume | into a single notated part, and assigning particular notations to these presets.           |
| nt"(sessio |                                                                                            |
| n, name[,  |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


======================================================================
=== FILE: scamp_extensions.process/scamp_extensions.process.fibonacci.txt
======================================================================

scamp_extensions.process.fibonacci
**********************************

Module containing generators for the fibonacci sequence and its
relatives, including the cycles that arise from taking such a sequence
modulo some number (the Pisano periods).


======================================================================
=== FILE: scamp_extensions.process/scamp_extensions.process.generators.non_repeating_shuffle.txt
======================================================================

scamp_extensions.process.generators.non_repeating_shuffle
*********************************************************

scamp_extensions.process.generators.non_repeating_shuffle(input_list, stop_after=inf, insertion_threshold=0.5)

   Returns a generator that randomly selects items from the input
   list, avoiding repeat selections.

   Parameters:
      * **input_list** -- the list to shuffle through

      * **stop_after** -- stops after returning this many items

      * **insertion_threshold** -- how close to insert an item back in
        the deck after it has been selected. When close to 1, the same
        item can be returned in close proximity to itself, when close
        to 0, we cycle through almost every other item before getting
        the same item again. (At 0, becomes a deterministic repeated
        shuffle.)


======================================================================
=== FILE: scamp_extensions.process/scamp_extensions.process.generators.random_walk.txt
======================================================================

scamp_extensions.process.generators.random_walk
***********************************************

scamp_extensions.process.generators.random_walk(start_value, step=1, turn_around_chance=0.5, clamp_min=None, clamp_max=None)

   Returns a generator starting on *start_value* that randomly walks
   between *clamp_min* and *clamp_max*, using a step size of *step*,
   and turning around with probability *turn_around_chance*

   Parameters:
      * **start_value** -- walk start value

      * **step** -- walk step size

      * **turn_around_chance** -- probability of turning around
        (affects wiggliness)

      * **clamp_min** -- random walk bounces off of this lower limit.
        If None, walk can go arbitrarily low.

      * **clamp_max** -- random walk bounces off of this upper limit.
        If None, walk can go arbitrarily high.


======================================================================
=== FILE: scamp_extensions.process/scamp_extensions.process.generators.txt
======================================================================

scamp_extensions.process.generators
***********************************

Module containing useful generator functions that represent musical
processes.

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "non_repea | Returns a generator that randomly selects items from the input list, avoiding repeat       |
| ting_shuff | selections.                                                                                |
| le"(input_ |                                                                                            |
| list[,     |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "random_wa | Returns a generator starting on *start_value* that randomly walks between *clamp_min* and  |
| lk"(start_ | *clamp_max*, using a step size of *step*, and turning around with probability              |
| value[,    | *turn_around_chance*                                                                       |
| step,      |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.process.generators.non_repeating_shuffle

  * "non_repeating_shuffle()"

* scamp_extensions.process.generators.random_walk

  * "random_walk()"


======================================================================
=== FILE: scamp_extensions.process/scamp_extensions.process.l_systems.LSystem.txt
======================================================================

scamp_extensions.process.l_systems.LSystem
******************************************

class scamp_extensions.process.l_systems.LSystem(seed_string: str, production_rules: MutableMapping[str, str], meanings: MutableMapping[str, Any] = None)

   Bases: "object"

   Simple implementation of an LSystem. Each generation is a string
   consisting of an alphabet of characters. Optionally, these
   characters can be assigned meanings.

   Parameters:
      * **seed_string** -- the initial string

      * **production_rules** -- dictionary describing how each letter
        evolves in a subsequent generation. Any letter not found in
        the dictionary is assumed to be a constant. Also, stochastic
        rules are possible by providing a list or tuple of outcomes
        for a given letter, or a list/tuple consisting of a list of
        outcomes and a list of weightings.

      * **meanings** -- (optional) dictionary specifying the meaning
        of each letter. Should contain an entry for every letter
        potentially encountered.

   Variables:
      * **seed** -- the initial string

      * **rules** -- dictionary describing how each letter evolves in
        a subsequent generation. Any letter not found in the
        dictionary is assumed to be a constant

      * **meanings** -- (optional) dictionary specifying the meaning
        of each letter. Should contain an entry for every letter
        potentially encountered.

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "get_gener | Get the state of the system at the nth generation of iteration, where n=0 is the initial   |
   | ation"(n)  | state.                                                                                     |
   +------------+--------------------------------------------------------------------------------------------+
   | "get_gener | Get the meanings associated with the given generation, according to the meanings           |
   | ation_mean | dictionary.                                                                                |
   | ings"(n)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   get_generation(n: int) -> str

      Get the state of the system at the nth generation of iteration,
      where n=0 is the initial state. The first time a generation is
      requested, all previous generations must be processed; however,
      thereafter they are cached.

      Parameters:
         **n** -- which generation

   get_generation_meanings(n: int) -> Tuple

      Get the meanings associated with the given generation, according
      to the meanings dictionary.

      Parameters:
         **n** -- which generation


======================================================================
=== FILE: scamp_extensions.process/scamp_extensions.process.l_systems.txt
======================================================================

scamp_extensions.process.l_systems
**********************************

Module containing the "LSystem" class, a simple implementation of a
Lindenmayer system. (See https://en.wikipedia.org/wiki/L-system).

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "LSystem"( | Simple implementation of an LSystem.                                                       |
| seed_strin |                                                                                            |
| g, product |                                                                                            |
| ion_rules[ |                                                                                            |
| , ...])    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.process.l_systems.LSystem

  * "LSystem"

    * "LSystem.get_generation()"

    * "LSystem.get_generation_meanings()"


======================================================================
=== FILE: scamp_extensions.process/scamp_extensions.process.markov.MarkovIterator.txt
======================================================================

scamp_extensions.process.markov.MarkovIterator
**********************************************

class scamp_extensions.process.markov.MarkovIterator(markov_model: MarkovModel, order: float, start_values: Sequence = None, keep_looping: bool = False)

   Bases: "object"

   Iterator that returns generated values from the given MarkovModel.
   Order can be fractional and can change during iteration.

   Parameters:
      * **markov_model** -- the MarkovModel used for resynthesis.

      * **order** -- the Markov order used in generating new states.
        Can be floating point, in which case the order for any given
        move is a weighted random choice between the adjacent integer
        orders.

      * **start_values** -- Values with which to seed this iterator's
        history. If none, simply starts at random state from within
        the data set.

      * **keep_looping** -- if True, then when we hit a dead end, keep
        reducing the order by one until we find a next move (once it
        gets to order zero, it just chooses randomly)


======================================================================
=== FILE: scamp_extensions.process/scamp_extensions.process.markov.MarkovModel.txt
======================================================================

scamp_extensions.process.markov.MarkovModel
*******************************************

class scamp_extensions.process.markov.MarkovModel(data: Sequence = None, max_order: int = 1, cyclic: bool = True)

   Bases: "object"

   A Markov analysis-synthesis tool that analyzes the given data, and
   can generate new data based on the same statistical patterns.

   Parameters:
      * **data** -- A sequence of states whose transition
        probabilities to analyze (can train after instantiating too)

      * **max_order** -- The maximum order of Markov analysis to
        perform

      * **cyclic** -- Whether or not to treat the data as cyclic. (If
        not, resynthesis can reach a dead end.)

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "generate" | Generates a sequence of states following the Markov analysis performed on the input data.  |
   | (num_value |                                                                                            |
   | s, order[, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get_itera | Returns a "MarkovIterator" based on this model.                                            |
   | tor"(order |                                                                                            |
   | [, start_v |                                                                                            |
   | alues, kee |                                                                                            |
   | p_looping] |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "move"(sta | Do one step from the indicated state, and return the final state.                          |
   | te[, rando |                                                                                            |
   | m_func])   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "move_zero | Returns a randomly selected state (weighted by frequency).                                 |
   | th_order"( |                                                                                            |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "train"(da | Train this model on a sequence, tallying which states follow which, for every order up to  |
   | ta[,       | this model's max order.                                                                    |
   | cyclic])   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   move_zeroth_order()

      Returns a randomly selected state (weighted by frequency).

   generate(num_values: int, order: float, initial_history: Sequence = None, keep_looping: bool = False) -> Sequence

      Generates a sequence of states following the Markov analysis
      performed on the input data.

      Parameters:
         * **num_values** -- How many states to generate.

         * **order** -- The Markov order used in generating new
           states. Can be floating point, in which case the order for
           any given move is a weighted random choice between the
           adjacent integer orders.

         * **initial_history** -- Values with which to seed the state
           history. If none, simply starts at random state from within
           the data set.

         * **keep_looping** -- if True, then when we hit a dead end,
           keep reducing the order by one until we find a next move
           (once it gets to order zero, it just chooses randomly)

   move(state, random_func=None)

      Do one step from the indicated state, and return the final
      state. Optionally, a function that generates a random number can
      be supplied.

   train(data, cyclic=True)

      Train this model on a sequence, tallying which states follow
      which, for every order up to this model's max order.

      Parameters:
         * **data** -- the sequence of states to learn from

         * **cyclic** -- whether to treat the sequence as looping
           around, so that the states at the end are counted as
           leading back into those at the start

   get_iterator(order: float, start_values: Sequence = None, keep_looping: bool = False) -> MarkovIterator

      Returns a "MarkovIterator" based on this model.

      Parameters:
         * **order** -- the Markov order to use in generating new
           states. Can be floating point (see "MarkovIterator"), and
           can be altered during iteration.

         * **start_values** -- Values with which to seed the
           iterator's history. If none, simply starts at random state
           from within the data set.

         * **keep_looping** -- if True, then when we hit a dead end,
           keep reducing the order by one until we find a next move
           (once it gets to order zero, it just chooses randomly)


======================================================================
=== FILE: scamp_extensions.process/scamp_extensions.process.markov.txt
======================================================================

scamp_extensions.process.markov
*******************************

Module containing the "MarkovModel" and "MarkovIterator" classes for
analyzing and resynthesizing a sequence based on Markov analysis.
Capable of fractional order resynthesis. Relies upon an embedded copy
of the *pykov* (https://github.com/riccardoscalco/Pykov) library,
which in turn relies upon the *numpy*, *scipy*, and *six* libraries.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "MarkovIte | Iterator that returns generated values from the given MarkovModel.                         |
| rator"(mar |                                                                                            |
| kov_model, |                                                                                            |
| order[,    |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "MarkovMod | A Markov analysis-synthesis tool that analyzes the given data, and can generate new data   |
| el"([data, | based on the same statistical patterns.                                                    |
| max_order, |                                                                                            |
| cyclic])   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.process.markov.MarkovIterator

  * "MarkovIterator"

* scamp_extensions.process.markov.MarkovModel

  * "MarkovModel"

    * "MarkovModel.move_zeroth_order()"

    * "MarkovModel.generate()"

    * "MarkovModel.move()"

    * "MarkovModel.train()"

    * "MarkovModel.get_iterator()"


======================================================================
=== FILE: scamp_extensions.process.txt
======================================================================

scamp_extensions.process package
********************************

Subpackage containing tools for modeling a compositional process, such
as Markov chains and L-Systems.

-[ Modules: ]-

+------------+--------------------------------------------------------------------------------------------+
| "fibonacci | A simple fibonacci generator function                                                      |
| "([seed_va |                                                                                            |
| lues])     |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "generator | Module containing useful generator functions that represent musical processes.             |
| s"         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "l_systems | Module containing the "LSystem" class, a simple implementation of a Lindenmayer system.    |
| "          |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "markov"   | Module containing the "MarkovModel" and "MarkovIterator" classes for analyzing and         |
|            | resynthesizing a sequence based on Markov analysis.                                        |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.process.fibonacci

* scamp_extensions.process.generators

  * scamp_extensions.process.generators.non_repeating_shuffle

    * "non_repeating_shuffle()"

  * scamp_extensions.process.generators.random_walk

    * "random_walk()"

* scamp_extensions.process.l_systems

  * scamp_extensions.process.l_systems.LSystem

    * "LSystem"

      * "LSystem.get_generation()"

      * "LSystem.get_generation_meanings()"

* scamp_extensions.process.markov

  * scamp_extensions.process.markov.MarkovIterator

    * "MarkovIterator"

  * scamp_extensions.process.markov.MarkovModel

    * "MarkovModel"

      * "MarkovModel.move_zeroth_order()"

      * "MarkovModel.generate()"

      * "MarkovModel.move()"

      * "MarkovModel.train()"

      * "MarkovModel.get_iterator()"

-[ Public-Facing API (result of *import **): ]-

+------------+--------------------------------------------------------------------------------------------+
| "all_fibon | For a given modulo, get a list of all possible cycles using the fibonacci recurrence       |
| acci_cycle | relation.                                                                                  |
| s"(modulo[ |                                                                                            |
| , return_p |                                                                                            |
| airs])     |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "fibonacci | A simple fibonacci generator function                                                      |
| "([seed_va |                                                                                            |
| lues])     |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "fibonacci | Gets the cycle of fibonacci (or related) numbers with the given modulo and pair of seed    |
| _cycle"(mo | values.                                                                                    |
| dulo[,     |                                                                                            |
| seed, num_ |                                                                                            |
| cycles,    |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "non_repea | Returns a generator that randomly selects items from the input list, avoiding repeat       |
| ting_shuff | selections.                                                                                |
| le"(input_ |                                                                                            |
| list[,     |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "random_wa | Returns a generator starting on *start_value* that randomly walks between *clamp_min* and  |
| lk"(start_ | *clamp_max*, using a step size of *step*, and turning around with probability              |
| value[,    | *turn_around_chance*                                                                       |
| step,      |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "LSystem"( | Simple implementation of an LSystem.                                                       |
| seed_strin |                                                                                            |
| g, product |                                                                                            |
| ion_rules[ |                                                                                            |
| , ...])    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "MarkovIte | Iterator that returns generated values from the given MarkovModel.                         |
| rator"(mar |                                                                                            |
| kov_model, |                                                                                            |
| order[,    |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "MarkovMod | A Markov analysis-synthesis tool that analyzes the given data, and can generate new data   |
| el"([data, | based on the same statistical patterns.                                                    |
| max_order, |                                                                                            |
| cyclic])   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


======================================================================
=== FILE: scamp_extensions.rhythm/scamp_extensions.rhythm.boolean_streamer.txt
======================================================================

scamp_extensions.rhythm.boolean_streamer
****************************************

Module containing the "boolean_streamer()" decorator, which converts a
boolean-yielding generator into a "BooleanStreamer" object.
"BooleanStreamer" objects are iterable and can be combined using the
*&*, *|* and *~* operators to compose more complex streams of
booleans. A few useful decorated boolean_streamer functions are given,
including the "SieveStreamer()", which implements Xenakis-style sieves
the "RandStreamer()", which generates weighted random *True*/*False*
values, and the "FreqStreamer()" which generates regularly spaced
*True*'s at the frequency defined by the function.


======================================================================
=== FILE: scamp_extensions.rhythm/scamp_extensions.rhythm.indispensability.barlow_style_indispensability_array.txt
======================================================================

scamp_extensions.rhythm.indispensability.barlow_style_indispensability_array
****************************************************************************

scamp_extensions.rhythm.indispensability.barlow_style_indispensability_array(*rhythmic_strata: int | Sequence[int], normalize: bool = False) -> List[INT_OR_FLOAT]

   Alternate implementation of
   "get_standard_indispensability_array()", leveraging the
   "MetricStructure" class to do the calculations.

   Parameters:
      * **rhythmic_strata** -- can be either tuples, representing
        additive metric layers, or integers, representing simple
        metric layers.

      * **normalize** -- if True, indispensabilities range from 0 to
        1. If false, they count up from 0.

   Returns:
      a list of indispensabilities for the pulses of the given meter.


======================================================================
=== FILE: scamp_extensions.rhythm/scamp_extensions.rhythm.indispensability.indispensability_array_from_expression.txt
======================================================================

scamp_extensions.rhythm.indispensability.indispensability_array_from_expression
*******************************************************************************

scamp_extensions.rhythm.indispensability.indispensability_array_from_expression(meter_arithmetic_expression: str, normalize: bool = False, break_up_large_numbers: bool = False, upbeats_before_group_length: bool = True) -> List[INT_OR_FLOAT]

   Generates an array of indispensability values for a meter and
   subdivision, as expressed by a meter arithmetic expression. Such
   expressions allow great flexibility in describing metric structure,
   making possible additive, multiplicative, and hybrid metrical
   structures.

   Parameters:
      * **meter_arithmetic_expression** -- An string expression
        representing a metric hierarchy (meter and subdivision
        structure). For instance, "2 * 3" would create the eighth-note
        subdivisions of 6/8, and "2 + 3 + 2" would create an additive
        meter (2+3+2)/8.  "(2 + 3 + 2) * 3" would create a kind of
        hybrid of these: seven main beats in a 2 + 3 + 2 pattern, each
        of which is subdivided in 3. This might be notated as
        6/8+9/8+6/8.

      * **normalize** -- if True, indispensabilities range from 0 to
        1. If false, they count up from 0.

      * **break_up_large_numbers** -- if True, numbers greater than 3
        are broken up into a sum of 2's followed by one 3 if odd. This
        is the Barlow approach.

      * **upbeats_before_group_length** -- see description in
        "metric_structure.flatten_beat_groups()". Affects the result
        when there are groups of uneven length at some level of metric
        structure. To achieve the standard Barlowian result, set this
        to False. I think it works better as True, though.

   Returns:
      a list of indispensabilities for the pulses of the given meter.


======================================================================
=== FILE: scamp_extensions.rhythm/scamp_extensions.rhythm.indispensability.indispensability_array_from_strata.txt
======================================================================

scamp_extensions.rhythm.indispensability.indispensability_array_from_strata
***************************************************************************

scamp_extensions.rhythm.indispensability.indispensability_array_from_strata(*rhythmic_strata: int | Sequence[int], normalize: bool = False, break_up_large_numbers: bool = False, upbeats_before_group_length: bool = True) -> List[INT_OR_FLOAT]

   Alternate implementation of "get_indispensability_array()",
   leveraging the "MetricStructure" class to do the calculations.

   Parameters:
      * **rhythmic_strata** -- can be either tuples, representing
        additive metric layers, or integers, representing simple
        metric layers.

      * **normalize** -- if True, indispensabilities range from 0 to
        1. If false, they count up from 0.

      * **break_up_large_numbers** -- if True, numbers greater than 3
        are broken up into a sum of 2's followed by one 3 if odd. This
        is the Barlow approach.

      * **upbeats_before_group_length** -- see description in
        "metric_structure.flatten_beat_groups()". Affects the result
        when there are groups of uneven length at some level of metric
        structure. To achieve the standard Barlowian result, set this
        to False. I think it works better as True, though.

   Returns:
      a list of indispensabilities for the pulses of the given meter.


======================================================================
=== FILE: scamp_extensions.rhythm/scamp_extensions.rhythm.indispensability.txt
======================================================================

scamp_extensions.rhythm.indispensability
****************************************

Re-implementation and extension of Clarence Barlow's concept of
rhythmic indispensability such that it works for additive meters (even
nested additive meters). Since these are my own extensions of Barlow's
ideas, they are here instead of in
"scamp_extensions.composers.barlicity".

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "barlow_st | Alternate implementation of "get_standard_indispensability_array()", leveraging the        |
| yle_indisp | "MetricStructure" class to do the calculations.                                            |
| ensability |                                                                                            |
| _array"(.. |                                                                                            |
| .[, ...])  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "indispens | Generates an array of indispensability values for a meter and subdivision, as expressed by |
| ability_ar | a meter arithmetic expression.                                                             |
| ray_from_e |                                                                                            |
| xpression" |                                                                                            |
| (...)      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "indispens | Alternate implementation of "get_indispensability_array()", leveraging the                 |
| ability_ar | "MetricStructure" class to do the calculations.                                            |
| ray_from_s |                                                                                            |
| trata"(... |                                                                                            |
| [, ...])   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.rhythm.indispensability.barlow_style_indispensabili
  ty_array

  * "barlow_style_indispensability_array()"

* scamp_extensions.rhythm.indispensability.indispensability_array_from
  _expression

  * "indispensability_array_from_expression()"

* scamp_extensions.rhythm.indispensability.indispensability_array_from
  _strata

  * "indispensability_array_from_strata()"


======================================================================
=== FILE: scamp_extensions.rhythm/scamp_extensions.rhythm.metric_structure.MeterArithmeticGroup.txt
======================================================================

scamp_extensions.rhythm.metric_structure.MeterArithmeticGroup
*************************************************************

class scamp_extensions.rhythm.metric_structure.MeterArithmeticGroup(elements: Sequence[MeterArithmeticGroup | int], operation: str | None)

   Bases: "object"

   This class exists as an aid to parsing arithmetic expressions into
   MetricStructures. Simply defining __add__ and __mul__ for
   MetricStructure wasn't flexible enough, since it was important to
   differentiate between, say, a "4 + 2 + 3" meter and a "(4 + 2) + 3"
   meter. The former establishes a flat hierarchy with three groups,
   whereas the latter establishes a nested hierarchy with two groups,
   the first of which is split into two smaller groups.

   Parameters:
      * **elements** -- a list of MeterArithmeticGroups or integers
        representing simple beat groups

      * **operation** -- either "+", "*", or None, in the case of just
        a number

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "parse"(in | Parses an input string containing an arithmetic expression into a (probably nested)        |
   | put_string | MeterArithmeticGroup. For instance an input string of "(3+2)+3*2" will be parsed as::.     |
   | )          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "to_metric | Renders this arithmetic group as a "MetricStructure".                                      |
   | _structure |                                                                                            |
   | "([break_u |                                                                                            |
   | p_large_nu |                                                                                            |
   | mbers])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   classmethod parse(input_string: str) -> MeterArithmeticGroup

      Parses an input string containing an arithmetic expression into
      a (probably nested) MeterArithmeticGroup. For instance an input
      string of "(3+2)+3*2" will be parsed as:

         MeterArithmeticGroup(
             [MeterArithmeticGroup([MeterArithmeticGroup([3], "None"), MeterArithmeticGroup([2], "None")], "+"),
             MeterArithmeticGroup([MeterArithmeticGroup([3], "None"), MeterArithmeticGroup([2], "None")], "*")],
             "+"
         )

      Parameters:
         **input_string** -- input string consisting of integers, plus
         signs, multiplication signs, and parentheses

      Returns:
         a MeterArithmeticGroup

   to_metric_structure(break_up_large_numbers: bool = False) -> MetricStructure

      Renders this arithmetic group as a "MetricStructure".

      Parameters:
         **break_up_large_numbers** -- see "MetricStructure"


======================================================================
=== FILE: scamp_extensions.rhythm/scamp_extensions.rhythm.metric_structure.MetricStructure.txt
======================================================================

scamp_extensions.rhythm.metric_structure.MetricStructure
********************************************************

class scamp_extensions.rhythm.metric_structure.MetricStructure(*groups: Sequence[int, Sequence, MetricStructure], break_up_large_numbers: bool = False)

   Bases: "object"

   A highly flexible representation of a metric hierarchy, capable of
   describing both additive, multiplicative, and hybrid
   additive/multiplicative meters. Each MetricStructure describes a
   single layer of a metric grouping, and more complex hierarchies can
   be created by nesting metric structures inside of one another. For
   instance, a 2 + 3 + 2 additive meter is simply constructed with
   "MetricStructure(2, 3, 2)". If we want each of the eight pulses in
   this meter to be subdivided in three, we could accomplish this by
   nesting metric strucures like this:
   "MetricStructure(MetricStructure(3, 3), MetricStructure(3, 3, 3),
   MetricStructure(3, 3))". Of course, this is quite a cumbersome
   expression, so it is usually much easier and more intuitive to use
   the "from_string()" class method:
   "MetricStructure.from_string("(2+3+2)*3")".

   Note that instances of MetricStructure do not contain any
   information as to the speed of fastest subdivision; they simply
   describe how subdivisions come together to form beats, how beats
   come together to form meters, etc. A MetricStructure can be asked
   to calculate an array of indispensibility values (following the
   theories of Clarence Barlow), or an array of beat depths, showing
   how nested each pulse is within the underlying meter (i.e. the
   degree to which it is on or off the beat, and at what layer of
   structure).

   Parameters:
      * **groups** -- list of additively combined groups. If all
        integers, then this is like a simple additive meter without
        considering subdivisions. For instance, (2, 4, 3) is like the
        time signature (2+4+3)/8. However, any component of this
        structure can instead be itself a MetricStructure, allowing
        for nesting. Nested structures can also be created by having
        one of the groups be a tuple, or tuple of tuples, etc.

      * **break_up_large_numbers** -- if True, groups with number
        greater than 3 are broken up into a sum of 2's followed by one
        3 if odd. This is the Barlow approach.

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "append"(o | Adds a new group to this MetricStructure consisting of other_metric_structure.             |
   | ther_metri |                                                                                            |
   | c_structur |                                                                                            |
   | e[,        |                                                                                            |
   | in_place]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "extend"(o | Extends this MetricStructure by appending all of the groups of other_metric_structure.     |
   | ther_metri |                                                                                            |
   | c_structur |                                                                                            |
   | e[,        |                                                                                            |
   | in_place]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_stri | Creates a MetricStructure from an appropriately formatted input string.                    |
   | ng"(input_ |                                                                                            |
   | string[,   |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get_beat_ | Returns a list of integers representing how nested each beat/subdivision is within the     |
   | depths"()  | metric structure.                                                                          |
   +------------+--------------------------------------------------------------------------------------------+
   | "get_indis | Resolve the nested structure to a single one-dimensional indispensability array.           |
   | pensabilit |                                                                                            |
   | y_array"([ |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "join"(oth | Creates a new MetricStructure with two groups: this MetricStructure and                    |
   | er_metric_ | other_metric_structure.                                                                    |
   | structure) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "num_pulse | The total number of pulses (smallest subdivisions) in this MetricStructure                 |
   | s"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   classmethod from_string(input_string: str, break_up_large_numbers: bool = False) -> MetricStructure

      Creates a MetricStructure from an appropriately formatted input
      string. This is the simplest way of creating complex nested
      structures. For example, "3 * 2 + 5 + (2 + 3)" renders to
      *MetricStructure(MetricStructure(2, 2, 2), 5, MetricStructure(2,
      3))*.

      Parameters:
         * **input_string** -- input string consisting of integers,
           plus signs, multiplication signs, and parentheses

         * **break_up_large_numbers** -- see "MetricStructure"

   get_beat_depths() -> list[int]

      Returns a list of integers representing how nested each
      beat/subdivision is within the metric structure. For example,
      *MetricStructure(MetricStructure(2, 2, 2), 5, MetricStructure(2,
      3))* will give us beat depths *[0, 3, 2, 3, 2, 3, 1, 3, 3, 3, 3,
      1, 3, 2, 3, 3]*. Notice that the first beat has depth zero, and
      the start of each of the three main groups --- (2, 2, 2), 5, and
      (3, 2) --- has depth 1.

   get_indispensability_array(upbeats_before_group_length: bool = True, normalize: bool = False) -> list[INT_OR_FLOAT]

      Resolve the nested structure to a single one-dimensional
      indispensability array. See Barlow's "On Musiquantics"
      (http://clarlow.org/wp-content/uploads/2016/10/On-
      MusiquanticsA4.pdf) for more detail.

      Parameters:
         * **upbeats_before_group_length** -- see description in
           "flatten_beat_groups()" above. Affects the result when
           there are groups of uneven length at some level of metric
           structure. To achieve the standard Barlowian result, set
           this to False. I think it works better as True, though.

         * **normalize** -- if True, indispensabilities range from 0
           to 1. If false, they count up from 0.

      Returns:
         an indispensability array

   num_pulses() -> int

      The total number of pulses (smallest subdivisions) in this
      MetricStructure

   extend(other_metric_structure: MetricStructure, in_place: bool = True) -> MetricStructure

      Extends this MetricStructure by appending all of the groups of
      other_metric_structure. For example: *MetricStructure(3,
      3).extend(MetricStructure(2, 2))* results in *MetricStructure(3,
      3, 2, 2)*.

      Parameters:
         * **other_metric_structure** -- another MetricStructure

         * **in_place** -- if True, alters this object; if false
           returns an extended copy.

   append(other_metric_structure: MetricStructure, in_place: bool = True) -> MetricStructure

      Adds a new group to this MetricStructure consisting of
      other_metric_structure. For example, *MetricStructure(3,
      3).append(MetricStructure(2, 2))* results in *MetricStructure(3,
      3, MetricStructure(2, 2))*.

      Parameters:
         * **other_metric_structure** -- another MetricStructure

         * **in_place** -- if True, alters this object; if false
           returns an extended copy.

   join(other_metric_structure) -> MetricStructure

      Creates a new MetricStructure with two groups: this
      MetricStructure and other_metric_structure. For example,
      *MetricStructure(3, 3).join(MetricStructure(2, 2))* results in
      *MetricStructure(MetricStructure(3, 3), MetricStructure(2, 2))*.

      Parameters:
         **other_metric_structure** -- another MetricStructure


======================================================================
=== FILE: scamp_extensions.rhythm/scamp_extensions.rhythm.metric_structure.flatten_beat_groups.txt
======================================================================

scamp_extensions.rhythm.metric_structure.flatten_beat_groups
************************************************************

scamp_extensions.rhythm.metric_structure.flatten_beat_groups(beat_groups: list[list], upbeats_before_group_length: bool = True) -> list

   Returns a flattened version of beat_groups, unraveling the outer
   layer according to rules of indispensability. Repeated application
   of this function to nested beat groups leads to a 1-d ordered list
   of beat priorities

   Parameters:
      * **beat_groups** -- list of nested beat group

      * **upbeats_before_group_length** -- This is best explained with
        an example. Consider a 5 = 2 + 3 beat pattern. The Barlow
        approach to indispensability would give indispensabilities [4,
        0, 3, 1, 2]. The idea would be downbeat first, then start of
        the group of 3, then upbeat to downbeat, and then the fourth
        eighth note because it's the upbeat to that upbeat, and
        because he would say the eighth note right after the downbeat
        should be the most dispensable. However, another way of
        looking at it would be to say that once we get to [4, _, 3, _,
        2], the next most indispensable beat should be the second
        eighth note, since it is the pickup to the second most
        indispensable beat! This would yield indispensabilities [4, 1,
        3, 0, 2], which also makes sense. I've chosen to make this
        latter approach the default; I think it generally sounds more
        correct.

   Returns:
      a (perhaps still nested) list of beat groups with the outer
      layer unraveled so that it's a layer less deep


======================================================================
=== FILE: scamp_extensions.rhythm/scamp_extensions.rhythm.metric_structure.txt
======================================================================

scamp_extensions.rhythm.metric_structure
****************************************

Contains the "MetricStructure" class, which provides a highly flexible
representation of metric hierarchy. The easiest and most flexible way
of creating MetricStructures is through the "from_string()" method,
which makes use of the "MeterArithmeticGroup" class to parse
expressions like "(2 + 3 + 2) * 3" (which would representing a 6/8 +
9/8 + 6/8 additive compound meter).

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "MetricStr | A highly flexible representation of a metric hierarchy, capable of describing both         |
| ucture"(*g | additive, multiplicative, and hybrid additive/multiplicative meters.                       |
| roups[,    |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "MeterArit | This class exists as an aid to parsing arithmetic expressions into MetricStructures.       |
| hmeticGrou |                                                                                            |
| p"(element |                                                                                            |
| s,         |                                                                                            |
| operation) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.rhythm.metric_structure.MetricStructure

  * "MetricStructure"

    * "MetricStructure.from_string()"

    * "MetricStructure.get_beat_depths()"

    * "MetricStructure.get_indispensability_array()"

    * "MetricStructure.num_pulses()"

    * "MetricStructure.extend()"

    * "MetricStructure.append()"

    * "MetricStructure.join()"

* scamp_extensions.rhythm.metric_structure.MeterArithmeticGroup

  * "MeterArithmeticGroup"

    * "MeterArithmeticGroup.parse()"

    * "MeterArithmeticGroup.to_metric_structure()"

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "flatten_b | Returns a flattened version of beat_groups, unraveling the outer layer according to rules  |
| eat_groups | of indispensability.                                                                       |
| "(beat_gro |                                                                                            |
| ups[,      |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.rhythm.metric_structure.flatten_beat_groups

  * "flatten_beat_groups()"


======================================================================
=== FILE: scamp_extensions.rhythm.txt
======================================================================

scamp_extensions.rhythm package
*******************************

Subpackage containing rhythm-related extensions. These include
abstractions for representing metric structures, a more flexible
implementation of Clarence Barlow's concept of indispensability, and a
boolean streamer module that implements, among other things, a
Xenakian sieve rhythms.

-[ Modules: ]-

+------------+--------------------------------------------------------------------------------------------+
| "boolean_s | Decorator that converts a boolean-yielding generator function into a "BooleanStreamer"     |
| treamer"(f | object                                                                                     |
| unc)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "indispens | Re-implementation and extension of Clarence Barlow's concept of rhythmic indispensability  |
| ability"   | such that it works for additive meters (even nested additive meters).                      |
+------------+--------------------------------------------------------------------------------------------+
| "metric_st | Contains the "MetricStructure" class, which provides a highly flexible representation of   |
| ructure"   | metric hierarchy.                                                                          |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.rhythm.boolean_streamer

* scamp_extensions.rhythm.indispensability

  * scamp_extensions.rhythm.indispensability.barlow_style_indispensabi
    lity_array

    * "barlow_style_indispensability_array()"

  * scamp_extensions.rhythm.indispensability.indispensability_array_fr
    om_expression

    * "indispensability_array_from_expression()"

  * scamp_extensions.rhythm.indispensability.indispensability_array_fr
    om_strata

    * "indispensability_array_from_strata()"

* scamp_extensions.rhythm.metric_structure

  * scamp_extensions.rhythm.metric_structure.MetricStructure

    * "MetricStructure"

      * "MetricStructure.from_string()"

      * "MetricStructure.get_beat_depths()"

      * "MetricStructure.get_indispensability_array()"

      * "MetricStructure.num_pulses()"

      * "MetricStructure.extend()"

      * "MetricStructure.append()"

      * "MetricStructure.join()"

  * scamp_extensions.rhythm.metric_structure.MeterArithmeticGroup

    * "MeterArithmeticGroup"

      * "MeterArithmeticGroup.parse()"

      * "MeterArithmeticGroup.to_metric_structure()"

  * scamp_extensions.rhythm.metric_structure.flatten_beat_groups

    * "flatten_beat_groups()"

-[ Public-Facing API (result of *import **): ]-

+------------+--------------------------------------------------------------------------------------------+
| "BooleanSt | Wrapper for a generator function that returns only boolean values.                         |
| reamer"(ge |                                                                                            |
| nerator_fu |                                                                                            |
| nction,    |                                                                                            |
| *args,     |                                                                                            |
| ...)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "FreqStrea | A phase-accumulation based "BooleanStreamer" that yields True values with a frequency      |
| mer"(freq_ | given by the frequency function.                                                           |
| func)      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "RandStrea | A "BooleanStreamer" that yields True values with the given probability.                    |
| mer"(true_ |                                                                                            |
| prob)      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "SieveStre | A Xenakis-sieve-style "BooleanStreamer" that yields patterns of True/False based on a      |
| amer"(modu | modulo, which defines the cycle length; and a shift, which defines which remainder (or     |
| lo[,       | remainders) yielding True values.                                                          |
| shift])    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "boolean_s | Decorator that converts a boolean-yielding generator function into a "BooleanStreamer"     |
| treamer"(f | object                                                                                     |
| unc)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "barlow_st | Alternate implementation of "get_standard_indispensability_array()", leveraging the        |
| yle_indisp | "MetricStructure" class to do the calculations.                                            |
| ensability |                                                                                            |
| _array"(.. |                                                                                            |
| .[, ...])  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "indispens | Generates an array of indispensability values for a meter and subdivision, as expressed by |
| ability_ar | a meter arithmetic expression.                                                             |
| ray_from_e |                                                                                            |
| xpression" |                                                                                            |
| (...)      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "indispens | Alternate implementation of "get_indispensability_array()", leveraging the                 |
| ability_ar | "MetricStructure" class to do the calculations.                                            |
| ray_from_s |                                                                                            |
| trata"(... |                                                                                            |
| [, ...])   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "MeterArit | This class exists as an aid to parsing arithmetic expressions into MetricStructures.       |
| hmeticGrou |                                                                                            |
| p"(element |                                                                                            |
| s,         |                                                                                            |
| operation) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "MetricStr | A highly flexible representation of a metric hierarchy, capable of describing both         |
| ucture"(*g | additive, multiplicative, and hybrid additive/multiplicative meters.                       |
| roups[,    |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


======================================================================
=== FILE: scamp_extensions.txt
======================================================================

scamp_extensions package
************************

Package intended to provide extra, non-core functionality to the SCAMP
(Suite for Computer-Assisted Music in Python) framework for music
composition. This package is the place for models of music-theoretical
concepts (e.g. scales, pitch-class sets), conveniences for interacting
with various types of input and output, and in general anything that
builds upon SCAMP but is outside of the scope of the main framework.

The package is split into several subpackages: the pitch subpackage
has tools for manipulating pitches, such as scales and intervals;
rhythm has tools for representing meters and rhythmic structures;
playback has extensions such as multi-preset instruments; engraving
has extensions such as graphic notation; interaction has utilities for
human interface devices and other live interactions; process has tools
for modeling a compositional process, such as Markov chains and
L-systems; composers showcases some composer-specific tools and
theoretical devices; parsing has utilities for parsing data formats;
and utilities has general helpers that fit nowhere else.

-[ Sub-packages: ]-

+------------+--------------------------------------------------------------------------------------------+
| "composers | Subpackage containing composer-specific tools and theoretical devices.                     |
| "          |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "engraving | Subpackage containing engraving-related extensions.                                        |
| "          |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "interacti | Subpackage containing utilities for human interface devices and other live interactions.   |
| on"        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "parsing"  | Subpackage containing utilities for parsing data formats.                                  |
+------------+--------------------------------------------------------------------------------------------+
| "pitch"    | Subpackage containing pitch-related extensions.                                            |
+------------+--------------------------------------------------------------------------------------------+
| "playback" | Subpackage containing playback-related extensions, such as support for multi-preset        |
|            | instruments.                                                                               |
+------------+--------------------------------------------------------------------------------------------+
| "process"  | Subpackage containing tools for modeling a compositional process, such as Markov chains    |
|            | and L-Systems.                                                                             |
+------------+--------------------------------------------------------------------------------------------+
| "rhythm"   | Subpackage containing rhythm-related extensions.                                           |
+------------+--------------------------------------------------------------------------------------------+
| "utilities | Subpackage containing utility functions that do not fit into any of the other extension    |
| "          | categories.                                                                                |
+------------+--------------------------------------------------------------------------------------------+


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.AtanWarp.txt
======================================================================

scamp_extensions.utilities.math.AtanWarp
****************************************

class scamp_extensions.utilities.math.AtanWarp(in_lo: float, in_hi: float, out_min: float, out_max: float)

   Bases: "object"

   A warping function that uses an appropriately scaled arctan to warp
   values from the input range to the output range. See "atan_warp()"
   for details. This callable object version is callable allows you to
   define the warp on instantiation and then call it like a function.
   E.g:

      warper = AtanWarp(-10, 10, 100, 200)
      print(warper(0), warper(-5), warper(20))

   Parameters:
      * **in_lo** -- soft input minimum

      * **in_hi** -- soft input maximum

      * **out_min** -- hard input minimum

      * **out_max** -- hard input maximum


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.atan_warp.txt
======================================================================

scamp_extensions.utilities.math.atan_warp
*****************************************

scamp_extensions.utilities.math.atan_warp(value, in_lo, in_hi, out_min, out_max) -> float

   Uses an appropriately scaled arctan function to warp values from
   the input range to the output range. The input range is a soft
   boundary for the inputs expected, whereas the output range is a
   hard limit, to which extreme high and low input values asymptote.
   At the exact center of the input range there is no warping, and the
   slope of the transformation is the same as if it were linear; as
   input values approach or exceed the boundaries of the input range,
   the output approaches, but never exceeds the output range.

   Parameters:
      * **value** -- the value to warp

      * **in_lo** -- soft input minimum

      * **in_hi** -- soft input maximum

      * **out_min** -- hard output minimum

      * **out_max** -- hard output maximum


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.ceil_to_multiple.txt
======================================================================

scamp_extensions.utilities.math.ceil_to_multiple
************************************************

scamp_extensions.utilities.math.ceil_to_multiple(x, factor)

   Returns the multiple of factor that is closest above x. The first
   argument can optionally be a list, tuple, or iterator, in which
   case this is performed on each element.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.ceil_x_to_pow_of_y.txt
======================================================================

scamp_extensions.utilities.math.ceil_x_to_pow_of_y
**************************************************

scamp_extensions.utilities.math.ceil_x_to_pow_of_y(x, y)

   Returns the integer power of y that is closest above x. The first
   argument can optionally be a list, tuple, or iterator, in which
   case this is performed on each element.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.floor_to_multiple.txt
======================================================================

scamp_extensions.utilities.math.floor_to_multiple
*************************************************

scamp_extensions.utilities.math.floor_to_multiple(x, factor)

   Returns the multiple of factor that is closest below x. The first
   argument can optionally be a list, tuple, or iterator, in which
   case this is performed on each element.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.floor_x_to_pow_of_y.txt
======================================================================

scamp_extensions.utilities.math.floor_x_to_pow_of_y
***************************************************

scamp_extensions.utilities.math.floor_x_to_pow_of_y(x, y)

   Returns the integer power of y that is closest below x. The first
   argument can optionally be a list, tuple, or iterator, in which
   case this is performed on each element.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.gcd.txt
======================================================================

scamp_extensions.utilities.math.gcd
***********************************

scamp_extensions.utilities.math.gcd(*integers)

   Greatest Common Divisor.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.is_multiple.txt
======================================================================

scamp_extensions.utilities.math.is_multiple
*******************************************

scamp_extensions.utilities.math.is_multiple(x, y) -> bool

   Checks if x is a multiple of y.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.is_prime.txt
======================================================================

scamp_extensions.utilities.math.is_prime
****************************************

scamp_extensions.utilities.math.is_prime(a: int) -> bool

   Checks if a is a prime number.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.is_x_pow_of_y.txt
======================================================================

scamp_extensions.utilities.math.is_x_pow_of_y
*********************************************

scamp_extensions.utilities.math.is_x_pow_of_y(x, y) -> bool

   Checks if x is an integer (including negative) power of y


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.lcm.txt
======================================================================

scamp_extensions.utilities.math.lcm
***********************************

scamp_extensions.utilities.math.lcm(a, b)

   Return lowest common multiple.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.prime_factor.txt
======================================================================

scamp_extensions.utilities.math.prime_factor
********************************************

scamp_extensions.utilities.math.prime_factor(n: int) -> list[int]

   Returns a list of the prime factors of n.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.remap.txt
======================================================================

scamp_extensions.utilities.math.remap
*************************************

scamp_extensions.utilities.math.remap(value_or_values, out_min, out_max, in_min=None, in_max=None, input_warp='lin', output_warp='lin', clip=True)

   Rescales the given value or values so that they fall within the
   given output range. Not efficient or vectorized, but unless you're
   using large datasets, that shouldn't be an issue.

   Parameters:
      * **value_or_values** -- the value or values to rescale

      * **out_min** -- lower bound of output range

      * **out_max** -- upper bound of output range

      * **in_min** -- lower bound of input range (defaults to minimum
        input value)

      * **in_max** -- upper bound of input range (defaults to maximum
        input value)

      * **input_warp** -- either "lin", or "exp" depending on whether
        the input values are linearly (e.g. pitch) or exponentially
        (e.g. frequency) spaced.

      * **output_warp** -- either "lin", "exp", or a number that
        corresponds to the shape of the warping curve. When using a
        number, 0 is linear, > 0 warps outputs towards the bottom of
        the range, and < 0 warps outputs towards the top of the range
        (see *~expenvelope.envelope.Envelope* for a description of
        *curve_shape*).

      * **clip** -- if True, clip output values so that they do not go
        outside of the designated output range

   Returns:
      a suitable warped output value or list of output values


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.round_to_multiple.txt
======================================================================

scamp_extensions.utilities.math.round_to_multiple
*************************************************

scamp_extensions.utilities.math.round_to_multiple(x, factor)

   Returns the multiple of factor that is closest to x (above or
   below). The first argument can optionally be a list, tuple, or
   iterator, in which case this is performed on each element.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.round_x_to_pow_of_y.txt
======================================================================

scamp_extensions.utilities.math.round_x_to_pow_of_y
***************************************************

scamp_extensions.utilities.math.round_x_to_pow_of_y(x, y)

   Returns the integer power of y that is closest to x (above or
   below). The first argument can optionally be a list, tuple, or
   iterator, in which case this is performed on each element.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.txt
======================================================================

scamp_extensions.utilities.math
*******************************

Subpackage containing mathematical utility functions (many of which
are imported from "scamp.utilities".

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "AtanWarp" | A warping function that uses an appropriately scaled arctan to warp values from the input  |
| (in_lo,    | range to the output range.                                                                 |
| in_hi,     |                                                                                            |
| out_min,   |                                                                                            |
| out_max)   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.utilities.math.AtanWarp

  * "AtanWarp"

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "atan_warp | Uses an appropriately scaled arctan function to warp values from the input range to the    |
| "(value,   | output range.                                                                              |
| in_lo,     |                                                                                            |
| in_hi,     |                                                                                            |
| out_min,   |                                                                                            |
| out_max)   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "lcm"(a,   | Return lowest common multiple.                                                             |
| b)         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "remap"(va | Rescales the given value or values so that they fall within the given output range.        |
| lue_or_val |                                                                                            |
| ues,       |                                                                                            |
| out_min,   |                                                                                            |
| out_max[,  |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "wrap_to_r | Wraps the input x into the given range, either jumping back to the other side of the range |
| ange"(x,   | at the boundaries, or if the mirror parameter is set, reflecting at the boundaries.        |
| range_min, |                                                                                            |
| range_max[ |                                                                                            |
| , mirror]) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "ceil_to_m | Returns the multiple of factor that is closest above x.                                    |
| ultiple"(x |                                                                                            |
| , factor)  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "prime_fac | Returns a list of the prime factors of n.                                                  |
| tor"(n)    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "is_multip | Checks if x is a multiple of y.                                                            |
| le"(x, y)  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "gcd"(*int | Greatest Common Divisor.                                                                   |
| egers)     |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "is_prime" | Checks if a is a prime number.                                                             |
| (a)        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "is_x_pow_ | Checks if x is an integer (including negative) power of y                                  |
| of_y"(x,   |                                                                                            |
| y)         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "round_x_t | Returns the integer power of y that is closest to x (above or below).                      |
| o_pow_of_y |                                                                                            |
| "(x, y)    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "floor_x_t | Returns the integer power of y that is closest below x.                                    |
| o_pow_of_y |                                                                                            |
| "(x, y)    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "ceil_x_to | Returns the integer power of y that is closest above x.                                    |
| _pow_of_y" |                                                                                            |
| (x, y)     |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "floor_to_ | Returns the multiple of factor that is closest below x.                                    |
| multiple"( |                                                                                            |
| x, factor) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "round_to_ | Returns the multiple of factor that is closest to x (above or below).                      |
| multiple"( |                                                                                            |
| x, factor) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.utilities.math.atan_warp

  * "atan_warp()"

* scamp_extensions.utilities.math.lcm

  * "lcm()"

* scamp_extensions.utilities.math.remap

  * "remap()"

* scamp_extensions.utilities.math.wrap_to_range

  * "wrap_to_range()"

* scamp_extensions.utilities.math.ceil_to_multiple

  * "ceil_to_multiple()"

* scamp_extensions.utilities.math.prime_factor

  * "prime_factor()"

* scamp_extensions.utilities.math.is_multiple

  * "is_multiple()"

* scamp_extensions.utilities.math.gcd

  * "gcd()"

* scamp_extensions.utilities.math.is_prime

  * "is_prime()"

* scamp_extensions.utilities.math.is_x_pow_of_y

  * "is_x_pow_of_y()"

* scamp_extensions.utilities.math.round_x_to_pow_of_y

  * "round_x_to_pow_of_y()"

* scamp_extensions.utilities.math.floor_x_to_pow_of_y

  * "floor_x_to_pow_of_y()"

* scamp_extensions.utilities.math.ceil_x_to_pow_of_y

  * "ceil_x_to_pow_of_y()"

* scamp_extensions.utilities.math.floor_to_multiple

  * "floor_to_multiple()"

* scamp_extensions.utilities.math.round_to_multiple

  * "round_to_multiple()"


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.math.wrap_to_range.txt
======================================================================

scamp_extensions.utilities.math.wrap_to_range
*********************************************

scamp_extensions.utilities.math.wrap_to_range(x, range_min, range_max, mirror=False)

   Wraps the input x into the given range, either jumping back to the
   other side of the range at the boundaries, or if the mirror
   parameter is set, reflecting at the boundaries.

   Parameters:
      * **x** -- the input

      * **range_min** -- minimum of wrapping range

      * **range_max** -- maximum of wrapping range

      * **mirror** -- whether to mirror at the boundaries


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.sequences.cyclic_slice.txt
======================================================================

scamp_extensions.utilities.sequences.cyclic_slice
*************************************************

scamp_extensions.utilities.sequences.cyclic_slice(l: Sequence, start: int, end: int) -> Sequence

   Takes a slice that loops back to the beginning if end is before
   start

   Parameters:
      * **l** -- the list to slice

      * **start** -- start index

      * **end** -- end index

   Returns:
      list representing the cyclic slice


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.sequences.make_flat_list.txt
======================================================================

scamp_extensions.utilities.sequences.make_flat_list
***************************************************

scamp_extensions.utilities.sequences.make_flat_list(l: Sequence, indivisible: Type | tuple[Type] = None) -> list

   Flattens a list, including ones containing multiple levels of
   nesting. Certain types can be excluded from expansion.

   Parameters:
      * **l** -- a list or similar iterable

      * **indivisible** -- a type or tuple of types that should not be
        expanded out. E.g. a custom named tuple

   Returns:
      a flattened version of the list


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.sequences.multi_option_function.txt
======================================================================

scamp_extensions.utilities.sequences.multi_option_function
**********************************************************

scamp_extensions.utilities.sequences.multi_option_function(f)

   Decorator that allows the first argument of the function to be a
   list, tuple, or iterator, and in that case performs the function
   one each element individually, returning a list, tuple, or
   iterator.

   Parameters:
      **f** -- the function, taking at least one argument

   Returns:
      a wrapped version that can take list, tuple, or iterator


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.sequences.multi_option_method.txt
======================================================================

scamp_extensions.utilities.sequences.multi_option_method
********************************************************

scamp_extensions.utilities.sequences.multi_option_method(f)

   Same as "multi_option_function()", but used to decorate methods
   instead of functions.

   Parameters:
      **f** -- the method, taking at least one argument

   Returns:
      a wrapped version that can take list, tuple, or iterator


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.sequences.rotate_sequence.txt
======================================================================

scamp_extensions.utilities.sequences.rotate_sequence
****************************************************

scamp_extensions.utilities.sequences.rotate_sequence(s: Sequence, n: int) -> Sequence

   Rotates a sequence s such that it begins with element l[n] and
   wraps back around to l[n-1].

   Parameters:
      * **s** -- the list to rotate

      * **n** -- number of elements to shift by (can be negative
        and/or greater than the length of l)

   Returns:
      a "rotated" version of the input sequence


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.sequences.sequence_depth.txt
======================================================================

scamp_extensions.utilities.sequences.sequence_depth
***************************************************

scamp_extensions.utilities.sequences.sequence_depth(seq: Sequence) -> int

   Find the maximum _depth of any element in a nested sequence.
   Slightly adapted from pillmuncher's answer here:
   https://stackoverflow.com/questions/6039103/counting-depth-or-the-
   deepest-level-a-nested-list-goes-to

   Parameters:
      **seq** -- a nested Sequence (list, tuple, etc)

   Returns:
      int representing maximum _depth


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.sequences.sum_nested_list.txt
======================================================================

scamp_extensions.utilities.sequences.sum_nested_list
****************************************************

scamp_extensions.utilities.sequences.sum_nested_list(l: list)

   Sums up all of the values within a nested list. For instance
   "sum_nested_list([6, [4, 2], [[-7]]])" will return 5

   Parameters:
      **l** -- the input list

   Returns:
      sum of the l's nested values


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.sequences.txt
======================================================================

scamp_extensions.utilities.sequences
************************************

Subpackage containing utility functions for manipulating
lists/sequences (some of which are imported from "scamp.utilities").

-[ Functions ]-

+------------+--------------------------------------------------------------------------------------------+
| "cyclic_sl | Takes a slice that loops back to the beginning if end is before start                      |
| ice"(l,    |                                                                                            |
| start,     |                                                                                            |
| end)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "multi_opt | Decorator that allows the first argument of the function to be a list, tuple, or iterator, |
| ion_functi | and in that case performs the function one each element individually, returning a list,    |
| on"(f)     | tuple, or iterator.                                                                        |
+------------+--------------------------------------------------------------------------------------------+
| "multi_opt | Same as "multi_option_function()", but used to decorate methods instead of functions.      |
| ion_method |                                                                                            |
| "(f)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "rotate_se | Rotates a sequence s such that it begins with element l[n] and wraps back around to        |
| quence"(s, | l[n-1].                                                                                    |
| n)         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "sequence_ | Find the maximum _depth of any element in a nested sequence.                               |
| depth"(seq |                                                                                            |
| )          |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "sum_neste | Sums up all of the values within a nested list.                                            |
| d_list"(l) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "make_flat | Flattens a list, including ones containing multiple levels of nesting.                     |
| _list"(l[, |                                                                                            |
| indivisibl |                                                                                            |
| e])        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.utilities.sequences.cyclic_slice

  * "cyclic_slice()"

* scamp_extensions.utilities.sequences.multi_option_function

  * "multi_option_function()"

* scamp_extensions.utilities.sequences.multi_option_method

  * "multi_option_method()"

* scamp_extensions.utilities.sequences.rotate_sequence

  * "rotate_sequence()"

* scamp_extensions.utilities.sequences.sequence_depth

  * "sequence_depth()"

* scamp_extensions.utilities.sequences.sum_nested_list

  * "sum_nested_list()"

* scamp_extensions.utilities.sequences.make_flat_list

  * "make_flat_list()"


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.time_varying_parameter.TimeVaryingParameter.txt
======================================================================

scamp_extensions.utilities.time_varying_parameter.TimeVaryingParameter
**********************************************************************

class scamp_extensions.utilities.time_varying_parameter.TimeVaryingParameter(levels: Sequence = (0,), durations: Sequence[float] = (), curve_shapes: Sequence[float | str] = None, offset: float = 0, clock: Clock = None, units: str = 'beats')

   Bases: "Envelope"

   A simple wrapper around "Envelope" that is aware of the current
   time or beat in the current clock. Simply call it like a function
   to get its value at the current time or beat.

   Parameters:
      * **levels** -- see "Envelope"

      * **durations** -- see "Envelope"

      * **curve_shapes** -- see "Envelope"

      * **offset** -- see "Envelope"

      * **clock** -- the clock whose time/beat this
        TimeVaryingParameter uses for lookup. Defaults to the current
        active clock.

      * **units** -- either "beats" or "time"; whether or not to use
        the time or the beat of the clock to look up the parameter
        value

   -[ Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "adsr"(att | Same as "adsr()", but taking an optional clock and units parameter.                        |
   | ack_length |                                                                                            |
   | , attack_l |                                                                                            |
   | evel,      |                                                                                            |
   | ...[,      |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "ar"(attac | Same as "ar()", but taking an optional clock and units parameter.                          |
   | k_length,  |                                                                                            |
   | release_le |                                                                                            |
   | ngth[,     |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "asr"(atta | Same as "asr()", but taking an optional clock and units parameter.                         |
   | ck_length, |                                                                                            |
   | sustain_le |                                                                                            |
   | vel, ...[, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "finished" | Whether this parameter has run its course, i.e. whether enough time has passed on its      |
   | ()         | clock, since it was created, to reach the end of the underlying envelope.                  |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_func | Same as "from_function()", but taking an optional clock and units parameter.               |
   | tion"(func |                                                                                            |
   | tion[, dom |                                                                                            |
   | ain_start, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_leve | Same as "from_levels()", but taking an optional clock and units parameter.                 |
   | ls"(levels |                                                                                            |
   | [, length, |                                                                                            |
   | offset,    |                                                                                            |
   | clock,     |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_leve | Same as "from_levels_and_durations()", but taking an optional clock and units parameter.   |
   | ls_and_dur |                                                                                            |
   | ations"(le |                                                                                            |
   | vels,      |                                                                                            |
   | durations) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_list | Same as "from_list()", but taking an optional clock and units parameter.                   |
   | "(construc |                                                                                            |
   | tor_list[, |                                                                                            |
   | clock,     |                                                                                            |
   | units])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_poin | Same as "from_points()", but taking an optional clock and units parameter.                 |
   | ts"(*point |                                                                                            |
   | s[, clock, |                                                                                            |
   | units])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "from_segm | Same as "from_segments()", but taking an optional clock and units parameter.               |
   | ents"(segm |                                                                                            |
   | ents[,     |                                                                                            |
   | clock,     |                                                                                            |
   | units])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "release"( | Same as "release()", but taking an optional clock and units parameter.                     |
   | duration[, |                                                                                            |
   | start_leve |                                                                                            |
   | l, ...])   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Inherited Methods ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "append_en | Extends this envelope by another one (shifted to start at the end of this one).            |
   | velope"(en |                                                                                            |
   | velope_to_ |                                                                                            |
   | append)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "append_se | Append a segment to the end of the curve ending at level and lasting for duration.         |
   | gment"(lev |                                                                                            |
   | el,        |                                                                                            |
   | duration[, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "average_l | Returns the average value that the Envelope takes over the given range.                    |
   | evel"([t_r |                                                                                            |
   | ange])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "duplicate | Returns a copy of this object by serializing to and from JSON.                             |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "end_level | Ending value of the Envelope                                                               |
   | "()        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "end_time" | End of the domain on which this Envelope is defined.                                       |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get_durat | Tuple of all the segment lengths.                                                          |
   | ions"([rou |                                                                                            |
   | nded])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "get_upper | Given a lower integration bound, find the upper bound that will result in the desired      |
   | _integrati | integral.                                                                                  |
   | on_bound"( |                                                                                            |
   | t1, desire |                                                                                            |
   | d_area)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "insert"(t | Insert a curve point at time t, and set the shape of the curve into and out of it.         |
   | , level[,  |                                                                                            |
   | curve_shap |                                                                                            |
   | e_in,      |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "insert_in | Insert another curve point at the given time, without changing the shape of the curve.     |
   | terpolated |                                                                                            |
   | "(t[, rela |                                                                                            |
   | tive_toler |                                                                                            |
   | ance])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "integrate | Get the definite integral under this Envelope from t1 to t2                                |
   | _interval" |                                                                                            |
   | (t1, t2)   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "is_shifte | Determines if this segment is simply a shifted version of another segment                  |
   | d_version_ |                                                                                            |
   | of"(other[ |                                                                                            |
   | , toleranc |                                                                                            |
   | e])        |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_dump | Dump this object as a JSON string.                                                         |
   | s"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "json_load | Load this object from a JSON string.                                                       |
   | s"(s)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "length"() | The length of the domain on which this Envelope is defined (end time minus start time).    |
   +------------+--------------------------------------------------------------------------------------------+
   | "load_from | Load this object from a JSON file with the given path.                                     |
   | _json"(fil |                                                                                            |
   | e_path)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "local_ext | Returns a list of the times where the curve changes direction.                             |
   | rema"([inc |                                                                                            |
   | lude_saddl |                                                                                            |
   | e_points]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "max_absol | Returns the maximum absolute value of the slope over the entire Envelope.                  |
   | ute_slope" |                                                                                            |
   | ()         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "max_level | Returns the highest value that the Envelope takes over the given range.                    |
   | "([t_range |                                                                                            |
   | ])         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "min_level | Returns the lowest value that the Envelope takes over the given range.                     |
   | "([t_range |                                                                                            |
   | ])         |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "normalize | Stretch or squeeze the segments of this Envelope so that it has the desired total          |
   | _to_durati | duration.                                                                                  |
   | on"(desire |                                                                                            |
   | d_duration |                                                                                            |
   | [, ...])   |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pop_segme | Remove and return the last segment of this Envelope.                                       |
   | nt"()      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "pop_segme | Remove and return the first segment of this Envelope.                                      |
   | nt_from_st |                                                                                            |
   | art"()     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "prepend_e | Extends this envelope backwards by another one (shifted to end at the start of this one).  |
   | nvelope"(e |                                                                                            |
   | nvelope_to |                                                                                            |
   | _prepend)  |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "prepend_s | Prepend a segment to the beginning of the curve, starting at level and lasting for         |
   | egment"(le | duration.                                                                                  |
   | vel,       |                                                                                            |
   | duration[, |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "remove_se | Removes all segments after the given time (including a partial segment if t lands in the   |
   | gments_aft | middle of a segment).                                                                      |
   | er"(t)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "remove_se | Removes all segments before the given time (including a partial segment if t lands in the  |
   | gments_bef | middle of a segment).                                                                      |
   | ore"(t)    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "save_to_j | Save this object to a JSON file using the given path.                                      |
   | son"(file_ |                                                                                            |
   | path)      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "scale_hor | Scales the domain of this Envelope by the specified amount.                                |
   | izontal"(a |                                                                                            |
   | mount)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "scale_ver | Scales the levels of this segment by the specified amount.                                 |
   | tical"(amo |                                                                                            |
   | unt)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "shift_hor | Shifts the domain of this Envelope by the specified amount.                                |
   | izontal"(a |                                                                                            |
   | mount)     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "shift_ver | Shifts the levels of this Envelope the specified amount.                                   |
   | tical"(amo |                                                                                            |
   | unt)       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "show_plot | Shows a plot of this Envelope using matplotlib.                                            |
   | "([title,  |                                                                                            |
   | resolution |                                                                                            |
   | , ...])    |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "simplifie | Simplifies the envelope to only extrema and inflection points.                             |
   | d"([use_cu |                                                                                            |
   | rvature,   |                                                                                            |
   | ...])      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "split_at" | Splits the Envelope at one or several points and returns a tuple of the pieces             |
   | (t[, chang |                                                                                            |
   | e_original |                                                                                            |
   | , zero_out |                                                                                            |
   | _offsets]) |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_lev | Beginning value of the Envelope                                                            |
   | el"()      |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "start_tim | Beginning of the domain on which this Envelope is defined.                                 |
   | e"()       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "value_at" | Get the value of this Envelope at the given time.                                          |
   | (t[, from_ |                                                                                            |
   | left])     |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+

   -[ Attributes ]-

   +------------+--------------------------------------------------------------------------------------------+
   | "curve_sha | Tuple of all the segment curve shapes.                                                     |
   | pes"       |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "durations | Tuple of all the segment lengths.                                                          |
   | "          |                                                                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "levels"   | Tuple of levels at all segment boundary points.                                            |
   +------------+--------------------------------------------------------------------------------------------+
   | "offset"   | Alias for "Envelope.start_time()".                                                         |
   +------------+--------------------------------------------------------------------------------------------+
   | "times"    | Tuple of all the segment start times.                                                      |
   +------------+--------------------------------------------------------------------------------------------+

   finished()

      Whether this parameter has run its course, i.e. whether enough
      time has passed on its clock, since it was created, to reach the
      end of the underlying envelope.

   classmethod from_segments(segments: Sequence[EnvelopeSegment], clock: Clock = None, units: str = 'beats') -> T

      Same as "from_segments()", but taking an optional clock and
      units parameter. (See "TimeVaryingParameter")

   classmethod from_levels_and_durations(levels: Sequence, durations: Sequence[float], curve_shapes: Sequence[float | str] = None, offset: float = 0, clock: Clock = None, units: str = 'beats') -> T

      Same as "from_levels_and_durations()", but taking an optional
      clock and units parameter. (See "TimeVaryingParameter")

   classmethod from_levels(levels: Sequence, length: float = 1.0, offset: float = 0, clock: Clock = None, units: str = 'beats') -> T

      Same as "from_levels()", but taking an optional clock and units
      parameter. (See "TimeVaryingParameter")

   classmethod from_list(constructor_list: Sequence, clock: Clock = None, units: str = 'beats') -> T

      Same as "from_list()", but taking an optional clock and units
      parameter. (See "TimeVaryingParameter")

   classmethod from_points(*points: Sequence, clock: Clock = None, units: str = 'beats') -> T

      Same as "from_points()", but taking an optional clock and units
      parameter. (See "TimeVaryingParameter")

   classmethod release(duration: float, start_level=1, curve_shape: float | str = None, clock: Clock = None, units: str = 'beats') -> T

      Same as "release()", but taking an optional clock and units
      parameter. (See "TimeVaryingParameter")

   classmethod ar(attack_length: float, release_length: float, peak_level=1, attack_shape: float | str = None, release_shape: float | str = None, clock: Clock = None, units: str = 'beats') -> T

      Same as "ar()", but taking an optional clock and units
      parameter. (See "TimeVaryingParameter")

   classmethod asr(attack_length: float, sustain_level, sustain_length: float, release_length: float, attack_shape: float | str = None, release_shape: float | str = None, clock: Clock = None, units: str = 'beats') -> T

      Same as "asr()", but taking an optional clock and units
      parameter. (See "TimeVaryingParameter")

   classmethod adsr(attack_length: float, attack_level, decay_length: float, sustain_level, sustain_length: float, release_length: float, attack_shape: float | str = None, decay_shape: float | str = None, release_shape: float | str = None, clock: Clock = None, units: str = 'beats') -> T

      Same as "adsr()", but taking an optional clock and units
      parameter. (See "TimeVaryingParameter")

   classmethod from_function(function: Callable[[float], float], domain_start: float = 0, domain_end: float = 1, resolution_multiple: int = 2, key_point_precision: int = 2000, key_point_iterations: int = 5, clock: Clock = None, units: str = 'beats') -> T

      Same as "from_function()", but taking an optional clock and
      units parameter. (See "TimeVaryingParameter")

   append_envelope(envelope_to_append: T) -> T

      Extends this envelope by another one (shifted to start at the
      end of this one).

   append_segment(level, duration: float, curve_shape: float = None, tolerance: float = 0, halfway_level=None) -> None

      Append a segment to the end of the curve ending at level and
      lasting for duration. If we're adding a linear segment to a
      linear segment, then we extend the last linear segment instead
      of adding a new one if the level is within tolerance of where
      the last one was headed

      Parameters:
         * **level** -- the level we're going to

         * **duration** -- the duration of the new segment

         * **curve_shape** -- defaults to 0 (linear)

         * **tolerance** -- tolerance for extending a linear segment
           rather than adding a new one

         * **halfway_level** -- alternate way of defining the curve
           shape. If this is set and the curve shape is not then we
           use this to determine the curve shape.

   average_level(t_range: tuple[float, float] = None)

      Returns the average value that the Envelope takes over the given
      range.

      Parameters:
         **t_range** -- tuple defining the start and end time of the
         interval to check. If None, return the average level reached
         over the entire Envelope.

   property curve_shapes: Sequence[float | str]

      Tuple of all the segment curve shapes.

   duplicate() -> T

      Returns a copy of this object by serializing to and from JSON.

   property durations: Sequence[float]

      Tuple of all the segment lengths.

   end_level()

      Ending value of the Envelope

   end_time() -> float

      End of the domain on which this Envelope is defined.

   get_durations(rounded: bool = False) -> Sequence[float]

      Tuple of all the segment lengths.

      Segment lengths are derived as "end_time - start_time", so an
      envelope built up on a regular grid (e.g. repeated 0.1-long
      segments) accumulates floating-point dust in these differences
      even though each segment was appended with a clean duration.
      Pass "rounded=True" to snap each length to a nearby nice decimal
      — used for serialization / repr so the intended durations show,
      without disturbing the exact segment boundary times that the
      curve math relies on.

      Parameters:
         **rounded** -- if True, snap each duration to a nearby nice
         decimal (see "snap_float_to_nice_decimal()")

   get_upper_integration_bound(t1: float, desired_area: float, max_error: float = 1e-14) -> float

      Given a lower integration bound, find the upper bound that will
      result in the desired integral.

      Walks the envelope segment by segment, subtracting each
      segment's closed-form area until the remaining area falls within
      a single segment, then inverts that segment using
      "EnvelopeSegment.get_t_at_integral()" — exactly for
      constant/linear segments, and to within "max_error" for
      exponential ones.

      Assumes a non-negative integrand, so that the integral increases
      monotonically (true for tempo and dynamics curves, the primary
      use). Regions before the first segment and after the last are
      treated as flat (at the start/end level), matching
      "integrate_interval()".

      Parameters:
         * **t1** -- lower bound of integration

         * **desired_area** -- desired value of the integral.

         * **max_error** -- convergence tolerance forwarded to the
           per-segment inverse for the exponential case; ignored by
           the (exact) constant and linear cases.

   insert(t, level, curve_shape_in=0, curve_shape_out=0) -> None

      Insert a curve point at time t, and set the shape of the curve
      into and out of it. This essentially divides the segment at that
      point in two.

      Parameters:
         * **t** -- The time at which to add a point

         * **level** -- The level of the new point we are adding

         * **curve_shape_in** -- the curve shape of the new segment
           going into the point we are adding

         * **curve_shape_out** -- the curve shape of the new segment
           going out of the point we are adding

   insert_interpolated(t: float, relative_tolerance: float = 1e-07) -> float

      Insert another curve point at the given time, without changing
      the shape of the curve. Returns the t value of the new (or
      already existing) interpolated point.

      To avoid manufacturing degenerate, near-zero-width segments due
      to floating point imprecision, a point is only added if it is at
      least "relative_tolerance * segment_width" away from the
      endpoints of the segment it falls in. If "t" lands *within* that
      tolerance of an existing control point, this function call is
      assumed to be an idempotent re-insertion of an existing curve
      point after floating point error has muddied the waters. In this
      case no point is added, and the existing control point's time is
      returned instead.

      Parameters:
         * **t** -- the point at which to insert the point

         * **relative_tolerance** -- how close "t" may come to an
           existing control point before it is treated as coincident
           with it, expressed as a fraction of the width of the
           segment containing "t".

      Returns:
         the t value at which we interpolated. If we snapped to an
         existing control point, its t is returned; otherwise the
         passed value of "t" is returned.

   integrate_interval(t1: float, t2: float)

      Get the definite integral under this Envelope from t1 to t2

      Parameters:
         * **t1** -- lower bound of integration

         * **t2** -- upper bound of integration

   is_shifted_version_of(other: T, tolerance: float = 1e-10) -> bool

      Determines if this segment is simply a shifted version of
      another segment

      Parameters:
         * **other** -- another EnvelopeSegment

         * **tolerance** -- how close it needs to be to count as the
           same

   json_dumps() -> str

      Dump this object as a JSON string. This uses a custom encoder
      that recognizes and appropriately converts any attributes that
      are object inheriting from SavesToJSON.

   classmethod json_loads(s: str) -> T

      Load this object from a JSON string. This uses a custom decoder
      that looks for a "_type" key in any object/dictionary being
      parsed and converts it to the class specified (assuming it a
      subclass of SavesToJSON).

      Parameters:
         **s** -- a string representing this object in JSON format

   length() -> float

      The length of the domain on which this Envelope is defined (end
      time minus start time).

   property levels: Sequence

      Tuple of levels at all segment boundary points.

   classmethod load_from_json(file_path: str) -> T

      Load this object from a JSON file with the given path. This uses
      a custom decoder that looks for a "_type" key in any
      object/dictionary being parsed and converts it to the class
      specified (assuming it a subclass of SavesToJSON).

      Parameters:
         **file_path** -- path for loading the file

   local_extrema(include_saddle_points: bool = False) -> Sequence[float]

      Returns a list of the times where the curve changes direction.

      Parameters:
         **include_saddle_points** -- if True, also include points
         where the curve starts or stops plateauing

   max_absolute_slope()

      Returns the maximum absolute value of the slope over the entire
      Envelope.

   max_level(t_range: tuple[float, float] = None)

      Returns the highest value that the Envelope takes over the given
      range.

      Parameters:
         **t_range** -- tuple defining the start and end time of the
         interval to check. If None, return the max level reached over
         the entire Envelope.

   min_level(t_range: tuple[float, float] = None)

      Returns the lowest value that the Envelope takes over the given
      range.

      Parameters:
         **t_range** -- tuple defining the start and end time of the
         interval to check. If None, return the max level reached over
         the entire Envelope.

   normalize_to_duration(desired_duration: float, in_place: bool = True) -> T

      Stretch or squeeze the segments of this Envelope so that it has
      the desired total duration.

      Parameters:
         * **desired_duration** -- the desired new duration of the
           Envelope

         * **in_place** -- if True, modifies this Envelope in place;
           if False, makes a copy first

   property offset: float

      Alias for "Envelope.start_time()".

   pop_segment() -> EnvelopeSegment | None

      Remove and return the last segment of this Envelope. If there is
      only one segment, reduce it to length zero and return None.

   pop_segment_from_start() -> EnvelopeSegment | None

      Remove and return the first segment of this Envelope. If there
      is only one segment, reduce it to length zero and return None.

   prepend_envelope(envelope_to_prepend: T) -> T

      Extends this envelope backwards by another one (shifted to end
      at the start of this one).

   prepend_segment(level, duration: float, curve_shape: float = None, tolerance: float = 0, halfway_level=None) -> None

      Prepend a segment to the beginning of the curve, starting at
      level and lasting for duration. If we're adding a linear segment
      to a linear segment, then we extend the last linear segment
      instead of adding a new one if the level is within tolerance of
      where the last one was headed

      Parameters:
         * **level** -- the level that the prepended segment starts at

         * **duration** -- the duration of the new segment

         * **curve_shape** -- defaults to 0 (linear)

         * **tolerance** -- tolerance for extending a linear segment
           rather than adding a new one

         * **halfway_level** -- alternate way of defining the curve
           shape. If this is set and the curve shape is not then we
           use this to determine the curve shape.

   remove_segments_after(t: float) -> None

      Removes all segments after the given time (including a partial
      segment if t lands in the middle of a segment).

      Parameters:
         **t** -- the point at which this Envelope is to be truncated.

   remove_segments_before(t: float) -> None

      Removes all segments before the given time (including a partial
      segment if t lands in the middle of a segment).

      Parameters:
         **t** -- the point at which this Envelope is to be truncated.

   save_to_json(file_path: str) -> None

      Save this object to a JSON file using the given path. This uses
      a custom encoder that recognizes and appropriately converts any
      attributes that are object inheriting from SavesToJSON.

      Parameters:
         **file_path** -- path for saving the file

   scale_horizontal(amount: float) -> T

      Scales the domain of this Envelope by the specified amount.

      Parameters:
         **amount** -- amount to scale domain by

      Returns:
         self, for chaining purposes

   scale_vertical(amount) -> T

      Scales the levels of this segment by the specified amount.

      Parameters:
         **amount** -- amount to scale output by

      Returns:
         self, for chaining purposes

   shift_horizontal(amount: float) -> T

      Shifts the domain of this Envelope by the specified amount.

      Parameters:
         **amount** -- the amount to shift the domain by

      Returns:
         self, for chaining purposes

   shift_vertical(amount) -> T

      Shifts the levels of this Envelope the specified amount.

      Parameters:
         **amount** -- the amount to shift up and down by

      Returns:
         self, for chaining purposes

   show_plot(title: str = None, resolution: int = 25, show_segment_divisions: bool = True, x_range: tuple[float, float] = None, y_range: tuple[float, float] = None) -> None

      Shows a plot of this Envelope using matplotlib.

      Parameters:
         * **title** -- A title to give the plot.

         * **resolution** -- number of points to use per envelope
           segment

         * **show_segment_divisions** -- Whether or not to place dots
           at the division points between envelope segments

         * **x_range** -- min and max value shown on the x-axis

         * **y_range** -- min and max value shown on the y-axis

   simplified(use_curvature=True, include_saddle_points=True) -> T

      Simplifies the envelope to only extrema and inflection points.

      Parameters:
         * **use_curvature** -- if True, adjusts the curvature of the
           segments to match the half-way point between key points. If
           False, linearly interpolate between key points.

         * **include_saddle_points** -- if True, include saddle points
           as well as extrema

   split_at(t: float | Sequence[float], change_original: bool = False, zero_out_offsets: bool = True) -> Sequence[T]

      Splits the Envelope at one or several points and returns a tuple
      of the pieces

      Parameters:
         * **t** -- either the time t or a tuple/list of times t at
           which to split the curve

         * **change_original** -- if true, the original Envelope gets
           turned into the first of the returned tuple

         * **zero_out_offsets** -- if true, each new piece is shifted
           to start at zero

      Returns:
         tuple of Envelopes representing the pieces this has been
         split into

   start_level()

      Beginning value of the Envelope

   start_time() -> float

      Beginning of the domain on which this Envelope is defined.

   property times: Sequence[float]

      Tuple of all the segment start times.

   value_at(t: float, from_left: bool = False)

      Get the value of this Envelope at the given time.

      Parameters:
         * **t** -- the time

         * **from_left** -- if true, get the limit as we approach t
           from the left. In the case of a zero-length segment, which
           suddenly changes the value, this tells us what the value
           was right before the jump instead of right after the jump.


======================================================================
=== FILE: scamp_extensions.utilities/scamp_extensions.utilities.time_varying_parameter.txt
======================================================================

scamp_extensions.utilities.time_varying_parameter
*************************************************

This module defines the "TimeVaryingParameter" class, a convenience
subclasses of "Envelope" that is aware of the clock and can be called
to look up its value at the current beat or time.

-[ Classes ]-

+------------+--------------------------------------------------------------------------------------------+
| "TimeVaryi | A simple wrapper around "Envelope" that is aware of the current time or beat in the        |
| ngParamete | current clock.                                                                             |
| r"([levels |                                                                                            |
| ,          |                                                                                            |
| durations, |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.utilities.time_varying_parameter.TimeVaryingParamet
  er

  * "TimeVaryingParameter"

    * "TimeVaryingParameter.finished()"

    * "TimeVaryingParameter.from_segments()"

    * "TimeVaryingParameter.from_levels_and_durations()"

    * "TimeVaryingParameter.from_levels()"

    * "TimeVaryingParameter.from_list()"

    * "TimeVaryingParameter.from_points()"

    * "TimeVaryingParameter.release()"

    * "TimeVaryingParameter.ar()"

    * "TimeVaryingParameter.asr()"

    * "TimeVaryingParameter.adsr()"

    * "TimeVaryingParameter.from_function()"

    * "TimeVaryingParameter.append_envelope()"

    * "TimeVaryingParameter.append_segment()"

    * "TimeVaryingParameter.average_level()"

    * "TimeVaryingParameter.curve_shapes"

    * "TimeVaryingParameter.duplicate()"

    * "TimeVaryingParameter.durations"

    * "TimeVaryingParameter.end_level()"

    * "TimeVaryingParameter.end_time()"

    * "TimeVaryingParameter.get_durations()"

    * "TimeVaryingParameter.get_upper_integration_bound()"

    * "TimeVaryingParameter.insert()"

    * "TimeVaryingParameter.insert_interpolated()"

    * "TimeVaryingParameter.integrate_interval()"

    * "TimeVaryingParameter.is_shifted_version_of()"

    * "TimeVaryingParameter.json_dumps()"

    * "TimeVaryingParameter.json_loads()"

    * "TimeVaryingParameter.length()"

    * "TimeVaryingParameter.levels"

    * "TimeVaryingParameter.load_from_json()"

    * "TimeVaryingParameter.local_extrema()"

    * "TimeVaryingParameter.max_absolute_slope()"

    * "TimeVaryingParameter.max_level()"

    * "TimeVaryingParameter.min_level()"

    * "TimeVaryingParameter.normalize_to_duration()"

    * "TimeVaryingParameter.offset"

    * "TimeVaryingParameter.pop_segment()"

    * "TimeVaryingParameter.pop_segment_from_start()"

    * "TimeVaryingParameter.prepend_envelope()"

    * "TimeVaryingParameter.prepend_segment()"

    * "TimeVaryingParameter.remove_segments_after()"

    * "TimeVaryingParameter.remove_segments_before()"

    * "TimeVaryingParameter.save_to_json()"

    * "TimeVaryingParameter.scale_horizontal()"

    * "TimeVaryingParameter.scale_vertical()"

    * "TimeVaryingParameter.shift_horizontal()"

    * "TimeVaryingParameter.shift_vertical()"

    * "TimeVaryingParameter.show_plot()"

    * "TimeVaryingParameter.simplified()"

    * "TimeVaryingParameter.split_at()"

    * "TimeVaryingParameter.start_level()"

    * "TimeVaryingParameter.start_time()"

    * "TimeVaryingParameter.times"

    * "TimeVaryingParameter.value_at()"


======================================================================
=== FILE: scamp_extensions.utilities.txt
======================================================================

scamp_extensions.utilities package
**********************************

Subpackage containing utility functions that do not fit into any of
the other extension categories.

-[ Modules: ]-

+------------+--------------------------------------------------------------------------------------------+
| "math"     | Subpackage containing mathematical utility functions (many of which are imported from      |
|            | "scamp.utilities".                                                                         |
+------------+--------------------------------------------------------------------------------------------+
| "sequences | Subpackage containing utility functions for manipulating lists/sequences (some of which    |
| "          | are imported from "scamp.utilities").                                                      |
+------------+--------------------------------------------------------------------------------------------+
| "time_vary | This module defines the "TimeVaryingParameter" class, a convenience subclasses of          |
| ing_parame | "Envelope" that is aware of the clock and can be called to look up its value at the        |
| ter"       | current beat or time.                                                                      |
+------------+--------------------------------------------------------------------------------------------+

* scamp_extensions.utilities.math

  * scamp_extensions.utilities.math.AtanWarp

    * "AtanWarp"

  * scamp_extensions.utilities.math.atan_warp

    * "atan_warp()"

  * scamp_extensions.utilities.math.lcm

    * "lcm()"

  * scamp_extensions.utilities.math.remap

    * "remap()"

  * scamp_extensions.utilities.math.wrap_to_range

    * "wrap_to_range()"

  * scamp_extensions.utilities.math.ceil_to_multiple

    * "ceil_to_multiple()"

  * scamp_extensions.utilities.math.prime_factor

    * "prime_factor()"

  * scamp_extensions.utilities.math.is_multiple

    * "is_multiple()"

  * scamp_extensions.utilities.math.gcd

    * "gcd()"

  * scamp_extensions.utilities.math.is_prime

    * "is_prime()"

  * scamp_extensions.utilities.math.is_x_pow_of_y

    * "is_x_pow_of_y()"

  * scamp_extensions.utilities.math.round_x_to_pow_of_y

    * "round_x_to_pow_of_y()"

  * scamp_extensions.utilities.math.floor_x_to_pow_of_y

    * "floor_x_to_pow_of_y()"

  * scamp_extensions.utilities.math.ceil_x_to_pow_of_y

    * "ceil_x_to_pow_of_y()"

  * scamp_extensions.utilities.math.floor_to_multiple

    * "floor_to_multiple()"

  * scamp_extensions.utilities.math.round_to_multiple

    * "round_to_multiple()"

* scamp_extensions.utilities.sequences

  * scamp_extensions.utilities.sequences.cyclic_slice

    * "cyclic_slice()"

  * scamp_extensions.utilities.sequences.multi_option_function

    * "multi_option_function()"

  * scamp_extensions.utilities.sequences.multi_option_method

    * "multi_option_method()"

  * scamp_extensions.utilities.sequences.rotate_sequence

    * "rotate_sequence()"

  * scamp_extensions.utilities.sequences.sequence_depth

    * "sequence_depth()"

  * scamp_extensions.utilities.sequences.sum_nested_list

    * "sum_nested_list()"

  * scamp_extensions.utilities.sequences.make_flat_list

    * "make_flat_list()"

* scamp_extensions.utilities.time_varying_parameter

  * scamp_extensions.utilities.time_varying_parameter.TimeVaryingParam
    eter

    * "TimeVaryingParameter"

      * "TimeVaryingParameter.finished()"

      * "TimeVaryingParameter.from_segments()"

      * "TimeVaryingParameter.from_levels_and_durations()"

      * "TimeVaryingParameter.from_levels()"

      * "TimeVaryingParameter.from_list()"

      * "TimeVaryingParameter.from_points()"

      * "TimeVaryingParameter.release()"

      * "TimeVaryingParameter.ar()"

      * "TimeVaryingParameter.asr()"

      * "TimeVaryingParameter.adsr()"

      * "TimeVaryingParameter.from_function()"

      * "TimeVaryingParameter.append_envelope()"

      * "TimeVaryingParameter.append_segment()"

      * "TimeVaryingParameter.average_level()"

      * "TimeVaryingParameter.curve_shapes"

      * "TimeVaryingParameter.duplicate()"

      * "TimeVaryingParameter.durations"

      * "TimeVaryingParameter.end_level()"

      * "TimeVaryingParameter.end_time()"

      * "TimeVaryingParameter.get_durations()"

      * "TimeVaryingParameter.get_upper_integration_bound()"

      * "TimeVaryingParameter.insert()"

      * "TimeVaryingParameter.insert_interpolated()"

      * "TimeVaryingParameter.integrate_interval()"

      * "TimeVaryingParameter.is_shifted_version_of()"

      * "TimeVaryingParameter.json_dumps()"

      * "TimeVaryingParameter.json_loads()"

      * "TimeVaryingParameter.length()"

      * "TimeVaryingParameter.levels"

      * "TimeVaryingParameter.load_from_json()"

      * "TimeVaryingParameter.local_extrema()"

      * "TimeVaryingParameter.max_absolute_slope()"

      * "TimeVaryingParameter.max_level()"

      * "TimeVaryingParameter.min_level()"

      * "TimeVaryingParameter.normalize_to_duration()"

      * "TimeVaryingParameter.offset"

      * "TimeVaryingParameter.pop_segment()"

      * "TimeVaryingParameter.pop_segment_from_start()"

      * "TimeVaryingParameter.prepend_envelope()"

      * "TimeVaryingParameter.prepend_segment()"

      * "TimeVaryingParameter.remove_segments_after()"

      * "TimeVaryingParameter.remove_segments_before()"

      * "TimeVaryingParameter.save_to_json()"

      * "TimeVaryingParameter.scale_horizontal()"

      * "TimeVaryingParameter.scale_vertical()"

      * "TimeVaryingParameter.shift_horizontal()"

      * "TimeVaryingParameter.shift_vertical()"

      * "TimeVaryingParameter.show_plot()"

      * "TimeVaryingParameter.simplified()"

      * "TimeVaryingParameter.split_at()"

      * "TimeVaryingParameter.start_level()"

      * "TimeVaryingParameter.start_time()"

      * "TimeVaryingParameter.times"

      * "TimeVaryingParameter.value_at()"

-[ Public-Facing API (result of *import **): ]-

+------------+--------------------------------------------------------------------------------------------+
| "AtanWarp" | A warping function that uses an appropriately scaled arctan to warp values from the input  |
| (in_lo,    | range to the output range.                                                                 |
| in_hi,     |                                                                                            |
| out_min,   |                                                                                            |
| out_max)   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "atan_warp | Uses an appropriately scaled arctan function to warp values from the input range to the    |
| "(value,   | output range.                                                                              |
| in_lo,     |                                                                                            |
| in_hi,     |                                                                                            |
| out_min,   |                                                                                            |
| out_max)   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "gcd"(*int | Greatest Common Divisor.                                                                   |
| egers)     |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "lcm"(a,   | Return lowest common multiple.                                                             |
| b)         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "remap"(va | Rescales the given value or values so that they fall within the given output range.        |
| lue_or_val |                                                                                            |
| ues,       |                                                                                            |
| out_min,   |                                                                                            |
| out_max[,  |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "wrap_to_r | Wraps the input x into the given range, either jumping back to the other side of the range |
| ange"(x,   | at the boundaries, or if the mirror parameter is set, reflecting at the boundaries.        |
| range_min, |                                                                                            |
| range_max[ |                                                                                            |
| , mirror]) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "ceil_to_m | Returns the multiple of factor that is closest above x.                                    |
| ultiple"(x |                                                                                            |
| , factor)  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "ceil_x_to | Returns the integer power of y that is closest above x.                                    |
| _pow_of_y" |                                                                                            |
| (x, y)     |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "floor_to_ | Returns the multiple of factor that is closest below x.                                    |
| multiple"( |                                                                                            |
| x, factor) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "floor_x_t | Returns the integer power of y that is closest below x.                                    |
| o_pow_of_y |                                                                                            |
| "(x, y)    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "is_multip | Checks if x is a multiple of y.                                                            |
| le"(x, y)  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "is_prime" | Checks if a is a prime number.                                                             |
| (a)        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "is_x_pow_ | Checks if x is an integer (including negative) power of y                                  |
| of_y"(x,   |                                                                                            |
| y)         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "make_flat | Flattens a list, including ones containing multiple levels of nesting.                     |
| _list"(l[, |                                                                                            |
| indivisibl |                                                                                            |
| e])        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "prime_fac | Returns a list of the prime factors of n.                                                  |
| tor"(n)    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "round_to_ | Returns the multiple of factor that is closest to x (above or below).                      |
| multiple"( |                                                                                            |
| x, factor) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "round_x_t | Returns the integer power of y that is closest to x (above or below).                      |
| o_pow_of_y |                                                                                            |
| "(x, y)    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "sum_neste | Sums up all of the values within a nested list.                                            |
| d_list"(l) |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "cyclic_sl | Takes a slice that loops back to the beginning if end is before start                      |
| ice"(l,    |                                                                                            |
| start,     |                                                                                            |
| end)       |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "rotate_se | Rotates a sequence s such that it begins with element l[n] and wraps back around to        |
| quence"(s, | l[n-1].                                                                                    |
| n)         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "sequence_ | Find the maximum _depth of any element in a nested sequence.                               |
| depth"(seq |                                                                                            |
| )          |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "TimeVaryi | A simple wrapper around "Envelope" that is aware of the current time or beat in the        |
| ngParamete | current clock.                                                                             |
| r"([levels |                                                                                            |
| ,          |                                                                                            |
| durations, |                                                                                            |
| ...])      |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+