Getting Started

The Overview and User Interface sections below give a concise guide to what scriptSONIC is and how to use it. These are followed by a reference for the JavaScript library which has more detail on writing scripts.

When you start the app you'll find example projects which highlight various ways of using scriptSONIC. These come with explanatory notes within their scripts which can be found by loading a project and going to the Script screen.

Many of the examples generate only MIDI, and so require an external synth or effect app to be running to hear anything. The notes explain what is required.

For more help go to www.scriptsonic.com where there are tutorials and a forum.


Overview

scriptSONIC is a programmable musical instrument for the iPad. Use it to generate and control interactive musical patterns using simple JavaScript code. Make interactive rhythms; send and respond to MIDI messages; explore notes, chords and scales; manipulate samples and live sound input, and record the results. scriptSONIC combines the open-ended creative power of a programming language with the expressiveness of a touch-screen.

Concept

The key idea of scriptSONIC is to put code onto a timeline to create an 'executable' score. The code can do musical things like send MIDI, choose chords, sample or play sounds. It can also respond to user actions, make decisions, and do maths. All code runs in real-time, thanks to the fast JavaScript interpreter that comes with iOS. Code can also be used to generate the timeline and its elements, to script things that can be done with the user interface, and to 'live code', that is, to execute intructions while playing. To do all this, at your disposal is a library of simple, but flexible, JavaScript objects and functions.

Loops and Events

The main elements of the timeline are Loops and Events. Loops are divided into consecutive Events which can contain fragments of code. Loops play in time and trigger the Events, executing the code they contain.

Events can be created by splitting a Loop into parts of the same or differerent lengths. Events themselves can likewise be split. Splitting can take place using the UI, or from code. Or, Events can be added individually, and their durations set directly.

Loops or Events are played by touch in the UI, or from code.

Each Loop has several buttons on its left-hand side. These can start and stop playback; set whether the Loop repeats; set if playback continues after an individual Event is played; and set simultaneous starting.

Events can be played individually by touching them directly. Loop playback then starts from that event. If the Loop's continue button is highlighted, playback continues onto the next Event, otherwise it stops at the end of the Event.

You can touch any number of Loops or Events simultaneously. Sliding fingers over the screen triggers any Events in their path.

The starting and stopping of Loops and Events can also be bound to incoming MIDI events. This provides a powerful means to respond to, and generate, MIDI messages with code.

Timing

A Loop has a duration, measured in seconds, which can be set in the UI, or from code. When a Loop is played, the time cursor advances and triggers Events as it passes their start. Playback time is measured in normalised time units, running from 0.0 at the start of the Loop to 1.0 at the end. Event times also use these time units. So, for example, an 8 second Loop split into 3 equal Events has Events with start times of 0.0, 0.33, and 0.66.

Using seconds for Loops and time units for Events means that the ratios of Event timings can be set independently from Loop length. A musical pattern can be created independently from its duration.

Indexing

Each Loop and Event has a unique id which locates it within the Stack. Loop ids are numbered from 0 at the top of the Stack, upto a maximum of 15. Event ids are numbered from 0 at the left, upto a maximum of 127. The small white numbers in the corner of each Event show 'loop id.event id'. Ids do not persist if you add, remove or move Loops or Events; they always refer to the location in the Stack. JavaScript variables that refer to Loops or Events, however, do persist, if you want to keep a handle on an object that will move around.

Tickable & Touchable

Events can have two special properties: tickable and touchable. Flags to set or unset these properties can be accessed from JavaScript. If either flag is set, the Event's text changes from black to white, to show it is different.

Tickable Events execute their scripts continuously while playing, not just once at the start, but at an adjustable tick rate of many times per second. Tickable Events can be used when, for example, a MIDI CC message is to be computed as an Event plays. At each tick the script is executed and passed a value of the Event playback time.

Touchable Events can be used as controls. Instead of triggering playback, a touch will move the playback cursor to the location of the touch and execute the script for the corresponding value of Event time.

Tickable and touchable Event scripts can access playback time within the Event with the '$.t' variable.

Script Execution Order

Each Loop's time cursor is updated in id, or top to bottom, order for each tick of the audio clock. When the time cursor passes the start of an Event, any script in that Event is executed. This means that any changes a script makes to JavaScript objects or variables are available to scripts in Loops that follow it.

