scamp.instruments.Ensemble

class scamp.instruments.Ensemble(default_soundfont: str = 'default', default_audio_driver: str = 'default', default_spelling_policy: Optional[Union[SpellingPolicy, str, tuple]] = None, instruments: Optional[Sequence[ScampInstrument]] = None)

Bases: SavesToJSON

Host for multiple ScampInstrument objects, keeping shared resources, and shared default settings. A Session is, among other things, an Ensemble.

Parameters:

• default_audio_driver – value to initialize default_audio_driver instance variable to

• default_soundfont – value to initialize default_soundfont instance variable to

• default_spelling_policy – a SpellingPolicy (or a string or tuple interpretable as such) to use for all instruments in this ensemble, overriding scamp defaults.

• instruments – list of instruments to populate this ensemble with. NOTE: generally it is not a good idea to initialize an Ensemble with this argument, but better to use the new_part methods after the fact. This is because instrument playback implementations look to share ensemble resources when they are created, and this is not possible if they are not already part of an ensemble.

Variables:

• default_audio_driver – the audio driver instruments in this ensemble will default to. If “default”, then this defers to the scamp global playback_settings default.

• default_soundfont – the soundfont that instruments in this ensemble will default to. If “default”, then this defers to the scamp global playback_settings default.

• instruments – List of all of the ScampInstruments within the Ensemble.

Methods

add_instrument(instrument)	Adds an instance of ScampInstrument to this Ensemble.
get_available_midi_output_devices()	Returns an enumeration of available ports and devices for midi output.
get_instrument_by_name(name[, which])	Returns the instrument of the given name.
new_midi_part([name, midi_output_device, ...])	Creates and returns a new ScampInstrument for this Ensemble that uses a MIDIStreamPlaybackImplementation.
new_osc_part([name, port, ip_address, ...])	Creates and returns a new ScampInstrument for this Ensemble that uses a OSCPlaybackImplementation.
new_part([name, preset, soundfont, ...])	Creates and returns a new ScampInstrument for this Ensemble that uses a SoundfontPlaybackImplementation.
new_silent_part([name, ...])	Creates and returns a new ScampInstrument for this Ensemble with no PlaybackImplementations.
pop_instrument(index)	Pops the instrument at the given index, severing its ties to the ensemble.
print_available_midi_output_devices()	Prints a list of available ports and devices for midi output.
print_default_soundfont_presets()	Prints a list of presets available with the default soundfont.

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

default_spelling_policy	Default spelling policy used for transcriptions made with this Ensemble.
instruments	Returns a tuple of the instruments currently in this Ensemble.

property instruments

Returns a tuple of the instruments currently in this Ensemble.

add_instrument(instrument: ScampInstrument) → ScampInstrument

Adds an instance of ScampInstrument to this Ensemble. Generally, creating of and instrument and adding it to an ensemble are done simultaneously via one of the “new_instrument” methods.

Parameters:

instrument – instrument to add to this ensemble

Returns:

self

pop_instrument(index)

Pops the instrument at the given index, severing its ties to the ensemble.

Parameters:

index – which instrument

new_silent_part(name: Optional[str] = None, default_spelling_policy: Optional[SpellingPolicy] = None, clef_preference='from_name') → ScampInstrument

Creates and returns a new ScampInstrument for this Ensemble with no PlaybackImplementations.

Parameters:

• name – name of the new part

• default_spelling_policy – the default_spelling_policy for the new part

• clef_preference – the clef_preference for the new part

Returns:

the newly created ScampInstrument

new_part(name: Optional[str] = None, preset='auto', soundfont: str = 'default', num_channels: int = 8, audio_driver: str = 'default', max_pitch_bend: int = 'default', note_on_and_off_only: bool = False, default_spelling_policy: Optional[SpellingPolicy] = None, clef_preference='from_name') → ScampInstrument

Creates and returns a new ScampInstrument for this Ensemble that uses a SoundfontPlaybackImplementation. Unless otherwise specified, the default soundfont for this Ensemble/Session will be used, and we will search for the preset that best matches the name given.

Parameters:

• name – name used for this instrument in score, etc.

