ipytone.Signal#

class ipytone.Signal(**kwargs: Any)#

Bases: SignalOperator, ParamScheduleMixin, ScheduleObserveMixin

A node that defines a value that can be modulated or calculated at the audio sample-level accuracy.

Signal objects support basic arithmetic operators such as +, -, *, **, abs, neg as well as the > comparison operator.

Like any other node, a signal can be connected to/from other nodes. When a signal receives an incoming signal, its value is ignored (reset to 0) and the incoming signal passes through the node (overridden=True).

Parameters:

  • value (integer or float or str, optional) – Initial value of the signal (default: 0)

  • units (str) – Signal value units, e.g., ‘time’, ‘number’, ‘frequency’, ‘bpm’, etc.

  • min_value (integer or float, optional) – Signal value lower limit (default: no limit).

  • max_value (integer or float, optional) – Signal value upper limit (default: no limit).

  • **kwargs – Arguments passed to AudioNode

__init__(value=0, units='number', min_value=None, max_value=None, **kwargs)#

Public constructor

Methods

cancel_and_hold_at_time(time)

Like Param.cancel_scheduled_values() but also holds the automated value at time until the next automated event.

cancel_scheduled_values(time)

Cancels all scheduled parameter changes with times greater than or equal to a given time.

chain(*nodes)

Connect the output of this audio node to the other audio nodes in series.

connect(destination[, output_number, ...])

Connect the output of this audio node to the input of another node.

disconnect(destination[, output_number, ...])

Disconnect the ouput of this audio node from a connected node.

dispose()

Dispose and disconnect this audio node (as well as its input/output).

exp_approach_value_at_time(value, time, ...)

Start exponentially approaching the target value at the given time.

exp_ramp_to(value, ramp_time[, start_time])

Schedules an exponential continuous change from the current time and current value to the given value over the duration of ramp_time.

exp_ramp_to_value_at_time(value, time)

Schedules an exponential continuous change from the previous scheduled parameter value to the given value at the given time.

fan(*destinations)

Connect the output of this audio node to the destinations audio nodes in parallel.

linear_ramp_to(value, ramp_time[, start_time])

Schedules a linear continuous change from the current time and current value to the given value over the duration of ramp_time.

linear_ramp_to_value_at_time(value, time)

Schedules a linear continuous change from the previous scheduled parameter value to the given value at the given time.

ramp_to(value, ramp_time[, start_time])

Ramps to the given value over the duration of the ramp_time.

schedule_dlink(target[, update_interval, ...])

Link a source attribute of this ipytone widget with a target widget attribute.

schedule_jsdlink(target[, update_interval, ...])

Link a source attribute of this ipytone widget with a target widget attribute.

schedule_observe(handler[, update_interval, ...])

Setup a handler to be called at regular intervals with the updated time / value of this ipytone widget.

schedule_unobserve(handler)

Cancel the scheduled updates of the time / value trait associated with the given handler.

set_ramp_point(time)

Creates a schedule point with the value computed at the given time.

set_target_at_time(value, start_time, time_const)

Start exponentially approaching the target value at the given time.

set_value_at_time(value, time)

Schedules a parameter value change at the given time.

set_value_curve_at_time(values, start_time, ...)

Sets an array of arbitrary parameter values starting at the given time for the given duration.

target_ramp_to(value, ramp_time[, start_time])

Start exponentially approaching the target value at the given time.

to_destination()

Convenience method to directly connect the output of this audio node to the main output (speakers) node.

Attributes

channel_count

An int trait.

channel_count_mode

An enum whose value must be in a given sequence.

channel_interpretation

An enum whose value must be in a given sequence.

disposed

Returns True if the node was disposed (i.e., disconnected and web audio node freed for garbage collection).

input

Returns the input node, or None if this node is a source.

log

A trait whose value must be an instance of a specified class.

max_value

Signal value upper limit.

min_value

Signal value lower limit.

name

A trait for unicode strings.