When you trigger an Event by touching it, the script is not executed immediately, but the time cursor is moved to the start of the Event, and it is updated in Loop order. However, when an Event is touchable its script is executed immediately.

Signal Flow

Audio input from the microphone, an audiobus connection, or inter-app audio is always available to record by any input Buffer. Likewise, audio generated by playback from Samples and Buffers is available to output Buffers. Additionally, audio input can be heard at the output and made available to output Buffers using the Monitor button.

CPU Load

Although the iOS JavaScript interpreter is very fast, there is obviously a limit to how much code can be executed in a real-time audio setting. This depends on many factors: the model of iPad used; the nature of the scripts being executed; how much CPU is being used by other apps running alongside; and the size of the audio buffer. The colour of the load meter on the Loops screen, going from green to red, shows scriptSONIC's CPU load. The audio buffer size, if not set by another audio app started previously, can be set via the Settings object to trade-off between scripting muscle and latency.

Be warned that there is no way (that I know of) to break a running script without closing the app. Avoid long, and of course, infinite loops!


User Interface

scriptSONIC has three main screens: Loops, Scripts and Projects. You can cycle between them using the navigation buttons at top-right. The Loops screen is the main screen showing a stack of Loops and their interactive Events. The Scripts page has a code editor and command line console for generating and manipulating content and for live-coding. The Projects screen is for managing projects and their associated sample files. On each screen you can bring up the documentation using the Info button.

The onscreen keyboard that pops-up when editing code has been customised to give access to all the symbols needed to write JavaScript with a single key press. Sliding a finger left or right across the keyboard moves the current cursor position in the text. The regular iOS keyboard can be used instead by tapping the keyboard icon to toggle between keyboards. To dismiss the keyboard, press 'Done' on the keyboard bar or two-finger double tap on the script text view.

Note that if you are using a hardware keyboard, you may find that the onscreen keyboard only hides if the iOS and not the custom one is chosen.

Loops Screen

There are two modes for handling touches to Events or Loops. In Edit mode, touching an Event applies the choice of edit selected by the Script/Delete/Copy/Split buttons. Likewise, touching a Loop via its Start/Stop buttons applies the edit to the whole loop.

However, in Play mode, touching an Event either triggers it, or toggles its activation according to the state of the Trigger/Toggle buttons. And in Play mode, the Loop's Start/Stop buttons control loop playback. You'll notice that selecting the different modes activates or inactivates other buttons as a guide. Event and Loop border colours also change - in Edit mode they are white, in Play mode, grey.'

Monitor live audio input.

Colour changes from green to red to indicate CPU load.

Undo/redo Loop and Event edits.

Open documentation browser.

Navigate interface screens.

Start all active Loops.

Pause all active Loops on first touch, reset on second.

Has three uses in different contexts: propagates a touch to any Active, Continue or Loop button to all other Loops; toggles the activation of all Events in a Loop; or applies Event script changes to all Events in a Loop.

In Play mode, trigger an Event on touch, or toggle it as active or inactive.

In Edit mode, either open an Event's' script editor, delete an Event or Loop, copy a Loop, or split an Event or Loop. To close a script editor, tap the Done button on the keyboard, or double tap with two fingers on the text edit.

The number of equal length Events to create from a single Event or the whole Loop.

Add a Loop.

Start Loop playback from the current cursor position.

On first touch, pause Loop playback, on second touch, reset the cursor to the start of the Loop.

Activated loops respond to the Start button in the top toolbar. You can use this feature to select any number of loops to start simultaneously.

When inactive, playback of a triggered Event ends at the end of that Event. Otherwise, when active, playback continues onto the next event. If playback is at the end of the loop, the state of the loop button determines if playback continues or stops.

When active, playback loops when the cursor reaches the end of the loop. When inactive, playback stops when the cursor reaches the end.

Shows the length of the Loop in seconds, either as a number, or as a JavaScript expression. Touching brings up a text editor where a value or expression can be entered. An expression can be used to set the length equal to the length of a sample, for example.

The position of a Loop can be changed by dragging it via its Start or Stop buttons when in Edit mode.

Projects Screen

Create a new project called 'new_##'.

Load the selected project.

Save the current project to its existing name.

