Automation:
Filter:
Automation/Classes (extension) | GUI

Automation
ExtensionExtension

Automation allows to record and playback live changes made to other GUI elements in particular, or anything else you wish to setup.

Description

Automation is a SuperCollider Quark to record, save and load GUI element motions. (c) 2009,2016 Neels J. Hofmeyr <neels@hofmeyr.de>, GNU GPL v3 or later. Contributions by: escuta <http://escuta.org>

To get started, please see the Automation tutorial!

This is Automation, the main class of the Automation Quark. This is what you instantiate to use Automation. Automation has a number of subscribed AutomationClient instances and delegates them, as well as plays back their actions. Most GUIs you are already using can be docked to Automation without changing any of your old code. Automation provides a control GUI to start/stop/record/save/load the Automation.

Class Methods

.new

Arguments:

length

The initial max value for playing time (default is 180, that's 3 minutes). This value *only* affects the time slider, nothing else. Recorded values are NOT interfered with based on this number, it simply determines the scale of the time slider GUI element.

server

The server to use. If server==nil, then Server.default will be used. If you were ever to run this on a different server from the default server, you have to pass the server arg to the Automation constructor. You may then access it here.

showLoadSave

Show or hide the Load and Save buttons on the transport. The default is true.

showSnapshot

Show or hide the Snapshot button on the transport. The default is true.

minTimeStep

Time lapse in seconds between recorded GUI updates. The default is 0.01.

Returns:

Instance

Instance Methods

.findAndDock

Automatically find dockable GUI elements in a given window, e.g.

.dock

Manual docking of GUI elements, if findAndDock doesn't do what you need.

Arguments:

guiElement

The GUI element to dock, like a slider, etc.

name

The name to save the element's values as. If name==nil, name will be "automatedN", where N is the current number of GUI elements docked.

.front

Open a transport control GUI.

Arguments:

win

If nil, open a new window. Otherwise the given GUI.window is used to show the transport GUI.

bounds

A Rect(x,y,w,h) for size and position of the transport.

.play

User callable function to start playback at the current position.

.stop

User callable function that stops playback, staying at the current position.

.seek

User callable function to seek a given position in seconds. The seeking action is instantaneous.

Arguments:

seconds

Time positiong in seconds to seek to.

dostop

If false, playback (if running) continues at the new position. If true, playback is stopped at the new position. If omitted, the value from doStopOnSeek will be used, which in turn is false by default.

.save

Save all clients' values to disk, using client names as the filenames in a given directory.

.load

Load as many clients as possible from disk.

Arguments:

dir

Directory to load from.

.snapshot

User callable function that records this instant value for each subscribed client. For example, this is useful for setting initial values for all GUI elements.

.onPlay

User provided callback function called when when play is carried out in transport.

.onStop

User provided callback function called when the transport is stopped. The current transport time in seconds is passed in as a parameter. For example, use this to launch and stop some background action like audio file playback and such. Note, when doStopOnSeek is true, both onStop and onSeek will be called for each seek operation.

.onSeek

User provided callback function called when seek is carried out. The current transport time in seconds is passed in as a parameter. For example, use this to launch and stop some background action like audio file playback and such. Note, when doStopOnSeek is true, both onStop and onSeek will be called for each seek operation.

.onEnd

This callback function is called when the time slider hits its end boundary. The default behaviour is to add 20% of time and continue to run:

But instead, we could also, for example, stop at the end:

Or wrap back to the start:

.seekLatency

Add headstart given to the onSeek callback, i.e. call onSeek, and carry out the actual transport and GUI seek this many seconds later. Useful for audio recording that has latency.

.playLatency

Add headstart given to the onPlay callback, i.e. call onPlay, and carry out the actual transport and GUI playback this many seconds later. Useful for audio recording that has latency.

.doStopOnSeek

If true, the transport is stopped whenever the transport position is modified.

.verbose

If false, all informational posts on the server window are omitted.

.now

Returns:

the current position on the time scale.

.isMyGuiElement

Arguments:

guiElement

Gui element

Returns:

the AutomationGui instance that is connected to this Automation instance, if any.

.stopRecording

Button action to switch off recording.

.enableRecording

The button action that signals readyness for recording. It makes the record button orange.

.doRecord

If true, then the recording button is active (either orange or red).

.quit

rewind and stop.

.defer

Internal: defer a given function only if doDefer is true. Used for sending GUI signals.

Arguments:

func

Function to be deferred.

.doDefer

Internal flag to indicate whether GUI actions should be deferred. May be necessary for specific GUI implementations.

.clients

Instance variable. A List of AutomationClient instances that are currently docked.

.clientStartsRecordingMsg

Message function called from any AutomationClient as soon as it was first modified in recording mode. It makes the record button red.

.clockTime

Used as base for all transport timing.

Returns:

the current real wall clock time

.privatePlay

The core of the play function without the semaphore stuff. Don't use unless within a semaphore.wait ... semaphore.signal block.

.privateStop

The core of the stop function without the semaphore stuff. It is also called from the playRoutine itself. Don't use unless within a semaphore.wait ... semaphore.signal block.

.privateSeek

The core of the seek function without the semaphore stuff. Don't use unless within a semaphore.wait ... semaphore.signal block.

.addClient

private, don't use unless within a semaphore.wait ... semaphore.signal block.

Examples

Please refer to the Automation tutorial!