Swarm

Swarm is a free lightweight programming environment for spatial sound and other purposes.

Swarm enables creative coders to intuitively develop new algorithms for live control of large numbers of objects.

Swarm is designed to be flexible and easy-to-use, using simple Lua scripts that can be edited in real-time.

Swarm is meant to integrate with different creative software setups and workflows:

• Swarm can control any software that listens to OSC input (such as 4DSOUND, WFSCollider, SuperCollider synths, TouchDesigner patches, Max/MSP patches)
• Swarm itself can be controlled using any OSC controller (such as TouchOSC).

Swarm is extremely customisable. Using Lua scripts, users can define their own input parameters, output data fields and develop their own algorithms with real-time 3D visual feedback.

Swarm is developed by Casimir Geelhoed on top of the NAP Framework. It it a standalone application that runs on MacOS.

Key features

• Specifically designed for controlling large numbers of sound sources / data elements (think: particle systems, flocking algorithms, etc)
• Real-time scripting in Lua
• Integrated 3D visualisation
• Complete customisation of OSC input & output addresses

Scripting

Location

Lua scripts are located in the /Resources/data/scripts folder inside the package contents of the app. New scripts can be added to this folder and edited while the app is running. Press "Refresh" to rescan the folder.

init() & update(t)

A valid Lua script in Swarm needs to implement two functions:

• init(): initialisation function that is called once after the script is (re)loaded. Use this function to set the sources count, initialise input parameters & output fields.
• update(t): function that is called every frame. t indicates the time passed since the last call. Use this function to implement an algorithm that sets output field data based on input parameters and passed time.

Available functions

Input parameters

• addFloatParameter(name, min, max, default): Creates an input parameter of type float.
  • name is the name & OSC address of the input parameter.
  • min & max are the bounds of the value.
  • default is the default value.
• addVec3Parameter(name, min, max, default): Creates an input parameter of type vec3.
  • name is the name & OSC address of the inpu tparameter.
  • min & max are the bounds of the value (as floats).
  • default is the default value (as vec3).
• getFloat(name): Returns the value of a float input parameter with the given name.
• getVec3(name): Returns the value of a vec3 input parameter with the given name.

Output fields

• setCount(count): Should be called in init(). Sets the number of sources / the number of output OSC address per output field.
• addFloatField(name): Creates an output field of type float.
  • name is the name of the output field.
• addVec3Field(name): Creates an output field of type vec3.
  • name is the name of the output field.
• setFloat(index, name, value): Sets the value for the given index of a float field.
  • index is the index of the source you are setting the data of (starting counting from 1). _
  • name_ is the name of the field.
  • value is the value.
• setVec3(index, name, value): Sets the value for the given index of a vec3 field.
  • index is the index of the source you are setting the data of (starting counting from 1).
  • name is the name of the field.
  • value is the value.

Mathematics

• normalize(vec): Normalizes a vec3.
• distance(vecA, vecB): Returns the distance between two vec3's.
• cross(vecA, vecB): Returns the cross product of two vec3's.
• dot(vecA, vecB): Returns the dot product of two vec3's.
• length(vec): Returns the length of a vec3.

Logging

• log(message): Logs a message.

Visualisation

The 3D visualisation is controlled through fields. Certain field names are mapped to certain aspects of the visualisation.

A vec3 field named displayPosition will control the position of sources in the 3D visualisation.

A float field named displayScale will control the scale of sources in the 3D visualisation.

A float field named displayIntensity will control the color of sources in the 3D visualisation (-1 is blue, 0 is grey, 1 is orange).

OSC Input

All input parameters can be controlled over OSC, their name being the address. The OSC input port can be set under the 'Settings' dropdown menu.

OSC Output

OSC output settings

The OSC output address, port and rate can be set under the 'Settings' dropdown menu.

Generation of OSC output addresses

A field contains a separate OSC output address per source.

Normally, these output addresses are generated as follows:

/sourceINDEX/FIELDNAME

where INDEX is the index of the source and FIELDNAME the name of the field.

For example: if the count is set to 3, the field named 'position' will have the OSC output addresses: /source1/position, /source2/position & /source3/position.

Custom OSC output addresses using the '$' token

To customise the generated OSC output addresses, you can give a field a name with the token '$' in it. For a field with a token '$' in its name, OSC addresses will be generated by replacing '$' by the index.

For example: if the count is set to 3, the field named 'position/$' will have the following OSC output addresses: /position/1, /position/2 and /position/3.

Building from source (for contributors)

1. Clone swarm-nap-0.7.
2. Clone naplua in /modules.
3. Clone this repository in /apps.
4. Execute the 'generate_solution.sh' script to generate the XCode project.

For more information, see the readme and documentation of NAP Framework.