NexusUI

mobile music interfaces

Download NexusUI
NexusUI is a library of audio interface components made with HTML5 that transmit OSC data locally or to other applications via AJAX.

Nexus can be used to integrate directly with the Web Audio API in the browser, or to communicate with Max, SuperCollider or Chuck via server-side applications.

Nexus is mobile-friendly and multi-touch compatible. It enables large-scale collaborative performances by distributing interfaces through a browser -- something that many people have at home, in their bag, or carry in their pocket.

Simple Sequencer Demo
Animated Matrix Demo
Metroball Demo
(Thanks to Gibberish for the audio support!)


Example HTML

Gallery of Recent Nexus Projects
Add your own(!) by posting to Instagram with the hashtag #nexusui

How to Use Nexus UI

Creating Elements
link to nexus and jquery
Nexus requires links to jquery.js and nexusUI.js libraries

adding elements with <canvas>
Any canvas with a valid nx attribute will turn into a nexus element.

current nexus elements
dial  •  position  •  keyboard  •  button  •  toggle  •  slider  •  multislider  •  matrix  •  select  •  tilt  •  metroball  •  pixels  •  colors  •  sandbox  •  joints  •  mango
Accessing elements in JS
nx
Nexus is globally instantiated in JavaScript as nx

nx.onload( )
When Nexus loads, it triggers the nx.onload function which you can define in your javascript. Accessing Nexus elements should be done only after Nexus loads.

element naming
By default, the first dial on the page will be given the js variable of dial1, the third toggle will be toggle3, etc. You can overwrite this default by giving the canvas an ID attribute in the HTML, which will become the element's js variable name.

Transmitting data to Max
with AJAX
Nexus includes a PHP file, nexusOSCRelay.php, that forwards data from the UI to a specified IP and port (default ip 127.0.0.1 and port 7475).

nx.setTransmissionProtocol( )
To forward with AJAX and PHP, use the global nx.setTransmissionProtocol() method to set all UI elements to send with AJAX. You can override individual elements' paths by setting their transmissionProtocol property directly.

nx.setTransmitCommand( )
An element's transmitCommand property specifies the location to send to. To use Nexus' PHP relay, set the transmitCommand to the filepath of nexusOSCRelay.php. transmitCommand can also be set for all elements with the nx.setTransmitCommand() method.

OSC naming conventions
Each element's OSC name will be the same as its JS variable name. I.e. the first dial on the page will be /dial1, the third dial will be /dial3, etc., unless you set its name with an ID.

Transmitting data locally to Web Audio
or to graphics, other Nexus Elements, or other JavaScript variables
To make UI data accessible from within JavaScript, set the global or local transmission protocol to "local"

.localTransmit( )
Define individual localTransmit functions for each element you wish to receive data from.

nx.globalLocalTransmit( )
Or define one function that receives all data sent from any object, with OSC name.

Styling
size
Elements auto-adjust to fit the CSS or inline style of the canvas.

color
Nexus allows for global coloring with nx.colorize or setting individual elements with their .colors property. Parameters to set: accent (default), fill, border, accentborder, black, white.

Animation
.animate()
A few elements have options for animation and simple physics. To animate an object, give it an animation type with .animate()
e.g. dial1.animate("bounce");

nx.startPulse()
Nexus has a centralized animation pulse that you should turn on if you have any animated objects. Turn on the pulse with nx.startPulse()

current elements supporting animation
position
dial

Component Docs

Shared properties and methods
properties
methods
.draw( )
Redraws the element (with any new values that have been set)

.nxTransmit( value to send )
Sends value to previously defined transmit location.

Dial
output data
0-1 float, rounded to 3 decimals.
properties
.value (default data output)
0-1 float, rounded to 3 decimals.
methods

Position
output data
An array [ x,y ] of floats scaled 0-1. If transmitted to another program like Max, the data may be received as a list.
properties
.nodePos
An array [ x,y ] of floats scaled to the width/height of the canvas.
methods
.animate( type )
Sets animation. Current valid types: "bounce", "none"
Keyboard
output data
A MIDI data note in a two-note array [ note number, on/off ].
Example: Middle C on a two-octave nexus keybaord sends [ 12, 1 ] when pressed and [ 12, 0 ] when unpressed. If transmitted to another program like Max, the data may be received as a list.
properties
methods

Button
output data
output depends on mode.
impulse (default): 1 (on) when clicked.
toggle: 1 (on) when clicked, 0 (off) when released.
position: array/list of 3 numbers: on/off, x of press, y of press

properties
.value (default data output)
0 (off) or 1 (on).

.mode
options: "impulse", "toggle", "position"

methods

Toggle
output data
0 (off) or 1 (on).
properties
.value (default data output)
0 (off) or 1 (on).
methods

Slider
output data
0-1 float, rounded to 3 decimals.
properties
.value (default data output)
0-1 float, rounded to 3 decimals.
methods

Multislider
output data
An array of 0-1 float values. Length of array depends on the number of sliders in the multislider.
properties
.values (default data output)
An array of 0-1 float values. Length of array depends on the number of sliders in the multislider.
methods
.setNumberOfSliders( number )
Set # of sliders in the multislider.
Matrix
output data
An array of arrays of 0-1 floats. The inner arrays are rows.
A 2x2 matrix's output array will look like:
[ [ row1col1, row1col2 ] , [ row2col1, row2col2 ] ]
properties
.matrix (default data output)
An array of arrays of 0-1 floats. The inner arrays are rows.
A 2x2 matrix's output array will look like:
[ [ row1col1, row1col2 ] , [ row2col1, row2col2 ] ]
methods

Select
output data
String value of selected keyword.
properties
.choices (default data output)
An array of menu items.
methods

Tilt
output data
An array of tilt positions: [ x, y, z ];
properties

methods

Metroball
output data
An array of three floats:
y-location of bounce (0-1 left-to-right)
x-location of bounce (1 = bottom wall, 0 = top wall)
ball index (3 bouncing balls will be numbered 0, 1, and 2, depending on time of creation)
properties

methods

Pixels
output data
If set to "write", outputs whole pixel matrix as RGB values in a list.
If set to "read", outputs RGB color data from click position.
properties
.mode
If set to "write" (default), clicking draws pixels
If set to "read", clicking will output color data from click position
methods
.sequence
forthcoming ... will turn this pixel matrix into a sequencer .. !!
Colors
output data
List of 3 integers: RGB value at mouse position if clicked.
properties

methods

Sandbox
output data
3 integer array:
index # of circle being dragged
x value of that circle
y value of that circle
more coming soon
properties

methods

Joints
output data
Array of integer float pairs:
Index of node connected to
Proximity (0-1) to that node

In JavaScript: [ [nodeindex, prox], [nodeindex, prox], [nodeindex, prox] ]
In Max: nodeindex prox nodeindex prox nodeindex prox

Will be empty if not connected to any nodes
properties

methods

Comment
output data
None
properties

methods

Message
output data
String of message text
properties

methods

Number
output data
Float
properties

methods

Banner
output data
None
properties

methods

Multitouch
output data
Array/list of 10 floats (5 x/y pairs of finger touch points)
properties

methods

©
experimental music & digital media @ louisiana state univeristy 2013
Fork me on GitHub