scamp.session.Session

class scamp.session.Session(tempo: float = 60, default_soundfont: str = 'default', default_audio_driver: str = 'default', default_midi_output_device: Union[str, int] = 'default', default_spelling_policy: Union[scamp.spelling.SpellingPolicy, str, tuple] = None, instruments: Sequence[ScampInstrument] = None, max_threads=200)

Bases: clockblocks.clock.Clock, scamp.instruments.Ensemble, scamp.transcriber.Transcriber, expenvelope.json_serializer.SavesToJSON

A Session combines the functionality of a master Clock, an Ensemble, and a Transcriber. Since it’s a master Clock, it manages global tempo; since it’s an Ensemble, you use it to create and keep track of instruments, and since it’s a Transcriber, it allows you to transcribe and generate notation from what the instruments are playing. You can also use a Session to set up interactive callbacks for MIDI, OSC, mouse events, and keyboard events.

Parameters

• tempo – the initial tempo of the master clock

• default_soundfont – the default soundfont used by instruments in this session. (Can be overridden at instrument creation.)

• default_audio_driver – the default driver used by (soundfont) instruments to output audio. (Can be overridden at instrument creation.)

• default_midi_output_device – the default midi_output_device (by name or port number) for outgoing midi streams. (Again, can be overridden at instrument creation.)

Methods

get_available_midi_input_devices()	Returns a list of available ports and devices for midi input.
print_available_midi_input_devices()	Prints a list of available ports and devices for midi input.
print_available_midi_output_devices()	Prints a list of available ports and devices for midi output.
register_keyboard_listener([on_press, …])	Register a callback_function to respond to incoming keyboard events
register_midi_listener(…)	Register a callback_function to respond to incoming midi events from port_number_or_device_name
register_mouse_listener([on_move, on_press, …])	Register a callback_function to respond to incoming mouse events
register_osc_listener(port, …[, ip_address])	Register a callback function for OSC messages on a given address/port with given pattern
remove_keyboard_listener()	Remove a previously added keyboard listener.
remove_midi_listener(port_number_or_device_name)	Removes the midi listener with the given port_number_or_device_name
remove_mouse_listener()	Remove a previously added mouse listener
remove_osc_listener(port[, ip_address])	Remove OSC listener on the given port and IP address
run_as_server()	Runs this session on a parallel thread so that it can act as a server.
start_transcribing([…])	Starts transcribing everything played in this Session’s (or by the given instruments) to a Performance.

Inherited Methods

