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)[source]¶ 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
Returns a list of available ports and devices for midi input.
Prints a list of available ports and devices for midi input.
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 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 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 a previously added mouse listener
remove_osc_listener
(port[, ip_address])Remove OSC listener on the given port and IP address
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
The beat length of this clock in (true) seconds, accounting for the rates of all parent clocks.
The rate of this clock in beats / (true) second, accounting for the rates of all parent clocks.
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.
Get all children, grandchildren, etc.
Returns a copy of this object by serializing to and from JSON.
Extracts this clock’s absolute TempoEnvelope (as opposed to the TempoEnvelope relative to parent clock).
Fast forward clock, skipping ahead instantaneously by b beats.
Fast forward clock, skipping ahead instantaneously by t seconds.
Fast forward clock, skipping instantaneously to beat b.
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.
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.
Determine if the clock is fast-forwarding.
Check if this is the master clock
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.
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.
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.
Prints a list of presets available with the default soundfont.
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.
Disables logging statements about calculation time between wait calls.
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.
How much time (in seconds) has passed since the master clock was created.
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
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.
Causes this thread to block until all forked child processes have finished.
Causes this thread to block forever.
Attributes
Whether or not this clock is still running
The length of a beat in this clock in seconds.
Default spelling policy used for transcriptions made with this Ensemble.
The master clock under which this clock operates (possibly itself)
The rate of this clock in beats / second.
Determines whether or not this clock actively updates the beat and time of related clocks when it wakes up.
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.
Determines how this clock should respond to getting behind.
-
run_as_server
() → scamp.session.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: Union[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: Union[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: Callable = None, on_release: 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
-
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[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
-
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[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: 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
-
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 ofplay_note
in music that doesn’t do any dynamic pitch/volume/parameter changes. Without this flag, notes will all be placed on separate MIDI channels, since they could potentially change pitch or volume; with this flags, we know they won’t, so they can share the same MIDI channels, only using an extra one due to microtonality.default_spelling_policy – the
default_spelling_policy
for the new partclef_preference – the
clef_preference
for the new partstart_channel – the first channel to use. For instance, if start_channel is 4, and num_channels is 5, we will use channels (4, 5, 6, 7, 8). NOTE: channel counting in SCAMP starts from 0, so this may show up as channels 5-9 in your MIDI software.
- Returns
the newly created ScampInstrument
-
new_osc_part
(name: str = None, port: int = None, ip_address: str = '127.0.0.1', message_prefix: str = None, osc_message_addresses: dict = 'default', default_spelling_policy: scamp.spelling.SpellingPolicy = None, clef_preference='from_name') → scamp.instruments.ScampInstrument¶ Creates and returns a new ScampInstrument for this Ensemble that uses a OSCPlaybackImplementation. This means that when notes are played by this instrument, osc messages are sent out to the specified address
- Parameters
name – name used for this instrument in score, etc. for a preset of the appropriate name.
port – port osc messages are sent to
ip_address – ip_address osc messages are sent to
message_prefix – prefix used for this instrument in osc messages
osc_message_addresses – dictionary defining the address used for each type of playback message. defaults to using “start_note”, “end_note”, “change_pitch”, “change_volume”, “change_parameter”. The default can be changed in playback settings.
default_spelling_policy – the
default_spelling_policy
for the new partclef_preference – the
clef_preference
for the new part
- Returns
the newly created ScampInstrument
-
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 ofplay_note
in music that doesn’t do any dynamic pitch/volume/parameter changes. Without this flag, notes will all be placed on separate MIDI channels, since they could potentially change pitch or volume; with this flags, we know they won’t, so they can share the same MIDI channels, only using an extra one due to microtonality.default_spelling_policy – the
default_spelling_policy
for the new partclef_preference – the
clef_preference
for the new part
- Returns
the newly created ScampInstrument
-
new_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 partclef_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.
-
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.