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 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.
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 |
|---|
 |
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.
Please see the list of availaible objects.
You can also use availables shortcuts to instantiate GUI objects more easily.
play mode
| play mode |
|---|
 |
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
You can open a new view by pressing
cmd/ctrl+shift+n.
Audio Settings
You can access the audio settings in the
Options/Audio Settingsmenu.
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
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.
You will receive an email containing a token to be passed with your new password to reset it.
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.
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 |
|---|---|
 |
|
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.
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.
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 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.