absolute_beat_length()	The beat length of this clock in (true) seconds, accounting for the rates of all parent clocks.
absolute_rate()	The rate of this clock in beats / (true) second, accounting for the rates of all parent clocks.
absolute_tempo()	The tempo of this clock in beats / (true) minute, accounting for the rates of all parent clocks.
add_instrument(instrument)	Adds an instance of ScampInstrument to this Ensemble.
apply_beat_length_function(function[, …])	Applies a function to be used to set the beat_length (and therefore rate and tempo) of this clock.
apply_rate_function(function[, …])	Applies a function to be used to set the rate (and therefore beat_length and tempo) of this clock.
apply_tempo_function(function[, …])	Applies a function to be used to set the tempo (and therefore beat_length and rate) of this clock.
beat()	How many beats have passed since this clock was created.
children()	Get all direct child clocks forked by this clock.
descendants()	Get all children, grandchildren, etc.
duplicate()	Returns a copy of this object by serializing to and from JSON.
extract_absolute_tempo_envelope([…])	Extracts this clock’s absolute TempoEnvelope (as opposed to the TempoEnvelope relative to parent clock).
fast_forward_in_beats(b)	Fast forward clock, skipping ahead instantaneously by b beats.
fast_forward_in_time(t)	Fast forward clock, skipping ahead instantaneously by t seconds.
fast_forward_to_beat(b)	Fast forward clock, skipping instantaneously to beat b.
fast_forward_to_time(t)	Fast forward clock, skipping instantaneously to the time of t seconds.
fork(process_function[, args, kwargs, name, …])	Spawns a parallel process running on a child clock.
fork_unsynchronized(process_function[, …])	Spawns a parallel process, but as an asynchronous thread, not on a child clock.
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.
inheritance([include_self])	Get all parent, grandparent, etc.
is_fast_forwarding()	Determine if the clock is fast-forwarding.
is_master()	Check if this is the master clock
is_transcribing()	Checks if any transcriptions are in progress.
iterate_all_relatives([include_self])	Iterate through all related clocks to this clock.
iterate_descendants([include_self])	Iterate through all children, grandchildren, etc.
iterate_inheritance([include_self])	Iterate through parent, grandparent, etc.
json_dumps()	Dump this object as a JSON string.
json_loads(s)	Load this object from a JSON string.
kill()	Ends the process forked on this clock and all child processes.
load_from_json(file_path)	Load this object from a JSON file with the given path.
log_processing_time()	Enables logging statements about calculation time between wait calls.
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.
print_default_soundfont_presets()	Prints a list of presets available with the default soundfont.
print_family_tree()	Print a hierarchical representation of this clock’s family tree.
register_note(instrument, note_info)	Called when an instrument wants to register that it finished a note, records note in all transcriptions
release_from_suspension([releasing_clock])	Called after “rouse_and_hold” to release the roused clock.
rouse_and_hold([holding_clock])	Rouse this clock if it is dormant, but keep it suspended until release_from_suspension is called.
save_to_json(file_path)	Save this object to a JSON file using the given path.
set_beat_length_target(beat_length_target, …)	Set a target beat length for this clock to reach in duration beats/seconds (with the unit defined by duration_units).
set_beat_length_targets(beat_length_targets, …)	Same as set_beat_length_target, except that you can set multiple targets at once by providing lists to each of the arguments.
set_rate_target(rate_target, duration[, …])	Set a target rate for this clock to reach in duration beats/seconds (with the unit defined by duration_units)
set_rate_targets(rate_targets, durations[, …])	Same as set_rate_target, except that you can set multiple targets at once by providing lists to each of the arguments.
set_tempo_target(tempo_target, duration[, …])	Set a target tempo for this clock to reach in duration beats/seconds (with the unit defined by duration_units)
set_tempo_targets(tempo_targets, durations)	Same as set_tempo_target, except that you can set multiple targets at once by providing lists to each of the arguments.
stop_logging_processing_time()	Disables logging statements about calculation time between wait calls.
stop_tempo_loop_or_function()	If we set up a looping list of tempo targets, this stops that looping process.
stop_transcribing([which_performance, …])	Stops transcribing a Performance and returns it.
time()	How much time has passed since this clock was created.
time_in_master()	How much time (in seconds) has passed since the master clock was created.
use_absolute_timing_policy()	This timing policy only cares about keeping the time since the clock start accurate to what it should be.
use_mixed_timing_policy(absolute_relative_mix)	Balance considerations of relative timing and absolute timing accuracy according to the given coefficient
use_relative_timing_policy()	This timing policy only cares about making each individual wait call as accurate as possible.
wait(dt[, units, sub_call])	Causes the current thread to block for dt beats (or seconds if units=”time”) in this clock.
wait_for_children_to_finish()	Causes this thread to block until all forked child processes have finished.
wait_forever()	Causes this thread to block forever.

Attributes

alive	Whether or not this clock is still running
beat_length	The length of a beat in this clock in seconds.
default_spelling_policy	Default spelling policy used for transcriptions made with this Ensemble.
master	The master clock under which this clock operates (possibly itself)
rate	The rate of this clock in beats / second.
synchronization_policy	Determines whether or not this clock actively updates the beat and time of related clocks when it wakes up.
tempo	The rate of this clock in beats / minute Note that beat_length, tempo and rate are interconnected properties, and that by setting one of them the other two are automatically set in response according to the relationship: beat_length = 1/rate = 60/tempo.
timing_policy	Determines how this clock should respond to getting behind.
transcriptions_in_progress	Tuple of all current transcriptions.

run_as_server() → scamp.session.Session

Runs this session on a parallel thread so that it can act as a server. This is the approach that should be taken if running scamp from an interactive terminal session. Simply type s = Session().run_as_server()

