objects.html

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>bf-pd : objects</title>
  <style>
    code{white-space: pre-wrap;}
    span.smallcaps{font-variant: small-caps;}
    span.underline{text-decoration: underline;}
    div.column{display: inline-block; vertical-align: top; width: 50%;}
    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
    ul.task-list{list-style: none;}
  </style>
  <link rel="stylesheet" href="img/style.css" />
</head>
<body>
<nav>
	<li><a href="index.html">Home</a></li>
	<li><a href="boeuf.html">BOEUF</a></li>
	<li><a href="objects.html">Objects</a></li>
</nav>
<main>
<p>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.</p>
<h2 id="bf-session">bf-session</h2>
<p>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.</p>
<p>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].</p>
<p>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.)</p>
<h6 id="arguments">Arguments:</h6>
<ol type="1">
<li>The name of the session.</li>
</ol>
<h6 id="outlets">Outlets:</h6>
<ol type="1">
<li>Outlet 1 sends all the session messages which are used “behind the scenes” by the bf-pd objects.</li>
</ol>
<h2 id="bf-instrument">bf-instrument</h2>
<p>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].</p>
<p>The audio output of your instrument should be connected to the first inlet of bf-instrument object. The interface has an <em>activity monitor</em> 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 <em>collaboration window</em>. (Note: you must also send your audio to [dac~] in order to hear it!)</p>
<p>The <em>collaboration window</em> 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.</p>
<h6 id="arguments-1">Arguments:</h6>
<ol type="1">
<li>The name of the instrument.</li>
</ol>
<h6 id="inlets">Inlets:</h6>
<ol type="1">
<li>The audio output of your instrument should be sent here. (It must also be sent to [dac~].)</li>
</ol>
<h2 id="bf-param">bf-param</h2>
<p>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.</p>
<p>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.</p>
<p>A bf-param can be one of four <em>types</em>: * <em>cont</em> are numbers between 0.0 and 1.0. * <em>midi</em> are numbers between 0.0 and 127.0. * <em>bool</em> can take values of 0 or 1. * <em>bang</em> are bang messages which are used to trigger actions.</p>
<p>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 sequencer.</p>
<h6 id="arguments-2">Arguments:</h6>
<ol type="1">
<li>The name of the instrument, e.g. “myDrumMachine”.</li>
<li>The name of the parameter, e.g. “kickOnOff”</li>
<li>The dimensionality of the parameter, e.g. “8”</li>
<li>The type of the parameter, e.g. “bool”</li>
</ol>
<p>So a bf-param with 8 drum machine note triggers would be: <code>[bf-param myDrumMachine kickOnOff 8 bool]</code> and creates this object within your patch:</p>
<figure>
<img src="img/bf-param_example.png" alt="" /><figcaption>bf-param_example</figcaption>
</figure>
<h6 id="inlets-1">Inlets:</h6>
<ol type="1">
<li>Sets the value of the parameter. If the parameter is a multiple, then <em>Inlet 1</em> sets the parameter at the index last received on <em>Inlet 2</em>.</li>
<li>Sets the index of the parameter which will be changed by sending values to <em>Inlet 1</em>.</li>
<li>An integer in <em>Inlet 3</em> will send the value of the parameter at that index to <em>Outlet 3</em>.</li>
</ol>
<p>(The first two inlets for bf-param operate similar to the first two inlets for [array set] in Pd.)</p>
<h6 id="outlets-1">Outlets:</h6>
<ol type="1">
<li>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.)</li>
<li>A list of the parameter value of the most recent change, and the index of the parameter that was changed.</li>
<li>The parameter value for the index that was sent to <em>Inlet 3</em>.</li>
</ol>
<h2 id="bf-output">bf-output</h2>
<p>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.</p>
<p>Each bf-output in your bf-instrument will appear [TODO continue]</p>
<p>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.</p>
<h6 id="arguments-3">Arguments:</h6>
<ol type="1">
<li>arg1</li>
</ol>
<h6 id="inlets-2">Inlets:</h6>
<ol type="1">
<li>blah</li>
</ol>
<h6 id="outlets-2">Outlets:</h6>
<ol type="1">
<li>blah</li>
</ol>
<h2 id="bf-watch">bf-watch</h2>
<p>Bf-watch is used to get data from another bf-instrument into your bf-instrument.</p>
<h6 id="arguments-4">Arguments:</h6>
<ol type="1">
<li>arg1</li>
</ol>
<h6 id="inlets-3">Inlets:</h6>
<ol type="1">
<li>blah</li>
</ol>
<h6 id="outlets-3">Outlets:</h6>
<ol type="1">
<li>blah</li>
</ol>
<h2 id="bf-ask">bf-ask</h2>
<p>Description blah blah</p>
<h6 id="arguments-5">Arguments:</h6>
<ol type="1">
<li>arg1</li>
</ol>
<h6 id="inlets-4">Inlets:</h6>
<ol type="1">
<li>blah</li>
</ol>
<h6 id="outlets-4">Outlets:</h6>
<ol type="1">
<li>blah</li>
</ol>
</main>
</body>
</html>