Copy the current project to a new name. Will present the option to copy just the project, or the project and all associated sound and JavaScript files.

Rename the selected project.

Delete the selected project.

Import a project via iCloud drive, Google Drive, Dropbox etc.

Export a project via iCloud drive, Google Drive, Dropbox etc.

Show the sound file explorer for the selected project, or for the root directory if no project is selected. Sounds can be played, deleted, or copied and pasted using Kymatica's AudioShare.

Script Screen

Executes the script currently showing in the editor.

Load or Save the current script as a JavaScript .js file. Load will show a list of all files saved, allowing files to be shared between projects.

The editor has 5 seperate pages, whose content is saved with the project.

All variables created by scripts are saved when the project is saved, and restored when the project is loaded.

You can change the size of the script text by pinch-zooming on either panel.

In the console, a previous command can be recalled by tapping on it. The current command line can be cleared also by tapping on it.


Scripting Reference

All library objects will print a meaningful description of themselves in the console if the variable name is typed followed by enter. This same description is also available as the .name property, and via the JavaScript .toString() method.

After each object method and function described below is a box showing the places where that method or function can be executed. The three places are: in a script or console; in an Event; or in a tickable or touchable Event.

A guide to JavaScript, including introductory tutorials and a complete reference, can be found here.

The JavaScript interpreter currently included with iOS9 is about 50% ECMAScript6 compatible. A chart showing what is implemented can be found here.

Also included in scriptSONIC is the underscore JavaScript utility library.

Objects

Midi

Midi output manager object. Use it to send MIDI notes and CC messages on a given channel.

Properties

channel - Integer, get/set - MIDI channel from 1 to 16. Default value is 1.

Methods

play(note)

cc(controller,value)

Use

Create a Midi object

m=Midi()

Script Event Tick/Touch
X

Midi.play(note)
Midi.play(notes)

Play single note or an array of notes simultaneously.

Parameters

note - Note object

notes - array of Note objects

Use

Play single note

m.play(n)

Play several notes

m.play([n1,n2,n3])

Script Event Tick/Touch
X

Midi.cc(controller,value)

Send a MIDI control change message.

Parameters

controller - Integer, 0 to 127 - MIDI controller number

value - Number, 0.0 to 1.0 - MIDI controller value

Use

Send MIDI controller value 0.5 to controller number 100 on current channel.

m.cc(100,0.5)

Script Event Tick/Touch

Note

Note object.

Properties

name - String, get/set - pitch name and octave

pitch - String, get/set - pitch name - one of 'C','C#','Db','D','D#','Eb','E','F','F#','Gb','G','G#','Ab','A','A#','Bb','B'

value - Integer, get/set - MIDI value 0 to 127

octave - Integer, get/set - MIDI octave 0 to 8

vel - Integer, get/set - MIDI velocity 0 to 127. Default is 100

ratio - Number, get - note frequency relative to middle C

Use

Create Note with default values

n=Note()

Create Note with given pitch and octave

n=Note('D3')

Set velocity to 50

n.vel=50

Script Event Tick/Touch
X

Notes

An object containing a sequence of Note objects. A base class for the Chord, RomanChord and Scale objects. Not instantiated directly. Notes objects have transpose and octave pitch shifts, and inversion properties to transform any chord or scale after it has been constructed. They also have corresponding methods for constructing transformed copies of themselves.

Properties

notes - [Note], get - array of Note objects

transpose - Int, get/set - offset to all note pitch values -127 to 127

octave - Int, get/set - octave offset to all note pitch values -8 to 8

inversion - Int, get/set - inversion number 0 to 12. Rotates the order of the notes right to left and transposes wrapped notes by an octave. For example, 1st inversion of [C3 E3 G3] is [E3 G3 C4] and 2nd inversion is [G3 C4 E4].

Methods

note(i)

notex(i)

transposed(s)

octaved(o)

inverted(i)

Notes.note(i)

Select a single note at index i from Note sequence. The index wraps around the end of the array and so can never be out of range.

Parameters

i - Integer - Note array index

Returns

Note object

Use

Get third note

x=n.note(3)

Script Event Tick/Touch
X

Notes.notex(i)

Extended note selection. Instead of wrapping, a value of i outside the range of the Note array will generate a Note in a lower or higher octave.