Returns

self

static get_available_midi_input_devices() → Iterator[Tuple[int, str]]

Returns a list of available ports and devices for midi input.

static print_available_midi_input_devices() → None

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

static print_available_midi_output_devices() → None

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

register_midi_listener(port_number_or_device_name: Union[int, str], callback_function: Callable) → None

Register a callback_function to respond to incoming midi events from port_number_or_device_name

Parameters

• port_number_or_device_name – either the port number to be used, or an device name for which the port number will be determined. (Fuzzy string matching is used to pick the device with closest name.)

• callback_function – the callback function used when a new midi event arrives. Should take either one argument (the midi message) or two arguments (the midi message, and the dt since the last message)

remove_midi_listener(port_number_or_device_name: Union[int, str]) → None

Removes the midi listener with the given port_number_or_device_name

Parameters

port_number_or_device_name – either the port number to be used, or an device name for which the port number will be determined. (Fuzzy string matching is used to pick the device with closest name.)

register_osc_listener(port: int, osc_address_pattern: str, callback_function: Callable, ip_address: str = '127.0.0.1') → None

Register a callback function for OSC messages on a given address/port with given pattern

Parameters

• port – port on which to receive messages

• osc_address_pattern – address pattern to respond to (e.g. “/gesture/start”)

• callback_function – function to call upon receiving a message. The first argument of the function will be the address, and the remaining arguments will be those passed along in the osc message.

• ip_address – ip address on which to receive messages

remove_osc_listener(port: int, ip_address: str = '127.0.0.1') → None

Remove OSC listener on the given port and IP address

Parameters

• port – port of the listener to remove

• ip_address – ip_address of the listener to remove

register_keyboard_listener(on_press: Callable = None, on_release: Callable = None, suppress: bool = False, **kwargs) → None

Register a callback_function to respond to incoming keyboard events

Parameters

• on_press – function taking two arguments: key name (string) and key number (int) called on key down

• on_release – function taking two arguments: key name (string) and key number (int) called on key up

• suppress – if true, keyboard events are consumed and not passed on to other processes

remove_keyboard_listener() → None

Remove a previously added keyboard listener.

register_mouse_listener(on_move: Callable = None, on_press: Callable = None, on_release: Callable = None, on_scroll: Callable = None, suppress: bool = False, relative_coordinates: bool = False, **kwargs) → None

Register a callback_function to respond to incoming mouse events

Parameters

• on_move – callback function taking two arguments (x, y) called when the mouse is moved

• on_press – callback function taking three arguments: (x, y, button), where button is one of “left”, “right”, or “middle”

• on_release – callback function taking three arguments: (x, y, button), where button is one of “left”, “right”, or “middle”

• on_scroll – callback function taking four arguments: (x, y, dx, dy)

• relative_coordinates – if True (requires tkinter library), x and y values are normalized to screen width and height and are floating point. Otherwise they are ints in units of pixels.

• suppress – if true, mouse events are consumed and not passed on to other processes

remove_mouse_listener() → None

Remove a previously added mouse listener

start_transcribing(instrument_or_instruments: Union[scamp.instruments.ScampInstrument, Sequence[scamp.instruments.ScampInstrument]] = None, clock: clockblocks.clock.Clock = None, units: str = 'beats') → scamp.performance.Performance

Starts transcribing everything played in this Session’s (or by the given instruments) to a Performance. Defaults to using this Session as the clock.

Parameters

• instrument_or_instruments – which instruments to transcribe. Defaults to all session instruments

• clock – which clock to record on, i.e. what are all the timings notated relative to

• units – one of [“beats”, “time”]. Do we use the beats of the clock or the time?

Returns

the Performance we will be transcribing to

absolute_beat_length() → float

The beat length of this clock in (true) seconds, accounting for the rates of all parent clocks. (As opposed to beat_length, which just gives the length in parent beats.)

absolute_rate() → float

The rate of this clock in beats / (true) second, accounting for the rates of all parent clocks. (As opposed to rate, which just gives the rate relative to the parent clock.)

