scamp.performance.Performance¶
-
class
scamp.performance.
Performance
(parts: Sequence[scamp.performance.PerformancePart] = None, tempo_envelope: clockblocks.tempo_envelope.TempoEnvelope = None)[source]¶ Bases:
expenvelope.json_serializer.SavesToJSON
Representation of note playback events, usually a transcription of the notes played by an
Ensemble
. Operates in continuous time, without regard to any particular way of notating it. (As opposed to aScore
, which represents the notated music.)- Parameters
parts – list of parts (
PerformancePart
objects) to start with (defaults to empty list)tempo_envelope – a tempo_envelope to associate with this performance
- Variables
parts – list of parts (
PerformancePart
objects) in this Performancetempo_envelope – the tempo_envelope associated this performance and used for playback by default
Methods
add_part
(part)Add the given PerformancePart to this performance
apply_note_filter
(filter_function[, …])Applies a filter function to every note in this Performance.
apply_pitch_filter
(filter_function[, …])Applies a filter function to transform the pitch of every note in this Performance.
apply_volume_filter
(filter_function[, …])Applies a filter function to transform the volume of every note in this Performance.
get_note_iterator
([start_beat, stop_beat, …])Returns an iterator returning all the notes from start_beat to stop_beat in the selected voices, in all parts.
get_part_by_index
(index)Get the part with the given index (Parts are numbered starting with 0, in order that they are added/created.)
get_parts_by_instrument
(instrument)Get all parts with the given instrument
get_parts_by_name
(name)Get all parts with the given name
Checks if this Performance has been quantized
length
()Total length of this performance.
new_part
([instrument])Construct and add a new PerformancePart to this Performance
If this Performance has been quantized, gets the number of measures
play
([start_beat, stop_beat, ensemble, …])Play back this Performance (or a selection of it)
quantize
([quantization_scheme, …])Quantizes all parts according to the quantization_scheme
quantized
([quantization_scheme, …])Same as quantize, except that it returns a new copy, rather than changing this Performance in place.
set_instruments_from_ensemble
(ensemble[, …])Set the playback instruments for each part in this Performance by their best match in the ensemble given.
to_score
([quantization_scheme, …])Convert this Performance (list of note events in continuous time and pitch) to a Score object, which represents the music in traditional western notation.
transpose
(interval)Transposes all notes in this Performance up or down by the desired interval.
warp_to_tempo_curve
(tempo_curve)(Not yet implemented)
Inherited Methods
Returns a copy of this object by serializing to and from JSON.
Dump this object as a JSON string.
json_loads
(s)Load this object from a JSON string.
load_from_json
(file_path)Load this object from a JSON file with the given path.
save_to_json
(file_path)Save this object to a JSON file using the given path.
Attributes
The end beat of this performance.
-
new_part
(instrument: scamp.instruments.ScampInstrument = None) → scamp.performance.PerformancePart[source]¶ Construct and add a new PerformancePart to this Performance
- Parameters
instrument – the instrument to use as a default for playing back the part
- Returns
the newly constructed part
-
add_part
(part: scamp.performance.PerformancePart) → None[source]¶ Add the given PerformancePart to this performance
- Parameters
part – a PerformancePart to add
-
get_part_by_index
(index: int) → scamp.performance.PerformancePart[source]¶ Get the part with the given index (Parts are numbered starting with 0, in order that they are added/created.)
- Parameters
index – the index of the part in question
- Returns
the PerformancePart
-
get_parts_by_name
(name: str) → Sequence[scamp.performance.PerformancePart][source]¶ Get all parts with the given name
- Parameters
name – the part name to search for
- Returns
a list of parts with this name
-
get_parts_by_instrument
(instrument: scamp.instruments.ScampInstrument) → Sequence[scamp.performance.PerformancePart][source]¶ Get all parts with the given instrument
- Parameters
instrument – the instrument to search for
- Returns
a list of parts with this instrument
-
property
end_beat
¶ The end beat of this performance. (i.e. the beat corresponding to the end of the last note)
- Returns
float representing the beat at which all notes are done playing
-
length
() → float[source]¶ Total length of this performance. (Identical to Performance.end_beat)
- Returns
float representing the total length of the Performance
-
get_note_iterator
(start_beat: float = 0, stop_beat: float = None, selected_voices: Sequence[str] = None) → Iterator[scamp.performance.PerformanceNote][source]¶ Returns an iterator returning all the notes from start_beat to stop_beat in the selected voices, in all parts. In order of start time, jumping from part to part as needed.
- Parameters
start_beat – beat to start on
stop_beat – beat to stop on (None keeps going until the end of the part)
selected_voices – which voices to take notes from (defaults to all if None)
- Returns
an iterator
-
apply_note_filter
(filter_function: Callable[[PerformanceNote], None], start_beat: float = 0, stop_beat: float = None, selected_voices: Sequence[str] = None) → scamp.performance.Performance[source]¶ Applies a filter function to every note in this Performance. This can be used to apply a transformation to the entire Performance on a note-by-note basis.
- Parameters
filter_function – function taking a PerformanceNote object and modifying it in place
start_beat – beat to start on
stop_beat – beat to stop on (None keeps going until the end of the part)
selected_voices – which voices to take notes from (defaults to all if None)
- Returns
self, for chaining purposes
-
apply_pitch_filter
(filter_function: Callable[[Union[expenvelope.envelope.Envelope, float]], Union[expenvelope.envelope.Envelope, float]], start_beat: float = 0, stop_beat: float = None, selected_voices: Sequence[str] = None) → scamp.performance.Performance[source]¶ Applies a filter function to transform the pitch of every note in this Performance.
- Parameters
filter_function – function taking a pitch (can be envelope, float, or even a chord tuple) and returning another pitch-like object. If the performance hasn’t been quantized and you’re not using any glissandi, though, you can assume the pitch is a float.
start_beat – beat to start on
stop_beat – beat to stop on (None keeps going until the end of the part)
selected_voices – which voices to take notes from (defaults to all if None)
- Returns
self, for chaining purposes
-
transpose
(interval: float) → scamp.performance.Performance[source]¶ Transposes all notes in this Performance up or down by the desired interval. For greater flexibility, use the
apply_pitch_filter
andapply_note_filter
methods.- Parameters
interval – the interval by which to transpose this Performance
- Returns
self, for chaining purposes
-
apply_volume_filter
(filter_function: Callable[[Union[expenvelope.envelope.Envelope, float]], Union[expenvelope.envelope.Envelope, float]], start_beat: float = 0, stop_beat: float = None, selected_voices: Sequence[str] = None) → scamp.performance.Performance[source]¶ Applies a filter function to transform the volume of every note in this Performance.
- Parameters
filter_function – function taking a volume (can be envelope or float) and returning another volume-like object. If you haven’t used any envelopes, though, you can assume the pitch is a float.
start_beat – beat to start on
stop_beat – beat to stop on (None keeps going until the end of the part)
selected_voices – which voices to take notes from (defaults to all if None)
- Returns
self, for chaining purposes
-
play
(start_beat: float = 0, stop_beat: float = None, ensemble: scamp.instruments.Ensemble = 'auto', clock: clockblocks.clock.Clock = 'auto', blocking: bool = True, tempo_envelope: clockblocks.tempo_envelope.TempoEnvelope = 'auto', note_filter: Callable[[scamp.performance.PerformanceNote], scamp.performance.PerformanceNote] = None) → clockblocks.clock.Clock[source]¶ Play back this Performance (or a selection of it)
- Parameters
start_beat – Place to start playing from
stop_beat – Place to stop playing at
ensemble – The Ensemble whose instruments to use for playback. If “auto”, checks to see if we are operating in a particular Session, and uses those instruments if so.
clock – clock to use for playback
blocking – if True, don’t return until the part is done playing; if False, return immediately
tempo_envelope – the TempoEnvelope with which to play back this performance. The default value of “auto” uses the tempo_envelope associated with the performance, and None uses a flat tempo of rate 60bpm
note_filter – a function that takes the PerformanceNote about to be played and returns a modified PerformanceNote to play. NB: this will modify the original note unless the input to the function is duplicated and left unaltered!
- Returns
the clock on which this performance is playing back
-
set_instruments_from_ensemble
(ensemble: scamp.instruments.Ensemble, override: bool = True) → scamp.performance.Performance[source]¶ Set the playback instruments for each part in this Performance by their best match in the ensemble given. If override is False, only set the instrument for parts that don’t already have one set.
- Parameters
ensemble – the Ensemble in which to search for instruments
override – Whether or not to override any instruments already assigned to parts
- Returns
self
-
quantize
(quantization_scheme: scamp.quantization.QuantizationScheme = 'default', onset_weighting: float = 'default', termination_weighting: float = 'default') → scamp.performance.Performance[source]¶ Quantizes all parts according to the quantization_scheme
- Parameters
quantization_scheme – the QuantizationScheme to use. If “default”, uses the default time signature defined in the quantization_settings.
onset_weighting – how much to weight note onsets in the quantization. If “default”, uses the default value defined in the quantization_settings.
termination_weighting – how much to weight note terminations in the quantization. If “default”, uses the default value defined in the quantization_settings.
- Returns
this Performance, having been quantized
-
quantized
(quantization_scheme: scamp.quantization.QuantizationScheme = 'default', onset_weighting: float = 'default', termination_weighting: float = 'default') → scamp.performance.Performance[source]¶ Same as quantize, except that it returns a new copy, rather than changing this Performance in place.
- Parameters
quantization_scheme – the QuantizationScheme to use. If “default”, uses the default time signature defined in the quantization_settings.
onset_weighting – how much to weight note onsets in the quantization. If “default”, uses the default value defined in the quantization_settings.
termination_weighting – how much to weight note terminations in the quantization. If “default”, uses the default value defined in the quantization_settings.
- Returns
a quantized copy of this Performance
-
is_quantized
() → bool[source]¶ Checks if this Performance has been quantized
- Returns
True if all parts are quantized, False if not
-
num_measures
() → int[source]¶ If this Performance has been quantized, gets the number of measures
- Returns
number of measures
-
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
-
to_score
(quantization_scheme: scamp.quantization.QuantizationScheme = None, time_signature: Union[str, Sequence] = None, bar_line_locations: Sequence[float] = None, max_divisor: int = None, max_divisor_indigestibility: int = None, simplicity_preference: float = None, title: str = 'default', composer: str = 'default') → scamp.score.Score[source]¶ Convert this Performance (list of note events in continuous time and pitch) to a Score object, which represents the music in traditional western notation. In the process, the music must be quantized, for which two different options are available: one can either pass a QuantizationScheme to the first argument, which is very flexible but rather verbose to create, or one can specify arguments such as time signature and max divisor directly.
- Parameters
quantization_scheme – The quantization scheme to be used when converting this performance into a score. If this is defined, none of the other quantization-related arguments should be defined.
time_signature – the time signature to be used, represented as a string, e.g. “3/4”, or a tuple, e.g. (3, 2). Alternatively, a list of time signatures can be given. If this list ends in “loop”, then the pattern specified by the list will be looped. For example, [“4/4”, “2/4”, “3/4”, “loop”] will cause the fourth measure to be in “4/4”, the fifth in “2/4”, etc. If the list does not end in “loop”, all measures after the final time signature specified will continue to be in that time signature.
bar_line_locations – As an alternative to defining the time signatures, a list of numbers representing the bar line locations can be given. For instance, [4.5, 6.5, 8, 11] would result in bars of time signatures 9/8, 2/4, 3/8, and 3/4
max_divisor – The largest divisor that will be allowed to divide the beat.
max_divisor_indigestibility – Indigestibility, devised by composer Clarence Barlow, is a measure of the “primeness” of a beat divisor, and therefore of its complexity from the point of view of a performer. For instance, it is easier to divide a beat in 8 than in 7, even though 7 is a smaller number. See Clarence’s paper here: https://mat.ucsb.edu/Publications/Quantification_of_Harmony_and_Metre.pdf. By setting a max indigestibility, we can allow larger divisions of the beat, but only so long as they are easy ones. For instance, a max_divisor of 16 and a max_divisor_indigestibility of 8 would allow the beat to be divided in 1, 2, 3, 4, 5, 6, 8, 9, 10, 12, and 16.
simplicity_preference – This defines the degree to which the quantizer will favor simple divisors. The higher the simplicity preference, the more precisely the notes have to fit for you to get a divisor like 7. Simplicity preference can range from 0 (in which case the divisor is chosen purely based on the lowest error) to infinity, with a typical value somewhere around 1.
title – Title of the piece to be printed on the score.
composer – Composer of the piece to be printed on the score.
- Returns
the resulting Score object, which can then be rendered either as XML or LilyPond