Parameters

i - Integer - Note array index

Returns

Note object

Use

For a Notes object n containing 3 notes

x=n.notex(3)

will return the first note one octave higher.

x=n.notex(6)

will return the first note two octaves higher.

x=n.notex(-1)

will return the last note one octave lower.

Script Event Tick/Touch
X

Notes.transposed(s)

Return a copy of the Notes object transposed by s semitones.

Parameters

s - Integer - number of semitones - -127 to 127

Returns

Notes object with each Note transposed. Resulting note values will be clamped to range 0..127

Use

Transpose all notes up by a perfect 5th, or 7 semitones

m=n.transposed(7)

Script Event Tick/Touch
X

Notes.octaved(o)

Return a copy of the Notes object transposed by o octaves.

Parameters

o - Integer - number of octaves - -8 to 8

Returns

Notes object with each Note transposed. Resulting note values will be clamped to range 0..127

Use

Transpose all notes down by one octave.

m=n.octaved(-1)

Script Event Tick/Touch
X

Notes.inverted(i)

Return a copy of the Notes object that is its ith inversion.

Parameters

i - Integer - inversion number - 0 to 12

Returns

Notes object with order of notes rotated right to left by i and wrapped notes transposed by an octave.

Use

If c is a Chord [C3 E3 G3], return 2nd inversion [G3 C4 E4].

c2=c.inverted(2)

Script Event Tick/Touch
X

Chord

A Chord object. Inherits from Notes. Construct a chord from a root note and quality, which include major, minor, augmented, diminished, half-diminished, seventh, ninth, and dominant.

Properties

name - String, get - root note and chord quality

root - String, get/set - root note - one of 'C','C#','Db','D','D#','Eb','E','F','F#','Gb','G','G#','Ab','A','A#','Bb','B' (upper or lower case)

rootValue - Integer, get/set - root note as value - 0 to 11

quality - String, get/set - chord quality - one of ' '(for major)','min','aug','dim','sus2','sus4', '7','maj7','minmaj7','min7','augmaj7','aug7','min7dim5','dim7','dom7dim5', 'maj9','dom9','minmaj9','min9','augmaj9','aug9','hdim9','hdimmin9','dim9','dimmin9'

qualityValue - Integer, get/set - chord quality expressed as index into the list of qualities above

Use

Create E major Chord

c=Chord('E')

Create F# diminished 7th Chord

c=Chord('F#dim7')

Show notes in console

>c.notes
Gb4,A4,C5,Eb5

Script Event Tick/Touch
X

RomanChord

A RomanChord object. Inherits from Notes. An alternative chord representation that uses the 'roman' system such as CIII9.

Properties

name - String, get - root key, scale, number and quality

key - Integer, get/set - key on which chord is built - 0 to 11, or one of C,Cs,Db,D,Ds,Eb,E,F,Fs,Gb,G,Gs,Ab,A,As,Bb,B. Note that these are JavaScript variables holding Integers, and not Strings as used with Chord and Scale objects.

scale - Integer, get/set - scale on which chord is built - 0 or 1, or, MAJ or MIN

chord - Integer, get/set - chord number i.e. position on scale that chord is built - 0 to 6, or one of I,II,III,IV,V,VI,VII

quality - Integer, get/set - chord quality - 0 to 4, or one of TRI,SEV,NIN,ELE or THR, for triad, seventh, ninth, eleventh or thirteenth chords.

Use

Create CIII9 Chord

c=RomanChord(C,MAJ,III,NIN)

or

c=RomanChord(0,0,2,2)

Create G#MinV Chord

c=RomanChord(Gs,MIN,V,TRI)

or

c=RomanChord(11,1,4,0)

Script Event Tick/Touch
X

Scale

A scale object. Inherits from Notes. Construct a scale from a root note and type, one of major, minor, phrygian, lydian, mixolydian, aeolian, locrian, melodic minor, harmonic minor, 8 note diminished, 8 note dominant, whole tone, pentatonic major, pentatonic minor, pentatonic blues and blues

Properties

name - String, get - root note and scale type

root - String, get/set - root note - one of 'C','C#','Db','D','D#','Eb','E','F','F#','Gb','G','G#','Ab','A','A#','Bb','B' (upper or lower case)

