scamp.session.Session

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

Bases: Clock, Ensemble, Transcriber, 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.)

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 TempoHistory (as opposed to the TempoHistory relative to parent clock).
`fast_forward`([on_or_off])	Set fast-forwarding of the clock; when fast-forwarding, all waiting is instantaneous.
`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.
`pop_instrument`(index)	Pops the instrument at the given index, severing its ties to the ensemble.
`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.
`instruments`	Returns a tuple of the instruments currently in 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() → Session[source]

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]][source]: Returns a list of available ports and devices for midi input.

static print_available_midi_input_devices() → None[source]: Prints a list of available ports and devices for midi input.

static print_available_midi_output_devices() → None[source]: Prints a list of available ports and devices for midi output.

register_midi_listener(port_number_or_device_name: int | str, callback_function: Callable) → None[source]

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: int | str) → None[source]

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[source]

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[source]

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: Optional[Callable] = None, on_release: Optional[Callable] = None, suppress: bool = False, **kwargs) → None[source]

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[source]: Remove a previously added keyboard listener.

register_mouse_listener(on_move: Optional[Callable] = None, on_press: Optional[Callable] = None, on_release: Optional[Callable] = None, on_scroll: Optional[Callable] = None, suppress: bool = False, relative_coordinates: bool = False, **kwargs) → None[source]

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[source]: Remove a previously added mouse listener

start_transcribing(instrument_or_instruments: Optional[Union[ScampInstrument, Sequence[ScampInstrument]]] = None, clock: Optional[Clock] = None, units: str = 'beats') → Performance[source]

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

property alive: bool

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 = 2.0, scanning_step_size: float = 0.05, key_point_resolution_multiple: int = 2, iterations: int = 6, min_key_point_distance: float = 1e-07) → 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.
scanning_step_size – see Envelope.from_function()
key_point_resolution_multiple – see Envelope.from_function()
iterations – see Envelope.from_function()
min_key_point_distance – see Envelope.from_function()

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 = 2.0, scanning_step_size: float = 0.05, key_point_resolution_multiple: int = 2, iterations: int = 6, min_key_point_distance: float = 1e-07) → 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.
scanning_step_size – see Envelope.from_function()
key_point_resolution_multiple – see Envelope.from_function()
iterations – see Envelope.from_function()
min_key_point_distance – see Envelope.from_function()

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 = 2.0, scanning_step_size: float = 0.05, key_point_resolution_multiple: int = 2, iterations: int = 6, min_key_point_distance: float = 1e-07) → 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.
scanning_step_size – see Envelope.from_function()
key_point_resolution_multiple – see Envelope.from_function()
iterations – see Envelope.from_function()
min_key_point_distance – see Envelope.from_function()

beat() → float: How many beats have passed since this clock was created.

property beat_length: float: 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[Clock]

Get all direct child clocks forked by this clock.

Returns:: tuple of all child clocks of this clock

property default_spelling_policy: SpellingPolicy: Default spelling policy used for transcriptions made with this Ensemble.

descendants() → Sequence[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) → TempoEnvelope

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

Parameters:

start_beat – where on the TempoHistory 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 TempoHistory representing the true variation of tempo on this clock, as filtered through the changing rates of its parents.

fast_forward(on_or_off=True) → None

Set fast-forwarding of the clock; when fast-forwarding, all waiting is instantaneous. (Only available on the master clock.)

Parameters:: on_or_off – if True, start fast-forwarding; if False, stop fast-forwarding.

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: Optional[dict] = None, name: Optional[str] = None, initial_rate: Optional[float] = None, initial_tempo: Optional[float] = None, initial_beat_length: Optional[float] = None, schedule_at: Optional[Union[float, MetricPhaseTarget]] = None, done_callback: Optional[Callable] = None) → 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.
done_callback – a callback function to be invoked when the clock has terminated

Returns:

the clock of the spawned child process

fork_unsynchronized(process_function: Callable, args: Sequence = (), kwargs: Optional[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[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

property instruments: Returns a tuple of the instruments currently in this Ensemble.

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[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[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[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: Clock: The master clock under which this clock operates (possibly itself)

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

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

pop_instrument(index)

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

Parameters:: index – which instrument

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: float: 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: 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[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[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: float | 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[float | 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: float | 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[float | 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: float | 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[float | 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) → 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: str: 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: float: 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: str | float: 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[Performance]: 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.