scamp.instruments.ScampInstrument

class scamp.instruments.ScampInstrument(name: str = None, ensemble: Ensemble = None, default_spelling_policy: SpellingPolicy | str | tuple = None, clef_preference='from_name', playback_implementations: Sequence[PlaybackImplementation] = None, start_note_fixed: bool = True)[source]

Bases: SavesToJSON

Instrument class that does the playing of the notes. Generally this will be created through one of the “new_part” methods of the Session or Ensemble class.

Parameters:

name – name of this instrument (e.g. when printed in a score)
ensemble – Ensemble to which this instrument will belong.
default_spelling_policy – sets ScampInstrument.default_spelling_policy
clef_preference – sets ScampInstrument.clef_preference
playback_implementations – PlaybackImplementation(s) used to actually playback notes

Variables:

name – name of this instrument (e.g. when printed in a score)
name_count – when there are multiple instruments of the same name within an Ensemble, this variable assigns each a unique index (starting with 0), to distinguish them
ensemble – Ensemble to which this instrument will belong.
playback_implementations – list of PlaybackImplementation(s) used to actually playback notes

Methods

`add_osc_playback`(port[, ip_address, ...])	Add an OSCPlaybackImplementation for this instrument.
`add_soundfont_playback`([preset, soundfont, ...])	Add a soundfont playback implementation for this instrument.
`add_streaming_midi_playback`([...])	Add a streaming MIDI playback implementation for this instrument.
`change_note_parameter`(note_id, param_name, ...)	Changes the value of parameter of note playback over a given time; can also take a sequence of targets and times
`change_note_pitch`(note_id, ...[, ...])	Change the pitch of an already started note; can also take a sequence of targets and times.
`change_note_volume`(note_id, ...[, ...])	Change the volume of an already started note; can also take a sequence of targets and times
`end_all_notes`()	Ends all notes currently playing
`end_note`([note_id])	Ends the note with the given note id.
`num_notes_playing`()	Returns the number of notes currently playing.
`pedal_change`([duration, press_amount])	Quickly lifts and re-presses the sustain pedal, clearing resonating notes.
`pedal_down`([press_amount])	Presses the sustain pedal, by sending a CC 64 message to all midi-based playback implementations.
`pedal_up`()	Releases the sustain pedal, by sending a CC 64 message of 0 to all midi-based playback implementations.
`play_chord`(pitches, volume, length[, ...])	Play a chord with the given pitches, volume, and length.
`play_note`(pitch, volume, length[, ...])	Play a note on this instrument, with the given pitch, volume and length.
`remove_osc_playback`()	Remove the most recent OSCPlaybackImplementation from this instrument.
`remove_soundfont_playback`()	Remove the most recent SoundfontPlaybackImplementation from this instrument.
`remove_streaming_midi_playback`()	Remove the most recent MIDIStreamPlaybackImplementation from this instrument.
`resolve_clef_preference`()	Resolves the clef preference to a sequence of possible clef choices.
`send_midi_cc`(cc_number, value_from_0_to_1)	Sends a midi cc message to all midi-based playback implementations, affecting all channels this instrument uses.
`set_ensemble`(ensemble)	Sets the ensemble that this instrument belongs to.
`set_max_pitch_bend`(semitones)	Set the max pitch bend for all midi playback implementations on this instrument
`split_note`(note_id)	Adds a split point in a note, causing it later to be rendered as tied pieces.
`start_chord`(pitches, volume[, properties, ...])	Simple utility for starting chords without starting each note individually.
`start_note`(pitch, volume[, properties, ...])	Start a note with the given pitch, volume, and properties

Inherited Methods