absolute_tempo() → float

The tempo of this clock in beats / (true) minute, accounting for the rates of all parent clocks. (As opposed to tempo, which just gives the tempo relative to the parent clock.)

add_instrument(instrument: scamp.instruments.ScampInstrument) → scamp.instruments.ScampInstrument

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

property alive

Whether or not this clock is still running

Returns

True if running, False if it was killed or its process ended.

apply_beat_length_function(function: Callable, domain_start: float = 0, domain_end: float = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False, extension_increment: float = 1.0, resolution_multiple: int = 2) → None

Applies a function to be used to set the beat_length (and therefore rate and tempo) of this clock.

Parameters

• function – a function (usually a lambda function) taking a single argument representing the beat or the time (depending on the ‘duration_units’ argument) and outputting the beat_length. Note that the beat or time argument is measured in relation to the moment that apply_beat_length_function was called, not from the start of the clock.

• domain_start – along with domain_end, allows us to specify a specific portion of the function to be used

• domain_end – along with domain_start, allows us to specify a specific portion of the function to be used. If None, the tempo continues to be defined according to the function formula.

• duration_units – either “beats” or “time”, depending on what the function argument refers to

• truncate – whether or not to remove all future plans before applying this function

• loop – If a finite portion of the function’s domain is being used, this argument will loop that portion of the domain when we come to the end of it.

• extension_increment – if domain_end is None, then this defines how far in advance we extend the function at any given time.

• resolution_multiple – determines how precisely the function is to be approximated

apply_rate_function(function: Callable, domain_start: float = 0, domain_end: float = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False, extension_increment: float = 1.0, resolution_multiple: int = 2) → None

Applies a function to be used to set the rate (and therefore beat_length and tempo) of this clock.

Parameters

• function – a function (usually a lambda function) taking a single argument representing the beat or the time (depending on the ‘duration_units’ argument) and outputting the rate. Note that the beat or time argument is measured in relation to the moment that apply_beat_length_function was called, not from the start of the clock.

• domain_start – along with domain_end, allows us to specify a specific portion of the function to be used

• domain_end – along with domain_start, allows us to specify a specific portion of the function to be used. If None, the tempo continues to be defined according to the function formula.

• duration_units – either “beats” or “time”, depending on what the function argument refers to

• truncate – whether or not to remove all future plans before applying this function

• loop – If a finite portion of the function’s domain is being used, this argument will loop that portion of the domain when we come to the end of it.

• extension_increment – if domain_end is None, then this defines how far in advance we extend the function at any given time.

• resolution_multiple – determines how precisely the function is to be approximated

apply_tempo_function(function: Callable, domain_start: float = 0, domain_end: float = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False, extension_increment: float = 1.0, resolution_multiple: int = 2) → None

Applies a function to be used to set the tempo (and therefore beat_length and rate) of this clock.

Parameters

• function – a function (usually a lambda function) taking a single argument representing the beat or the time (depending on the ‘duration_units’ argument) and outputting the tempo in BPM. Note that the beat or time argument is measured in relation to the moment that apply_beat_length_function was called, not from the start of the clock.

• domain_start – along with domain_end, allows us to specify a specific portion of the function to be used

• domain_end – along with domain_start, allows us to specify a specific portion of the function to be used. If None, the tempo continues to be defined according to the function formula.

• duration_units – either “beats” or “time”, depending on what the function argument refers to

• truncate – whether or not to remove all future plans before applying this function

• loop – If a finite portion of the function’s domain is being used, this argument will loop that portion of the domain when we come to the end of it.

• extension_increment – if domain_end is None, then this defines how far in advance we extend the function at any given time.

• resolution_multiple – determines how precisely the function is to be approximated

beat() → float

How many beats have passed since this clock was created.

property beat_length

The length of a beat in this clock in seconds. Note that beat_length, tempo and rate are interconnected properties, and that by setting one of them the other two are automatically set in response according to the relationship: beat_length = 1/rate = 60/tempo. Also, note that “seconds” refers to actual seconds only in the master clock; otherwise it refers to beats in the parent clock.

