Presentation

Kiwi is a graphical programming environment dedicated to music and sound creation, such as Max or Pure Data softwares, but offering a real-time collaborative approach: Kiwi allows several distant users to work simultaneously on the same patch hosted online.

Kiwi Screenshot

Kiwi is part of the French ANR-funded MUSICOLL project that unites the CICM and OhmForce. The main goal of this project is to study how collaboration can enhance the way digital audio music composition is taught and more generally how it can renew music creation practices and improve its workflow.

Installation

Download

You can download the latest Kiwi application from the github repository.

Compatibility

Kiwi is compatible with the three main operating systems :

OS version
Mac > 10.7
Windows > windows 7
Linux > ubuntu 14.04

Kiwi is only compatible with the 64 bit operating systems.

You also may need to authorize/unlock Kiwi on Mac or to deactivate your antivirus to install it on Windows.

Installing

Once download is complete, the corresponding archive shall be extracted by double clicking on it. A Kiwi folder containing the application is then created. On Mac and Linux, copy the application to your app folder (Application folder on Mac or /usr/bin on linux). Windows users may execute the installer.

You will find in the application a list of help patches that describes the objects' behaviour and a set of examples.

Quick Tour

When Kiwi is executed two windows will appear: the Document Browser and the Kiwi Console.

DocumentBrowser Kiwi Console

The Kiwi Console displays messages from the app or from the patcher. You can access the console from the Window/Console menu or by typing cmd + k on Mac or ctrl + k on Windows or Linux. Messages can be sent to the console through a print object from a patcher.

The Document Browser window allows you to view, create and join remote patchers hosted online. To see hosted documents you first need to login.

See the Register/login section

Patching

In Kiwi you can either join a shared patch using the Document Browser window or open a local patch from your machine. In this section we will show how to open and manipulate a local patch. Instructions on how to collaborate over a patch are given here.

Risset's bell modelling, you can find the patch in the examples.

The patcher above is taken from the Kiwi examples. As you can see, a patch is a set of objects each one carrying out an operation. Control or signal data is sent between objects using links. Grey connections are used to send messages (numbers, strings, lists, bang ect...) whereas dark connections send signals, always from the top to the bottom.

To create a new patcher, press cmd/ctrl + n or go to File/New Patcher.

A patch can either be in edit or in play mode. To switch between edit and play mode, click on the lock button or press cmd + e on Mac (ctrl + e for linux or windows users).

edit mode

edit mode
patcher edit

In edit mode objects and links can be added, removed or edited into the patch.

You can add objects in a patch by first creating an empty box with n or by double clicking and type an object name in the text editor.

Object box popup

Please see the list of availaible objects.

You can also use availables shortcuts to instantiate GUI objects more easily.

play mode

play mode
patcher playing

In play mode graphical objects (the slider object for example) can be manipulated directly to change the state of the patch that is executed.

The audio processing is by default disabled, to put the audio on, click on the speaker icon on the top left part of the patch .

Once you have locked the patch and started the audio processing, in the above example, you could alter the gain of the signal with the slider or change the frequency of the oscillator using the number box.

Multiview

patcher multiview

You can open a new view by pressing cmd/ctrl + shift+ n.

Audio Settings

You can access the audio settings in the Options/Audio Settings menu.

Register/Login

To save and access online documents and start collaborating, you first need to login. There is two options to connect to Kiwi's server: either by creating a new user account or use an already created account.

register/login

Register

To create an account, click on Register under the Account menu. A register window appears. Enter your username, your email address and your password. After clicking the register button, you will receive an email with a temporary link to validate your account. Check that mail then

Login

To connect to an existing user account, click on login in the Account menu. A login window shows up. Enter your email address or username and your password.

Password Reset

If you forgot your password, you can reset it using your email address by clicking on the button Forgot password.

reset password

You will receive an email containing a token to be passed with your new password to reset it.

Network Settings

Network Settings

You can access the network settings by pressing cmd/ctrl + , or via the Settings menu. There is option to connect to another server or on different ports. Most users don't need to make changes here but it could be usefull if you want to run your own Kiwi server.

Please refers to the github repository to get more informations.

Collaborate

In this section we will describe how one can join a patch and collaborate with other users. Once you are logged in, you can access the remote documents from the document browser window.

As you can see the window displays a list of documents accessible online. They can be access by anyone connected to the same server. You can download, delete, upload, rename, duplicate patches from this window by right clicking on an item. Sorting documents using various criteria is also possible.

Double click on a document to join an online session and start collaborating with other users. You can click on the top left icon of the patcher to show the users that are currently editing or playing with the patch.

user list popup FM Synth collaborate

Objects currently selected by other users are highlighted in orange, whereas your own selection is shown in blue.

