scamp.settings.EngravingSettings

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

Bases: _ScampSettings

Namespace containing the settings relevant to the engraving of scores.

Parameters:

settings_dict – dictionary from which to set all settings attributes

Variables:

• allow_duple_tuplets_in_compound_time – There are two ways to express a division of a beat in compound time in two: with a duple tuplet or with dotted notes. For instance, half of a beat in 3/8 can be represented as a dotted-eighth or an eighth inside of a 2:3 tuplet. If this is set to True, we allow the latter option.

• max_voices_per_part – integer specifying how many voices we allow in a single staff before creating extra staves to accommodate them.

• max_dots_allowed – integer specifying how many dots we allow a note to have before it’s just too many dots.

• beat_hierarchy_spacing – Should be >= 1. Larger numbers treat the various nested levels of beat subdivision as further apart, leading to a greater tendency to show the beat structure rather than combine tie notes into fewer pieces.

• num_divisions_penalty – Ranges from 0 to 1, where 0 treats having multiple tied notes to represent a single note event as just as good as having fewer notes, while numbers closer to 1 increasingly favor using fewer notes in a tied group.

• rest_beat_hierarchy_spacing – Same as beat_hierarchy_spacing, but for rests. (We generally want rests to be more likely to split.)

• rest_num_divisions_penalty – Same as num_divisions_penalty, but for rests. (We generally want rests to be less inclined to recombine.)

• articulation_split_protocols – Dictionary mapping articulation names to either “first”, “last”, “both” or “all”. When a note has been given a particular articulation during playback, but needs to be engraved as a group of tied notes, the question arises: which of those tied pieces should get the articulation? For instance, an accent probably wants to be on the first note, since it’s an attack, and a staccato dot probably should be on the last note, since it’s about release. The value “both” will place the articulation on both the first and last note, and “all” will place the articulation on every note of the tied group.

• clefs_by_instrument – Dictionary mapping instrument names to a list of clefs used by those instruments. Instead of simply the clef name, a tuple of (clef name, redefined_pitch_center) can be given. This overrides the pitch center given in clef_pitch_centers for that clef on that instrument, since clef choice can be idiosyncratic to the given instrument. The “DEFAULT” entry is used for instruments not explicitly specified.

• clef_pitch_centers – Pitch center used when deciding on clef choice. Default is to use the pitch of the center line. The clef chosen will be the one whose pitch center is closest to the average pitch.

• clef_selection_policy – Either “measure-wise”, in which case clef can be changed measure by measure if needed, or “part-wise”, in which case a single clef choice is used for the entire part..

• default_titles – Title or list of titles from which to choose for a score that has been created without specifying a title.

• default_composers – Name or list of name from which to choose for a score that has been created without specifying a composer.

• default_spelling_policy – the SpellingPolicy to use by default in determining accidentals.

• ignore_empty_parts – if True, don’t bother to include parts in a score if there’s nothing in them.

• glissandi – instance of GlissandiSettings specifying how glissandi should be engraved.

• tempo – instance of TempoSettings specifying how tempo changes should be engraved.

• pad_incomplete_parts – If true, add measures to parts that don’t have enough music in them so that they are go the full length of the score.

• show_music_xml_command_line – Terminal command to run when opening up MusicXML scores. It is easiest to set this by calling set_music_xml_application. The value “auto” tries to find an appropriate application automatically.

• show_microtonal_annotations – if True, annotates microtonal pitches with the exact floating-point MIDI pitch value that they are intended to represent. (This is useful, since normally the best a notation program can do is quarter tones.

• microtonal_annotation_digits – number of digits after the decimal place to show when showing microtonal annotations.

Methods

get_default_composer()	Grabs one of the default composer names.
get_default_title()	Grabs one of the default score titles.
set_music_xml_application([application_name])	Sets the application to use when opening generated MusicXML scores

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 engraving settings (from when SCAMP was installed)

factory_defaults = {'allow_duple_tuplets_in_compound_time': False, 'articulation_split_protocols': {'accent': 'first', 'default': 'all', 'marcato': 'first', 'staccatissimo': 'last', 'staccato': 'last', 'tenuto': 'both'}, 'beat_hierarchy_spacing': 2.4, 'clef_pitch_centers': {'alto': 60, 'baritone': 53, 'bass': 48, 'mezzo-soprano': 64, 'soprano': 67, 'tenor': 57, 'treble': 71}, 'clef_selection_policy': 'measure-wise', 'clefs_by_instrument': {'bass': ['bass', 'treble'], 'bassoon': [('bass', 59), ('tenor', 66), ('treble', 74)], 'cello': [('bass', 59), ('tenor', 66), ('treble', 74)], 'clarinet': ['treble'], 'default': ['treble', 'bass'], 'flute': ['treble'], 'guitar': ['treble'], 'horn': ['treble'], 'oboe': ['treble'], 'piano': ['treble', 'bass'], 'timpani': ['bass'], 'trombone': ['bass', 'tenor', 'treble'], 'trumpet': ['treble'], 'tuba': ['bass'], 'viola': ['alto', ('treble', 75)], 'violin': ['treble']}, 'default_composers': ['HTMLvis', 'Rustin Beiber', 'Javan Morrison', 'Sia++', 'The Rubytles', "CSStiny's Child", 'Perl Jam', 'PHPrince'], 'default_spelling_policy': SpellingPolicy(((0, 0), (0, 1), (1, 0), (2, -1), (2, 0), (3, 0), (3, 1), (4, 0), (5, -1), (5, 0), (6, -1), (6, 0))), 'default_titles': ['On the Code Again', 'The Long and Winding Code', 'Code To Joy', 'Take Me Home, Country Codes', 'Thunder Code', 'Code to Nowhere', 'Goodbye Yellow Brick Code', 'Hit the Code, Jack'], 'export_note_velocities_to_xml': False, 'glissandi': GlissandiSettings(control_point_policy='split', consider_non_extrema_control_points=True, include_end_grace_note=True, inner_grace_relevance_threshold=1.5, max_inner_graces_music_xml=1, slur_glisses=True), 'ignore_empty_parts': True, 'lilypond_dir': None, 'lilypond_search_paths': {'Darwin': ['/Applications', '~/Applications', '/usr/local/bin', '/opt/homebrew/bin'], 'Windows': ['C:\\Program Files (x86)', 'C:\\Program Files']}, 'max_dots_allowed': 3, 'max_voices_per_part': 4, 'microtonal_annotation_digits': 2, 'notation_split_protocols': {'default': 'first', 'fermata': 'last', 'tremolo': 'all', 'tremolo1': 'all', 'tremolo2': 'all', 'tremolo3': 'all', 'tremolo4': 'all', 'tremolo5': 'all', 'tremolo6': 'all', 'tremolo7': 'all', 'tremolo8': 'all'}, 'num_divisions_penalty': 0.6, 'pad_incomplete_parts': True, 'rest_beat_hierarchy_spacing': 20, 'rest_num_divisions_penalty': 0.2, 'show_microtonal_annotations': False, 'show_music_xml_command_line': 'auto', 'tempo': TempoSettings(guide_mark_resolution=0.125, guide_mark_sensitivity=0.08, include_guide_marks=True, parenthesize_guide_marks=True)}

Default engraving settings (from when SCAMP was installed)

set_music_xml_application(application_name: Optional[str] = None) → None

Sets the application to use when opening generated MusicXML scores

Parameters:

application_name – name of the application to use. If None, defaults to a generic file open command.

get_default_title() → str | None

Grabs one of the default score titles.

get_default_composer() → str | None

Grabs one of the default composer names.

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