rootValue - Integer, get/set - root note as value - 0 to 11

scale - String, get/set - scale type - one of 'maj','min','phr','lyd','mix','aeo','loc', 'mel','harm','8dim','8dom','whole','pentmaj','pentmin','pentblues','Blues'

scaleValue - Integer, get/set - scale type expressed as index into the list of types above

Use

Create an F harmonic minor scale

s=Scale('Fharm')

Show notes in console

>s.notes
F4,G4,G#4,A#4,C5,C#5,E5

Script Event Tick/Touch
X

Player

An audio player object. Holds a monophonic array of samples which can be played back. Base class for Buffer, Sample and Recorder, and not directly instantiated.

Properties

length - Number, get - length of sample array in seconds

rate - Number, get/set - playback rate, 1.0 being normal speed - 0.0 to 60.0

Methods

play()

grain(begin,volume,rate,ramp)

Script Event Tick/Touch
X X

Player.play()

Play the audio samples from the start, at playback speed of rate. Only to be called from an Event.

Use

Play back samples in p at half-speed

p.rate=1/2
p.play()

Script Event Tick/Touch
X X

Player.grain(begin,amp,rate,ramp)

Play an enveloped grain of audio samples from begin, at playback speed of rate, with amplitude amp. The envelope profile is determined by ramp. The grain plays for the duration of the event in which it is called. If sample playback ends before the event ends, nothing is played. Note that for negative values of rate i.e. playing backwards, begin must be >0.0 or nothing will be played. Only to be called from an Event.

Parameters

begin - Number - normalised position in sample array - 0.0 to 1.0

amp - Number - amplitude - 0.0 to 2.0

rate - Number - playback speed. - -60.0 to 60.0

ramp - Number - normalised attack/decay ramp of the grain envelope, 0.0 being no ramp, 1.0 being a ramp that peaks half-way into the sample. - 0.0 to 1.0

Use

Play a grain starting from half-way into a sample s, playing backwards at double-speed, with full amplitude, and a fast grain envelope.

s.grain(0.5,1.0,-2,0.01)

Script Event Tick/Touch
X X

Sample

An audio sample file loaded into memory. Sample formats supported are WAV, AIF and MP3. Note that stereo files are loaded as mono. Inherits from Player.

Properties

name - String, get - the project and file name

Use

Create a sample from a file in the current project

s=Sample('filename.wav')

Create a sample from a file in another project

s=Sample('project/filename.wav')

Create a sample from a file in the root directory

s=Sample('/filename.wav')

Script Event Tick/Touch
X

Buffer

An audio buffer object. Holds an array of samples which can be recorder into from either the app's audio input, or output. The buffer can be simultaneously written to and played back from with scripts in different Events. Inherits from Player.

Properties

length - Number, get/set - length of sample array in seconds - 0.0 to 600.0

type - String, get - record source - 'in' or 'out'

Methods

rec()

Use

Buffer creation defaults to input source, and length 1 sec.

Create an input source Buffer of length 1 secs

b=Buffer()

Create an input source Buffer of length equal to sample s

b=Buffer(s.length)

Create an output source Buffer of length 2 secs

b=Buffer('out',2)

Script Event Tick/Touch
X

Buffer.rec()

Record the source into the buffer. Only to be called from an Event.

Use

b.rec()

Script Event Tick/Touch
X

Recorder

Records an input or output source into a WAV sound file within the current project, as well as an audio buffer. Unlike a Buffer, the length cannot be set, but is determined by how long the recording lasts. Each time rec() is called, a take counter is incremented and a new sound file is created with the take number appended to the end. Inherits from Player.

Properties

name - String, get - filename

type - String, get - record source - 'in' or 'out'

take - Integer, get - take counter - 0 upwards

Methods

rec()

Use

Recorder creation defaults to output source, and a filename of 'recording_take.wav'.

Create an output source Recorder with default filename 'recording_take.wav'

r=Recorder()

Create an output source Recorder with default filename 'recording_take.wav'

b=Recorder('out')

Create an input source Recorder with filename 'blah_take.wav'

b=Recorder('in','blah')

Script Event Tick/Touch
X

Recorder.rec()

Record the source into the file and the buffer. Only to be called from an Event. Recording lasts as long as the Event plays. If the Event loops, multiple takes and files will be recorded.

