Bf-pd is a library of pd objects for enabling real-time collaboration. This page describes each of the objects in bf-pd, their arguments, inlets and outlets.
## bf-session
A bf-session represents a group of musicians (as represented by their bf-instruments) making music together. Within the bf-pd system a bf-session works "behind the scenes" to coordinate the data exchanged between bf-instruments.
To participate in a bf-session there must be at least one instance of bf-session instantiated somewhere. A bf-session has a name, e.g. "technoJam1", and this session would be instantiated as [bf-session technoJam1].
There can be more than one bf-session object with the same name within the patches running in Pd. So you can add the same bf-session to each bf-instrument. (However if you instantiate two different bf-sessions within pd, the second one will not work.)
###### Arguments:
1. The name of the session.
###### Outlets:
1. Outlet 1 sends all the session messages which are used "behind the scenes" by the bf-pd objects.
## bf-instrument
A bf-instrument represents a musical instrument within the bf-pd system. Each instrument joins a bf-session and can contain bf-params and bf-outputs. To create an instrument you should instantiate a bf-instrument with the name of your instrument, e.g. [bf-instrument myDrumMachine].
The audio output of your instrument should be connected to the first inlet of bf-instrument object. The interface for has an *activity monitor* which shows a simple representation of the changing spectrum of the instrument's sound, and the activity for each bf-instrument in the bf-session appears in the *collaboration window*. (Note: you must also send your audio to [dac~] in order to hear it!)
The *collaboration window* can be opened with the toggle in the bf-instrument object. If musicians enter or leave the session you may need to close and re-open the collaboration window.
###### Arguments:
1. The name of the instrument.
###### Inlets:
1. The audio output of your instrument should be sent here. (It must also be sent to [dac~].)
## bf-param
A bf-param creates a user parameter within the bf-pd system. A bf-param can be controlled by the user of the bf-instrument it belongs to, and the bf-param will also be accessible to other instruments within the bf-session, via the collaboration window, if the user of the bf-instrument grants access.
A bf-param object has a user interface within the instrument patch itself, and it creates a user interface in the collaboration window of each musician in the session.
A bf-param can be one of four *types*:
**cont* are numbers between 0.0 and 1.0.
**midi* are numbers between 0.0 and 127.0.
**bool* can take values of 0 or 1.
**bang* are bang messages which are used to trigger actions.
A bf-param can be a single instance of its type or it can be a multiple, which creates an array of values within a single bf-param object. For example, a bf-param "8 bool" creates an interface with 8 toggles, and might be used to represent 8 on/off values in a drum machine sequencers.
###### Arguments:
1. The name of the instrument, e.g. "myDrumMachine".
2. The name of the parameter, e.g. "kickOnOff"
3. The dimensionality of the parameter, e.g. "8"
4. The type of the parameter, e.g. "bool"
So a parameter to store 8 drum machine note triggers would be:
`[bf-param myDrumMachine kickOnOff 8 bool]` and creates this object within your patch:
1. Sets the value of the parameter. If the parameter is a multiple, then *Inlet 1* sets the parameter at the index last received on *Inlet 2*.
2. Sets the index of the parameter which will be changed by sending values to *Inlet 1*.
3. An integer in *Inlet 3* will send the value of the parameter at that index to *Outlet 3*.
(The first two inlets for bf-param operate similar to the first two inlets for [array set] in Pd.)
###### Outlets:
1. The parameter value of the most recent change to the bf-param (whether that change came from the inlets, the UI, or via the collaboration window.)
2. A list of the parameter value of the most recent change, and the index of the parameter that was changed.
3. The parameter value for the index that was sent to *Inlet 3*.
## bf-output
An bf-output can be used to send some musical data from your bf-instrument to another instrument in the same bf-session. A bf-output can have the same types and multiplicity as a bf-param.
Each bf-output in your bf-instrument will appear [TODO continue]
is a musical attribute that is produced by a module or instrument. They can have the same types as parameters. Outputs can be retrieved and watched by other instruments, and function as a means for both awareness and exchange.
###### Arguments:
1. arg1
###### Inlets:
1. blah
###### Outlets:
1. blah
## bf-watch
Bf-watch is used to get data from another bf-instrument into your bf-instrument.
