diff --git a/doc/objects.md b/doc/objects.md new file mode 100644 index 0000000000000000000000000000000000000000..20575c20d9819b0190b0cfa843b7ea07539480d5 --- /dev/null +++ b/doc/objects.md @@ -0,0 +1,110 @@ +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: + + + +###### Inlets: +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. + +###### Arguments: +1. arg1 + +###### Inlets: +1. blah + +###### Outlets: +1. blah + + +## bf-ask +Description blah blah + +###### Arguments: +1. arg1 + +###### Inlets: +1. blah + +###### Outlets: +1. blah + + +