Use

r.rec()

Script Event Tick/Touch
X X

Loop

A Loop object. A scripting interface to the Loops seen in the user interface which contain Events. Can be used to generate content, modify parameters, and control playback. Not directly instantiated, but created using the addloop() function, and accessed via the loops array.

Properties

colour - Integer, get/set - displayed colour, represented as 24 bit RGB value

continues - Bool, get/set - the Loop continue flag - true or false

events - [Event], get - array of events belonging to this Loop

id - Integer, get - position of this Loop in the Stack - 0 onwards

length - Number, get/set - Loop length in secs - 1/60 to 600.0

loops - Bool, get/set - the looping playback flag - true or false

rate - Number, get/set - reciprocal of length in per secs - 1/600 to 60.0

triggers - Bool, get/set - Loop triggers on 'Start All' button - true or false

t - Number, get set - playback time of the Loop normalised to 0.0 at the beginning and 1.0 at the end of the Loop. Can be set to initialise the Loop

Methods

Construction

addevent(start)

clear()

remevent(id)

split(N or [n])

Playback

start()

stop()

reset()

Loop.addevent(start)

Add an event with the given start time.

Parameters

start - Number, 0.0 to 1.0 - normalised start time of Event to add

Returns

Event object

Use

Add Event half-way into Loop

e=l0.addevent(0.5)

Add Event 1 sec into Loop of length 10 secs

e=l0.addevent(0.1)

Script Event Tick/Touch
X X

Loop.clear()

Remove all Events, then create single empty Event.

Use

l0.clear()

Script Event Tick/Touch
X X

Loop.remevent(id)

Remove the Event with the given id.

Use

Remove 4th Event from Loop

l0.remevent(4)

Script Event Tick/Touch
X X

Loop.split(N or [n])

Split loop into several Events, each a copy of the first Event. Either split into N equal length Events, or Events with relative lengths specified by an array of values.

Parameters

N - Integer, 1 to 64 - number of equal length Events to create

[n] - [Integer] - array of integers specifying the relative lengths of each Event to create

Returns

Array of Event objects

Use

Split loop into 4 equal Events

e=l0.split(4)

Split loop into 3 Events with lengths 1/4, 1/2, 1/4

e=l0.split([1,2,1])

Script Event Tick/Touch
X X

Loop.start()

Starts Loop playback as if its Start button had been touched.

Use

l0.start()

Script Event Tick/Touch
X

Loop.stop()

Stops Loop playback as if its Stop button had been touched.

Use

l0.stop()

Script Event Tick/Touch
X

Loop.reset()

Stops Loop playback, and resets time cursor to zero as if its Stop button had been touched twice.

Use

l0.reset()

Script Event Tick/Touch
X

Event

An Event object. A scripting interface to the Events that make up Loops. Can be used to modify parameters, alter UI states, set scripts and control playback. Not directly instantiated, but created using the Loop.addevent() and Loop.split() functions, and accessed via the Loop.events and 'ev' Events arrays.

Properties

active - Bool, get/set - Event triggers when touched. Set in UI when in Toggle mode. - true or false

id - Integer, get - position of this Event in the Loop - 0 onwards

lid - Integer, get - position of this Event's Loop in the Stack. Same as loop.id - 0 onwards

tid - String, get - String form of "lid.id" i.e. Event's coordinates in the Stack.

begin - Number, get/set - normalised time in Loop that Event begins - 0.0 to 1.0

end - Number, get/set - normalised time in Loop that Event ends - 0.0 to 1.0

length - Number, get/set - normalised length - 0.0 to 1.0

display - String, get/set - String to show in Event in Play mode. If this is empty, the script is shown instead.

script - String, get/set - Script for this Event.

loop - Loop, get - Loop object to which this Event belongs.

midievents - [MidiEvent], get - The Midievent objects which triggered this Event through a binding.

tickable - Bool, get/set - flag determining whether script is executed repeatedly while the Event plays, or only once, the default, when the Event triggers - true or false

touchable - Bool, get/set - flag determining whether script is executed repeatedly while an Event is touched - true or false

t - Number, get - playback time of the Event normalised to 0.0 at the beginning and 1.0 at the end of the Event. For use in tickable and touchable Events