children() → Sequence[clockblocks.clock.Clock]

Get all direct child clocks forked by this clock.

Returns

tuple of all child clocks of this clock

property default_spelling_policy

Default spelling policy used for transcriptions made with this Ensemble.

descendants() → Sequence[clockblocks.clock.Clock]

Get all children, grandchildren, etc. of this clock

Returns

tuple of all descendants

duplicate() → T

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

extract_absolute_tempo_envelope(start_beat: float = 0, step_size: float = 0.1, tolerance: float = 0.005) → clockblocks.tempo_envelope.TempoEnvelope

Extracts this clock’s absolute TempoEnvelope (as opposed to the TempoEnvelope relative to parent clock). Used when creating a score from this clock’s point of view.

Parameters

• start_beat – where on the TempoEnvelope to start

• step_size – granularity

• tolerance – error tolerance with which we allow a step to simply extend the previous segment rather than create a new one.

Returns

A TempoEnvelope representing the true variation of tempo on this clock, as filtered through the changing rates of its parents.

fast_forward_in_beats(b: float) → None

Fast forward clock, skipping ahead instantaneously by b beats. (Only available on the master clock.)

Parameters

b – number of beats to fast forward by

fast_forward_in_time(t: float) → None

Fast forward clock, skipping ahead instantaneously by t seconds. (Only available on the master clock.)

Parameters

t – number of seconds to fast forward by

fast_forward_to_beat(b: float) → None

Fast forward clock, skipping instantaneously to beat b. (Only available on the master clock.)

Parameters

b – beat to fast forward to

fast_forward_to_time(t: float) → None

Fast forward clock, skipping instantaneously to the time of t seconds. (Only available on the master clock.)

Parameters

t – time to fast forward to

fork(process_function: Callable, args: Sequence = (), kwargs: dict = None, name: str = None, initial_rate: float = None, initial_tempo: float = None, initial_beat_length: float = None, schedule_at: Union[float, clockblocks.tempo_envelope.MetricPhaseTarget] = None) → clockblocks.clock.Clock

Spawns a parallel process running on a child clock.

Parameters

• process_function – function defining the process to be spawned

• args – arguments to be passed to the process function. One subtlety to note here: if the number of arguments passed is one fewer than the number taken by the function, the clock on which the process is forked will be passed as the first argument, followed by the arguments given. For instance, if we define “forked_function(clock, a, b)”, and then call “parent.fork(forked_function, (13, 6))”, 13 will be passed to “a” and 6 to “b”, while the clock on which forked_function is running will be passed to “clock”. On the other hand, if the signature of the function were “forked_function(a, b)”, 13 would be simply be passed to “a” and 6 to “b”.

• kwargs – keyword arguments to be passed to the process function

• name – name to be given to the clock of the spawned child process

• initial_rate – starting rate of this clock (if set, don’t set initial tempo or beat length)

• initial_tempo – starting tempo of this clock (if set, don’t set initial rate or beat length)

• initial_beat_length – starting beat length of this clock (if set, don’t set initial tempo or rate)

• schedule_at – either a beat or a MetricPhaseTarget specifying when we want this forked process to begin. The default value of None indicates that it is to begin immediately. A float indicates the beat in this clock at which the process is to start (should be in the future). Alternatively, a MetricPhaseTarget can be used to specify where in a regular cycle the process should begin. For instance, if we want to sync every fork to 3/4 time, MetricPhaseTarget(0, 3) would start a process on the downbeat, MetricPhaseTarget(1, 3) would start it on beat 2, and MetricPhaseTarget(2.5, 3) would start it halfway through beat 3.

Returns

the clock of the spawned child process

fork_unsynchronized(process_function: Callable, args: Sequence = (), kwargs: dict = None) → None

Spawns a parallel process, but as an asynchronous thread, not on a child clock. (Still makes use of this clock’s ThreadPool, so it’s quicker to spawn than creating a new Thread)

Parameters

• process_function – the process to be spawned

• args – arguments for that function

• kwargs – keyword arguments for that function

static get_available_midi_output_devices() → enumerate

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

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)