number_of_inputs

Returns the number of input slots for the input node (0 for source nodes).

number_of_outputs

Returns the number of output slots for the output node (0 for sink nodes).

output

Returns the output node, or None if this node is a sink.

overridden

If True, the signal value is overridden by an incoming signal.

units

Signal value units.

value

Signal value
cancel_and_hold_at_time(time)#

Like Param.cancel_scheduled_values() but also holds the automated value at time until the next automated event.

cancel_scheduled_values(time)#

Cancels all scheduled parameter changes with times greater than or equal to a given time.

chain(*nodes)#

Connect the output of this audio node to the other audio nodes in series.

connect(destination, output_number=0, input_number=0)#

Connect the output of this audio node to the input of another node.

Parameters:

  • destination (AudioNode or NativeAudioNode or Param or NativeAudioParam) – The destination node.

  • output_number (int) – The channel number of the output of this node (default: 0).

  • input_number (int) – The channel number of the input of the destination node (default: 0).

disconnect(destination, output_number=0, input_number=0)#

Disconnect the ouput of this audio node from a connected node.

Parameters:

  • destination (AudioNode or NativeAudioNode or Param or NativeAudioParam) – The connected destination node.

  • output_number (int) – The channel number of the output of this node (default: 0).

  • input_number (int) – The channel number of the input of the destination node (default: 0).

dispose()#

Dispose and disconnect this audio node (as well as its input/output).

property disposed#

Returns True if the node was disposed (i.e., disconnected and web audio node freed for garbage collection).

exp_approach_value_at_time(value, time, ramp_time)#

Start exponentially approaching the target value at the given time.

Since it is an exponential approach it will continue approaching after the ramp duration. ramp_time is the time that it takes to reach over 99% of the way towards the value.

exp_ramp_to(value, ramp_time, start_time=None)#

Schedules an exponential continuous change from the current time and current value to the given value over the duration of ramp_time.

exp_ramp_to_value_at_time(value, time)#

Schedules an exponential continuous change from the previous scheduled parameter value to the given value at the given time.

fan(*destinations)#

Connect the output of this audio node to the destinations audio nodes in parallel.

property input#

Returns the input node, or None if this node is a source.

linear_ramp_to(value, ramp_time, start_time=None)#

Schedules a linear continuous change from the current time and current value to the given value over the duration of ramp_time.

linear_ramp_to_value_at_time(value, time)#

Schedules a linear continuous change from the previous scheduled parameter value to the given value at the given time.

property max_value#

Signal value upper limit.

property min_value#

Signal value lower limit.

property number_of_inputs#

Returns the number of input slots for the input node (0 for source nodes).

property number_of_outputs#

Returns the number of output slots for the output node (0 for sink nodes).

property output#

Returns the output node, or None if this node is a sink.

property overridden#

If True, the signal value is overridden by an incoming signal.

ramp_to(value, ramp_time, start_time=None)#

Ramps to the given value over the duration of the ramp_time.

Automatically selects the best ramp type (exponential or linear) depending on the units of the signal

Link a source attribute of this ipytone widget with a target widget attribute.

As the source attribute may have a continuously updated value (e.g., the gain of an audio signal, the current value of a parameter, etc.), The target widget attribute is synchronized at a given, finite resolution.

Parameters:

  • target ((object, str) tuple) – The target widget attribute to link, given as a (widget, attr_name) tuple.

  • update_interval (float or string, optional) – The interval at which the target attribute is updated in the front-end, in seconds (default: 0.04). If transport=True, any interval accepted by schedule_repeat() is also valid here.

  • transport (bool, optional) – if True, the target attribute is synced along the ipytone.Transport timeline, i.e., no update happens until the transport starts and updates stop when the transport stops. If False (default), the target attribute update is done with respect to the active audio context.

  • name (str, optional) – The name of the (source) Tone.js attribute to link. See schedule_observe for more details and for a list of available names.

Returns:

link – A link object that can be used to unlink the widget attributes (using the .unlink() method).

Return type:

ToneDirectionalLink

Link a source attribute of this ipytone widget with a target widget attribute.

The link is created in the front-end and does not rely on a roundtrip to the backend.

As the source attribute may have a continuously updated value (e.g., the gain of an audio signal, the current value of a parameter, etc.), The target widget attribute is synchronized at a given, finite resolution.

Parameters:

  • target ((object, str) tuple) – The target widget attribute to link, given as a (widget, attr_name) tuple.

  • update_interval (float or string, optional) – The interval at which the target attribute is updated in the front-end, in seconds (default: 0.04). If transport=True, any interval accepted by schedule_repeat() is also valid here.

  • transport (bool, optional) – if True, the target attribute is synced along the ipytone.Transport timeline, i.e., no update happens until the transport starts and updates stop when the transport stops. If False (default), the target attribute update is done with respect to the active audio context.

  • name (str, optional) – The name of the (source) Tone.js attribute to link. See schedule_observe for more details and for a list of available names.

Returns:

link – A link object that can be used to unlink the widget attributes (using the .unlink() method).

Return type:

ToneDirectionalLink

schedule_observe(handler, update_interval=1, transport=False, name=None, observe_time=False)#

Setup a handler to be called at regular intervals with the updated time / value of this ipytone widget.

Parameters:

  • handler (callable) – A callable that is called when the trait value is updated at regular intervals. The signature of the callable is similar to the signature expected by ipywidgets.Widget.observe(). Note that the handler will only apply to the trait given by the name argument here.

  • update_interval (float or string, optional) – The interval at which the trait is updated in the front-end, in seconds (default: 1). If transport=True, any interval accepted by schedule_repeat() is also valid here.

  • transport (bool, optional) – if True, the trait update is scheduled along the ipytone.Transport timeline, i.e., the handler is not called until the transport starts and will stop being called when the transport stops. If False (default), the trait update is done with respect to the active audio context.

  • name (str, optional) –

    The name of the Tone.js attribute to observe. Note that it doesn’t necessarily correspond to a trait of this ipytone widget. Instead, it may accept one of the following names (depending the observed ipytone widget, only a few may be supported):

    • ”time”: the current time (either transport time or audio context time).

    • ”value”: the current value of the Tone.js corresponding instance.

    • ”state”: current playback state

    • ”progress”: current progress (of an event or transport loop)

    • ”position”: current transport position in Bars:Beats:Sixteenths

    • ”ticks”: current transport tick position

    • ”seconds”: current transport time in seconds

    The default name also depends on the observed ipytone widget.

  • observe_time (bool, optional) – If True, both the (current audio context or transport) time and trait value are passed to the handler as a (time, trait_value) tuple when the trait value is updated (default: False).

schedule_unobserve(handler)#

Cancel the scheduled updates of the time / value trait associated with the given handler.

set_ramp_point(time)#

Creates a schedule point with the value computed at the given time.

Use this method to create an automation starting point when you don’t know what will be the value at this time. Otherwise use Param.set_value_at_time().

An automation starting point is needed when calling Param.linear_ramp_to_value_at_time() or Param.exp_ramp_to_value_at_time().

set_target_at_time(value, start_time, time_const)#

Start exponentially approaching the target value at the given time.

set_value_at_time(value, time)#

Schedules a parameter value change at the given time.

set_value_curve_at_time(values, start_time, duration, scaling=None)#

Sets an array of arbitrary parameter values starting at the given time for the given duration.

Optionally scale values with a scaling factor.

target_ramp_to(value, ramp_time, start_time=None)#

Start exponentially approaching the target value at the given time.

Since it is an exponential approach it will continue approaching after the ramp duration. ramp_time is the time that it takes to reach over 99% of the way towards the value.

to_destination()#

Convenience method to directly connect the output of this audio node to the main output (speakers) node.

property units#

Signal value units.

value#

Signal value