• preset – if an int, assumes bank #0; can also be a tuple of form (bank, preset). If “auto”, searches for a preset of the appropriate name.

• soundfont – the name of the soundfont to use for fluidsynth playback

• num_channels – maximum of midi channels available to this midi part. It’s wise to use more when doing microtonal playback, since pitch bends are applied per channel.

• audio_driver – which audio driver to use for this instrument (defaults to ensemble default)

• max_pitch_bend – max pitch bend to use for this instrument

• note_on_and_off_only – This enforces a rule of no dynamic pitch bends, expression (volume) changes, or other cc messages. Valuable when using start_note instead of play_note in music that doesn’t do any dynamic pitch/volume/parameter changes. Without this flag, notes will all be placed on separate MIDI channels, since they could potentially change pitch or volume; with this flags, we know they won’t, so they can share the same MIDI channels, only using an extra one due to microtonality.

• default_spelling_policy – the default_spelling_policy for the new part

• clef_preference – the clef_preference for the new part

Returns:

the newly created ScampInstrument

new_midi_part(name: Optional[str] = None, midi_output_device: Optional[Union[int, str]] = None, num_channels: int = 8, midi_output_name: Optional[str] = None, max_pitch_bend: int = 'default', note_on_and_off_only: bool = False, default_spelling_policy: Optional[SpellingPolicy] = None, clef_preference='from_name', start_channel: int = 0) → ScampInstrument

Creates and returns a new ScampInstrument for this Ensemble that uses a MIDIStreamPlaybackImplementation. This means that when notes are played by this instrument, midi messages are sent out to the given device.

Parameters:

• name – name used for this instrument in score, etc. for a preset of the appropriate name.

• midi_output_device – name or number of the device used to output midi. Call get_available_midi_output_devices to check what’s available.

• num_channels – maximum of midi channels available to this midi part. It’s wise to use more when doing microtonal playback, since pitch bends are applied per channel.

• midi_output_name – name of this part

• max_pitch_bend – max pitch bend to use for this instrument

• note_on_and_off_only – This enforces a rule of no dynamic pitch bends, expression (volume) changes, or other cc messages. Valuable when using start_note instead of play_note in music that doesn’t do any dynamic pitch/volume/parameter changes. Without this flag, notes will all be placed on separate MIDI channels, since they could potentially change pitch or volume; with this flags, we know they won’t, so they can share the same MIDI channels, only using an extra one due to microtonality.

• default_spelling_policy – the default_spelling_policy for the new part

• clef_preference – the clef_preference for the new part

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

Returns:

the newly created ScampInstrument

new_osc_part(name: Optional[str] = None, port: Optional[int] = None, ip_address: str = '127.0.0.1', message_prefix: Optional[str] = None, osc_message_addresses: dict = 'default', default_spelling_policy: Optional[SpellingPolicy] = None, clef_preference='from_name') → ScampInstrument

Creates and returns a new ScampInstrument for this Ensemble that uses a OSCPlaybackImplementation. This means that when notes are played by this instrument, osc messages are sent out to the specified address

Parameters:

• name – name used for this instrument in score, etc. for a preset of the appropriate name.

• port – port osc messages are sent to

• ip_address – ip_address osc messages are sent to

• message_prefix – prefix used for this instrument in osc messages

• osc_message_addresses – dictionary defining the address used for each type of playback message. defaults to using “start_note”, “end_note”, “change_pitch”, “change_volume”, “change_parameter”. The default can be changed in playback settings.

• default_spelling_policy – the default_spelling_policy for the new part

• clef_preference – the clef_preference for the new part

Returns:

the newly created ScampInstrument

get_instrument_by_name(name: str, which: int = 0)

Returns the instrument of the given name.

Parameters:

• name – name of the instrument to return

• which – If there are multiple with the same name, this parameter specifies the one returned. (If none match the number given by which, the first name match is returned)

print_default_soundfont_presets() → None

Prints a list of presets available with the default soundfont.

static get_available_midi_output_devices() → enumerate

Returns an enumeration of available ports and devices for midi output.

static print_available_midi_output_devices() → None

Prints a list of available ports and devices for midi output.

property default_spelling_policy: SpellingPolicy

Default spelling policy used for transcriptions made with this Ensemble.

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