inheritance(include_self: bool = True) → Sequence[clockblocks.clock.Clock]

Get all parent, grandparent, etc. of this clock up until the master clock

Parameters

include_self – whether or not to include this clock in the iterator or start with the parent

Returns

tuple containing the clock’s inheritance

is_fast_forwarding() → bool

Determine if the clock is fast-forwarding.

Returns

boolean representing whether the clock is fast-forwarding

is_master() → bool

Check if this is the master clock

Returns

True if this is the master clock, False otherwise

is_transcribing() → bool

Checks if any transcriptions are in progress.

iterate_all_relatives(include_self: bool = False) → Iterator[clockblocks.clock.Clock]

Iterate through all related clocks to this clock.

Parameters

include_self – whether or not to include this clock in the iterator

Returns

iterator going through all clocks in the family tree, starting with the master

iterate_descendants(include_self: bool = False) → Iterator[clockblocks.clock.Clock]

Iterate through all children, grandchildren, etc. of this clock

Parameters

include_self – whether or not to include this clock in the iterator

Returns

iterator going through all descendants

iterate_inheritance(include_self: bool = True) → Iterator[clockblocks.clock.Clock]

Iterate through parent, grandparent, etc. of this clock up until the master clock

Parameters

include_self – whether or not to include this clock in the iterator or start with the parent

Returns

iterator going up the clock family tree up to the master clock

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

kill() → None

Ends the process forked on this clock and all child processes. If this is the master clock, since it wasn’t forked, this simply kills all child processes.

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

log_processing_time() → None

Enables logging statements about calculation time between wait calls.

property master

The master clock under which this clock operates (possibly itself)

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

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: 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

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

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

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_silent_part(name: str = None, default_spelling_policy: scamp.spelling.SpellingPolicy = None, clef_preference='from_name') → scamp.instruments.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

print_default_soundfont_presets() → None

Prints a list of presets available with the default soundfont.

print_family_tree() → None

Print a hierarchical representation of this clock’s family tree.

property rate

The rate of this clock in beats / second. Note that beat_length, tempo and rate are interconnected properties, and that by setting one of them the other two are automatically set in response according to the relationship: beat_length = 1/rate = 60/tempo. Also, note that “seconds” refers to actual seconds only in the master clock; otherwise it refers to beats in the parent clock.

register_note(instrument: scamp.instruments.ScampInstrument, note_info: dict) → None

Called when an instrument wants to register that it finished a note, records note in all transcriptions

Parameters

• instrument – the ScampInstrument that played the note

• note_info – the note info dictionary on that note, containing time stamps, parameter changes, etc.

release_from_suspension(releasing_clock: Optional[clockblocks.clock.Clock] = None) → None

Called after “rouse_and_hold” to release the roused clock.

Parameters