You can now edit and/or play the patch as you will with the others in realtime. Every modification you make in the structure of the patch will automatically be synced between peers and saved on the server.

On the other hand, when you play with the patch, its state is not shared with the others. Indeed the execution of the patch stay local so you can control parameters independently and isolate or customize audio rendering.

User A User B
User A User B

If you want to share some data of the patch with other users or synchronize GUI objects, you can do it via a specific object of the language called a hub that broadcasts messages to every users connected to the same document through the server.

Using the kiwi hub object

Open the hub help patch in the Help menu for more infos

Objects

Help patches

To see the help of an object, select it in a patch, then right-click on it and click in the help option. It will open the corresponding help file.

A list of help patches describing how each object works is provided in the documentation accessible from the main application menu Help/Objects. Sometimes help patches gather several objects that are functionally linked, for instance gate and switch or gate~ and switch~.

Objects list

There is different kind of objects in Kiwi.

Kiwi Objects

Here is a list of all available objects :

Patching

Object Description Alias Shortcut
newbox Empty new box n
errorbox Error box (when an object is invalid)
send Send message to matching receive object s
receive Receive messages from a sender bound to the same name r
mtof Convert midi notes to frequencies
select Ouput bang if receive matching input sel
random Ouput random number in a uniform distribution
pack Create and outputs a list of messages
unpack Access elements in a list
trigger Trigger events based on received data t
print Print messages into Kiwi console
loadmess Output arguments as message when the patch is loaded
delay Delay messages as bang del
pipe Delay any message
metro Output bang at regular time interval
scale Convert a number from one range into another range
gate Route message to selected output
switch Output message receive in selected inlet
clip Clip a number between a maximum and a minimum value
float Store a float value f
route Route messages according to the first element

GUI Objects

Object Description Alias Shortcut
message Send messages or list of messages
slider Graphical slider sending values between 0 and 1 s
toggle A switch button t
bang Send a bang message b
meter~ A peak amplitude vu meter
comment Add a comment to the patch c
number~ Display audio samples values
number Display a number i/f

Operators

Object Description
+ Add two numbers
* Multiply two numbers
% Compute the modulo of number in desired basis
pow Compute exponentiation of a number
== Equality operator
!= Inequality operator
>= Greater than operator
> Strictly greater than operator
<= Lesser than operator
< Strictly lesser than operator
/ Divide two numbers
- Substract two numbers

Signal

Object Description
line~ Generate an audio ramp signal
noise~ A white noise generator
sah~ Samples and holds an input signal
snapshot~ Ouput sample signal values
adc~ Receive audio signals from inputs or external devices
dac~ Send audio signals to outputs or external devices
osc~ A cosine oscillator
phasor~ Generate a sawtooth signal
sig~ Convert numbers into audio signals
delaysimple~ Simple variable delay line with optional feedback value

Operators (signal)

Object Description
!=~ Signal inequality operator
==~ Signal equality operator
>=~ Signal superior operator
>~ Signal strict superior operator
<=~ Signal inferior operator
<~ Signal strict inferior operator
/~ Divide two signals
-~ Substract two signals
*~ Multiply two signals
+~ Add two signals

Record And play sound files

Object Description
sf.play~ Play an audio file from disk
sf.record~ Record an audio file on disk

Collaborate

Object Description
hub Send message to other users of the same patch

Others

Object Description
faust~ Edit and run FAUST code
OSC.receive Receive Open Sound Control messages over UDP
OSC.send Send Open Sound Control messages over UDP

Examples

A set of examples is provided in the Kiwi documentation. To explore them, simply go to the main software menu Help/Examples.

Each example aims at taking you through the creation of a specific audio processing or exploring a certain aspect of Kiwi :

Fx
flanger
granular
oscillo-pan
overlapped pitchshifter
simple delay
simple pitchshifter
synthesis
additive synthesis
Chowning FM with Pan
Chowning FM
Kontakte
odd harmonic gen 1
odd harmonic gen 2
odd harmonic gen 3
odd harmonic gen 3
Risset's Bell
others
play and record files

Shortcuts

Application shortcuts

  • cmd/ctrl + w : Close current window.
  • cmd/ctrl + k : Show Kiwi Console Window.

Patcher shortcuts

  • cmd + n : Create a new patcher.
  • cmd/ctrl + shift + n : Create a new patcher view.
  • cmd/ctrl + e : Switch between edit and perform mode.
  • cmd/ctrl + = : Zoom in.
  • cmd/ctrl + - : Zoom out.
  • cmd/ctrl + shift + 1 : Reset zoom.

Objects shortcuts

  • n : Add an object.
  • b : Add a bang object.
  • t : Add a toggle object.
  • s : Add a slider object.
  • i/f : Add a number object.
  • c : Add a comment object.
  • m : Add a message object.