======================================================================
=== 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, | |
| ...]) | |
+------------+--------------------------------------------------------------------------------------------+