ipytone.Param#

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

Bases: NodeWithContext, ParamScheduleMixin, ScheduleObserveMixin

Single, automatable parameter with units.

__init__(value=1, units='number', convert=True, min_value=None, max_value=None, swappable=False, **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.
`dispose`()	Dispose and disconnect this node.
`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.
`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.

Attributes

`convert`	If True, convert the value into the specified units
`disposed`	Returns True if the node was disposed (i.e., disconnected and web audio node freed for garbage collection).
`input`	Returns the input node.
`log`	A trait whose value must be an instance of a specified class.
`max_value`	Parameter value upper limit.
`min_value`	Parameter value lower limit.
`name`	A trait for unicode strings.
`overridden`	A boolean (True, False) trait.
`units`	Parameter value units.
`value`	Parameter 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.

convert#: If True, convert the value into the specified units

dispose()#: Dispose and disconnect this node.

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.

property input#: Returns the input node.

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#: Parameter value upper limit.

property min_value#: Parameter value lower limit.

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

schedule_dlink(target, update_interval=1, transport=False, name=None)#

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

schedule_jsdlink(target, update_interval=0.08, transport=False, name=None)#

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.

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.

property units#: Parameter value units.

value#: Parameter value