ipytone.transport.Transport#

class ipytone.transport.Transport#

Bases: ToneObject, ScheduleObserveMixin

Transport for timing musical events.

Note: the transport position is not updated until changing the playback state (play/pause/stop) or explicitly setting a new position.

Do not instanciate this class directly. Instead use get_transport() to get the instance created for the main audio context.

__init__(**kwargs)#: Public constructor

Methods

`cancel`([after])	Clear all scheduled events on the timeline that would start after a given time.
`clear`(event_id)	Clear an event from the timeline.
`dispose`()	Dispose and disconnect this node.
`pause`([time])	Pause the transport and all sources synced to the transport.
`schedule`(callback, time)	Schedule an event along the transport timeline.
`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_once`(callback, time)	Schedule an event along the transport timeline.
`schedule_repeat`(callback, interval[, ...])	Schedule a repeated event along the transport timeline.
`schedule_unobserve`(handler)	Cancel the scheduled updates of the time / value trait associated with the given handler.
`set_loop_points`(start, end)	Set the transport loop start and stop positions.
`start`([time, offset])	Start the transport and all sources synced to the transport.
`stop`([time])	Stop the transport and all sources synced to the transport.
`sync_signal`(signal[, ratio])	Attach a signal to the tempo so that any change in the tempo will change the signal in the same ratio.
`toggle`([time])	Toggle the current playback state of the transport.
`unsync_signal`(signal)	Unsync a previously synced signal.

Attributes

`bpm`	Transport tempo parameter (beats per minute).
`disposed`	Returns True if the node was disposed (i.e., disconnected and web audio node freed for garbage collection).
`log`	A trait whose value must be an instance of a specified class.
`loop`	whether the transport loops or not
`loop_end`	ending position of transport loop
`loop_start`	starting position of transport loop
`position`	transport position
`progress`	transport loop relative position
`seconds`	transport position in seconds
`state`	current playback state
`swing`	transport swing
`swing_subdivision`	transport swing subdivision
`ticks`	transport position in ticks
`time_signature`	transport time signature

property bpm: Param#: Transport tempo parameter (beats per minute).

cancel(after=0)#

Clear all scheduled events on the timeline that would start after a given time.

Parameters: after (str or float) – The time threshold along the transport timeline.

clear(event_id)#

Clear an event from the timeline.

Parameters: event_id (int) – The id of the event to clear.

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).

loop#: whether the transport loops or not

loop_end#: ending position of transport loop

loop_start#: starting position of transport loop

pause(time=None)#

Pause the transport and all sources synced to the transport.

Parameters: time (str or float) – The time time when the transport should pause.

position#: transport position

progress#: transport loop relative position

schedule(callback, time)#

Schedule an event along the transport timeline.

Parameters

callback (callable) – The callback to be invoked at the scheduled time. It must accept exactly one argument that corresponds to the time value (in seconds).
time (str or float) – The time to invoke the callback at (any value/units supported by Tone.js Time).

Returns

event_id – The id of the event which can be used for canceling the event.

Return type

int

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_once(callback, time)#

Schedule an event along the transport timeline.

After being invoked, the event is removed.

Parameters

callback (callable) – The callback to be invoked at the scheduled time. It must accept exactly one argument that corresponds to the time value (in seconds).
time (str or float) – The time to invoke the callback at (any value/units supported by Tone.js Time).

Returns

event_id – The id of the event which can be used for canceling the event.

Return type

int

schedule_repeat(callback, interval, start_time=0, duration=None)#

Schedule a repeated event along the transport timeline.

The event may start at a given time and may be repeated only for a specified duration.

Parameters

callback (callable) – The callback to be invoked at the scheduled time. It must accept exactly one argument that corresponds to the time value (in seconds).
interval (str or float) – The duration between successive callbacks (any value/units supported by Tone.js Time but must be positive).
start_time (str or float, optional) – When along the timeline the events should start being invoked (default: at the beginning of the timeline).
duration (str or float, optional) – How long the event should repeat (default: indefinitely).

Returns

event_id – The id of the event which can be used for canceling the event.

Return type

int

schedule_unobserve(handler)#: Cancel the scheduled updates of the time / value trait associated with the given handler.

seconds#: transport position in seconds

set_loop_points(start, end)#: Set the transport loop start and stop positions.

start(time=None, offset=None)#

Start the transport and all sources synced to the transport.

Parameters

time (str or float) – The time time when the transport should start.
offset (str or float) – The timeline offset (position) to start the transport.

state#: current playback state

stop(time=None)#

Stop the transport and all sources synced to the transport.

Parameters: time (str or float) – The time time when the transport should stop.

swing#: transport swing

swing_subdivision#: transport swing subdivision

sync_signal(signal, ratio=None)#

Attach a signal to the tempo so that any change in the tempo will change the signal in the same ratio.

Parameters

signal (ipytone.Signal) – The audio signal object to sync with the tempo.
ratio (float, optional) – Ratio between the signal value and the tempo BPM value. By default computed from their current values.

ticks#: transport position in ticks

time_signature#: transport time signature

toggle(time=None)#

Toggle the current playback state of the transport.

Parameters: time (str or float) – The time of the event.

unsync_signal(signal)#

Unsync a previously synced signal.

Parameters: signal (ipytone.Signal) – The audio signal object to unsync with the tempo.