diff --git a/README.md b/README.md index d671ba5641093e1e39df8b656f9d902dff2548e0..e9c3cc1a6812eb24c7ba9206f94dcf087a424d48 100644 --- a/README.md +++ b/README.md @@ -19,28 +19,48 @@ The design of bf-pd is based on the BOEUF conceptual framework which consists of  -- Create a declare object with -path bf-pd -- Create a bf-instrument object with your instrument name as argument -- Connect the sound output of your instrument to its inlet -- Create a bf-param object for each control you want to share with the others and insert it into your instrument -- Create a bf-session object with the name of the session you want to connect to +Starting from an existing instrument made in PureData : + +1. Create a declare object with -path bf-pd +2. Create a bf-instrument object with your instrument name as argument +3. Connect the sound output of your instrument to its inlet +4. Create a bf-param object for each control you want to share with the others and insert it into your instrument +5. Create a bf-session object with the name of the session you want to connect to ## Performance: Making music together using bf-pd ### The collaboration window -### Sharing parameters +The collaboration window is a collaboration interface that comes with bf-pd and provides a way to connect your instrument with other instruments in the session. + +To open the collaboration window, simply check the *collab* toggle in the bf-instrument object. + +The leftmost green column shows your instrument with its outputs and parameters. The grey columns show the other instruments in the session with their respective activity, outputs and parameters. + +### Sharing / granting access + +By default, all your parameters are in the *granted* mode, which means that all the other musicians can set their values. You can of course change that by clicking the red *grant* toggle for each parameter, or the *grant all* toggle at the top of your column. +If not granted, values *asked* by others are only displayed on the gray widgets and can be retrieved using the *1x* bang. + +### Using others parameters and outputs to change your parameters + +A *watch* bus selector is placed below each parameter and output of the other instruments. By choosing a bus other than 0, the values are sent to the corresponding bus and can be sent to your parameters connected to the same bus using the *watching* selector. + +### Controlling others parameters with your parameters and outputs + +Symmetrically, you can control others parameters by choosing a non-zero bus on the *ask* selector and the same *asking* bus below one of your outputs or parameters. This requires however that the parameter that you want to controlled is *granted* (i.e. that the green *granted* toggle is checked). -### Connecting parameters using ask and watch +### Directly asking / Controlling others parameters +You can also ask another instrument's parameter to be set to a specific value by interacting with the white sliders/toggles/bangs. It the access is granted, the value will be directly set. -### Video example +## Video example <a href="https://vimeo.com/214380530">Video showing a simple session</a> ## More resources -Documentation for each of the user objects in bf-pd can be found in [objects.md](doc/objects.md). +Documentation for each of the user objects in bf-pd can be found in [objects.md](doc/objects.md) and on help patches directly in PureData (right-click an object -> Help) The *BOEUF conceptual framework* describes the *modes of collaboration* used in musical collaboration and describes a set of *components* for realizing these modes in a software framework. Bf-pd is based on this framework. More info can be found in [boeuf.md](doc/boeuf.md).