diff --git a/bf-clock-help.pd b/bf-clock-help.pd index 152aab2677e52f8e2b92c1057a5ae6abcba8c7da..c8c09239c27e309a3bfc710bca7cb4f0fac3edc4 100644 Binary files a/bf-clock-help.pd and b/bf-clock-help.pd differ diff --git a/doc/README.md b/doc/README.md index 12918a28c46c9f542367df571f5097462ed8fb50..c7baf1b0416223f30ec7a2e94b4ebe060b5195cc 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,5 +1,5 @@ # bf-pd documentation -* Explanations on the BOEUF framework for collaboration modes in orchestras [on this page](boeuf.md). -* List of bf-pd [objects](objects.md) +* A description of the BOEUF conceptual framework can be found on [this page](boeuf.md). +* A list of the objects in the bf-pd library can be found [here](objects.md) diff --git a/doc/objects.md b/doc/objects.md index bb826f864f7ca4605ea2284d6ea959840424c337..99dd13e82da2d83920da290be69711667be865f8 100644 --- a/doc/objects.md +++ b/doc/objects.md @@ -1,4 +1,4 @@ -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-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. (Note, there is also a help file for each of the bf-pd objects ## 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. @@ -19,7 +19,7 @@ A bf-instrument represents a musical instrument within the bf-pd system. Each in The audio output of your instrument should be connected to the first inlet of bf-instrument object. The interface 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. +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 to update the collab window. ###### Arguments: 1. The name of the instrument. @@ -29,7 +29,7 @@ The *collaboration window* can be opened with the toggle in the bf-instrument ob ## 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 owner of the bf-instrument grants access. +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 owner of the bf-instrument has granted access.) A bf-param object has a user interface within the instrument patch itself, and it also creates a user interface in the collaboration window of each musician in the session. @@ -46,6 +46,7 @@ A bf-param can be a single instance of its type or it can be a multiple, which c 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" +5. The order you want the parameter to appear in the Collab Window. So a bf-param with 8 drum machine note triggers would be: `[bf-param myDrumMachine kickOnOff 8 bool]` and creates this object within your patch: @@ -61,25 +62,59 @@ So a bf-param with 8 drum machine note triggers would be: ###### 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. +2. A list with 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] +When you open the collab window (by clicking on the 'collab' toggle in your bf-instrument) +Each bf-output in your bf-instrument will appear on the left of the column for your instrument. You will also see three default outputs which are computed from your instrument's audio: one detects onsets in your instrument's audio, one outputs a pitch estimate, and one which outputs a loudness estimate. - 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 +1. The name of your instrument, e.g. "myDrumMachine" +2. The name of your output, e.g. "triggers" +3. The dimensionality of the parameter, e.g. "4" +4. The type of the parameter, e.g. "bang" +5. The order you want the outlet to appear in the Collab Window (after the three default outputs). ###### Inlets: -1. blah +The inlets are similar to the first two inlets of bf-param +1. Sets the value of the output. If the output is a multiple, then *Inlet 1* sets the parameter at the index last received on *Inlet 2*. +2. Sets the index of the output which will be changed by sending values to *Inlet 1*. ###### Outlets: -1. blah +1. The bf-output object in your patch does not have any outlets. + + +## bf-clock +A bf-clock can be used for generating and sharing tempi and rhythmic events. You can use a bf-clock to create rhythmic events in your instrument, and you can synchronise instruments by sharing tempi between instruments via the collab window. + +###### Arguments: +1. The name of your instrument, e.g. "myDrumMachine" +2. The name of your bf-clock, e.g. "leadClock" +3. The order you want the clock to appear (amongst the other bf-params) in the Collab Window. + +###### Inlets: +1. A '1' or '0' turns the clock on and off +2. A number sets the tempo in beats-per-minute (BPM), e.g. "120" +3. A number sets the meter, i.e. the number of beats in a measure, e.g. "4" for 4/4 time. +4. A number sets the first beat subdivision. E.g. "2" will create eighth notes (or quavers). +5. A number sets the second beat subdivision. E.g. "3" will create eighth note triplets (or quaver triplets). +6. This inlet can take a variety of messages for controlling a bf-clock. (See bf-clock-help.pd for details.) + +###### Outlets: +1. Outputs a bang on each downbeat. E.g. if meter is set to '4', the downbeat will occur every four beats. You can think of this as the first beat in a measure. +2. Outputs a bang on each beat. E.g. if BPM is set to '120', then there will be two beats per second. +3. Outputs a bang on each subdivision1. E.g. if sub1 is "2", then the bangs can be thought of as eighth notes (quavers). +4. Outputs a bang on each subdivision1. E.g. if sub2 is "3", then the bangs can be thought of as eighth note triplets (quavertriplets). +5. This outlet sends various messages about the state of the bf-clock, which allows one bf-clock to control the bpm of, and synchronize with, another bf-clock within the same patch. + +See bf-clock-help.pd to see more details about using bf-clock. + ## bf-watch Bf-watch is used to get data from another bf-instrument into your bf-instrument. diff --git a/examples/bfex_BassSynth303.pd b/examples/bfex_BassSynth303.pd index be159ee4500277550d04bbddfdeba4c8f9abb65f..268780806d8147e5a161e0a693395df29f75a3b1 100644 Binary files a/examples/bfex_BassSynth303.pd and b/examples/bfex_BassSynth303.pd differ