scamp.instruments.Ensemble¶
-
class
scamp.instruments.
Ensemble
(default_soundfont: str = 'default', default_audio_driver: str = 'default', default_midi_output_device: str = 'default', default_spelling_policy: Union[scamp.spelling.SpellingPolicy, str, tuple] = None, instruments: Sequence[ScampInstrument] = None)[source]¶ Bases:
expenvelope.json_serializer.SavesToJSON
Host for multiple
ScampInstrument
objects, keeping shared resources, and shared default settings. ASession
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_midi_output_device – value to initialize default_midi_output_device 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) – 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.
default_midi_output_device – the midi output device 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.
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.
Prints a list of available ports and devices for midi output.
Prints a list of presets available with the default soundfont.
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
Default spelling policy used for transcriptions made with this Ensemble.
-
add_instrument
(instrument: scamp.instruments.ScampInstrument) → scamp.instruments.ScampInstrument[source]¶ Adds an instance of ScampInstrument to this Ensemble. Generally this will be done indirectly by calling one of the “new_instrument” methods.
- Parameters
instrument – instrument to add to this ensemble
- Returns
self
-
new_silent_part
(name: str = None, default_spelling_policy: scamp.spelling.SpellingPolicy = None, clef_preference='from_name') → scamp.instruments.ScampInstrument[source]¶ 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 partclef_preference – the
clef_preference
for the new part
- Returns
the newly created ScampInstrument
-
new_part
(name: 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: scamp.spelling.SpellingPolicy = None, clef_preference='from_name') → scamp.instruments.ScampInstrument[source]¶ 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 ofplay_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 partclef_preference – the
clef_preference
for the new part
- Returns
the newly created ScampInstrument
-
new_midi_part
(name: str = None, midi_output_device: Union[int, str] = 'default', num_channels: int = 8, midi_output_name: str = None, max_pitch_bend: int = 'default', note_on_and_off_only: bool = False, default_spelling_policy: scamp.spelling.SpellingPolicy = None, clef_preference='from_name', start_channel: int = 0) → scamp.instruments.ScampInstrument[source]¶ 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 ofplay_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 partclef_preference – the
clef_preference
for the new partstart_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: str = None, port: int = None, ip_address: str = '127.0.0.1', message_prefix: str = None, osc_message_addresses: dict = 'default', default_spelling_policy: scamp.spelling.SpellingPolicy = None, clef_preference='from_name') → scamp.instruments.ScampInstrument[source]¶ 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 partclef_preference – the
clef_preference
for the new part
- Returns
the newly created ScampInstrument
-
get_instrument_by_name
(name: str, which: int = 0)[source]¶ 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[source]¶ Prints a list of presets available with the default soundfont.
-
static
get_available_midi_output_devices
() → enumerate[source]¶ Returns an enumeration of available ports and devices for midi output.
-
static
print_available_midi_output_devices
() → None[source]¶ Prints a list of available ports and devices for midi output.
-
property
default_spelling_policy
¶ 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