Methods

split(N or [n])

start()

stop()

Event.split(N or [n])

Split Event into several copies. Either split into N equal length Events, or Events with relative lengths specified by an array of values.

Parameters

N - Integer, 1 to 64 - number of equal length Events to create

[n] - [Integer] - array of integers specifying the relative lengths of each Event to create

Returns

Array of Event objects

Use

Split Event into 2 equal copies

e.split(2)

Split into 3 Events with lengths 1/6, 1/3, 1/2

e.split([1,2,3])

Script Event Tick/Touch
X X

Event.start()

Starts Event playback as if it had been touched.

Use

e.start()

Script Event Tick/Touch
X

Event.stop()

Stops Event playback as if its Loop Stop button had been touched.

Use

e.stop()

Script Event Tick/Touch
X

MidiEvent

A MidiEvent object. Holds information on MIDI events received and passed to Events through binding.

Properties

type - String, get - MIDI event type - one of 'noteon', 'noteoff', 'cc', 'program'

channel - Integer, get - MIDI event channel - 1 to 16

pitch - Integer, get - MIDI note event pitch value - 0 to 127

vel - Integer, get - MIDI note event velocity value - 0 to 127

cc - Integer, get - MIDI CC controller value - 0 to 127

value - Integer, get - MIDI CC value - 0 to 127

program - Integer, get - MIDI program change value - 0 to 127

note - Note, get - MIDI note event as a Note object


Settings

A Settings object. Holds scriptSONIC app settings. A single instance exists for each project, and is loaded/saved with it.

Properties

buffersize - Integer, get/set - audio buffer size in samples - one of 128,256,512,1024

tickrate - Integer, get/set - tickable Event tick rate in ticks per sec - 1 to 30


Functions

Utils

print(v,...)

Print value, or values to console.

Parameters

v - Any - any JavaScript value.

Use

print(l0)

shows in console

> [Loop 0]

Print several variables at once

print(a,b,c)

Script Event Tick/Touch

Number.show()

An extension to the JavaScript Number object that returns a string of the number formatted to 2 significant places. Useful when setting the Event.display string.

Use

a=1/3
print(a.show())

shows 0.33

Within an Event script

$.display=$.t.show()

displays the value of the Event playback time.

Script Event Tick/Touch

list()

List all sound files in all projects.

Use

list()

Script Event Tick/Touch
X X

listjs()

List all JavaScript .js files in all projects.

Use

listjs()

Script Event Tick/Touch
X X

move()

Move or rename a file.

Parameters

from - String - project/filename of file to change

to - String - destination project/filename

Use

Move sound file from one project to another

move('proj1/noise.wav','proj2/noise.wav')

Rename a JavaScript file

move('proj/test.js','proj/newtest.js')

Script Event Tick/Touch
X X

clearcon()

Clears the console.

Use

clearcon()

Script Event Tick/Touch
X X

rand(from,to)

Generate random number within range.

Parameters

from - Number - beginning of range

to - Number - end of range

Returns

Number.

Use

Random number between 5.0 and 15.6

a=rand(5,15.6)

Script Event Tick/Touch

randint(from,to)

Generate random integer within range.

Parameters

from - Integer - beginning of range

to - Integer - end of range

Returns

Integer.

Use

Random number between 4 and 8

a=rand(4,8)

Script Event Tick/Touch

Loop construction

addloop()

Add new Loop to the Stack, upto a max of 16.

Returns

Loop object.

Use

l=addloop()

Script Event Tick/Touch
X X

copyloop(id)

Copies Loop with given id and adds it to the Stack.

Returns

Loop object.

Use

Copy second loop in the Stack

l=copyloop(2)

Script Event Tick/Touch
X X

remloop(id)

Removes Loop with given id.

Use

remloop(2)

Script Event Tick/Touch
X X

moveloop(id1,id2)

Moves Loop with id1 so that it has new id2.

Use

Copy 2nd loop to be at 4th position

copyloop(2,4)

Script Event Tick/Touch
X X

copyloop(id)

Copies Loop with given id and adds it to the Stack.

Returns

Loop object.

Use

Copy second loop in the Stack

l=copyloop(2)

Script Event Tick/Touch
X X

clear()

Removes all Loops to leave an empty Stack.

