scamp.performance.PerformancePart

class scamp.performance.PerformancePart(instrument: Optional[ScampInstrument] = None, name: Optional[str] = None, voices: Optional[Union[dict, Sequence]] = None, instrument_id: Optional[tuple[str, int]] = None, voice_quantization_records: Optional[dict] = None, clef_preference: Optional[Sequence[str | tuple[str, numbers.Real]]] = None)

Bases: SavesToJSON, _NoteFiltersMixin

Transcription of the notes played by a single ScampInstrument. Can be saved to and loaded from a json file and played back on a clock.

Parameters:

• instrument – the ScampInstrument associated with this part; used for playback

• name – The name of this part

• voices – either a list of PerformanceNotes (which is interpreted as one unnamed voice), a list of lists of PerformanceNotes (which is interpreted as several numbered voices), or a dictionary mapping voice names to lists of notes.

• instrument_id – a json serializable record of the instrument used

• voice_quantization_records – a record of how this part was quantized if it has been quantized

Variables:

• instrument – the ScampInstrument associated with this part; used for playback

• name – The name of this part

• voices – dictionary mapping voice names to lists of notes.

• instrument_id – a json serializable record of the instrument used

• voice_quantization_records – dictionary mapping voice names to QuantizationRecords, if this is quantized

Methods

add_note(note[, voice])	Add a new Performance note to this PerformancePart.
get_note_iterator([start_beat, stop_beat, ...])	Returns an iterator returning all the notes from start_beat to stop_beat in the selected voices
is_quantized()	Checks if this part has been quantized
name_count()	When there are multiple instrument of the same name in an ensemble, keeps track of which one we mean
new_note(start_beat, length, pitch, volume, ...)	Construct and add a new PerformanceNote to this Performance
num_measures()	If this PerformancePart has been quantized, gets the number of measures
play([start_beat, stop_beat, instrument, ...])	Play this PerformancePart (or a selection of it)
quantize([quantization_scheme, ...])	Quantizes this PerformancePart according to the quantization_scheme
quantized([quantization_scheme, ...])	Same as quantize, except that it returns a new copy, rather than changing this PerformancePart in place.
set_instrument(instrument)	Set the instrument with which this PerformancePart will play back by default
set_instrument_from_ensemble(ensemble)	Set the default instrument to play back with based on the best fit in the given ensemble
to_staff_group()	Converts this PerformancePart to a StaffGroup object.
write_to_midi_file_track(midi_file, track_num)	Writes the contents of this part to a track of a midiutil.MIDIFile.

Inherited Methods

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.
duplicate()	Returns a copy of this object by serializing to and from JSON.
json_dumps()	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.
transpose(interval)	Transposes all notes in this Performance up or down by the desired interval.

Attributes

end_beat	End beat of the last note in this part.
measure_lengths	If this PerformancePart has been quantized, gets the lengths of all the measures

add_note(note: PerformanceNote, voice: Optional[str] = None) → PerformanceNote

Add a new Performance note to this PerformancePart.

Parameters:

• note – the note to add

• voice – name of the voice to which to add it (defaults to “_unspecified_”)

Returns:

the note you just added (for chaining purposes)

new_note(start_beat: float, length, pitch, volume, properties: dict) → PerformanceNote

Construct and add a new PerformanceNote to this Performance

Parameters:

• start_beat – the start beat of the note

• length – length of the note in beats (either a float or a list of floats representing tied segments)

• pitch – pitch of the note (float, Envelope, or list to interpret as an envelope)

• volume – volume of the note (float or Envelope, or list to interpret as an envelope)

• properties – dictionary of note properties, or string representing those properties

Returns:

the note just added

set_instrument(instrument: ScampInstrument) → None

Set the instrument with which this PerformancePart will play back by default

Parameters:

instrument – the instrument to use

property end_beat: float

End beat of the last note in this part.

get_note_iterator(start_beat: float = 0, stop_beat: Optional[float] = None, selected_voices: Optional[Sequence[str]] = None) → Iterator[PerformanceNote]

Returns an iterator returning all the notes from start_beat to stop_beat in the selected voices

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

