scamp.settings.PlaybackSettings

class scamp.settings.PlaybackSettings(settings_dict: Optional[dict] = None, suppress_warnings: bool = False)

Bases: _ScampSettings

Namespace containing the settings relevant to playback implementation and adjustments.

Parameters:

settings_dict – dictionary from which to set all settings attributes

Variables:

• named_soundfonts – Dictionary mapping names of frequently-used soundfonts to their file paths

• default_soundfont – Soundfont (by name or path) to default to in playback

• default_audio_driver – Name of the audio driver use for soundfont playback by default. If “auto”, we test to see what audio driver will work, and replace this value with that driver.

• default_max_soundfont_pitch_bend – When playing back with soundfonts, instruments will be immediately set to use this value for the maximum pitch bend. (Makes sense to set this to a large value for maximum flexibility)

• default_max_streaming_midi_pitch_bend – When playing back with a midi stream to an external synthesizer/program, instruments will be immediately set to use this value for the maximum pitch bend. (Makes sense probably to leave this at the MIDI default of 2 semitones, in case the receiving device doesn’t listen to messages that reset the pitch bend range.)

• soundfont_volume_to_velocity_curve – an Envelope defining how volume values get mapped to MIDI velocities in soundfont-based playback. The default maps the range 0-1 to the range 0-127, but with some non-linear shaping towards higher velocity values. This is because, for some reason, soundfont playback is almost inaudible low velocities.

• streaming_midi_volume_to_velocity_curve – same as soundfont_volume_to_velocity_curve, but for streaming MIDI playback. This defaults to a linear mapping from 0-1 to 0-127.

• osc_message_addresses – Dictionary mapping the different kinds of playback messages to the OSC messages prefixes we will use for them. For instance, if you want start note messages to use “note_on”, set the osc_message_addresses[“start_note”] = “note_on”, and all OSC messages starting a note will come out as [instrument name]/note_on/

• adjustments – a dictionary defining how playback should be altered in response to different articulations/notations/etc.

• try_system_fluidsynth_first – if True, always tries system copy of the fluidsynth libraries first before using the one embedded in the scamp package.

• resize_parameter_envelopes – one of “never”, “lists”, and “always”. This determines whether or not parameter envelopes are resized to the length of the note. The default value of “lists” does this resizing only when the envelope was created indirectly by passing a list to the parameter.

Methods

get_playback_adjustment(note_property)
list_named_soundfonts()	Prints out a list of all of the named soundfonts and the paths of the soundfont files to which they point.
register_named_soundfont(name, soundfont_path)	Adds a named soundfont, so that it can be easily referred to in constructing a Session
set_playback_adjustment(note_property, ...)
unregister_named_soundfont(name)	Same as above, but removes a named soundfont

Inherited Methods

duplicate()	Returns a copy of this object by serializing to and from JSON.
factory_default()	Returns a factory default version of this settings object.
json_dumps()	Dump this object as a JSON string.
json_loads(s)	Load this object from a JSON string.
load()	Loads and instance of this settings object from its corresponding JSON file.
load_from_json(file_path)	Load this object from a JSON file with the given path.
make_persistent()	Rewrites the JSON file from which settings are loaded, meaning that this reset will persist to the running of scripts in the future.
open_json_file(*command_and_flags)	Open the JSON file for these settings.
restore_factory_defaults([persist])	Restores settings back to their "factory defaults" (the defaults when SCAMP was installed).
save_to_json(file_path)	Save this object to a JSON file using the given path.

Attributes

factory_defaults

Default playback settings (from when SCAMP was installed)

factory_defaults = {'adjustments': {'articulations': {'accent': NotePlaybackAdjustment(None, ParamPlaybackAdjustment(1.2, 0), None), 'marcato': NotePlaybackAdjustment(None, ParamPlaybackAdjustment(1.5, 0), None), 'staccatissimo': NotePlaybackAdjustment(None, None, ParamPlaybackAdjustment(0.3, 0)), 'staccato': NotePlaybackAdjustment(None, None, ParamPlaybackAdjustment(0.5, 0)), 'tenuto': NotePlaybackAdjustment(None, None, ParamPlaybackAdjustment(1.2, 0))}}, 'default_audio_driver': 'auto', 'default_max_soundfont_pitch_bend': 48, 'default_max_streaming_midi_pitch_bend': 2, 'default_soundfont': 'general_midi', 'named_soundfonts': {'general_midi': 'Merlin.sf2'}, 'osc_message_addresses': {'change_parameter': 'change_parameter', 'change_pitch': 'change_pitch', 'change_volume': 'change_volume', 'end_note': 'end_note', 'start_note': 'start_note'}, 'recording_file_path': None, 'recording_time_range': [0, 'inf'], 'resize_parameter_envelopes': 'lists', 'soundfont_search_paths': ['%PKG/soundfonts'], 'soundfont_volume_to_velocity_curve': Envelope((0, 40, 127), (0.1, 0.9), (0, 0), 0), 'streaming_midi_volume_to_velocity_curve': Envelope((0, 127), (1,), (0,), 0), 'try_system_fluidsynth_first': False}

Default playback settings (from when SCAMP was installed)

register_named_soundfont(name: str, soundfont_path: str) → None

Adds a named soundfont, so that it can be easily referred to in constructing a Session

Parameters:

• name – the soundfont name

• soundfont_path – the absolute path to the soundfont, staring with a slash, or a relative path that gets resolved relative to the soundfonts directory

unregister_named_soundfont(name: str) → None

Same as above, but removes a named soundfont

Parameters:

name – the default soundfont name to remove

list_named_soundfonts() → None

Prints out a list of all of the named soundfonts and the paths of the soundfont files to which they point.

set_playback_adjustment(note_property: str, adjustment: str | NotePlaybackAdjustment)

get_playback_adjustment(note_property: str)

duplicate() → T

Returns a copy of this object by serializing to and from JSON.

classmethod factory_default()

Returns a factory default version of this settings object.

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()

Loads and instance of this settings object from its corresponding JSON file. If no such file exists, or it is corrupted in some way, then this creates a fresh JSON file there. This doesn’t work with settings that are nested within other settings (like GlissandiSettings), since they do not have corresponding JSON files,

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

make_persistent() → None

Rewrites the JSON file from which settings are loaded, meaning that this reset will persist to the running of scripts in the future.

open_json_file(*command_and_flags)

Open the JSON file for these settings.

Parameters:

command_and_flags – the command-line tool with which to open the file, and any associated flags. Defaults to a platform-specific generic open command.

restore_factory_defaults(persist=False) → None

Restores settings back to their “factory defaults” (the defaults when SCAMP was installed). Unless the persist argument is set, this is temporary to the running of the current script.

Parameters:

persist – if True, rewrites the JSON file from which defaults are loaded, meaning that this reset will persist to the running of scripts in the future.

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