`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.

Attributes

`clef_preference`	The clef preference for this instrument.
`default_spelling_policy`	The default spelling policy for notes played back by this instrument.
`note_info_by_id`	Dictionary mapping the id of each note currently sounding on this instrument to the bookkeeping information kept about it (the clock that started it, its start/end time stamps, its current parameter values, any ongoing parameter change segments, and its `NoteProperties`).

set_ensemble(ensemble: Ensemble) → None[source]

Sets the ensemble that this instrument belongs to. Generally this happens automatically.

Parameters:: ensemble – the Ensemble that this instrument should belong to.

play_note(pitch: PitchCompatible, volume: VolumeCompatible, length: DurationCompatible, properties: NotePropertiesCompatible = None, blocking: bool = True, clock: Clock = None, velocity: float = None, silent: bool = False, transcribe: bool = True) → None[source]

Play a note on this instrument, with the given pitch, volume and length.

Parameters:

pitch – either a number, an Envelope, or a list used to create an Envelope. MIDI pitch values are used, with 60 representing middle C. However, microtones are allowed; for instance, a pitch of 64.7 produces an F4 30 cents flat. A pitch of None simply translates to a rest.
volume – either a number, an Envelope, or a list used to create an Envelope. Volume is scaled from 0 to 1, with 0 representing silence and 1 representing max volume.
length – either a number (of beats), or a tuple representing a set of tied segments
properties – Catch-all for a wide range of other playback and notation details that we may want to convey about a note. See The Note Properties Argument
blocking – if True, don’t return until the note is done playing; if False, return immediately
clock – which clock to use. If None, capture the clock from context.
velocity – for MIDI-based playback implementations (or other implementations that take velocity), fixes the note-on velocity (0 to 1), turning volume into expression cc. By default (None) velocity follows volume.
silent – if True, note is not played back, but is still transcribed when a Transcriber is active. (Generally ignored by end user.)
transcribe – if False, note is not transcribed even when a Transcriber is active. (Generally ignored by end user.)

play_chord(pitches: Sequence[TypeAliasForwardRef('PitchCompatible')], volume: VolumeCompatible, length: DurationCompatible, properties: NotePropertiesCompatible = None, blocking: bool = True, clock: Clock = None, velocity: float = None, silent: bool = False, transcribe: bool = True) → None[source]

Play a chord with the given pitches, volume, and length. Essentially, this is a convenience method that bundles together several calls to “play_note” and takes a list of pitches rather than a single pitch

Parameters:

pitches – a list of pitches for the notes of this chord
volume – see play_note()
length – see play_note()
properties – see The Note Properties Argument
blocking – see description for “play_note”
clock – see description for “play_note”
velocity – see play_note()
silent – see description for “play_note”
transcribe – see description for “play_note”

start_note(pitch: PitchCompatible, volume: VolumeCompatible, properties: NotePropertiesCompatible = None, clock: Clock = None, fixed: bool | str = 'auto', velocity: float = None, flags: Sequence[str] = None) → NoteHandle[source]

Start a note with the given pitch, volume, and properties

Parameters:

pitch – the pitch / starting pitch of the note
volume – the volume / starting volume of the note
properties – see The Note Properties Argument
clock – the clock on which to run any animation of pitch, volume, etc. If None, captures the clock from context.
fixed – whether the note is locked at note-on. True maps volume directly to velocity and allows the note to share a midi channel with other notes, but forbids any later changes. False gives the note its own channel and allows pitch, volume, and other parameters to change. A note with an Envelope argument or an explicit velocity must animate, so it is always unfixed, ignoring this argument. The default “auto” falls back to this instrument’s start_note_fixed.
velocity – an explicit note-on velocity (0 to 1), decoupling the attack from volume. By default (None) velocity follows the start volume, so expression starts at 100% and volume can only be lowered. Given a value, the note attacks at that velocity while the volume argument drives expression directly, over its full range.
flags – list of strings that act as flags for how the note should be processed. Should probably be ignored by a normal user.

Returns:

a NoteHandle with which to later manipulate the note

start_chord(pitches: Sequence[TypeAliasForwardRef('PitchCompatible')], volume: VolumeCompatible, properties: NotePropertiesCompatible = None, clock: Clock = None, fixed: bool | str = 'auto', velocity: float = None, flags: Sequence[str] = None) → ChordHandle[source]

Simple utility for starting chords without starting each note individually.

Parameters:

pitches – a list of pitches
volume – see start_note()
properties – see The Note Properties Argument
clock – see start_note
fixed – see start_note
velocity – see start_note
flags – see start_note

Returns:

a ChordHandle, which is used to manipulate the chord thereafter. Pitch change calls on the ChordHandle are based on the first note of the chord; all other notes are shifted in parallel

change_note_parameter(note_id: int | NoteHandle, param_name: str, target_value_or_values: float | Sequence[float], transition_length_or_lengths: float | Sequence[float] = 0, transition_curve_shape_or_shapes: float | Sequence[float] = 0, clock: Clock = None) → None[source]

Changes the value of parameter of note playback over a given time; can also take a sequence of targets and times

Parameters:

note_id – which note to affect (an id or a NoteHandle)
param_name – name of the parameter to affect. “pitch” and “volume” are special cases
target_value_or_values – target value (or list of values) for the parameter
transition_length_or_lengths – transition time(s) in beats to the target value(s)
transition_curve_shape_or_shapes – curve shape(s) for the transition(s)
clock – which clock all of this happens on; by default, reuses the clock that the note started on.

change_note_pitch(note_id: int | NoteHandle, target_value_or_values: float | Sequence[float], transition_length_or_lengths: float | Sequence[float] = 0, transition_curve_shape_or_shapes: float | Sequence[float] = 0, clock: Clock = None) → None[source]

Change the pitch of an already started note; can also take a sequence of targets and times.

Parameters:

note_id – which note to affect (an id or a NoteHandle)
target_value_or_values – target value (or list of values) for the parameter
transition_length_or_lengths – transition time(s) in beats to the target value(s)
transition_curve_shape_or_shapes – curve shape(s) for the transition(s)
clock – which clock all of this happens on; by default, reuses the clock that the note started on.

change_note_volume(note_id: int | NoteHandle, target_value_or_values: float | Sequence[float], transition_length_or_lengths: float | Sequence[float] = 0, transition_curve_shape_or_shapes: float | Sequence[float] = 0, clock: Clock = None) → None[source]

Change the volume of an already started note; can also take a sequence of targets and times

Parameters:

note_id – which note to affect (an id or a NoteHandle)
target_value_or_values – target value (or list thereof) for the parameter
transition_length_or_lengths – transition time(s) in beats to the target value(s)
transition_curve_shape_or_shapes – curve shape(s) for the transition(s)
clock – which clock all of this happens on; “from_note” simply reuses the clock that the note started on.

split_note(note_id: int | NoteHandle) → None[source]

Adds a split point in a note, causing it later to be rendered as tied pieces.

Parameters:: note_id – Which note or NoteHandle to split

end_note(note_id: int | NoteHandle = None) → None[source]

Ends the note with the given note id. If none is specified, ends oldest note started. Note that this only applies to notes started in an open-ended way with start_note(), notes created using play_note() have their lifecycle controlled automatically.

Parameters:: note_id – either the id itself or a NoteHandle with that id. Default of None ends the oldest note

end_all_notes() → None[source]: Ends all notes currently playing

num_notes_playing() → int[source]: Returns the number of notes currently playing.

add_soundfont_playback(preset: str | int | tuple[int, int] = 'auto', soundfont: str = 'default', num_channels: int = 8, audio_driver: str = 'default', max_pitch_bend: int = 'default', note_on_and_off_only: bool = False, volume_cc_num: int = 11) → ScampInstrument[source]

Add a soundfont playback implementation for this instrument.

Parameters:

preset – either a preset number, a tuple of (bank, preset), a string giving a name to search for in the soundfont, or the string “auto”, in which case the name of this instrument is used to search for a preset.
soundfont – which soundfont to use. This can be either a path to a soundfont or the name of one of the soundfonts specified in playback_settings.named_soundfonts. If this instrument belongs to an Ensemble, “default” means use the Ensemble default; if not, we will fall back to the default provided in playback_settings.
num_channels – how many channels to allocate for managing pitch bends, etc.
audio_driver – which driver to use
max_pitch_bend – max pitch bend to allow
note_on_and_off_only – Deprecated; set the instrument’s start_note_fixed instead.
volume_cc_num – The cc value used for volume changes. Defaults to 11 (expression).

Returns:

self, for chaining purposes

remove_soundfont_playback() → ScampInstrument[source]

Remove the most recent SoundfontPlaybackImplementation from this instrument.

Returns:: self, for chaining purposes

add_streaming_midi_playback(midi_output_device: int | str = 'default', num_channels: int = 8, midi_output_name: str = None, max_pitch_bend: int = 'default', note_on_and_off_only: bool = False, start_channel: int = 0, volume_cc_num: int = 11) → ScampInstrument[source]

Add a streaming MIDI playback implementation for this instrument.

Parameters:

midi_output_device – name or number of the device to use
num_channels – how many channels to allocate for managing pitch bends, etc.
midi_output_name – name given to the output stream
max_pitch_bend – max pitch bend to allow
note_on_and_off_only – Deprecated; set the instrument’s start_note_fixed instead.
start_channel – the first channel to use. For instance, if start_channel is 4, and num_channels is 5, we will use channels (4, 5, 6, 7, 8). NOTE: channel counting in SCAMP starts from 0, so this may show up as channels 5-9 in your MIDI software.
volume_cc_num – The cc value used for volume changes. Defaults to 11 (expression).

Returns:

self, for chaining purposes

remove_streaming_midi_playback() → ScampInstrument[source]

Remove the most recent MIDIStreamPlaybackImplementation from this instrument.

Returns:: self, for chaining purposes

add_osc_playback(port: int, ip_address: str = '127.0.0.1', message_prefix: str = None, osc_message_addresses: dict = 'default')[source]

Add an OSCPlaybackImplementation for this instrument.

Parameters:

port – port to use
ip_address – ip address to use
message_prefix – the prefix to give to all outgoing osc messages; defaults to the instrument name with all spaces removed.
osc_message_addresses – the specifix message addresses to be used for each type of message. Defaults are defined in playback_settings

Returns:

self, for chaining purposes

remove_osc_playback() → ScampInstrument[source]

Remove the most recent OSCPlaybackImplementation from this instrument.

Returns:: self, for chaining purposes

set_max_pitch_bend(semitones: int) → None[source]: Set the max pitch bend for all midi playback implementations on this instrument

send_midi_cc(cc_number: int, value_from_0_to_1: float) → None[source]

Sends a midi cc message to all midi-based playback implementations, affecting all channels this instrument uses. This is useful for stuff like pedal messages, that we don’t really want to bundle with note playback, and that we want to apply to all channels.

Parameters:

cc_number – the cc number from 0 to 127
value_from_0_to_1 – the value to send, normalized from 0 to 1

pedal_down(press_amount: float = 1.0) → None[source]

Presses the sustain pedal, by sending a CC 64 message to all midi-based playback implementations.

Parameters:: press_amount – how far down to press the pedal, from 0 to 1 (values in between allow half-pedaling, if supported by the receiving device)

pedal_up() → None[source]: Releases the sustain pedal, by sending a CC 64 message of 0 to all midi-based playback implementations.

pedal_change(duration: float = 0.2, press_amount: float = None) → None[source]

Quickly lifts and re-presses the sustain pedal, clearing resonating notes. Returns immediately, with the re-press happening in a forked process after the given duration.

Parameters:

duration – how long (in seconds, regardless of tempo) to keep the pedal up before re-pressing it
press_amount – how far down to re-press the pedal, from 0 to 1; defaults to the press amount of the last call to pedal_down() or pedal_change().

property clef_preference

The clef preference for this instrument. Can be any of:

“from_name”, which picks clef based on the instrument name
“default”, which uses the default clef preferences for an unknown instrument
the name of a clef
the name of an instrument whose clef defaults to use
a list of possible clefs. Each of these choices should be either a valid clef name string or a tuple of (valid clef name string, center pitch).

resolve_clef_preference() → Sequence[str | tuple[str, Real]][source]: Resolves the clef preference to a sequence of possible clef choices.

property default_spelling_policy: The default spelling policy for notes played back by this instrument. (Can be set with a SpellingPolicy, or a string or tuple interpretable as such via interpret())

property note_info_by_id

Dictionary mapping the id of each note currently sounding on this instrument to the bookkeeping information kept about it (the clock that started it, its start/end time stamps, its current parameter values, any ongoing parameter change segments, and its NoteProperties).

This is exposed mostly for the benefit of custom PlaybackImplementation subclasses, which may need to consult the state of a note in progress.

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