play(start_beat: float = 0, stop_beat: Optional[float] = None, instrument: Optional[ScampInstrument] = None, clock: Optional[Clock] = None, blocking: bool = True, tempo_envelope: Optional[TempoEnvelope] = None, selected_voices: Optional[Sequence[str]] = None, note_filter: Optional[Callable[[PerformanceNote], PerformanceNote]] = None) → Clock

Play this PerformancePart (or a selection of it)

Parameters:

• start_beat – Place to start playing from

• stop_beat – Place to stop playing at

• instrument – instrument to play back with

• clock – clock to use for playback

• blocking – if True, don’t return until the part is done playing; if False, return immediately

• tempo_envelope – (optional) a tempo envelope to use for playback

• selected_voices – which voices to play back (defaults to all if None)

• 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 playback takes place

set_instrument_from_ensemble(ensemble: Ensemble) → PerformancePart

Set the default instrument to play back with based on the best fit in the given ensemble

Parameters:

ensemble – the ensemble to search in

Returns:

self

write_to_midi_file_track(midi_file: MIDIFile, track_num: int, max_channels=16, ring_time=0.5, pitch_bend_range=2, envelope_precision=0.01) → None

Writes the contents of this part to a track of a midiutil.MIDIFile. Used by Performance.export_to_midi_file().

Parameters:

• midi_file – a midiutil.MIDIFile

• track_num – which track to write to

• max_channels – maximum number of channels to use for different notes. By default, notes with different pitch bends and cc messages will be placed on different channels to avoid interference.

• ring_time – When multiple channels are used for juggling different pitch bends and cc messages, channels are reused when the notes on them have finished. However, if they’re reused right away, this can cause the note that just finished and is perhaps ringing/reverberating to get altered undesirably. ring_time is the amount of time that we wait before reassigning a channel.

• pitch_bend_range – By default +- 2 semitones. If a greater pitch bend is needed, this parameter will scale all pitch bend messages accordingly. It will also attempt to send RPN messages to let the synthesizer know, though in practice many softsynths ignore this and will need to have their pitch bend range set manually.

• envelope_precision – For glissandi, volume curves, and any other parameter that is being given an Envelope, this is the temporal precision of the corresponding midi events.

quantize(quantization_scheme: QuantizationScheme = 'default', onset_weighting: float = 'default', termination_weighting: float = 'default') → PerformancePart

Quantizes this PerformancePart 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 PerformancePart, having been quantized

quantized(quantization_scheme: QuantizationScheme = 'default', onset_weighting: float = 'default', termination_weighting: float = 'default') → PerformancePart

Same as quantize, except that it returns a new copy, rather than changing this PerformancePart 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 PerformancePart

is_quantized() → bool

Checks if this part has been quantized

Returns:

True if quantized, False if not

property measure_lengths: Sequence[float]

If this PerformancePart has been quantized, gets the lengths of all the measures

Returns:

list of measure lengths

num_measures() → int

If this PerformancePart has been quantized, gets the number of measures

Returns:

number of measures

to_staff_group() → StaffGroup

Converts this PerformancePart to a StaffGroup object. (Quantizes in a default way, if necessary, but it should be quantized already.)

Returns:

a new StaffGroup made from this PerformancePart

name_count() → int

When there are multiple instrument of the same name in an ensemble, keeps track of which one we mean

Returns:

int representing which instrument we mean

apply_note_filter(filter_function: Callable[[PerformanceNote], None], start_beat: float = 0, stop_beat: Optional[float] = None, selected_voices: Optional[Sequence[str]] = None)

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[[Envelope | float], Envelope | float], start_beat: float = 0, stop_beat: Optional[float] = None, selected_voices: Optional[Sequence[str]] = None)

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

apply_volume_filter(filter_function: Callable[[Envelope | float], Envelope | float], start_beat: float = 0, stop_beat: Optional[float] = None, selected_voices: Optional[Sequence[str]] = None)

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

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

transpose(interval: float)

Transposes all notes in this Performance up or down by the desired interval. For greater flexibility, use the apply_pitch_filter and apply_note_filter methods.

Parameters:

interval – the interval by which to transpose this Performance

Returns:

self, for chaining purposes