Use

clear()

Script Event Tick/Touch
X X

undo()

Undo last edit to Loops or Events.

Use

undo()

Script Event Tick/Touch
X X

redo()

Reverse last undo.

Use

redo()

Script Event Tick/Touch
X X

Playback

start()

Start playback as if the 'Start Active' button had been touched.

Use

start()

Script Event Tick/Touch
X

stop()

Stop playback as if the 'Stop All' button has been touched. Calling this twice resets all playback cursors.

Use

stop()

Script Event Tick/Touch
X

MIDI Binding

bind(obj,action,type,channel,value)

Bind a MIDI event to playback action. MIDI note, CC and program events can be mapped onto the start or stop actions of the Stack, a Loop or an Event, allowing MIDI control of scripts. MIDI events can be specified exactly, or with wildcards. Any number of bindings can be made to an object/action pair.

If a MIDI event has triggered an Event to start, that MIDI event can be retrieved from the midievents property of the Event. The midievents property may contain several MIDI events if, for example, several notes are played simultaneously. The Event will be triggered once, but the midievents property will contain all coincident MIDI events.
Also, the last received MIDI event, bound or not, can be retrieved with the midievent() function.

Parameters

obj - Object - Loop, Event or null - object to bind MIDI event to. If null, binds to the Stack

action - String - 'start' or 'stop' - object action to bind MIDI event to.

type - String - 'noteon','noteoff','cc','program' or null - type of MIDI event to bind, or null for any.

channel - Integer - 1 to 16 or null - - channel of MIDI event to bind, or null for any channel.

value - Integer - 0 to 127 or null - - value of MIDI event to bind, or null for any value.

Use

Bind MIDI C4 note on, channel 1, to start Event e

bind(e,'start','noteon',1,60)

Bind MIDI CC100 controller messages on channel 4, to start Event e

bind(e,'start','cc',4,100)

Bind all MIDI note off messages, on any channel, to stop loop l0

bind(l0,'stop','noteoff',null,null)

Start all active loops with any event

bind(null,'start',null,null,null)

Script Event Tick/Touch
X

unbind(obj,action)

Remove all MIDI bindings to an object/action pair.

Parameters

obj - Object - Loop, Event or null - object to remove MIDI event from. If null, remove from the Stack

action - String - 'start' or 'stop' - object action to remove.

Use

Remove all bindings to start Event e

unbind(e,'start')

Script Event Tick/Touch
X

clearbind()

Removes all MIDI bindings.

Use

clearbind()

Script Event Tick/Touch
X

bindings()

Returns a list of all bindings in the current project.

Returns

String. List of the form 'object.id.action - type.channel.value'

Use

For bind example above,

bindings()

returns

[event.0.0.start - noteon.1.60
event.0.0.start - cc.4.100
loop.0.stop - noteoff.*.*
stack.start - *.*.*]

Script Event Tick/Touch
X

midievent()

Returns the last MIDI event received, whether bound or not. Only logs note on, note off, cc, or program events.

Returns

MidiEvent object.

Use

e=midievent()

Script Event Tick/Touch
X

settings()

Returns the unique Settings object for the current project.

Returns

The Settings object.

Use

s=settings()

Change buffersize

s.buffersize=512

Script Event Tick/Touch
X X

Shortcuts

These are JavaScript variables that give shorthand access to Loops and Events.

loops

The Stack of Loops.

Type

Array of Loop objects

Use

Fourth loop in the Stack

l=loops[4]

ev

Events matrix. Any Event in the Stack can be accessed by using its id.

Type

2D Array of Event objects

Use

Event with id 4.3 ie 3rd Event in 4th Loop.

e=ev[4][3]

l0 - l15

Loops 0 to 16. These 16 variables always map onto the Loops in the Stack if they exist.

Type

Loop object

Use

Set length of 3rd Loop to 6 secs

l3.length=6

$

'This' within an Event script. When writing a script within an Event, $ refers to the Event itself

Type

Event object

Use

Get id of Event running the script

i=$.id

Get Loop id of Event running the script

j=$.lid




scriptSONIC uses code by AudioBus, Audeonic and Kymatica, and icons by www.flaticon.com.

© Jonathan Mackenzie 2016

Version 1.0.1

Contents