releasing_clock – the clock providing the initial impetus to release from suspension. Just like rouse_and_hold, a release propagates up the family tree, but we need to keep track of the initial clock from which it propagates. (Again, this is an implementation detail.

rouse_and_hold(holding_clock: Optional[clockblocks.clock.Clock] = None) → None

Rouse this clock if it is dormant, but keep it suspended until release_from_suspension is called. Generally this would not be called by the user, but it is useful for callback functions operating outside of the clock system, since they can wake up the clock of interest, carry out what they need to carry out and then release the clock from suspension.

Parameters

holding_clock – when rouse_and_hold is called on a child clock, all parents/grandparents/etc. must also be roused and held. However, we need to keep track of the child clock that started the whole process. That’s what this argument is for. (It’s an implementation detail).

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

set_beat_length_target(beat_length_target: float, duration: float, curve_shape: float = 0, metric_phase_target: Union[float, clockblocks.tempo_envelope.MetricPhaseTarget, Tuple] = None, duration_units: str = 'beats', truncate: bool = True) → None

Set a target beat length for this clock to reach in duration beats/seconds (with the unit defined by duration_units).

Parameters

• beat_length_target – The beat length we want to reach

• duration – How long until we reach that beat length

• curve_shape – > 0 makes change happen later, < 0 makes change happen sooner

• metric_phase_target – This argument lets us align the arrival at the given beat length with a particular part of the parent beat (time), or, if we specified “time” as our duration units, it allows us to align the arrival at that specified time with a particular part of this clock’s beat. This argument takes either a float in [0, 1), a MetricPhaseTarget object, or a tuple of arguments to the MetricPhaseTarget constructor

• duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.

• truncate – Whether or not to delete all future tempo plans before setting this goal.

set_beat_length_targets(beat_length_targets: Sequence[float], durations: Sequence[float], curve_shapes: Sequence[float] = None, metric_phase_targets: Sequence[Union[float, clockblocks.tempo_envelope.MetricPhaseTarget, Tuple]] = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False) → None

Same as set_beat_length_target, except that you can set multiple targets at once by providing lists to each of the arguments.

Parameters

• beat_length_targets – list of the target beat_lengths

• durations – list of segment durations (in beats or seconds, as defined by duration_units)

• curve_shapes – list of segment curve_shapes (or none to not set curve shape)

• metric_phase_targets – list of metric phase targets for each segment (or None to ignore metric phase)

• duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.

• truncate – Whether or not to delete all future tempo plans before setting these targets.

• loop – If true, loops the added sequence of targets indefinitely, or until stop_tempo_loop_or_function is called.

set_rate_target(rate_target: float, duration: float, curve_shape: float = 0, metric_phase_target: Union[float, clockblocks.tempo_envelope.MetricPhaseTarget, Tuple] = None, duration_units: str = 'beats', truncate: bool = True) → None

Set a target rate for this clock to reach in duration beats/seconds (with the unit defined by duration_units)

Parameters

• rate_target – The rate we want to reach

• duration – How long until we reach that tempo

• curve_shape – > 0 makes change happen later, < 0 makes change happen sooner

• metric_phase_target – This argument allows us to align the arrival at the given rate with a particular part of the parent beat (time), or, if we specified “time” as our duration units, it allows us to align the arrival at that specified time with a particular part of this clock’s beat. This argument takes either a float in [0, 1), a MetricPhaseTarget object, or a tuple of arguments to the MetricPhaseTarget constructor

• duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.

• truncate – Whether or not to delete all future tempo plans before setting this goal.

set_rate_targets(rate_targets: Sequence[float], durations: Sequence[float], curve_shapes: Sequence[float] = None, metric_phase_targets: Sequence[Union[float, clockblocks.tempo_envelope.MetricPhaseTarget, Tuple]] = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False) → None

Same as set_rate_target, except that you can set multiple targets at once by providing lists to each of the arguments.

Parameters

• rate_targets – list of the target rates

• durations – list of segment durations (in beats or seconds, as defined by duration_units)

• curve_shapes – list of segment curve_shapes (or none to not set curve shape)

• metric_phase_targets – list of metric phase targets for each segment (or None to ignore metric phase)

• duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.

• truncate – Whether or not to delete all future tempo plans before setting these targets.

• loop – If true, loops the added sequence of targets indefinitely, or until stop_tempo_loop_or_function is called.

set_tempo_target(tempo_target: float, duration: float, curve_shape: float = 0, metric_phase_target: Union[float, clockblocks.tempo_envelope.MetricPhaseTarget, Tuple] = None, duration_units: str = 'beats', truncate: bool = True) → None

Set a target tempo for this clock to reach in duration beats/seconds (with the unit defined by duration_units)

Parameters

• tempo_target – The tempo we want to reach

• duration – How long until we reach that tempo

• curve_shape – > 0 makes change happen later, < 0 makes change happen sooner

• metric_phase_target – This argument allows us to align the arrival at the given tempo with a particular part of the parent beat (time), or, if we specified “time” as our duration units, it allows us to align the arrival at that specified time with a particular part of this clock’s beat. This argument takes either a float in [0, 1), a MetricPhaseTarget object, or a tuple of arguments to the MetricPhaseTarget constructor

• duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.

• truncate – Whether or not to delete all future tempo plans before setting this goal.

set_tempo_targets(tempo_targets: Sequence[float], durations: Sequence[float], curve_shapes: Sequence[float] = None, metric_phase_targets: Sequence[Union[float, clockblocks.tempo_envelope.MetricPhaseTarget, Tuple]] = None, duration_units: str = 'beats', truncate: bool = True, loop: bool = False) → None

Same as set_tempo_target, except that you can set multiple targets at once by providing lists to each of the arguments.

Parameters

• tempo_targets – list of the target tempos

• durations – list of segment durations (in beats or seconds, as defined by duration_units)

• curve_shapes – list of segment curve_shapes (or none to not set curve shape)

• metric_phase_targets – list of metric phase targets for each segment (or None to ignore metric phase)

• duration_units – one of (“beats”, “time”); defines whether the duration is in beats or in seconds/parent beats.

• truncate – Whether or not to delete all future tempo plans before setting these targets.

• loop – If true, loops the added sequence of targets indefinitely, or until stop_tempo_loop_or_function is called.

stop_logging_processing_time() → None

Disables logging statements about calculation time between wait calls.

stop_tempo_loop_or_function() → None

If we set up a looping list of tempo targets, this stops that looping process. It also stops extending any tempo function that we set up to go indefinitely.

stop_transcribing(which_performance=None, tempo_envelope_tolerance=0.001) → scamp.performance.Performance

Stops transcribing a Performance and returns it. Defaults to the oldest started performance, unless otherwise specified.

Parameters

• which_performance – which performance to stop transcribing; defaults to oldest started

• tempo_envelope_tolerance – error tolerance when extracting the absolute tempo envelope for the Performance

Returns

the created Performance

property synchronization_policy

Determines whether or not this clock actively updates the beat and time of related clocks when it wakes up. Allowable values are “all relatives”, “all descendants”, “no synchronization”, and “inherit”. If “inherit” then it will adopt the setting of its parent clock. The default is to keep all clocks up-to-date. Turning off synchronization can save calculation time, but it can lead to clocks giving old information about what beat or time it is when asked from a different clock’s process.

property tempo

The rate of this clock in beats / minute Note that beat_length, tempo and rate are interconnected properties, and that by setting one of them the other two are automatically set in response according to the relationship: beat_length = 1/rate = 60/tempo. Also, note that “seconds” refers to actual seconds only in the master clock; otherwise it refers to beats in the parent clock.

time() → float

How much time has passed since this clock was created. Either in seconds, if this is the master clock, or in beats in the parent clock, if this clock was the result of a call to fork.

time_in_master() → float

How much time (in seconds) has passed since the master clock was created.

property timing_policy

Determines how this clock should respond to getting behind. Allowable values are “absolute”, “relative” or a float between 0 and 1 representing a balance between absolute and relative.

property transcriptions_in_progress

Tuple of all current transcriptions.

use_absolute_timing_policy() → None

This timing policy only cares about keeping the time since the clock start accurate to what it should be. The downside is that relative timings get distorted when it falls behind.

use_mixed_timing_policy(absolute_relative_mix: float) → None

Balance considerations of relative timing and absolute timing accuracy according to the given coefficient

Parameters

absolute_relative_mix – a float representing the minimum proportion of the ideal wait time we are willing to wait in order to catch up to the correct absolute time since the clock started.

use_relative_timing_policy() → None

This timing policy only cares about making each individual wait call as accurate as possible. The downside is that long periods of calculation cause the clock to drift and get behind.

wait(dt: float, units: str = 'beats', sub_call: bool = False) → float

Causes the current thread to block for dt beats (or seconds if units=”time”) in this clock.

Parameters

• dt – the number of beats in this clock

• units – either “beats” or “time”. If time, then it ignores the rate of this clock, and waits in seconds (or in parent clock beats, if this is a sub-clock)

• sub_call – flag that wouldn’t matter to the user, but indicates whether this wait call was called from within another wait call.

Returns

0 if this wait call is uninterrupted, otherwise the amount of beats that remained when interrupted

wait_for_children_to_finish() → None

Causes this thread to block until all forked child processes have finished.

wait_forever() → None

Causes this thread to block forever. Generally called from a parent clock when actions are being carried out on child clocks, or as a result of callback functions.